[PATCH v6] dt-bindings: arm: keystone: add boot_* mboxes to ti,sci

[PATCH v6] dt-bindings: arm: keystone: add boot_* mboxes to ti,sci

[Anshul Dalal]

The bootloader on K3 devices makes use of mailboxes as per the ROM spec
which might be different than one's available to the kernel (firmware
spec).

Therefore, this patch adds the missing mailbox entries to the DT binding
if the matching compatible is ti,am654-sci to represent the mailboxes
exposed by the hardware during boot for the purpose of loading the
firmware.

The new ti,am642-sci compatible is also added to represent SoCs which do
not expose a "notify" channel as part of their TI-SCI spec such as AM64x
or the AM62 family. The newly added mboxes are made optional by keeping
minItems as 2 to remain compliant with existing device-trees.

Signed-off-by: Anshul Dalal <anshuld@ti.com>
---
Changes in v6:
- Added ti,am642-sci compatible to represent SoCs without a "notify" channel
- Added new examples instead of editing existing ones
- Link to v5: https://lore.kernel.org/r/20251215-k3_syscon_add_boot_mailboxes-v5-1-5a8fe567fd31@ti.com

Changes in v5:
- Added commit description for the optional mailboxes
- Link to v4: https://lore.kernel.org/r/20251205-k3_syscon_add_boot_mailboxes-v4-1-8e216fb88941@ti.com

Changes in v4:
- Make new boot_* mboxes conditional on ti,am654-sci compatible
- Link to v3: https://lore.kernel.org/r/20251112-k3_syscon_add_boot_mailboxes-v3-1-66155a4236dc@ti.com

Changes in v3:
- Drop [1/2] of the last patch series
- Update existing example with boot_* mailboxes instead of adding a new one
- Link to v2: https://lore.kernel.org/r/20251112-k3_syscon_add_boot_mailboxes-v2-0-aebc1e47b391@ti.com

Changes in v2:
- Remove maxItems entry
- Remove RFC tag from patch (added by mistake in v1)
- Document the new mailboxes in mboxes instead of mbox-names
- Provide example with all the mailboxes set
- Update commit title to have "ti,sci"
- Split into two patches
- Link to v1: https://lore.kernel.org/r/20251111-k3_syscon_add_boot_mailboxes-v1-1-529a27f21076@ti.com
---
 .../devicetree/bindings/arm/keystone/ti,sci.yaml   | 94 +++++++++++++++++++++-
 1 file changed, 91 insertions(+), 3 deletions(-)

diff --git a/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml b/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml
index 25a2b42105e5..0f2c764eae5a 100644
--- a/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml
+++ b/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml
@@ -40,6 +40,9 @@ properties:
       - description: System controller on TI AM654 SoC
         items:
           - const: ti,am654-sci
+      - description: System controller on TI AM642 SoC
+        items:
+          - const: ti,am642-sci
 
   reg-names:
     description: |
@@ -51,15 +54,15 @@ properties:
     minItems: 1
 
   mbox-names:
+    minItems: 2
+    maxItems: 6
     description: |
       Specifies the mailboxes used to communicate with TI-SCI Controller
       made available from TI-SCI controller.
-    items:
-      - const: rx
-      - const: tx
 
   mboxes:
     minItems: 2
+    maxItems: 6
 
   ti,host-id:
     $ref: /schemas/types.yaml#/definitions/uint32
@@ -79,6 +82,66 @@ properties:
     type: object
     $ref: /schemas/reset/ti,sci-reset.yaml#
 
