[PATCH v5 1/5] dt-bindings: ata: ahci-platform: Convert DT bindings to yaml

From: Frank Wunderlich
Date: Sat Mar 05 2022 - 06:26:32 EST

From: Frank Wunderlich <frank-w@xxxxxxxxxxxxxxx>

Create a yaml file for dtbs_check from the old txt binding.

Signed-off-by: Frank Wunderlich <frank-w@xxxxxxxxxxxxxxx>
---

v5:
- change subject
- drop brcm,iproc-ahci from standalone enum
- fix reg address in example 2
- move clocknames next to clocks, regnames to reg
- drop interrupts description
- drop newline from dma-coherent
- drop max-items from ports-implemented
- min2max in child phys
- fix identation for compatible and sata-common
- add additionalProperties=false for subnodes
- pipe for paragraphs and newline after title
- add maximum for ports-implemented (found only 0x1 as its value)
- add phy-names to sata-ports

v4:
- fix min vs. max
- fix indention of examples
- move up sata-common.yaml
- reorder compatible
- add descriptions/maxitems
- fix compatible-structure
- fix typo in example achi vs. ahci
- add clock-names and reg-names
- fix ns2 errors in separate patch
v3:
- add conversion to sata-series
- fix some errors in dt_binding_check and dtbs_check
- move to unevaluated properties = false

---
.../devicetree/bindings/ata/ahci-platform.txt | 79 ---------
.../bindings/ata/ahci-platform.yaml | 163 ++++++++++++++++++
2 files changed, 163 insertions(+), 79 deletions(-)
delete mode 100644 Documentation/devicetree/bindings/ata/ahci-platform.txt
create mode 100644 Documentation/devicetree/bindings/ata/ahci-platform.yaml

