[PATCH 14/14] dt-bindings: reset: Convert to yaml

Philipp Zabel
2022-04-07T15:44:48Z

Convert the common reset controller and reset consumer device tree
bindings to YAML schema.

Signed-off-by: Philipp Zabel <p.zabel@pengutronix.de>
Cc: Stephen Warren <swarren@nvidia.com>
---
.../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@nvidia.com>
+%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@pengutronix.de>
+
+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@nvidia.com>
+%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@pengutronix.de>
+
+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