+if:
+  properties:
+    compatible:
+      contains:
+        const: ti,am654-sci
+then:
+  properties:
+    mbox-names:
+      minItems: 2
+      items:
+        - const: rx
+        - const: tx
+        - const: notify
+        - const: boot_rx
+        - const: boot_tx
+        - const: boot_notify
+    mboxes:
+      minItems: 2
+      items:
+        - description: RX thread
+        - description: TX thread
+        - description: Notify thread
+        - description: boot stage RX thread
+        - description: boot stage TX thread
+        - description: boot stage Notify thread
+else:
+  if:
+    properties:
+      compatible:
+        contains:
+          const: ti,am642-sci
+  then:
+    properties:
+      mbox-names:
+        minItems: 2
+        items:
+          - const: rx
+          - const: tx
+          - const: boot_rx
+          - const: boot_tx
+          - const: boot_notify
+      mboxes:
+        minItems: 2
+        items:
+          - description: RX thread
+          - description: TX thread
+          - description: boot stage RX thread
+          - description: boot stage TX thread
+          - description: boot stage Notify thread
+  else:
+    properties:
+      mbox-names:
+        items:
+          - const: rx
+          - const: tx
+      mboxes:
+        items:
+          - description: RX thread
+          - description: TX thread
+
 required:
   - compatible
   - mbox-names
@@ -122,3 +185,28 @@ examples:
         #reset-cells = <2>;
       };
     };
+
+  - |
+    system-controller@44083000 {
+      compatible = "ti,am654-sci";
+      ti,host-id = <4>;
+      mbox-names = "rx", "tx", "notify", "boot_rx", "boot_tx";
+      mboxes = <&secure_proxy_mcu 6>, <&secure_proxy_mcu 8>,
+        <&secure_proxy_mcu 5>, <&secure_proxy_mcu 5>, <&secure_proxy_mcu 4>;
+
+      reg-names = "debug_messages";
+      reg = <0x44083000 0x1000>;
+    };
+
+  - |
+    system-controller@44083000 {
+      compatible = "ti,am642-sci";
+      ti,host-id = <35>;
+      mbox-names = "rx", "tx", "boot_rx", "boot_tx";
+      mboxes = <&secure_proxy_main 0>, <&secure_proxy_main 1>,
+        <&secure_proxy_main 0>, <&secure_proxy_main 1>;
+
+      reg-names = "debug_messages";
+      reg = <0x44083000 0x1000>;
+    };
+

---
base-commit: 4427259cc7f7571a157fbc9b5011e1ef6fe0a4a8
change-id: 20251105-k3_syscon_add_boot_mailboxes-8452bdd98962

Best regards,
-- 
Anshul Dalal <anshuld@ti.com>

Re: [PATCH v6] dt-bindings: arm: keystone: add boot_* mboxes to ti,sci

[Krzysztof Kozlowski]

On 22/12/2025 09:43, Anshul Dalal wrote:
> The bootloader on K3 devices makes use of mailboxes as per the ROM spec
> which might be different than one's available to the kernel (firmware
> spec).
> 
> Therefore, this patch adds the missing mailbox entries to the DT binding
> if the matching compatible is ti,am654-sci to represent the mailboxes
> exposed by the hardware during boot for the purpose of loading the
> firmware.
> 
> The new ti,am642-sci compatible is also added to represent SoCs which do
> not expose a "notify" channel as part of their TI-SCI spec such as AM64x
> or the AM62 family. The newly added mboxes are made optional by keeping
> minItems as 2 to remain compliant with existing device-trees.
> 
> Signed-off-by: Anshul Dalal <anshuld@ti.com>
> ---
> Changes in v6:
> - Added ti,am642-sci compatible to represent SoCs without a "notify" channel
> - Added new examples instead of editing existing ones

Why? Rob asked not to.

