[RFC,v2,04/19] dt-bindings: firmware: thead,th1520: Add support for firmware node

Commit Message

Michal Wilczynski Dec. 23, 2024, 12:55 p.m. UTC

The kernel communicates with the E902 core through the mailbox
transport using AON firmware protocol. Add dt-bindings to document it
the dt node.

Signed-off-by: Michal Wilczynski <[e-mail]>
---
 .../bindings/firmware/thead,th1520-aon.yaml   | 59 +++++++++++++++++++
 MAINTAINERS                                   |  1 +
 2 files changed, 60 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/firmware/thead,th1520-aon.yaml

Comments

Krzysztof Kozlowski Dec. 23, 2024, 4:11 p.m. UTC | #1

On 23/12/2024 13:55, Michal Wilczynski wrote:
> The kernel communicates with the E902 core through the mailbox
> transport using AON firmware protocol. Add dt-bindings to document it
> the dt node.
> 
> Signed-off-by: Michal Wilczynski <[e-mail]>
> ---
>  .../bindings/firmware/thead,th1520-aon.yaml   | 59 +++++++++++++++++++
>  MAINTAINERS                                   |  1 +
>  2 files changed, 60 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/firmware/thead,th1520-aon.yaml
> 
> diff --git a/Documentation/devicetree/bindings/firmware/thead,th1520-aon.yaml b/Documentation/devicetree/bindings/firmware/thead,th1520-aon.yaml
> new file mode 100644
> index 000000000000..ca4c276766a3
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/firmware/thead,th1520-aon.yaml
> @@ -0,0 +1,59 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/firmware/thead,th1520-aon.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: T-HEAD TH1520 AON (Always-On) Firmware Node

Drop "Node", unless this is somehow name of device (not a DT node).

> +
> +description: |
> +  The Always-On (AON) subsystem in the TH1520 SoC is responsible for managing
> +  low-power states, system wakeup events, and power management tasks. It is
> +  designed to operate independently in a dedicated power domain, allowing it to
> +  remain functional even during the SoC's deep sleep states.
> +
> +  At the heart of the AON subsystem is the E902, a low-power core that executes
> +  firmware responsible for coordinating tasks such as power domain control,
> +  clock management, and system wakeup signaling. Communication between the main
> +  SoC and the AON subsystem is handled through a mailbox interface, which
> +  enables message-based interactions with the AON firmware.
> +
> +maintainers:
> +  - Michal Wilczynski <[e-mail]>
> +
> +properties:
> +  compatible:
> +    const: thead,th1520-aon
> +
> +  mboxes:
> +    maxItems: 1
> +
> +  mbox-names:
> +    items:
> +      - const: aon
> +
> +  power-domain:
> +    $ref: /schemas/power/thead,th1520-power.yaml#
> +    description: Subnode representing the hardware power domain of the AON subsystem.
> +
> +additionalProperties: false
> +
> +required:
> +  - compatible
> +  - mboxes
> +  - mbox-names

In all your bindings patches: "required" block goes before
additional/unevaluatedProperties. See also example-schema.

> +
> +examples:
> +  - |
> +    firmware {
> +        aon: aon {

Best regards,
Krzysztof

Patch

diff --git a/Documentation/devicetree/bindings/firmware/thead,th1520-aon.yaml b/Documentation/devicetree/bindings/firmware/thead,th1520-aon.yaml
new file mode 100644
index 000000000000..ca4c276766a3
--- /dev/null
+++ b/Documentation/devicetree/bindings/firmware/thead,th1520-aon.yaml
@@ -0,0 +1,59 @@ 
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/firmware/thead,th1520-aon.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: T-HEAD TH1520 AON (Always-On) Firmware Node
+
+description: |
+  The Always-On (AON) subsystem in the TH1520 SoC is responsible for managing
+  low-power states, system wakeup events, and power management tasks. It is
+  designed to operate independently in a dedicated power domain, allowing it to
+  remain functional even during the SoC's deep sleep states.
+
+  At the heart of the AON subsystem is the E902, a low-power core that executes
+  firmware responsible for coordinating tasks such as power domain control,
+  clock management, and system wakeup signaling. Communication between the main
+  SoC and the AON subsystem is handled through a mailbox interface, which
+  enables message-based interactions with the AON firmware.
+
+maintainers:
+  - Michal Wilczynski <[e-mail]>
+
+properties:
+  compatible:
+    const: thead,th1520-aon
+
+  mboxes:
+    maxItems: 1
+
+  mbox-names:
+    items:
+      - const: aon
+
+  power-domain:
+    $ref: /schemas/power/thead,th1520-power.yaml#
+    description: Subnode representing the hardware power domain of the AON subsystem.
+
+additionalProperties: false
+
+required:
+  - compatible
+  - mboxes
+  - mbox-names
+
+examples:
+  - |
+    firmware {
+        aon: aon {
+            compatible = "thead,th1520-aon";
+            mboxes = <&mbox_910t 1>;
+            mbox-names = "aon";
+
+            pd: power-domain {
+                compatible = "thead,th1520-pd";
+                #power-domain-cells = <1>;
+            };
+        };
+    };
diff --git a/MAINTAINERS b/MAINTAINERS
index c0e9639ac210..7705d1b6dd7a 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -20188,6 +20188,7 @@  M:	Fu Wei <[e-mail]>
 L:	[e-mail]
 S:	Maintained
 T:	git https://github.com/pdp7/linux.git
+F:	Documentation/devicetree/bindings/firmware/thead,th1520-aon.yaml
 F:	Documentation/devicetree/bindings/clock/thead,th1520-clk-ap.yaml
 F:	Documentation/devicetree/bindings/mailbox/thead,th1520-mbox.yaml
 F:	Documentation/devicetree/bindings/net/thead,th1520-gmac.yaml