diff --git a/Documentation/devicetree/bindings/ata/ahci-platform.txt b/Documentation/devicetree/bindings/ata/ahci-platform.txt
deleted file mode 100644
index 77091a277642..000000000000
--- a/Documentation/devicetree/bindings/ata/ahci-platform.txt
+++ /dev/null
@@ -1,79 +0,0 @@
-* AHCI SATA Controller
-
-SATA nodes are defined to describe on-chip Serial ATA controllers.
-Each SATA controller should have its own node.
-
-It is possible, but not required, to represent each port as a sub-node.
-It allows to enable each port independently when dealing with multiple
-PHYs.
-
-Required properties:
-- compatible : compatible string, one of:
- - "brcm,iproc-ahci"
- - "hisilicon,hisi-ahci"
- - "cavium,octeon-7130-ahci"
- - "ibm,476gtr-ahci"
- - "marvell,armada-380-ahci"
- - "marvell,armada-3700-ahci"
- - "snps,dwc-ahci"
- - "snps,spear-ahci"
- - "generic-ahci"
-- interrupts : <interrupt mapping for SATA IRQ>
-- reg : <registers mapping>
-
-Please note that when using "generic-ahci" you must also specify a SoC specific
-compatible:
- compatible = "manufacturer,soc-model-ahci", "generic-ahci";
-
-Optional properties:
-- dma-coherent : Present if dma operations are coherent
-- clocks : a list of phandle + clock specifier pairs
-- resets : a list of phandle + reset specifier pairs
-- target-supply : regulator for SATA target power
-- phy-supply : regulator for PHY power
-- phys : reference to the SATA PHY node
-- phy-names : must be "sata-phy"
-- ahci-supply : regulator for AHCI controller
-- ports-implemented : Mask that indicates which ports that the HBA supports
- are available for software to use. Useful if PORTS_IMPL
- is not programmed by the BIOS, which is true with
- some embedded SOC's.
-
-Required properties when using sub-nodes:
-- #address-cells : number of cells to encode an address
-- #size-cells : number of cells representing the size of an address
-
-Sub-nodes required properties:
-- reg : the port number
-And at least one of the following properties:
-- phys : reference to the SATA PHY node
-- target-supply : regulator for SATA target power
-
-Examples:
- sata@ffe08000 {
- compatible = "snps,spear-ahci";
- reg = <0xffe08000 0x1000>;
- interrupts = <115>;
- };
-
-With sub-nodes:
- sata@f7e90000 {
- compatible = "marvell,berlin2q-achi", "generic-ahci";
- reg = <0xe90000 0x1000>;
- interrupts = <GIC_SPI 7 IRQ_TYPE_LEVEL_HIGH>;
- clocks = <&chip CLKID_SATA>;
- #address-cells = <1>;
- #size-cells = <0>;
-
- sata0: sata-port@0 {
- reg = <0>;
- phys = <&sata_phy 0>;
- target-supply = <&reg_sata0>;
- };
-
- sata1: sata-port@1 {
- reg = <1>;
- phys = <&sata_phy 1>;
- target-supply = <&reg_sata1>;;
- };
- };
diff --git a/Documentation/devicetree/bindings/ata/ahci-platform.yaml b/Documentation/devicetree/bindings/ata/ahci-platform.yaml
new file mode 100644
index 000000000000..fae042539824
--- /dev/null
+++ b/Documentation/devicetree/bindings/ata/ahci-platform.yaml
@@ -0,0 +1,163 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/ata/ahci-platform.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: AHCI SATA Controller
+
+description: |
+ SATA nodes are defined to describe on-chip Serial ATA controllers.
+ Each SATA controller should have its own node.
+
+ It is possible, but not required, to represent each port as a sub-node.
+ It allows to enable each port independently when dealing with multiple
+ PHYs.
+
+maintainers:
+ - Hans de Goede <hdegoede@xxxxxxxxxx>
+ - Jens Axboe <axboe@xxxxxxxxx>
+
+allOf:
+ - $ref: "sata-common.yaml#"
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - enum:
+ - brcm,iproc-ahci
+ - marvell,armada-8k-ahci
+ - marvell,berlin2q-ahci
+ - const: generic-ahci
+ - enum:
+ - cavium,octeon-7130-ahci
+ - hisilicon,hisi-ahci
+ - ibm,476gtr-ahci
+ - marvell,armada-3700-ahci
+ - marvell,armada-380-ahci
+ - snps,dwc-ahci
+ - snps,spear-ahci
+
+ reg:
+ maxItems: 1
+
+ reg-names:
+ maxItems: 1
+
+ clocks:
+ description:
+ Clock IDs array as required by the controller.
+ minItems: 1
+ maxItems: 3
+
+ clock-names:
+ description:
+ Names of clocks corresponding to IDs in the clock property.
+ minItems: 1
+ maxItems: 3
+
+ interrupts:
+ maxItems: 1
+
+ ahci-supply:
+ description:
+ regulator for AHCI controller
+
+ dma-coherent: true
+
+ phy-supply:
+ description:
+ regulator for PHY power
+
+ phys:
+ description:
+ List of all PHYs on this controller
+ maxItems: 1
+
+ phy-names:
+ description:
+ Name specifier for the PHYs
+ maxItems: 1
+
+ ports-implemented:
+ $ref: '/schemas/types.yaml#/definitions/uint32'
+ description: |
+ Mask that indicates which ports that the HBA supports
+ are available for software to use. Useful if PORTS_IMPL
+ is not programmed by the BIOS, which is true with
+ some embedded SoCs.
+ maximum: 0x1
+
+ resets:
+ maxItems: 1
+
+ target-supply:
+ description:
+ regulator for SATA target power
+
+required:
+ - compatible
+ - reg
+ - interrupts
+
+patternProperties:
+ "^sata-port@[0-9a-f]+$":
+ type: object
+ additionalProperties: false
+ description:
+ Subnode with configuration of the Ports.
+
+ properties:
+ reg:
+ maxItems: 1
+
+ phys:
+ maxItems: 1
+
+ phy-names:
+ maxItems: 1
+
+ target-supply:
+ description:
+ regulator for SATA target power
+
+ required:
+ - reg
+
+ anyOf:
+ - required: [ phys ]
+ - required: [ target-supply ]
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ sata@ffe08000 {
+ compatible = "snps,spear-ahci";
+ reg = <0xffe08000 0x1000>;
+ interrupts = <115>;
+ };
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/clock/berlin2q.h>
+ sata@f7e90000 {
+ compatible = "marvell,berlin2q-ahci", "generic-ahci";
+ reg = <0xf7e90000 0x1000>;
+ interrupts = <GIC_SPI 7 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&chip CLKID_SATA>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ sata0: sata-port@0 {
+ reg = <0>;
+ phys = <&sata_phy 0>;
+ target-supply = <&reg_sata0>;
+ };
+
+ sata1: sata-port@1 {
+ reg = <1>;
+ phys = <&sata_phy 1>;
+ target-supply = <&reg_sata1>;
+ };
+ };
--
2.25.1