Received-SPF: pass (google.com: domain of linux-kernel+bounces-192763-linux.lists.archive=gmail.com@vger.kernel.org designates 147.75.199.223 as permitted sender) client-ip=147.75.199.223;
From: Frank Li <Frank.Li@nxp.com>
To: krzk@kernel.org
Cc: Frank.Li@nxp.com,
	conor+dt@kernel.org,
	devicetree@vger.kernel.org,
	dmaengine@vger.kernel.org,
	imx@lists.linux.dev,
	krzk+dt@kernel.org,
	linux-kernel@vger.kernel.org,
	robh@kernel.org,
	vkoul@kernel.org
Subject: [PATCH v2 1/1] dt-bindings: fsl-qdma: Convert to yaml format
Date: Tue, 28 May 2024 12:37:34 -0400
Message-Id: <20240528163734.2471268-1-Frank.Li@nxp.com>
Content-Transfer-Encoding: 8bit
Content-Type: text/plain
Precedence: bulk
MIME-Version: 1.0
X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1
X-MS-Exchange-AntiSpam-MessageData-0:
	=?us-ascii?Q?7EiIHABd5d+P3XoSgMMXyW2awuB6A2AgmaH12hJclH8qA3aD9Vo8/N6g+7ty?=
 =?us-ascii?Q?tt/i3kObkCrPalBb40lbMnvTLDBWZEIgdjnTOK88uydEwRnQPT9LG8WrdfYK?=
 =?us-ascii?Q?yRdva0Piw7b3okZvxvR67voP23U+Me28nCWePbsfbluTwa1cgXkbjW4r6gtn?=
 =?us-ascii?Q?9jLgCf6keDJceKQHB3/0h1G4moqQyXvNnHyCr63GFvYJ8x+50Fa/qD/mfEIr?=
 =?us-ascii?Q?xjQ/xqVB1FjwqZwm10NfrOfd1aCl+dO4UHjBbJDToQ0nIzRgzqFm4y9fXcWa?=
 =?us-ascii?Q?o+06sDdUC0ws76Ocb1B7ivpjLF99Yy6GeOPY/HlRCJi/vGAkHCKXlpveKrIU?=
 =?us-ascii?Q?/NMxYF+I6CpH+tYFuaGXp4PZaDn/WDjJ+Dj/XsHPkBG8Yd3+E90JwidI+saR?=
 =?us-ascii?Q?7ducnvUdNWMsbFdz+u1SqOUP5xsXl0cIMP13v7Wd61ma6rLevjf1h0fd+ZDz?=
 =?us-ascii?Q?9pqOxsll0w0TU1/isoIg99oytP2N0+MFz7Z+LHUk1+yf8EOHLWO8UQFiCvJg?=
 =?us-ascii?Q?zWY3UJfNDB1LLhBzelWjVxKDN+k/4dDano+YcccCimc6INfchqKyswKbJl9A?=
 =?us-ascii?Q?1WC8MA+kgkfAkEaBm9vGLg0gSer7pOezxrE7+Kc33+NrOXi1nwTSTN4jT8Ln?=
 =?us-ascii?Q?AJujDZVVuqUo/pcL+DLTy0JxMaurwOuShtSGskKupVobFoYp57N4pdy5HpQP?=
 =?us-ascii?Q?71Efkz/xDzqTNw+7fN7gFSJyYjfqnT5QDgbfIpIqQ+ekpmy9d0+fB36aH8ZA?=
 =?us-ascii?Q?oVExQIzHktY5wlenQZQ7wXP6VqsDzhfUUYPfFTOCvpitEVd0H3sRgCDCfLQO?=
 =?us-ascii?Q?XvUC4X9gOeccwCD8LahTWKanZPCyFG4DiRWkFrSdSDJR7RxDQ1QG7e1CtQ7I?=
 =?us-ascii?Q?7qB2rMvsn+PbYRjJB8Cr51s+O++vJX66JgmcrjM/z42dQWT39pQy22f02HoE?=
 =?us-ascii?Q?9/+g44szGaXOBrQZbD7JwceGoiQBaBude7IEbIroNoRmIrIn37YsmaB00ASl?=
 =?us-ascii?Q?YDCvcnYjGOwyKeqxCnHEg14calGYN37b3G51dZzYhrDHhMj+FyF3XTAhLaPH?=
 =?us-ascii?Q?VBec6tYI2y1Y8zGeFq1ZstGOpEbKL0SyTKBEo5J5f6CFq644c/NMqYZGUZC3?=
 =?us-ascii?Q?04Y9VylhXsic5ihdfJXt13ZpgB2MvG10gv4sKnO5LvLYHQYaC/NEgK3lk+Yc?=
 =?us-ascii?Q?X/oTunmmXiKYMg4T4MQq2YjQjP80OkHTNighQ8KTWcV56EuCQqK+TGXaILG3?=
 =?us-ascii?Q?jc6rZS5kWYdr0wmaDNWkyTaRe48xL71JicuLjIIezytF2mw7XD/AG3OWlhZI?=
 =?us-ascii?Q?RV9kqfNm+k8HbNBbjm76/i0ABhPXjoD1Y6/BKVK5tjhmNP+f5ZMd1G9Uz6iW?=
 =?us-ascii?Q?1z/IyuX2MWfxrGfTfOPo/WD114i2pEtbdKh3ECcmOmAOgY8ozYmY7aEyRMP3?=
 =?us-ascii?Q?NL2XL93FQNMYpS65+KJB/Nf66/6VmkkKVSt2Cv9NiCjGLGsXE58gPkbmBMRF?=
 =?us-ascii?Q?jCj6rLm0s9h2asYUJaqDhn+nFNKxCrlo3q/B+moUs9sZmnC/0OWXESH2ryyC?=
 =?us-ascii?Q?RhL7Bzskp9yssd1u4tmob850esh77lwvWRnSXm5M?=
