[PATCH 6/7] dt-bindings: mailbox: goog-mba: Add goog-mba mailbox bindings
Douglas Anderson
dianders at chromium.org
Tue Jul 14 15:21:45 PDT 2026
Introduce bindings for the MailBox Array IP block present in Laguna
SoCs (AKA "lga", AKA "Google Tensor G5").
Signed-off-by: Douglas Anderson <dianders at chromium.org>
---
.../bindings/mailbox/google,mba.yaml | 216 ++++++++++++++++++
1 file changed, 216 insertions(+)
create mode 100644 Documentation/devicetree/bindings/mailbox/google,mba.yaml
diff --git a/Documentation/devicetree/bindings/mailbox/google,mba.yaml b/Documentation/devicetree/bindings/mailbox/google,mba.yaml
new file mode 100644
index 000000000000..6c4505a369e2
--- /dev/null
+++ b/Documentation/devicetree/bindings/mailbox/google,mba.yaml
@@ -0,0 +1,216 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+# Copyright 2025 Google LLC
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mailbox/google,mba.yaml#
+$schema: http://devicetree.org/meta-schemas/base.yaml#
+
+title: Google MailBox Array
+
+maintainers:
+ - Douglas Anderson <dianders at chromium.org>
+
+description: |
+ The Google MailBox Array (MBA) is an IP block in Google-designed SoCs
+ starting in Laguna (AKA "lga", AKA Google Tensor G5). In a typical SoC
+ that includes this IP block, there are a number of instances of the MBA
+ controller with each instance having slightly different hardware
+ parameters and intended for communication with a different remote
+ processor.
+
+ An MBA instance has a "host" that is defined as the processor "providing"
+ a "service". This is typically not the main Application Processor (AP) but
+ is instead some specialized co-processor in the SoC like the Central Power
+ Manager (CPM). A processor (like the AP) talking to the "host" of the MBA
+ is a "client" of the MBA. A given MBA instance only ever has one host, but
+ it may have several clients. For instance, the CPM (an MBA "host") may need
+ to send/receive mailbox messages not just from the AP but from other
+ processors in the SoC and each of these other processors can be "clients"
+ of the same MBA.
+
+ The "host" of an MBA instance has full access to everything in the MBA
+ instance. It can access its own private set of "host" MBA registers, the
+ "global" MBA registers (if they exist), and all of the "client" MBA
+ registers.
+
+ A "client" of an MBA instance has access to the "global" MBA registers (if
+ they exist) and one or more sets of "client" MBA registers.
+
+ These bindings are focused on describing the MBA from the point of view of
+ a single client.
+
+ As per above, a client may have access to several sets of MBA "client"
+ registers. Each set of "client" registers represents a logical mailbox
+ "channel". However, because each channel may have different configuration
+ parameters and a mailbox "channel" in typical usage means one of a number
+ of identical channels, each channel in a Google MailBox Array is typically
+ referred to as a full "mailbox" and the whole collection of mailboxes as
+ the "mailbox array".
+
+ Mailboxes in an MBA instance have these features:
+ * 1 to 256 32-bit words of shared memory.
+ * The ability for the client to ring the main doorbell of the host and be
+ notified when the host Acks the doorbell.
+ * The ability for the host to ring the main doorbell of the client and be
+ notified when the client Acks the doorbell.
+
+ Some mailboxes may also have the ability to have counted doorbells. This
+ means that the receiver of the doorbell can tell how many times it rung.
+ This is intended for implementing "queued" mailboxes. See below.
+
+ The MBA hardware doesn't have any specific directionality. That is to
+ say, both the host and the client have full read and write access to
+ their shared memory. All mailbox instances have doorbells going both from
+ the client to the host as well as the host to the client.
+
+ The mailboxes can only be used for communication if the host and client
+ both agree on conventions. These conventions are described in the
+ device tree as they describe how the remote firmware is expecting to
+ communicate.
+
+ Current known in-use conventions:
+ 1. An RX mailbox with payloads that are of a well-defined size.
+ On mailboxes of this type, the host is the only one to write shared
+ memory. After placing a fixed-size message in shared memory, it rings
+ the main doorbell of the client. The client reads the message and Acks
+ the doorbell.
+ 2. A TX mailbox with payloads that could vary in size.
+ On mailboxes of this type, the mailbox client is the only one to write
+ shared memory. The client always writes a payload to the start of shared
+ memory and rings the main host doorbell. The client then looks for the
+ host to Ack the doorbell. The clients of the mailbox have ways to know
+ the size of any given message.
+ 3. A half-duplex TX/RX mailbox. This is a mailbox that can switch between
+ convention #1 and #2 above. Since both sides write data to the start of
+ shared memory, the two sides must have some convention to know whose
+ turn it is to send a message.
+ 4. A "queued" RX mailbox with a payload of a well-defined size.
+ This type of mailbox is only possible if the MBA instance can count
+ doorbells. On mailboxes of this type, the host is the only one to write
+ shared memory. When the client doorbell rings, the client reads a
+ fixed-size from the next "slot" in shared memory and then updates its
+ internal state. The shared memory is treated as a circular queue.
+ 5. A "queued" TX mailbox with a payload of a well-defined size.
+ This type of mailbox is only possible if the MBA instance can count
+ doorbells. On mailboxes of this type, the mailbox client is the only one
+ to write shared memory. The shared memory is treated as a circular queue.
+ The client writes a fixed-sized payload to the next "slot" in the shared
+ memory (where the slot size is determined by the client's first transfer),
+ updates its internal state, and rings the host doorbell. The client can
+ keep writing more messages as long as the circular queue isn't full. The
+ client gets an interrupt when the host Acks a doorbell and can tell how
+ many doorbells still haven't been Acked.
+
+ Conventions will be supported with a small number of properties specified
+ for each mailbox.
+
+properties:
+ compatible:
+ items:
+ - enum:
+ - google,lga-mailbox-array
+ - const: google,mailbox-array
+
+ reg:
+ minItems: 1
+ items:
+ - description: Host registers (not accessible to client)
+ - description: Global registers (not present on newer IP blocks)
+
+ ranges: true
+
+ "#address-cells":
+ const: 1
+
+ "#size-cells":
+ const: 1
+
+patternProperties:
+ "^mailbox@[0-9a-f]+$":
+ type: object
+ description:
+ Each sub-node is a single-channel mailbox.
+
+ properties:
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+ "#mbox-cells":
+ const: 0
+
+ google,rx-payload-words:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ maximum: 256
+ default: 0
+ description:
+ The number of 32-bit words in each mailbox message from the remote
+ processor. May be 0 for doorbell-only. If not specified this is
+ assumed to be 0.
+
+ google,mba-queue-mode:
+ type: boolean
+ description:
+ The remote processor is expecting the shared memory to be treated
+ as a circular queue and that there may be several outstanding
+ messages at once. Only usable on instances with counted doorbell
+ interrupts.
+
+ required:
+ - reg
+ - interrupts
+ - "#mbox-cells"
+
+ additionalProperties: false
+
+required:
+ - compatible
+ - ranges
+ - reg
+ - "#address-cells"
+ - "#size-cells"
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/arm-gic.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ soc {
+ #address-cells = <2>;
+ #size-cells = <2>;
+
+ cpm_ap_ns_mba: mailbox-array at 5240000 {
+ compatible = "google,lga-mailbox-array", "google,mailbox-array";
+ reg = <0x0 0x05240000 0x0 0x00010000>,
+ <0x0 0x05250000 0x0 0x00010000>;
+ ranges = <0x0 0x0 0x05260000 0x00020000>;
+
+ #address-cells = <1>;
+ #size-cells = <1>;
+
+ cpm_ap_ns_req_mba_client_0: mailbox at 0 {
+ reg = <0x0000 0x1000>;
+ interrupts = <GIC_SPI 250 IRQ_TYPE_LEVEL_HIGH 0>;
+
+ #mbox-cells = <0>;
+
+ google,mba-queue-mode;
+ };
+
+ cpm_ap_ns_resp_mba_client_1: mailbox at 1000 {
+ reg = <0x1000 0x1000>;
+ interrupts = <GIC_SPI 251 IRQ_TYPE_LEVEL_HIGH 0>;
+
+ #mbox-cells = <0>;
+
+ google,rx-payload-words = <4>;
+ google,mba-queue-mode;
+ };
+ };
+ };
+
+...
--
2.55.0.141.g00534a21ce-goog
More information about the linux-arm-kernel
mailing list