The contents of the clock binding have been moved to the clock binding schema in the dtschema repository. The desire is for common bindings to be hosted in the dtschema repository. Replace the contents with a link to the clock binding schema as there are still many references to clock-bindings.txt in the tree. This will prevent additions without a schema. Signed-off-by: Rob Herring <robh@xxxxxxxxxx> --- Most of the clock binding doc was already moved. 2 more sections are pending: https://lore.kernel.org/all/20220428152633.2261979-1-robh@xxxxxxxxxx/ https://lore.kernel.org/all/20220428152719.2263164-1-robh@xxxxxxxxxx/ --- .../bindings/clock/clock-bindings.txt | 188 +----------------- 1 file changed, 2 insertions(+), 186 deletions(-) diff --git a/Documentation/devicetree/bindings/clock/clock-bindings.txt b/Documentation/devicetree/bindings/clock/clock-bindings.txt index f2ea53832ac6..6fe541368889 100644 --- a/Documentation/devicetree/bindings/clock/clock-bindings.txt +++ b/Documentation/devicetree/bindings/clock/clock-bindings.txt @@ -1,186 +1,2 @@ -This binding is a work-in-progress, and are based on some experimental -work by benh[1]. - -Sources of clock signal can be represented by any node in the device -tree. Those nodes are designated as clock providers. Clock consumer -nodes use a phandle and clock specifier pair to connect clock provider -outputs to clock inputs. Similar to the gpio specifiers, a clock -specifier is an array of zero, one or more cells identifying the clock -output on a device. The length of a clock specifier is defined by the -value of a #clock-cells property in the clock provider node. - -[1] https://patchwork.ozlabs.org/patch/31551/ - -==Clock providers== - -Required properties: -#clock-cells: Number of cells in a clock specifier; Typically 0 for nodes - with a single clock output and 1 for nodes with multiple - clock outputs. - -Optional properties: -clock-output-names: Recommended to be a list of strings of clock output signal - names indexed by the first cell in the clock specifier. - However, the meaning of clock-output-names is domain - specific to the clock provider, and is only provided to - encourage using the same meaning for the majority of clock - providers. This format may not work for clock providers - using a complex clock specifier format. In those cases it - is recommended to omit this property and create a binding - specific names property. - - Clock consumer nodes must never directly reference - the provider's clock-output-names property. - -For example: - - oscillator { - #clock-cells = <1>; - clock-output-names = "ckil", "ckih"; - }; - -- this node defines a device with two clock outputs, the first named - "ckil" and the second named "ckih". Consumer nodes always reference - clocks by index. The names should reflect the clock output signal - names for the device. - -clock-indices: If the identifying number for the clocks in the node - is not linear from zero, then this allows the mapping of - identifiers into the clock-output-names array. - -For example, if we have two clocks <&oscillator 1> and <&oscillator 3>: - - oscillator { - compatible = "myclocktype"; - #clock-cells = <1>; - clock-indices = <1>, <3>; - clock-output-names = "clka", "clkb"; - } - - This ensures we do not have any empty strings in clock-output-names - - -==Clock consumers== - -Required properties: -clocks: List of phandle and clock specifier pairs, one pair - for each clock input to the device. Note: if the - clock provider specifies '0' for #clock-cells, then - only the phandle portion of the pair will appear. - -Optional properties: -clock-names: List of clock input name strings sorted in the same - order as the clocks property. Consumers drivers - will use clock-names to match clock input names - with clocks specifiers. -clock-ranges: Empty property indicating that child nodes can inherit named - clocks from this node. Useful for bus nodes to provide a - clock to their children. - -For example: - - device { - clocks = <&osc 1>, <&ref 0>; - clock-names = "baud", "register"; - }; - - -This represents a device with two clock inputs, named "baud" and "register". -The baud clock is connected to output 1 of the &osc device, and the register -clock is connected to output 0 of the &ref. - -==Example== - - /* external oscillator */ - osc: oscillator { - compatible = "fixed-clock"; - #clock-cells = <0>; - clock-frequency = <32678>; - clock-output-names = "osc"; - }; - - /* phase-locked-loop device, generates a higher frequency clock - * from the external oscillator reference */ - pll: pll@4c000 { - compatible = "vendor,some-pll-interface" - #clock-cells = <1>; - clocks = <&osc 0>; - clock-names = "ref"; - reg = <0x4c000 0x1000>; - clock-output-names = "pll", "pll-switched"; - }; - - /* UART, using the low frequency oscillator for the baud clock, - * and the high frequency switched PLL output for register - * clocking */ - uart@a000 { - compatible = "fsl,imx-uart"; - reg = <0xa000 0x1000>; - interrupts = <33>; - clocks = <&osc 0>, <&pll 1>; - clock-names = "baud", "register"; - }; - -This DT fragment defines three devices: an external oscillator to provide a -low-frequency reference clock, a PLL device to generate a higher frequency -clock signal, and a UART. - -* The oscillator is fixed-frequency, and provides one clock output, named "osc". -* The PLL is both a clock provider and a clock consumer. It uses the clock - signal generated by the external oscillator, and provides two output signals - ("pll" and "pll-switched"). -* The UART has its baud clock connected the external oscillator and its - register clock connected to the PLL clock (the "pll-switched" signal) - -==Assigned clock parents and rates== - -Some platforms may require initial configuration of default parent clocks -and clock frequencies. Such a configuration can be specified in a device tree -node through assigned-clocks, assigned-clock-parents and assigned-clock-rates -properties. The assigned-clock-parents property should contain a list of parent -clocks in the form of a phandle and clock specifier pair and the -assigned-clock-rates property should contain a list of frequencies in Hz. Both -these properties should correspond to the clocks listed in the assigned-clocks -property. - -To skip setting parent or rate of a clock its corresponding entry should be -set to 0, or can be omitted if it is not followed by any non-zero entry. - - uart@a000 { - compatible = "fsl,imx-uart"; - reg = <0xa000 0x1000>; - ... - clocks = <&osc 0>, <&pll 1>; - clock-names = "baud", "register"; - - assigned-clocks = <&clkcon 0>, <&pll 2>; - assigned-clock-parents = <&pll 2>; - assigned-clock-rates = <0>, <460800>; - }; - -In this example the <&pll 2> clock is set as parent of clock <&clkcon 0> and -the <&pll 2> clock is assigned a frequency value of 460800 Hz. - -Configuring a clock's parent and rate through the device node that consumes -the clock can be done only for clocks that have a single user. Specifying -conflicting parent or rate configuration in multiple consumer nodes for -a shared clock is forbidden. - -Configuration of common clocks, which affect multiple consumer devices can -be similarly specified in the clock provider node. - -==Protected clocks== - -Some platforms or firmwares may not fully expose all the clocks to the OS, such -as in situations where those clks are used by drivers running in ARM secure -execution levels. Such a configuration can be specified in device tree with the -protected-clocks property in the form of a clock specifier list. This property should -only be specified in the node that is providing the clocks being protected: - - clock-controller@a000f000 { - compatible = "vendor,clk95; - reg = <0xa000f000 0x1000> - #clocks-cells = <1>; - ... - protected-clocks = <UART3_CLK>, <SPI5_CLK>; - }; +This file has moved to the clock binding schema: +https://github.com/devicetree-org/dt-schema/blob/main/dtschema/schemas/clock/clock.yaml -- 2.34.1
