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

[PATCH v3] 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
to represent the mailboxes exposed by the hardware during boot for the
purpose of loading the firmware.

Signed-off-by: Anshul Dalal <anshuld@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      | 19 ++++++++++++++++---
 1 file changed, 16 insertions(+), 3 deletions(-)

diff --git a/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml b/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml
index 25a2b42105e541cb3c8ad12a0dfec1af038fa907..be8a5b2b051b441884795059c70892910d981130 100644
--- a/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml
+++ b/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml
@@ -51,15 +51,27 @@ properties:
     minItems: 1
 
   mbox-names:
+    minItems: 2
     description: |
       Specifies the mailboxes used to communicate with TI-SCI Controller
       made available from TI-SCI controller.
     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
 
   ti,host-id:
     $ref: /schemas/types.yaml#/definitions/uint32
@@ -90,9 +102,10 @@ examples:
   - |
     pmmc: system-controller@2921800 {
       compatible = "ti,k2g-sci";
-      mbox-names = "rx", "tx";
-      mboxes = <&msgmgr 5 2>,
-               <&msgmgr 0 0>;
+      mbox-names = "rx", "tx", "notify", "boot_rx", "boot_tx", "boot_notify";
+      mboxes = <&secure_proxy_mcu 8>, <&secure_proxy_mcu 6>,
+        <&secure_proxy_mcu 5>, <&secure_proxy_mcu 4>,
+        <&secure_proxy_mcu 5>, <&secure_proxy_sa3 5>;
       reg-names = "debug_messages";
       reg = <0x02921800 0x800>;
     };

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

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

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

[Nishanth Menon]

On 15:54-20251112, 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
> to represent the mailboxes exposed by the hardware during boot for the
> purpose of loading the firmware.
> 
> Signed-off-by: Anshul Dalal <anshuld@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      | 19 ++++++++++++++++---
>  1 file changed, 16 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml b/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml
> index 25a2b42105e541cb3c8ad12a0dfec1af038fa907..be8a5b2b051b441884795059c70892910d981130 100644
> --- a/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml
> +++ b/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml
> @@ -51,15 +51,27 @@ properties:
>      minItems: 1
>  
>    mbox-names:
> +    minItems: 2
>      description: |
>        Specifies the mailboxes used to communicate with TI-SCI Controller
>        made available from TI-SCI controller.
>      items:
>        - const: rx
>        - const: tx
> +      - const: notify
> +      - const: boot_rx
> +      - const: boot_tx
> +      - const: boot_notify

Sorry for joining the party late.. just saw the thread while happening
to glance at the pending list..

k2g does not use boot_* mboxes, the load mechanism doesn't involve
ROM talking over mboxes, we load the pmmc on that SoC! ti,am654-sci
onwards does. This would be a good case for adding a conditional
property, IMHO. That said majority of the K3 dts entries still use
k2g-sci for k3 (#facepalm.. i should have caught it, but missed).. but
that cleanup is for follow on patches that could fix.. driver seems to
be able to handle the same.

>  
>    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
>  
>    ti,host-id:
>      $ref: /schemas/types.yaml#/definitions/uint32
> @@ -90,9 +102,10 @@ examples:
>    - |
>      pmmc: system-controller@2921800 {
>        compatible = "ti,k2g-sci";
> -      mbox-names = "rx", "tx";
> -      mboxes = <&msgmgr 5 2>,
> -               <&msgmgr 0 0>;
> +      mbox-names = "rx", "tx", "notify", "boot_rx", "boot_tx", "boot_notify";
> +      mboxes = <&secure_proxy_mcu 8>, <&secure_proxy_mcu 6>,
> +        <&secure_proxy_mcu 5>, <&secure_proxy_mcu 4>,
> +        <&secure_proxy_mcu 5>, <&secure_proxy_sa3 5>;


>        reg-names = "debug_messages";
>        reg = <0x02921800 0x800>;
>      };
> 
> ---
> base-commit: 4427259cc7f7571a157fbc9b5011e1ef6fe0a4a8
> change-id: 20251105-k3_syscon_add_boot_mailboxes-8452bdd98962
> 
> Best regards,
> -- 
> Anshul Dalal <anshuld@ti.com>
> 

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

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

[Anshul Dalal]

On Wed Nov 12, 2025 at 8:58 PM IST, Nishanth Menon wrote:
> On 15:54-20251112, 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
>> to represent the mailboxes exposed by the hardware during boot for the
>> purpose of loading the firmware.
>> 
>> Signed-off-by: Anshul Dalal <anshuld@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      | 19 ++++++++++++++++---
>>  1 file changed, 16 insertions(+), 3 deletions(-)
>> 
>> diff --git a/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml b/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml
>> index 25a2b42105e541cb3c8ad12a0dfec1af038fa907..be8a5b2b051b441884795059c70892910d981130 100644
>> --- a/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml
>> +++ b/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml
>> @@ -51,15 +51,27 @@ properties:
>>      minItems: 1
>>  
>>    mbox-names:
>> +    minItems: 2
>>      description: |
>>        Specifies the mailboxes used to communicate with TI-SCI Controller
>>        made available from TI-SCI controller.
>>      items:
>>        - const: rx
>>        - const: tx
>> +      - const: notify
>> +      - const: boot_rx
>> +      - const: boot_tx
>> +      - const: boot_notify
>
> Sorry for joining the party late.. just saw the thread while happening
> to glance at the pending list..
>
> k2g does not use boot_* mboxes, the load mechanism doesn't involve
> ROM talking over mboxes, we load the pmmc on that SoC! ti,am654-sci
> onwards does. This would be a good case for adding a conditional
> property, IMHO. That said majority of the K3 dts entries still use
> k2g-sci for k3 (#facepalm.. i should have caught it, but missed).. but
> that cleanup is for follow on patches that could fix.. driver seems to
> be able to handle the same.
>

Should we therefore have the new mboxes be conditional on "ti,am654-sci"
while k2g continues to use the existing "rx" and "tx" mboxes?

Something similar to:

	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:
	      maxItems: 2

With the top level mbox* having a minItems of 2 and max of 6.

Regards,
Anshul

>>  
>>    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
>>  
>>    ti,host-id:
>>      $ref: /schemas/types.yaml#/definitions/uint32
>> @@ -90,9 +102,10 @@ examples:
>>    - |
>>      pmmc: system-controller@2921800 {
>>        compatible = "ti,k2g-sci";
>> -      mbox-names = "rx", "tx";
>> -      mboxes = <&msgmgr 5 2>,
>> -               <&msgmgr 0 0>;
>> +      mbox-names = "rx", "tx", "notify", "boot_rx", "boot_tx", "boot_notify";
>> +      mboxes = <&secure_proxy_mcu 8>, <&secure_proxy_mcu 6>,
>> +        <&secure_proxy_mcu 5>, <&secure_proxy_mcu 4>,
>> +        <&secure_proxy_mcu 5>, <&secure_proxy_sa3 5>;
>
>
>>        reg-names = "debug_messages";
>>        reg = <0x02921800 0x800>;
>>      };
>> 
>> ---
>> base-commit: 4427259cc7f7571a157fbc9b5011e1ef6fe0a4a8
>> change-id: 20251105-k3_syscon_add_boot_mailboxes-8452bdd98962
>> 
>> Best regards,
>> -- 
>> Anshul Dalal <anshuld@ti.com>
>>