> - Link to v5: https://lore.kernel.org/r/20251215-k3_syscon_add_boot_mailboxes-v5-1-5a8fe567fd31@ti.com
> 
> Changes in v5:
> - Added commit description for the optional mailboxes
> - Link to v4: https://lore.kernel.org/r/20251205-k3_syscon_add_boot_mailboxes-v4-1-8e216fb88941@ti.com
> 
> Changes in v4:
> - Make new boot_* mboxes conditional on ti,am654-sci compatible
> - Link to v3: https://lore.kernel.org/r/20251112-k3_syscon_add_boot_mailboxes-v3-1-66155a4236dc@ti.com
> 
> Changes in v3:
> - Drop [1/2] of the last patch series
> - Update existing example with boot_* mailboxes instead of adding a new one
> - Link to v2: https://lore.kernel.org/r/20251112-k3_syscon_add_boot_mailboxes-v2-0-aebc1e47b391@ti.com
> 
> Changes in v2:
> - Remove maxItems entry
> - Remove RFC tag from patch (added by mistake in v1)
> - Document the new mailboxes in mboxes instead of mbox-names
> - Provide example with all the mailboxes set
> - Update commit title to have "ti,sci"
> - Split into two patches
> - Link to v1: https://lore.kernel.org/r/20251111-k3_syscon_add_boot_mailboxes-v1-1-529a27f21076@ti.com
> ---
>  .../devicetree/bindings/arm/keystone/ti,sci.yaml   | 94 +++++++++++++++++++++-
>  1 file changed, 91 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml b/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml
> index 25a2b42105e5..0f2c764eae5a 100644
> --- a/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml
> +++ b/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml
> @@ -40,6 +40,9 @@ properties:
>        - description: System controller on TI AM654 SoC
>          items:
>            - const: ti,am654-sci
> +      - description: System controller on TI AM642 SoC
> +        items:
> +          - const: ti,am642-sci

Why this is not part of enum with previous entries like that?

>  
>    reg-names:
>      description: |
> @@ -51,15 +54,15 @@ properties:
>      minItems: 1
>  
>    mbox-names:
> +    minItems: 2
> +    maxItems: 6
>      description: |
>        Specifies the mailboxes used to communicate with TI-SCI Controller
>        made available from TI-SCI controller.
> -    items:
> -      - const: rx
> -      - const: tx
>  
>    mboxes:
>      minItems: 2
> +    maxItems: 6
>  
>    ti,host-id:
>      $ref: /schemas/types.yaml#/definitions/uint32
> @@ -79,6 +82,66 @@ properties:
>      type: object
>      $ref: /schemas/reset/ti,sci-reset.yaml#
>  
> +if:
> +  properties:
> +    compatible:
> +      contains:
> +        const: ti,am654-sci
> +then:
> +  properties:
> +    mbox-names:
> +      minItems: 2
> +      items:
> +        - const: rx
> +        - const: tx
> +        - const: notify

Move the notify to the end, so you have only one common list defined at
the top and you only change number of items per variant.

> +        - const: boot_rx
> +        - const: boot_tx
> +        - const: boot_notify
> +    mboxes:
> +      minItems: 2
> +      items:
> +        - description: RX thread
> +        - description: TX thread
> +        - description: Notify thread
> +        - description: boot stage RX thread
> +        - description: boot stage TX thread
> +        - description: boot stage Notify thread
> +else:
> +  if:

No, that's not readable. Don't nest these.

> +    properties:
> +      compatible:
> +        contains:
> +          const: ti,am642-sci
> +  then:
> +    properties:
> +      mbox-names:
> +        minItems: 2
> +        items:
> +          - const: rx
> +          - const: tx
> +          - const: boot_rx
> +          - const: boot_tx
> +          - const: boot_notify
> +      mboxes:
> +        minItems: 2
> +        items:
> +          - description: RX thread
> +          - description: TX thread
> +          - description: boot stage RX thread
> +          - description: boot stage TX thread
> +          - description: boot stage Notify thread
> +  else:
> +    properties:
> +      mbox-names:
> +        items:
> +          - const: rx
> +          - const: tx
> +      mboxes:
> +        items:
> +          - description: RX thread
> +          - description: TX thread
> +
>  required:
>    - compatible
>    - mbox-names
> @@ -122,3 +185,28 @@ examples:
>          #reset-cells = <2>;
>        };
>      };
> +
> +  - |
> +    system-controller@44083000 {
> +      compatible = "ti,am654-sci";
> +      ti,host-id = <4>;
> +      mbox-names = "rx", "tx", "notify", "boot_rx", "boot_tx";
> +      mboxes = <&secure_proxy_mcu 6>, <&secure_proxy_mcu 8>,
> +        <&secure_proxy_mcu 5>, <&secure_proxy_mcu 5>, <&secure_proxy_mcu 4>;
> +
> +      reg-names = "debug_messages";
> +      reg = <0x44083000 0x1000>;
> +    };

