[PATCH v2 0/2] dt-bindings: arm: keystone: ti,sci: add entries for boot mboxes

[PATCH v2 0/2] dt-bindings: arm: keystone: ti,sci: add entries for boot mboxes

[Anshul Dalal]

K3 devices use the system controller HW block to run the TIFS firmware,
currently we document the RX and TX channels only however before the
firmware is loaded, a different set of  mailboxes are required to load
firmware to the HW block.

This patch set documents the missing mailboxes in the binding.

Signed-off-by: Anshul Dalal <anshuld@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

---
Anshul Dalal (2):
      dt-bindings: arm: keystone: add missing items to mboxes
      dt-bindings: arm: keystone: add boot_* mboxes to ti,sci

 .../devicetree/bindings/arm/keystone/ti,sci.yaml   | 26 ++++++++++++++++++++++
 1 file changed, 26 insertions(+)
---
base-commit: 4427259cc7f7571a157fbc9b5011e1ef6fe0a4a8
change-id: 20251105-k3_syscon_add_boot_mailboxes-8452bdd98962

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

[PATCH v2 1/2] dt-bindings: arm: keystone: add missing items to mboxes

[Anshul Dalal]

The mailboxes for the ti,sci node were not documented, this patch adds
the description for the two channel entries as per TI-SCI spec[1].

[1]:
https://software-dl.ti.com/tisci/esd/latest/5_soc_doc/am65x/sec_proxy.html

Signed-off-by: Anshul Dalal <anshuld@ti.com>
---
 Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml b/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml
index 25a2b42105e541cb3c8ad12a0dfec1af038fa907..182915c34fc1429fb627ac44c99c0c76fdf28e0f 100644
--- a/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml
+++ b/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml
@@ -60,6 +60,12 @@ properties:
 
   mboxes:
     minItems: 2
+    description: |
+      List of phandles to mailbox channels used for receiving and transmitting
+      data from and to the TI-SCI Controller.
+    items:
+      - description: RX thread
+      - description: TX thread
 
   ti,host-id:
     $ref: /schemas/types.yaml#/definitions/uint32

-- 
2.51.0

[PATCH v2 2/2] 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>
---
 .../devicetree/bindings/arm/keystone/ti,sci.yaml     | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml b/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml
index 182915c34fc1429fb627ac44c99c0c76fdf28e0f..770d6bc7c8f83493e448c426cb8f785dd73e824d 100644
--- a/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml
+++ b/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml
@@ -51,12 +51,17 @@ 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
@@ -66,6 +71,10 @@ properties:
     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
@@ -128,3 +137,14 @@ examples:
         #reset-cells = <2>;
       };
     };
+
+  - |
+    sms: system-controller@44083000 {
+      compatible = "ti,am654-sci";
+      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 = <0x44083000 0x1000>;
+    };

-- 
2.51.0

Re: [PATCH v2 1/2] dt-bindings: arm: keystone: add missing items to mboxes

[Krzysztof Kozlowski]

On 12/11/2025 09:30, Anshul Dalal wrote:
> The mailboxes for the ti,sci node were not documented, this patch adds
> the description for the two channel entries as per TI-SCI spec[1].
> 
> [1]:
> https://software-dl.ti.com/tisci/esd/latest/5_soc_doc/am65x/sec_proxy.html
> 
> Signed-off-by: Anshul Dalal <anshuld@ti.com>
> ---
>  Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml | 6 ++++++
>  1 file changed, 6 insertions(+)
> 
> diff --git a/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml b/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml
> index 25a2b42105e541cb3c8ad12a0dfec1af038fa907..182915c34fc1429fb627ac44c99c0c76fdf28e0f 100644
> --- a/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml
> +++ b/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml
> @@ -60,6 +60,12 @@ properties:
>  
>    mboxes:
>      minItems: 2

That's wrong now.

> +    description: |
> +      List of phandles to mailbox channels used for receiving and transmitting

Drop, completely redundant. I don't understand why you added it.

> +      data from and to the TI-SCI Controller.

Best regards,
Krzysztof

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

[Krzysztof Kozlowski]

On 12/11/2025 09:30, Anshul Dalal wrote:
>    ti,host-id:
>      $ref: /schemas/types.yaml#/definitions/uint32
> @@ -128,3 +137,14 @@ examples:
>          #reset-cells = <2>;
>        };
>      };
> +
> +  - |
> +    sms: system-controller@44083000 {
> +      compatible = "ti,am654-sci";

I asked to update the example. THE example, existing example, not adding
new example or examples.

You claim in this patch that EVERY device has 6 mailboxes, so I do not
understand why you need new example.

Best regards,
Krzysztof

Re: [PATCH v2 1/2] dt-bindings: arm: keystone: add missing items to mboxes

[Rob Herring (Arm)]

On Wed, 12 Nov 2025 14:00:53 +0530, Anshul Dalal wrote:
> The mailboxes for the ti,sci node were not documented, this patch adds
> the description for the two channel entries as per TI-SCI spec[1].
> 
> [1]:
> https://software-dl.ti.com/tisci/esd/latest/5_soc_doc/am65x/sec_proxy.html
> 
> Signed-off-by: Anshul Dalal <anshuld@ti.com>
> ---
>  Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml | 6 ++++++
>  1 file changed, 6 insertions(+)
> 

My bot found errors running 'make dt_binding_check' on your patch:

yamllint warnings/errors:

dtschema/dtc warnings/errors:
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml: properties:mboxes: 'oneOf' conditional failed, one must be fixed:
	False schema does not allow 2
	[{'description': 'RX thread'}, {'description': 'TX thread'}] is too long
	[{'description': 'RX thread'}, {'description': 'TX thread'}] is too short
	1 was expected
	hint: "minItems" is only needed if less than the "items" list length
	from schema $id: http://devicetree.org/meta-schemas/items.yaml

doc reference errors (make refcheckdocs):

See https://patchwork.ozlabs.org/project/devicetree-bindings/patch/20251112-k3_syscon_add_boot_mailboxes-v2-1-aebc1e47b391@ti.com

The base for the series is generally the latest rc1. A different dependency
should be noted in *this* patch.

If you already ran 'make dt_binding_check' and didn't see the above
error(s), then make sure 'yamllint' is installed and dt-schema is up to
date:

pip3 install dtschema --upgrade

Please check and re-submit after running the above command yourself. Note
that DT_SCHEMA_FILES can be set to your schema file to speed up checking
your schema. However, it must be unset to test all examples with your schema.