X-OriginatorOrg: nxp.com
X-MS-Exchange-CrossTenant-Network-Message-Id: dc41cd65-837f-46fd-5cd1-08dc7f34829e
X-MS-Exchange-CrossTenant-AuthSource: PAXPR04MB9642.eurprd04.prod.outlook.com
X-MS-Exchange-CrossTenant-AuthAs: Internal
X-MS-Exchange-CrossTenant-OriginalArrivalTime: 28 May 2024 16:37:48.7262
 (UTC)
X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted
X-MS-Exchange-CrossTenant-Id: 686ea1d3-bc2b-4c6f-a92c-d99c5c301635
X-MS-Exchange-CrossTenant-MailboxType: HOSTED
X-MS-Exchange-CrossTenant-UserPrincipalName: pdi33JhmOcd3f3mGSlAupx2eafAGMm9MN+jw63nRKjri8oiaVrQPMUBzP1UbJYZaf9KK5X9KKqnfVRaS/cWTXQ==
X-MS-Exchange-Transport-CrossTenantHeadersStamped: AM9PR04MB8416

Convert binding doc from txt to yaml.

Re-order interrupt-names to align example.
Add #dma-cell in example.
Change 'reg' in example to 32bit address.

Signed-off-by: Frank Li <Frank.Li@nxp.com>
---

Notes:
    Change from v1 to v2:
    - dma-channels's minimum and maximum
    - add Constraints for fsl,dma-queues
    - move unevaluatedProperties after allof
    - add interrupts contraints for ls1021.
    
    Pass dt_binding_check:
    
    make dt_binding_check DT_SCHEMA_FILES=fsl-qdma.yaml
      SCHEMA  Documentation/devicetree/bindings/processed-schema.json
      CHKDT   Documentation/devicetree/bindings
      LINT    Documentation/devicetree/bindings
      DTEX    Documentation/devicetree/bindings/dma/fsl-qdma.example.dts
      DTC_CHK Documentation/devicetree/bindings/dma/fsl-qdma.example.dtb

 .../devicetree/bindings/dma/fsl-qdma.txt      |  58 --------
 .../devicetree/bindings/dma/fsl-qdma.yaml     | 124 ++++++++++++++++++
 2 files changed, 124 insertions(+), 58 deletions(-)
 delete mode 100644 Documentation/devicetree/bindings/dma/fsl-qdma.txt
 create mode 100644 Documentation/devicetree/bindings/dma/fsl-qdma.yaml

