[PATCH] dt-bindings: sound: Convert TI OMAP2+ McBSP to DT schema

[PATCH] dt-bindings: sound: Convert TI OMAP2+ McBSP to DT schema

[Eduard Bostina]

Convert the Texas Instruments OMAP2+ McBSP (Multi-Channel Buffered
Serial Port) bindings to DT schema.

During the conversion, the following updates were made:
- Documented the 'clocks', 'clock-names', 'dmas', 'dma-names',
  '#sound-dai-cells' and 'port' properties, which are used by the
  boards but were missing from the old text binding.
- Added 'dma' to the 'reg-names' enum, which the boards use alongside
  'mpu' and 'sidetone'.
- Changed 'ti,hwmods' to a string array of up to two entries, as some
  boards pass both the base and sidetone hwmods.
- Made 'ti,hwmods' optional to resolve dtbs_check warnings. Modern OMAP
  platforms no longer provide this property, while older platforms still
  use it.
- Made 'ti,buffer-size' optional, as it only applies to OMAP2430 and
  newer SoCs.

Signed-off-by: Eduard Bostina <egbostina@gmail.com>
---
 .../devicetree/bindings/sound/omap-mcbsp.txt  |  36 -------
 .../bindings/sound/ti,omap2-mcbsp.yaml        | 101 ++++++++++++++++++
 2 files changed, 101 insertions(+), 36 deletions(-)
 delete mode 100644 Documentation/devicetree/bindings/sound/omap-mcbsp.txt
 create mode 100644 Documentation/devicetree/bindings/sound/ti,omap2-mcbsp.yaml

diff --git a/Documentation/devicetree/bindings/sound/omap-mcbsp.txt b/Documentation/devicetree/bindings/sound/omap-mcbsp.txt
deleted file mode 100644
index ae8bf703ce7a..000000000000
--- a/Documentation/devicetree/bindings/sound/omap-mcbsp.txt
+++ /dev/null
@@ -1,36 +0,0 @@
-* Texas Instruments OMAP2+ McBSP module
-
-Required properties:
-- compatible: "ti,omap2420-mcbsp" for McBSP on OMAP2420
-	      "ti,omap2430-mcbsp" for McBSP on OMAP2430
-	      "ti,omap3-mcbsp" for McBSP on OMAP3
-	      "ti,omap4-mcbsp" for McBSP on OMAP4 and newer SoC
-- reg: Register location and size, for OMAP4+ as an array:
-       <MPU access base address, size>,
-       <L3 interconnect address, size>;
-- reg-names: Array of strings associated with the address space
-- interrupts: Interrupt numbers for the McBSP port, as an array in case the
-	      McBSP IP have more interrupt lines:
-	<OCP compliant irq>,
-	<TX irq>,
-	<RX irq>;
-- interrupt-names: Array of strings associated with the interrupt numbers
-- ti,buffer-size: Size of the FIFO on the port (OMAP2430 and newer SoC)
-- ti,hwmods: Name of the hwmod associated to the McBSP port
-
-Example:
-
-mcbsp2: mcbsp@49022000 {
-	compatible = "ti,omap3-mcbsp";
-	reg = <0x49022000 0xff>,
-	      <0x49028000 0xff>;
-	reg-names = "mpu", "sidetone";
-	interrupts = <0 17 0x4>, /* OCP compliant interrupt */
-		     <0 62 0x4>, /* TX interrupt */
-		     <0 63 0x4>, /* RX interrupt */
-		     <0 4 0x4>;  /* Sidetone */
-	interrupt-names = "common", "tx", "rx", "sidetone";
-	interrupt-parent = <&intc>;
-	ti,buffer-size = <1280>;
-	ti,hwmods = "mcbsp2";
-};
diff --git a/Documentation/devicetree/bindings/sound/ti,omap2-mcbsp.yaml b/Documentation/devicetree/bindings/sound/ti,omap2-mcbsp.yaml
new file mode 100644
index 000000000000..17cd66460620
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/ti,omap2-mcbsp.yaml
@@ -0,0 +1,101 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/sound/ti,omap2-mcbsp.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Texas Instruments OMAP2+ McBSP
+
+maintainers:
+  - Eduard Bostina <egbostina@gmail.com>
+
+properties:
+  compatible:
+    enum:
+      - ti,omap2420-mcbsp
+      - ti,omap2430-mcbsp
+      - ti,omap3-mcbsp
+      - ti,omap4-mcbsp
+
+  reg:
+    minItems: 1
+    maxItems: 2
+    description: |
+      Register location and size. For OMAP4+ it may be an array containing:
+      - MPU access base address
+      - L3 interconnect address (or sidetone)
+
+  reg-names:
+    minItems: 1
+    maxItems: 2
+    items:
+      enum: [mpu, sidetone, dma]
+
+  interrupts:
+    minItems: 1
+    maxItems: 4
+
+  interrupt-names:
+    minItems: 1
+    maxItems: 4
+    items:
+      enum: [common, tx, rx, sidetone]
+
+  ti,buffer-size:
+    $ref: /schemas/types.yaml#/definitions/uint32
+    description: Size of the FIFO on the port (OMAP2430 and newer SoCs).
+
+  ti,hwmods:
+    $ref: /schemas/types.yaml#/definitions/string-array
+    minItems: 1
+    maxItems: 2
+    description: Name of the hwmod(s) associated with the McBSP port.
+
+  clocks:
+    minItems: 1
+    maxItems: 2
+
+  clock-names:
+    minItems: 1
+    maxItems: 2
+
+  dmas:
+    minItems: 1
+    maxItems: 2
+
+  dma-names:
+    minItems: 1
+    maxItems: 2
+
+  "#sound-dai-cells":
+    const: 0
+
+  port:
+    $ref: /schemas/sound/audio-graph-port.yaml#
+    unevaluatedProperties: false
+
+required:
+  - compatible
+  - reg
+  - reg-names
+  - interrupts
+  - interrupt-names
+
+additionalProperties: false
+
+examples:
+  - |
+    mcbsp@49022000 {
+        compatible = "ti,omap3-mcbsp";
+        reg = <0x49022000 0xff>,
+              <0x49028000 0xff>;
+        reg-names = "mpu", "sidetone";
+        interrupts = <0 17 0x4>, /* OCP compliant */
+                     <0 62 0x4>, /* TX */
+                     <0 63 0x4>, /* RX */
+                     <0 4 0x4>;  /* Sidetone */
+        interrupt-names = "common", "tx", "rx", "sidetone";
+        interrupt-parent = <&intc>;
+        ti,buffer-size = <1280>;
+        ti,hwmods = "mcbsp2";
+    };