You already have there two examples. You do not need three and for sure
you do not need four of which two are exactly the same. Rob already
commented on this.

Best regards,
Krzysztof

Re: [PATCH v6] dt-bindings: arm: keystone: add boot_* mboxes to ti,sci

[Anshul Dalal]

On Mon Dec 22, 2025 at 2:23 PM IST, Krzysztof Kozlowski wrote:
> On 22/12/2025 09:43, Anshul Dalal wrote:
>> The bootloader on K3 devices makes use of mailboxes as per the ROM spec
>> which might be different than one's available to the kernel (firmware
>> spec).
>> 
>> Therefore, this patch adds the missing mailbox entries to the DT binding
>> if the matching compatible is ti,am654-sci to represent the mailboxes
>> exposed by the hardware during boot for the purpose of loading the
>> firmware.
>> 
>> The new ti,am642-sci compatible is also added to represent SoCs which do
>> not expose a "notify" channel as part of their TI-SCI spec such as AM64x
>> or the AM62 family. The newly added mboxes are made optional by keeping
>> minItems as 2 to remain compliant with existing device-trees.
>> 
>> Signed-off-by: Anshul Dalal <anshuld@ti.com>
>> ---
>> Changes in v6:
>> - Added ti,am642-sci compatible to represent SoCs without a "notify" channel
>> - Added new examples instead of editing existing ones
>
> Why? Rob asked not to.

I had followed what Nishanth had said[1], I'll wait for him and Rob to
align first before posting the next revision.

[1]: https://lore.kernel.org/linux-devicetree/20251218190449.cnp46cf6hikt6cqa@freebie/

>
>> - Link to v5: https://lore.kernel.org/r/20251215-k3_syscon_add_boot_mailboxes-v5-1-5a8fe567fd31@ti.com
>> 
>> Changes in v5:
>> - Added commit description for the optional mailboxes
>> - Link to v4: https://lore.kernel.org/r/20251205-k3_syscon_add_boot_mailboxes-v4-1-8e216fb88941@ti.com
>> 
>> Changes in v4:
>> - Make new boot_* mboxes conditional on ti,am654-sci compatible
>> - Link to v3: https://lore.kernel.org/r/20251112-k3_syscon_add_boot_mailboxes-v3-1-66155a4236dc@ti.com
>> 
>> Changes in v3:
>> - Drop [1/2] of the last patch series
>> - Update existing example with boot_* mailboxes instead of adding a new one
>> - Link to v2: https://lore.kernel.org/r/20251112-k3_syscon_add_boot_mailboxes-v2-0-aebc1e47b391@ti.com
>> 
>> Changes in v2:
>> - Remove maxItems entry
>> - Remove RFC tag from patch (added by mistake in v1)
>> - Document the new mailboxes in mboxes instead of mbox-names
>> - Provide example with all the mailboxes set
>> - Update commit title to have "ti,sci"
>> - Split into two patches
>> - Link to v1: https://lore.kernel.org/r/20251111-k3_syscon_add_boot_mailboxes-v1-1-529a27f21076@ti.com
>> ---
>>  .../devicetree/bindings/arm/keystone/ti,sci.yaml   | 94 +++++++++++++++++++++-
>>  1 file changed, 91 insertions(+), 3 deletions(-)
>> 
>> diff --git a/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml b/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml
>> index 25a2b42105e5..0f2c764eae5a 100644
>> --- a/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml
>> +++ b/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml
>> @@ -40,6 +40,9 @@ properties:
>>        - description: System controller on TI AM654 SoC
>>          items:
>>            - const: ti,am654-sci
>> +      - description: System controller on TI AM642 SoC
>> +        items:
>> +          - const: ti,am642-sci
>
> Why this is not part of enum with previous entries like that?

