* [PATCH v2 3/4] dt-bindings: mailbox: goog-mba: Add goog-mba mailbox bindings
2026-10-23 23:52 [PATCH v2 0/4] mailbox: Improve the mbox core then introduce the goog-mba driver Douglas Anderson
@ 2026-10-23 23:52 ` Douglas Anderson
2026-10-24 0:07 ` sashiko-bot
0 siblings, 1 reply; 3+ messages in thread
From: Douglas Anderson @ 2026-10-23 23:52 UTC (permalink / raw)
To: Jassi Brar
Cc: Joonwon Kang, Subhash Jadavani, Peter Griffin, Lucas Wei,
André Draszik, Tudor Ambarus, Krzysztof Kozlowski,
Brian Norris, Douglas Anderson, Conor Dooley, Krzysztof Kozlowski,
Rob Herring, devicetree, linux-arm-kernel, linux-kernel,
linux-samsung-soc
Introduce bindings for the MailBox Array IP block present in Laguna
SoCs (AKA "lga", AKA "Google Tensor G5").
Signed-off-by: Douglas Anderson <dianders@chromium.org>
---
Changes in v2:
- Rename binding file to google,lga-mailbox-array.yaml.
- Drop generic "google,mailbox-array" fallback compatible.
- Add "google,tx-payload-words" property for queue-mode TX message size.
- Remove unused labels in DT example.
.../mailbox/google,lga-mailbox-array.yaml | 226 ++++++++++++++++++
1 file changed, 226 insertions(+)
create mode 100644 Documentation/devicetree/bindings/mailbox/google,lga-mailbox-array.yaml
diff --git a/Documentation/devicetree/bindings/mailbox/google,lga-mailbox-array.yaml b/Documentation/devicetree/bindings/mailbox/google,lga-mailbox-array.yaml
new file mode 100644
index 000000000000..f265993fe71d
--- /dev/null
+++ b/Documentation/devicetree/bindings/mailbox/google,lga-mailbox-array.yaml
@@ -0,0 +1,226 @@
+# 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,lga-mailbox-array.yaml#
+$schema: http://devicetree.org/meta-schemas/base.yaml#
+
+title: Google MailBox Array
+
+maintainers:
+ - Douglas Anderson <dianders@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, 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:
+ const: google,lga-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,tx-payload-words:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ maximum: 256
+ default: 0
+ description:
+ For queue-mode only, the number of 32-bit words in each message we
+ send to the remote processor. If not specified, this is assumed to
+ be 0. This is only for queue mode where we need to divide up the
+ message buffer into chunks.
+
+ 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.
+
+ dependencies:
+ google,tx-payload-words: ['google,mba-queue-mode']
+
+ 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>;
+
+ mailbox-array@5240000 {
+ compatible = "google,lga-mailbox-array";
+ reg = <0x0 0x05240000 0x0 0x00010000>,
+ <0x0 0x05250000 0x0 0x00010000>;
+ ranges = <0x0 0x0 0x05260000 0x00020000>;
+
+ #address-cells = <1>;
+ #size-cells = <1>;
+
+ mailbox@0 {
+ reg = <0x0000 0x1000>;
+ interrupts = <GIC_SPI 250 IRQ_TYPE_LEVEL_HIGH 0>;
+
+ #mbox-cells = <0>;
+
+ google,tx-payload-words = <4>;
+ google,mba-queue-mode;
+ };
+
+ mailbox@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.56.0.257.gf7497c7d27-goog
^ permalink raw reply related [flat|nested] 3+ messages in thread