-- 
2.43.0

Re: [PATCH] dt-bindings: sound: Convert TI OMAP2+ McBSP to DT schema

[sashiko-bot]

Thank you for your contribution! Sashiko AI review found 1 potential issue(s) to consider:
- [Low] The newly introduced device tree schema incorrectly restricts `interrupt-names`, causing validation failures for existing device trees.
--

--- Patch [1]: [PATCH] dt-bindings: sound: Convert TI OMAP2+ McBSP to DT schema ---
commit 76198b04e7315bea741fd54b86bf3bc924be8575
Author: Eduard Bostina <egbostina@gmail.com>

dt-bindings: sound: Convert TI OMAP2+ McBSP to DT schema

Convert the Texas Instruments OMAP2+ McBSP (Multi-Channel Buffered
Serial Port) bindings to DT schema.

> diff --git a/Documentation/devicetree/bindings/sound/ti,omap2-mcbsp.yaml b/Documentation/devicetree/bindings/sound/ti,omap2-mcbsp.yaml
> new file mode 100644
> index 0000000000000..17cd664606205
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/sound/ti,omap2-mcbsp.yaml

[ ... ]

> +  interrupts:
> +    minItems: 1
> +    maxItems: 4
> +
> +  interrupt-names:
> +    minItems: 1
> +    maxItems: 4
> +    items:
> +      enum: [common, tx, rx, sidetone]

[Severity: Low]
Does this enum incorrectly restrict the allowed interrupt names?

Looking at arch/arm/boot/dts/ti/omap/omap2430.dtsi, the mcbsp1 node 
legitimately uses an rx_overflow interrupt name:

			interrupt-names = "common", "tx", "rx", "rx_overflow";

Since rx_overflow is omitted from the allowed items in this binding, will
this cause dtbs_check validation failures for existing device trees?

-- 
Sashiko AI review · https://sashiko.dev/#/patchset/20260722171654.298557-1-egbostina@gmail.com?part=1