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

[PATCH v5] 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 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 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   | 50 +++++++++++++++++++---
 1 file changed, 43 insertions(+), 7 deletions(-)

diff --git a/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml b/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml
index 25a2b42105e5..d9eb2a81e539 100644
--- a/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml
+++ b/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml
@@ -51,15 +51,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 +79,42 @@ 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:
+  properties:
+    mbox-names:
+      items:
+        - const: rx
+        - const: tx
+    mboxes:
+      items:
+        - description: RX thread
+        - description: TX thread
+
 required:
   - compatible
   - mbox-names
@@ -99,11 +135,11 @@ examples:
 
   - |
     dmsc: system-controller@44083000 {
-      compatible = "ti,k2g-sci";
+      compatible = "ti,am654-sci";
       ti,host-id = <12>;
-      mbox-names = "rx", "tx";
-      mboxes = <&secure_proxy_main 11>,
-               <&secure_proxy_main 13>;
+      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>;
 

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

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

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

[Nishanth Menon]

On 11:38-20251215, 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 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 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   | 50 +++++++++++++++++++---
>  1 file changed, 43 insertions(+), 7 deletions(-)
> 
> diff --git a/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml b/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml
> index 25a2b42105e5..d9eb2a81e539 100644
> --- a/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml
> +++ b/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml
> @@ -51,15 +51,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 +79,42 @@ 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:
> +  properties:
> +    mbox-names:
> +      items:
> +        - const: rx
> +        - const: tx
> +    mboxes:
> +      items:
> +        - description: RX thread
> +        - description: TX thread
> +
>  required:
>    - compatible
>    - mbox-names
> @@ -99,11 +135,11 @@ examples:
>  
>    - |
>      dmsc: system-controller@44083000 {
> -      compatible = "ti,k2g-sci";
> +      compatible = "ti,am654-sci";
>        ti,host-id = <12>;
> -      mbox-names = "rx", "tx";
> -      mboxes = <&secure_proxy_main 11>,
> -               <&secure_proxy_main 13>;
> +      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>;

Please add a different example for am654, i want to make sure k2g still
continues to be checked.

That said, AM62 series of devices do not use notification pipe for
standard communication. So, the schema will break for those.

in summary:
k2g: rx, tx
am654, j721e, j721s2, j7200, j784s4, .. : rx, tx, notify, boot_rx,
boot_tx, boot_notify
am625, am62p ..: rx, tx, boot_rx, boot_tx, boot_notify

we will need three examples, and will need to add am62x series as one
additional compatible.

Though we could play a trick by reordering as follows to handle superset
of am62 and am65 series as follows, but I do prefer explicitly handling
them:

   - const: rx
   - const: tx
   - const: boot_rx
   - const: boot_tx
   - const: notify
   - const: boot_notify


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

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

[Anshul Dalal]

> On 11:38-20251215, 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 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 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   | 50 +++++++++++++++++++---
>>  1 file changed, 43 insertions(+), 7 deletions(-)
>> 
>> diff --git a/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml b/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml
>> index 25a2b42105e5..d9eb2a81e539 100644
>> --- a/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml
>> +++ b/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml
>> @@ -51,15 +51,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 +79,42 @@ 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:
>> +  properties:
>> +    mbox-names:
>> +      items:
>> +        - const: rx
>> +        - const: tx
>> +    mboxes:
>> +      items:
>> +        - description: RX thread
>> +        - description: TX thread
>> +
>>  required:
>>    - compatible
>>    - mbox-names
>> @@ -99,11 +135,11 @@ examples:
>>  
>>    - |
>>      dmsc: system-controller@44083000 {
>> -      compatible = "ti,k2g-sci";
>> +      compatible = "ti,am654-sci";
>>        ti,host-id = <12>;
>> -      mbox-names = "rx", "tx";
>> -      mboxes = <&secure_proxy_main 11>,
>> -               <&secure_proxy_main 13>;
>> +      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>;
>
> Please add a different example for am654, i want to make sure k2g still
> continues to be checked.
>
> That said, AM62 series of devices do not use notification pipe for
> standard communication. So, the schema will break for those.
>
> in summary:
> k2g: rx, tx
> am654, j721e, j721s2, j7200, j784s4, .. : rx, tx, notify, boot_rx,
> boot_tx, boot_notify
> am625, am62p ..: rx, tx, boot_rx, boot_tx, boot_notify
>
> we will need three examples, and will need to add am62x series as one
> additional compatible.
>
> Though we could play a trick by reordering as follows to handle superset
> of am62 and am65 series as follows, but I do prefer explicitly handling
> them:
>
>    - const: rx
>    - const: tx
>    - const: boot_rx
>    - const: boot_tx
>    - const: notify
>    - const: boot_notify

I'm in favour of adding the new compatible for the AM62 devices and
handling the mboxes properly, let's fix it properly this time :)

Will post a v6 shortly,
~ Anshul

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

[Rob Herring]

On Mon, Dec 15, 2025 at 07:57:08AM -0600, Nishanth Menon wrote:
> On 11:38-20251215, 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 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 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   | 50 +++++++++++++++++++---
> >  1 file changed, 43 insertions(+), 7 deletions(-)
> > 
> > diff --git a/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml b/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml
> > index 25a2b42105e5..d9eb2a81e539 100644
> > --- a/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml
> > +++ b/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml
> > @@ -51,15 +51,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 +79,42 @@ 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:
> > +  properties:
> > +    mbox-names:
> > +      items:
> > +        - const: rx
> > +        - const: tx
> > +    mboxes:
> > +      items:
> > +        - description: RX thread
> > +        - description: TX thread
> > +
> >  required:
> >    - compatible
> >    - mbox-names
> > @@ -99,11 +135,11 @@ examples:
> >  
> >    - |
> >      dmsc: system-controller@44083000 {
> > -      compatible = "ti,k2g-sci";
> > +      compatible = "ti,am654-sci";
> >        ti,host-id = <12>;
> > -      mbox-names = "rx", "tx";
> > -      mboxes = <&secure_proxy_main 11>,
> > -               <&secure_proxy_main 13>;
> > +      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>;
> 
> Please add a different example for am654, i want to make sure k2g still
> continues to be checked.
> 
> That said, AM62 series of devices do not use notification pipe for
> standard communication. So, the schema will break for those.
> 
> in summary:
> k2g: rx, tx
> am654, j721e, j721s2, j7200, j784s4, .. : rx, tx, notify, boot_rx,
> boot_tx, boot_notify
> am625, am62p ..: rx, tx, boot_rx, boot_tx, boot_notify
> 
> we will need three examples, and will need to add am62x series as one
> additional compatible.

Do we really? We have a whole tree of examples in .dts files.

Rob

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

[Nishanth Menon]

On 06:57-20251217, Rob Herring wrote:
> > >    - |
> > >      dmsc: system-controller@44083000 {
> > > -      compatible = "ti,k2g-sci";
> > > +      compatible = "ti,am654-sci";
> > >        ti,host-id = <12>;
> > > -      mbox-names = "rx", "tx";
> > > -      mboxes = <&secure_proxy_main 11>,
> > > -               <&secure_proxy_main 13>;
> > > +      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>;
> > 
> > Please add a different example for am654, i want to make sure k2g still
> > continues to be checked.
> > 
> > That said, AM62 series of devices do not use notification pipe for
> > standard communication. So, the schema will break for those.
> > 
> > in summary:
> > k2g: rx, tx
> > am654, j721e, j721s2, j7200, j784s4, .. : rx, tx, notify, boot_rx,
> > boot_tx, boot_notify
> > am625, am62p ..: rx, tx, boot_rx, boot_tx, boot_notify
> > 
> > we will need three examples, and will need to add am62x series as one
> > additional compatible.
> 
> Do we really? We have a whole tree of examples in .dts files.

We do not. But, I would rather leave existing valid example as is rather
than modifying it for a new compatible that was just added.

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