Convert the common reset controller and reset consumer device tree bindings to YAML schema. Signed-off-by: Philipp Zabel <p.zabel@xxxxxxxxxxxxxx> Cc: Stephen Warren <swarren@xxxxxxxxxx> --- .../bindings/reset/reset-consumer.yaml | 72 ++++++++++++++++++ .../bindings/reset/reset-controller.yaml | 50 +++++++++++++ .../devicetree/bindings/reset/reset.txt | 75 ------------------- 3 files changed, 122 insertions(+), 75 deletions(-) create mode 100644 Documentation/devicetree/bindings/reset/reset-consumer.yaml create mode 100644 Documentation/devicetree/bindings/reset/reset-controller.yaml delete mode 100644 Documentation/devicetree/bindings/reset/reset.txt diff --git a/Documentation/devicetree/bindings/reset/reset-consumer.yaml b/Documentation/devicetree/bindings/reset/reset-consumer.yaml new file mode 100644 index 000000000000..e17229eb49c0 --- /dev/null +++ b/Documentation/devicetree/bindings/reset/reset-consumer.yaml @@ -0,0 +1,72 @@ +# SPDX-License-Identifier: GPL-2.0 +# Copyright 2012 Stephen Warren <swarren@xxxxxxxxxx> +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/reset/reset-consumer.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Common reset signal consumer bindings + +maintainers: + - Philipp Zabel <p.zabel@xxxxxxxxxxxxxx> + +description: | + Hardware blocks typically receive a reset signal. This signal is generated by + a reset provider (e.g. power management or clock module) and received by a + reset consumer (the module being reset, or a module managing when a sub- + ordinate module is reset). This binding exists to represent the consumers of + reset signals provided by reset controllers. + + A reset signal is represented by the phandle of the provider, plus a reset + specifier - a list of DT cells that represents the reset signal within the + provider. The length (number of cells) and semantics of the reset specifier + are dictated by the binding of the reset provider, although common schemes + are described below. + + A word on where to place reset signal consumers in device tree: It is possible + in hardware for a reset signal to affect multiple logically separate HW blocks + at once. In this case, it would be unwise to represent this reset signal in + the DT node of each affected HW block, since if activated, an unrelated block + may be reset. Instead, reset signals should be represented in the DT node + where it makes most sense to control it; this may be a bus node if all + children of the bus are affected by the reset signal, or an individual HW + block node for dedicated reset signals. The intent of this binding is to give + appropriate software access to the reset signals in order to manage the HW, + rather than to slavishly enumerate the reset signal that affects each HW + block. + +select: true + +properties: + resets: + $ref: /schemas/types.yaml#/definitions/phandle-array + description: | + List of phandle and reset specifier pairs, one pair for each reset signal + that affects the device, or that the device manages. + Note: if the reset provider specifies '0' for "#reset-cells", then only + the phandle portion of the pair will appear. + + reset-names: + description: | + List of reset signal name strings sorted in the same order as the resets + property. Consumers drivers will use "reset-names" to match reset signal + names with reset specifiers. + +additionalProperties: true + +examples: + - | + // A device with a single reset signal named "reset". + device { + resets = <&rst 20>; + reset-names = "reset"; + }; + - | + // A bus that controls the reset signal of each of four subordinate + // devices. Consider for example a bus that fails to operate unless no + // child device has reset asserted. + bus { + resets = <&rst 10>, <&rst 11>, <&rst 12>, <&rst 11>; + reset-names = "i2s1", "i2s2", "dma", "mixer"; + }; +... diff --git a/Documentation/devicetree/bindings/reset/reset-controller.yaml b/Documentation/devicetree/bindings/reset/reset-controller.yaml new file mode 100644 index 000000000000..33468f94f4c2 --- /dev/null +++ b/Documentation/devicetree/bindings/reset/reset-controller.yaml @@ -0,0 +1,50 @@ +# SPDX-License-Identifier: GPL-2.0 +# Copyright 2021 Stephen Warren <swarren@xxxxxxxxxx> +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/reset/reset-controller.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Common reset controller provider bindings + +maintainers: + - Philipp Zabel <p.zabel@xxxxxxxxxxxxxx> + +description: | + This binding is intended to represent the hardware reset signals present + internally in most IC (SoC, FPGA, ...) designs. Reset signals for whole + standalone chips are most likely better represented as GPIOs, although there + are likely to be exceptions to this rule. + + Hardware blocks typically receive a reset signal. This signal is generated by + a reset provider (e.g. power management or clock module) and received by a + reset consumer (the module being reset, or a module managing when a sub- + ordinate module is reset). This binding exists to represent the provider of + one or more reset signals. + +select: + anyOf: + - properties: + $nodename: + pattern: '^reset-controller' + - required: + - '#reset-cells' + +properties: + '#reset-cells': + $ref: /schemas/types.yaml#/definitions/uint32 + +additionalProperties: true + +examples: + - | + // A reset controller providing multiple reset controls + rst: reset-controller { + #reset-cells = <1>; + }; + + // A reset consumer receiving a single reset signal with index 0 + peripheral { + resets = <&rst 0>; + }; +... diff --git a/Documentation/devicetree/bindings/reset/reset.txt b/Documentation/devicetree/bindings/reset/reset.txt deleted file mode 100644 index 31db6ff84908..000000000000 --- a/Documentation/devicetree/bindings/reset/reset.txt +++ /dev/null @@ -1,75 +0,0 @@ -= Reset Signal Device Tree Bindings = - -This binding is intended to represent the hardware reset signals present -internally in most IC (SoC, FPGA, ...) designs. Reset signals for whole -standalone chips are most likely better represented as GPIOs, although there -are likely to be exceptions to this rule. - -Hardware blocks typically receive a reset signal. This signal is generated by -a reset provider (e.g. power management or clock module) and received by a -reset consumer (the module being reset, or a module managing when a sub- -ordinate module is reset). This binding exists to represent the provider and -consumer, and provide a way to couple the two together. - -A reset signal is represented by the phandle of the provider, plus a reset -specifier - a list of DT cells that represents the reset signal within the -provider. The length (number of cells) and semantics of the reset specifier -are dictated by the binding of the reset provider, although common schemes -are described below. - -A word on where to place reset signal consumers in device tree: It is possible -in hardware for a reset signal to affect multiple logically separate HW blocks -at once. In this case, it would be unwise to represent this reset signal in -the DT node of each affected HW block, since if activated, an unrelated block -may be reset. Instead, reset signals should be represented in the DT node -where it makes most sense to control it; this may be a bus node if all -children of the bus are affected by the reset signal, or an individual HW -block node for dedicated reset signals. The intent of this binding is to give -appropriate software access to the reset signals in order to manage the HW, -rather than to slavishly enumerate the reset signal that affects each HW -block. - -= Reset providers = - -Required properties: -#reset-cells: Number of cells in a reset specifier; Typically 0 for nodes - with a single reset output and 1 for nodes with multiple - reset outputs. - -For example: - - rst: reset-controller { - #reset-cells = <1>; - }; - -= Reset consumers = - -Required properties: -resets: List of phandle and reset specifier pairs, one pair - for each reset signal that affects the device, or that the - device manages. Note: if the reset provider specifies '0' for - #reset-cells, then only the phandle portion of the pair will - appear. - -Optional properties: -reset-names: List of reset signal name strings sorted in the same order as - the resets property. Consumers drivers will use reset-names to - match reset signal names with reset specifiers. - -For example: - - device { - resets = <&rst 20>; - reset-names = "reset"; - }; - -This represents a device with a single reset signal named "reset". - - bus { - resets = <&rst 10> <&rst 11> <&rst 12> <&rst 11>; - reset-names = "i2s1", "i2s2", "dma", "mixer"; - }; - -This represents a bus that controls the reset signal of each of four sub- -ordinate devices. Consider for example a bus that fails to operate unless no -child device has reset asserted. -- 2.30.2