Yes, I missed adding it. Will fixed in the next revision if the
compatible is still required.

>
>>  
>>    reg-names:
>>      description: |
>> @@ -51,15 +54,15 @@ properties:
>>      minItems: 1
>>  
>>    mbox-names:
>> +    minItems: 2
>> +    maxItems: 6
>>      description: |
>>        Specifies the mailboxes used to communicate with TI-SCI Controller
>>        made available from TI-SCI controller.
>> -    items:
>> -      - const: rx
>> -      - const: tx
>>  
>>    mboxes:
>>      minItems: 2
>> +    maxItems: 6
>>  
>>    ti,host-id:
>>      $ref: /schemas/types.yaml#/definitions/uint32
>> @@ -79,6 +82,66 @@ properties:
>>      type: object
>>      $ref: /schemas/reset/ti,sci-reset.yaml#
>>  
>> +if:
>> +  properties:
>> +    compatible:
>> +      contains:
>> +        const: ti,am654-sci
>> +then:
>> +  properties:
>> +    mbox-names:
>> +      minItems: 2
>> +      items:
>> +        - const: rx
>> +        - const: tx
>> +        - const: notify
>
> Move the notify to the end, so you have only one common list defined at
> the top and you only change number of items per variant.
>
>> +        - const: boot_rx
>> +        - const: boot_tx
>> +        - const: boot_notify
>> +    mboxes:
>> +      minItems: 2
>> +      items:
>> +        - description: RX thread
>> +        - description: TX thread
>> +        - description: Notify thread
>> +        - description: boot stage RX thread
>> +        - description: boot stage TX thread
>> +        - description: boot stage Notify thread
>> +else:
>> +  if:
>
> No, that's not readable. Don't nest these.
>

I agree, perhaps we should drop the new ti,am642-sci compatible and just
reorder the list for ti,am654-sci to: rx, tx, boot_rx, boot_tx,
notify, boot_notify with a minItems of 2 as Nishanth had suggested?

>> +    properties:
>> +      compatible:
>> +        contains:
>> +          const: ti,am642-sci
>> +  then:
>> +    properties:
>> +      mbox-names:
>> +        minItems: 2
>> +        items:
>> +          - const: rx
>> +          - const: tx
>> +          - const: boot_rx
>> +          - const: boot_tx
>> +          - const: boot_notify
>> +      mboxes:
>> +        minItems: 2
>> +        items:
>> +          - description: RX thread
>> +          - description: TX thread
>> +          - description: boot stage RX thread
>> +          - description: boot stage TX thread
>> +          - description: boot stage Notify thread
>> +  else:
>> +    properties:
>> +      mbox-names:
>> +        items:
>> +          - const: rx
>> +          - const: tx
>> +      mboxes:
>> +        items:
>> +          - description: RX thread
>> +          - description: TX thread
>> +
>>  required:
>>    - compatible
>>    - mbox-names
>> @@ -122,3 +185,28 @@ examples:
>>          #reset-cells = <2>;
>>        };
>>      };
>> +
>> +  - |
>> +    system-controller@44083000 {
>> +      compatible = "ti,am654-sci";
>> +      ti,host-id = <4>;
>> +      mbox-names = "rx", "tx", "notify", "boot_rx", "boot_tx";
>> +      mboxes = <&secure_proxy_mcu 6>, <&secure_proxy_mcu 8>,
>> +        <&secure_proxy_mcu 5>, <&secure_proxy_mcu 5>, <&secure_proxy_mcu 4>;
>> +
>> +      reg-names = "debug_messages";
>> +      reg = <0x44083000 0x1000>;
>> +    };
>
> You already have there two examples. You do not need three and for sure
> you do not need four of which two are exactly the same. Rob already
> commented on this.