diff --git a/Documentation/devicetree/bindings/dma/fsl-qdma.txt b/Documentation/devicetree/bindings/dma/fsl-qdma.txt
deleted file mode 100644
index da371c4d406ce..0000000000000
--- a/Documentation/devicetree/bindings/dma/fsl-qdma.txt
+++ /dev/null
@@ -1,58 +0,0 @@
-NXP Layerscape SoC qDMA Controller
-==================================
-
-This device follows the generic DMA bindings defined in dma/dma.txt.
-
-Required properties:
-
-- compatible:		Must be one of
-			 "fsl,ls1021a-qdma": for LS1021A Board
-			 "fsl,ls1028a-qdma": for LS1028A Board
-			 "fsl,ls1043a-qdma": for ls1043A Board
-			 "fsl,ls1046a-qdma": for ls1046A Board
-- reg:			Should contain the register's base address and length.
-- interrupts:		Should contain a reference to the interrupt used by this
-			device.
-- interrupt-names:	Should contain interrupt names:
-			 "qdma-queue0": the block0 interrupt
-			 "qdma-queue1": the block1 interrupt
-			 "qdma-queue2": the block2 interrupt
-			 "qdma-queue3": the block3 interrupt
-			 "qdma-error":  the error interrupt
-- fsl,dma-queues:	Should contain number of queues supported.
-- dma-channels:	Number of DMA channels supported
-- block-number:	the virtual block number
-- block-offset:	the offset of different virtual block
-- status-sizes:	status queue size of per virtual block
-- queue-sizes:		command queue size of per virtual block, the size number
-			based on queues
-
-Optional properties:
-
-- dma-channels:		Number of DMA channels supported by the controller.
-- big-endian:		If present registers and hardware scatter/gather descriptors
-			of the qDMA are implemented in big endian mode, otherwise in little
-			mode.
-
-Examples:
-
-	qdma: dma-controller@8390000 {
-			compatible = "fsl,ls1021a-qdma";
-			reg = <0x0 0x8388000 0x0 0x1000>, /* Controller regs */
-			      <0x0 0x8389000 0x0 0x1000>, /* Status regs */
-			      <0x0 0x838a000 0x0 0x2000>; /* Block regs */
-			interrupts = <GIC_SPI 185 IRQ_TYPE_LEVEL_HIGH>,
-				     <GIC_SPI 76 IRQ_TYPE_LEVEL_HIGH>,
-				     <GIC_SPI 77 IRQ_TYPE_LEVEL_HIGH>;
-			interrupt-names = "qdma-error",
-				"qdma-queue0", "qdma-queue1";
-			dma-channels = <8>;
-			block-number = <2>;
-			block-offset = <0x1000>;
-			fsl,dma-queues = <2>;
-			status-sizes = <64>;
-			queue-sizes = <64 64>;
-			big-endian;
-		};
-
-DMA clients must use the format described in dma/dma.txt file.
diff --git a/Documentation/devicetree/bindings/dma/fsl-qdma.yaml b/Documentation/devicetree/bindings/dma/fsl-qdma.yaml
new file mode 100644
index 0000000000000..1b689a2529c87
--- /dev/null
+++ b/Documentation/devicetree/bindings/dma/fsl-qdma.yaml
@@ -0,0 +1,124 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/dma/fsl-qdma.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: NXP Layerscape SoC qDMA Controller
+
+maintainers:
+  - Frank Li <Frank.Li@nxp.com>
+
+properties:
+  compatible:
+    enum:
+      - fsl,ls1021a-qdma
+      - fsl,ls1028a-qdma
+      - fsl,ls1043a-qdma
+      - fsl,ls1046a-qdma
+
+  reg:
+    items:
+      - description: Controller regs
+      - description: Status regs
+      - description: Block regs
+
+  interrupts:
+    minItems: 2
+    maxItems: 5
+
+  interrupt-names:
+    minItems: 2
+    items:
+      - const: qdma-error
+      - const: qdma-queue0
+      - const: qdma-queue1
+      - const: qdma-queue2
+      - const: qdma-queue3
+
+  dma-channels:
+    minimum: 1
+    maximum: 64
+
+  fsl,dma-queues:
+    $ref: /schemas/types.yaml#/definitions/uint32
+    description: Should contain number of queues supported.
+    minimum: 1
+    maximum: 4
+
+  block-number:
+    $ref: /schemas/types.yaml#/definitions/uint32
+    description: the virtual block number
+
+  block-offset:
+    $ref: /schemas/types.yaml#/definitions/uint32
+    description: the offset of different virtual block
+
+  status-sizes:
+    $ref: /schemas/types.yaml#/definitions/uint32
+    description: status queue size of per virtual block
+
+  queue-sizes:
+    $ref: /schemas/types.yaml#/definitions/uint32-array
+    description:
+      command queue size of per virtual block, the size number
+      based on queues
+
+  big-endian:
+    $ref: /schemas/types.yaml#/definitions/flag
+    description:
+      If present registers and hardware scatter/gather descriptors
+      of the qDMA are implemented in big endian mode, otherwise in little
+      mode.
+
+required:
+  - compatible
+  - reg
+  - interrupts
+  - interrupt-names
+  - fsl,dma-queues
+  - block-number
+  - block-offset
+  - status-sizes
+  - queue-sizes
+
+allOf:
+  - $ref: dma-controller.yaml#
+  - if:
+      properties:
+        compatible:
+          contains:
+            enum:
+              - fsl,ls1021a-qdma
+    then:
+      properties:
+        interrupts:
+          maxItems: 3
+        interrupt-names:
+          maxItems: 3
+
+unevaluatedProperties: false
+
+examples:
+  - |
+    #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+    dma-controller@8390000 {
+        compatible = "fsl,ls1021a-qdma";
+        reg = <0x8388000 0x1000>, /* Controller regs */
+              <0x8389000 0x1000>, /* Status regs */
+              <0x838a000 0x2000>; /* Block regs */
+        interrupts = <GIC_SPI 185 IRQ_TYPE_LEVEL_HIGH>,
+                     <GIC_SPI 76 IRQ_TYPE_LEVEL_HIGH>,
+                     <GIC_SPI 77 IRQ_TYPE_LEVEL_HIGH>;
+        interrupt-names = "qdma-error", "qdma-queue0", "qdma-queue1";
+        #dma-cells = <1>;
+        dma-channels = <8>;
+        block-number = <2>;
+        block-offset = <0x1000>;
+        status-sizes = <64>;
+        queue-sizes = <64 64>;
+        big-endian;
+        fsl,dma-queues = <2>;
+    };
+
-- 
2.34.1