Updates the Device Tree bindings for Xilinx firmware by introducing
conditional schema references for the pinctrl node.

Previously, the pinctrl node directly referenced
xlnx,zynqmp-pinctrl.yaml. However, this patch modifies the schema to
conditionally apply the correct pinctrl schema based on the compatible
property. Specifically:
- If compatible contains "xlnx,zynqmp-pinctrl", reference
  xlnx,zynqmp-pinctrl.yaml.
- If compatible contains "xlnx,versal-pinctrl", reference
  xlnx,versal-pinctrl.yaml.

Additionally, an example entry for "xlnx,versal-pinctrl" has been
added under the examples section.

Signed-off-by: Ronak Jain <ronak.jain@amd.com>
---
Suggestion from Rob:

The somewhat preferred way to do this would be to do this in the top
level:

pinctrl:
  type: object
  additionalProperties: true
  properties:
    compatible:
      contains:
        enum:
          - xlnx,zynqmp-pinctrl
          - xlnx,versal-pinctrl
  required:
    - compatible

Otherwise, the pinctrl schema ends up being applied twice.


My response:

In your suggested code, the schema allows either xlnx,zynqmp-pinctrl
or xlnx,versal-pinctrl on any platform, which is incorrect. This
means that if a user mistakenly assigns xlnx,versal-pinctrl to a
ZynqMP platform or xlnx,zynqmp-pinctrl to a Versal platform, the
wrong reference will be used, but no error is reported. The
dt-binding check still passes instead of flagging this as an issue.

By using a conditional schema, we can enforce platform-specific
compatibility, ensuring that the correct compatible string is used
for the corresponding platform. This would also generate an error if
an incorrect compatible string is provided, preventing
misconfigurations.


Please review and let me know your thoughts.

---
 .../firmware/xilinx/xlnx,zynqmp-firmware.yaml | 20 ++++++++++++++++++-
 1 file changed, 19 insertions(+), 1 deletion(-)

diff --git a/Documentation/devicetree/bindings/firmware/xilinx/xlnx,zynqmp-firmware.yaml b/Documentation/devicetree/bindings/firmware/xilinx/xlnx,zynqmp-firmware.yaml
index 7020eeeb4ec0..c4a137f8e06e 100644
--- a/Documentation/devicetree/bindings/firmware/xilinx/xlnx,zynqmp-firmware.yaml
+++ b/Documentation/devicetree/bindings/firmware/xilinx/xlnx,zynqmp-firmware.yaml
@@ -79,7 +79,6 @@ properties:
     type: object
 
   pinctrl:
-    $ref: /schemas/pinctrl/xlnx,zynqmp-pinctrl.yaml#
     description: The pinctrl node provides access to pinconfig and pincontrol
       functionality available in firmware.
     type: object
@@ -114,6 +113,21 @@ properties:
     type: object
     deprecated: true
 
+allOf:
+  - if:
+      properties:
+        compatible:
+          contains:
+            const: xlnx,zynqmp-firmware
+    then:
+      properties:
+        pinctrl:
+          $ref: /schemas/pinctrl/xlnx,zynqmp-pinctrl.yaml#
+    else:
+      properties:
+        pinctrl:
+          $ref: /schemas/pinctrl/xlnx,versal-pinctrl.yaml#
+
 required:
   - compatible
 
@@ -172,6 +186,10 @@ examples:
         compatible = "xlnx,versal-fpga";
       };
 
+      pinctrl {
+        compatible = "xlnx,versal-pinctrl";
+      };
+
       xlnx_aes: zynqmp-aes {
         compatible = "xlnx,zynqmp-aes";
       };
-- 
2.34.1

On Fri, Dec 12, 2025 at 02:05:42AM -0800, Ronak Jain wrote:
> Updates the Device Tree bindings for Xilinx firmware by introducing
> conditional schema references for the pinctrl node.
> 
> Previously, the pinctrl node directly referenced
> xlnx,zynqmp-pinctrl.yaml. However, this patch modifies the schema to
> conditionally apply the correct pinctrl schema based on the compatible
> property. Specifically:
> - If compatible contains "xlnx,zynqmp-pinctrl", reference
>   xlnx,zynqmp-pinctrl.yaml.
> - If compatible contains "xlnx,versal-pinctrl", reference
>   xlnx,versal-pinctrl.yaml.
> 
> Additionally, an example entry for "xlnx,versal-pinctrl" has been
> added under the examples section.
> 
> Signed-off-by: Ronak Jain <ronak.jain@amd.com>
> ---
> Suggestion from Rob:
> 
> The somewhat preferred way to do this would be to do this in the top
> level:
> 
> pinctrl:
>   type: object
>   additionalProperties: true
>   properties:
>     compatible:
>       contains:
>         enum:
>           - xlnx,zynqmp-pinctrl
>           - xlnx,versal-pinctrl
>   required:
>     - compatible
> 
> Otherwise, the pinctrl schema ends up being applied twice.
> 
> 
> My response:
> 
> In your suggested code, the schema allows either xlnx,zynqmp-pinctrl
> or xlnx,versal-pinctrl on any platform, which is incorrect. This
> means that if a user mistakenly assigns xlnx,versal-pinctrl to a
> ZynqMP platform or xlnx,zynqmp-pinctrl to a Versal platform, the
> wrong reference will be used, but no error is reported. The
> dt-binding check still passes instead of flagging this as an issue.

True, but you can create a whole DT that's just random bindings from all 
sorts of different SoCs and the schema validation would be perfectly 
happy. We can't really ever check everything.

> By using a conditional schema, we can enforce platform-specific
> compatibility, ensuring that the correct compatible string is used
> for the corresponding platform. This would also generate an error if
> an incorrect compatible string is provided, preventing
> misconfigurations.

But what you have is fine too. It will validate the node twice as I 
pointed out and that slows things down some, but it's already slow...

Rob