I can edit the existing example instead if Rob and Nishanth are aligned.

Regards,
Anshul

Re: [PATCH v6] dt-bindings: arm: keystone: add boot_* mboxes to ti,sci

[Krzysztof Kozlowski]

On 23/12/2025 09:44, Anshul Dalal wrote:
> On Mon Dec 22, 2025 at 2:23 PM IST, Krzysztof Kozlowski wrote:
>> On 22/12/2025 09:43, Anshul Dalal wrote:
>>> The bootloader on K3 devices makes use of mailboxes as per the ROM spec
>>> which might be different than one's available to the kernel (firmware
>>> spec).
>>>
>>> Therefore, this patch adds the missing mailbox entries to the DT binding
>>> if the matching compatible is ti,am654-sci to represent the mailboxes
>>> exposed by the hardware during boot for the purpose of loading the
>>> firmware.
>>>
>>> The new ti,am642-sci compatible is also added to represent SoCs which do
>>> not expose a "notify" channel as part of their TI-SCI spec such as AM64x
>>> or the AM62 family. The newly added mboxes are made optional by keeping
>>> minItems as 2 to remain compliant with existing device-trees.
>>>
>>> Signed-off-by: Anshul Dalal <anshuld@ti.com>
>>> ---
>>> Changes in v6:
>>> - Added ti,am642-sci compatible to represent SoCs without a "notify" channel
>>> - Added new examples instead of editing existing ones
>>
>> Why? Rob asked not to.
> 
> I had followed what Nishanth had said[1], I'll wait for him and Rob to
> align first before posting the next revision.


Existing examples are fine. There is no rule saying you need to keep
updating examples or keep adding new device to examples. If someone told
you about such rule, tell them to stop inventing rules...

Best regards,
Krzysztof

Re: [PATCH v6] dt-bindings: arm: keystone: add boot_* mboxes to ti,sci

[Nishanth Menon]

Anshul,

On 14:40-20251223, Krzysztof Kozlowski wrote:
> On 23/12/2025 09:44, Anshul Dalal wrote:
> > On Mon Dec 22, 2025 at 2:23 PM IST, Krzysztof Kozlowski wrote:
> >> On 22/12/2025 09:43, Anshul Dalal wrote:
> >>> The bootloader on K3 devices makes use of mailboxes as per the ROM spec
> >>> which might be different than one's available to the kernel (firmware
> >>> spec).
> >>>
> >>> Therefore, this patch adds the missing mailbox entries to the DT binding
> >>> if the matching compatible is ti,am654-sci to represent the mailboxes
> >>> exposed by the hardware during boot for the purpose of loading the
> >>> firmware.
> >>>
> >>> The new ti,am642-sci compatible is also added to represent SoCs which do
> >>> not expose a "notify" channel as part of their TI-SCI spec such as AM64x
> >>> or the AM62 family. The newly added mboxes are made optional by keeping
> >>> minItems as 2 to remain compliant with existing device-trees.
> >>>
> >>> Signed-off-by: Anshul Dalal <anshuld@ti.com>
> >>> ---
> >>> Changes in v6:
> >>> - Added ti,am642-sci compatible to represent SoCs without a "notify" channel
> >>> - Added new examples instead of editing existing ones
> >>
> >> Why? Rob asked not to.
> > 
> > I had followed what Nishanth had said[1], I'll wait for him and Rob to
> > align first before posting the next revision.
> 
> 
> Existing examples are fine. There is no rule saying you need to keep
> updating examples or keep adding new device to examples. If someone told
> you about such rule, tell them to stop inventing rules...

As I had responded to Rob (the reference you posted), leave the
existing example in the binding as is, we do not need to add new
examples either for each of the compatibles. We have enough examples
in device tree now. So, IMHO, just update the binding.

-- 
Regards,
Nishanth Menon
Key (0xDDB5849D1736249D) / Fingerprint: F8A2 8693 54EB 8232 17A3  1A34 DDB5 849D 1736 249D
https://ti.com/opensource