[PATCH 0/7] mailbox: Improve the mbox core then introduce the goog-mba driver

[PATCH 0/7] mailbox: Improve the mbox core then introduce the goog-mba driver

[Douglas Anderson]

The goal of this series is to land support for the goog-mba (MailBox
Array) IP block that's present in Pixel 10 phones.

As can be seen in the device-tree bindings for the goog-mba IP block,
the mailbox IP block in Pixel 10 phones is fairly sophisticated.
Notably:
* It has hardware features that support queuing, meaning that more
  than one mailbox message can be pending at a time.
* The "channels" in a given mailbox array aren't homogeneous. Each
  "channel" in the mailbox array can have a different amount of memory
  for messages. Really, the "channels" in a mailbox are considered to
  be full single-channel mailboxes and a grouping of mailboxes is
  considered a "mailbox array" (hence the IP block being named "mba")

In order to cleanly support some of the sophisticated goog-mba
features, improvements are made to the mailbox core. Specifically,
support for mailbox controllers that can queue is added and also
support for mailbox drivers that have more than one sub-node is added.

This is a fairly big rewrite from the downstream MBA driver shipping
on Pixel 10 phones, which awkwardly makes due without the improvements
to the mailbox core. It has been lightly tested both by porting it to
an experimental downstream tree based on 7.1 and also by running it
directly upstream against a stripped down Pixel 10 device tree.


Douglas Anderson (7):
  dt-bindings: mailbox: Don't require #mbox-cells to be 1
  mailbox: Allow #mbox-cells = <0> without specifying a custom xlate
  mailbox: Find a matching mailbox by fwnode rather than device
  mailbox: Simplify circular queue math with mod arithmetic
  mailbox: Add support for mailbox controllers that can queue
  dt-bindings: mailbox: goog-mba: Add goog-mba mailbox bindings
  mailbox: goog-mba: Introduce the goog-mba mailbox driver

 .../bindings/mailbox/google,mba.yaml          | 216 +++++++
 .../devicetree/bindings/mailbox/mailbox.txt   |   6 +-
 MAINTAINERS                                   |   8 +
 drivers/mailbox/Kconfig                       |   8 +
 drivers/mailbox/Makefile                      |   2 +
 drivers/mailbox/goog-mba-priv.h               | 108 ++++
 drivers/mailbox/goog-mba-trace.h              | 183 ++++++
 drivers/mailbox/goog-mba.c                    | 567 ++++++++++++++++++
 drivers/mailbox/mailbox.c                     |  84 ++-
 include/linux/mailbox/goog-mba-message.h      |  38 ++
 include/linux/mailbox_controller.h            |  15 +-
 11 files changed, 1209 insertions(+), 26 deletions(-)
 create mode 100644 Documentation/devicetree/bindings/mailbox/google,mba.yaml
 create mode 100644 drivers/mailbox/goog-mba-priv.h
 create mode 100644 drivers/mailbox/goog-mba-trace.h
 create mode 100644 drivers/mailbox/goog-mba.c
 create mode 100644 include/linux/mailbox/goog-mba-message.h

-- 
2.55.0.141.g00534a21ce-goog

[PATCH 1/7] dt-bindings: mailbox: Don't require #mbox-cells to be 1

[Douglas Anderson]

Existing mailboxes have #mbox-cells and this makes sense if a mailbox
only exposes one channel. Update the bindings to match.

Signed-off-by: Douglas Anderson <dianders@chromium.org>
---
I assume this is worth doing (?). As noted [1], mailbox bindings are
already in the core schema, so what's here just provides extra context
and descriptions.

[1] https://lore.kernel.org/all/20260322-mailbox-v1-1-c6251f18187c@gmail.com/

 Documentation/devicetree/bindings/mailbox/mailbox.txt | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/devicetree/bindings/mailbox/mailbox.txt b/Documentation/devicetree/bindings/mailbox/mailbox.txt
index af8ecee2ac68..f50727e9686f 100644
--- a/Documentation/devicetree/bindings/mailbox/mailbox.txt
+++ b/Documentation/devicetree/bindings/mailbox/mailbox.txt
@@ -6,8 +6,7 @@ assign appropriate mailbox channel to client drivers.
 * Mailbox Controller
 
 Required property:
-- #mbox-cells: Must be at least 1. Number of cells in a mailbox
-		specifier.
+- #mbox-cells: Number of cells in a mailbox specifier.
 
 Example:
 	mailbox: mailbox {
@@ -19,7 +18,8 @@ Example:
 * Mailbox Client
 
 Required property:
-- mboxes: List of phandle and mailbox channel specifiers.
+- mboxes: List of phandle and mailbox channel specifiers. If #mbox-cells is 0
+          then a mailbox only provides one channel and only a phandle is needed.
 
 Optional property:
 - mbox-names: List of identifier strings for each mailbox channel.
-- 
2.55.0.141.g00534a21ce-goog

[PATCH 6/7] dt-bindings: mailbox: goog-mba: Add goog-mba mailbox bindings

[Douglas Anderson]

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>
---

 .../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@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@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@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@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

Re: [PATCH 1/7] dt-bindings: mailbox: Don't require #mbox-cells to be 1

[sashiko-bot]

Thank you for your contribution! Sashiko AI review found 1 potential issue(s) to consider:
- [Low] The commit message contains a typo and is missing the value '0' after '#mbox-cells', making the sentence incomplete and confusing.
--

--- Patch [1]: [PATCH 1/7] dt-bindings: mailbox: Don't require #mbox-cells to be 1 ---
commit 6ada1cfb4e312b11f6e334039168356fbbe9bd88
Author: Douglas Anderson <dianders@chromium.org>

dt-bindings: mailbox: Don't require #mbox-cells to be 1

This commit updates the mailbox bindings to clarify that #mbox-cells does
not need to be strictly 1, allowing 0 when a mailbox only provides one
channel.

Link: https://lore.kernel.org/all/20260322-mailbox-v1-1-c6251f18187c@gmail.com/

> Existing mailboxes have #mbox-cells and this makes sense if a mailbox
> only exposes one channel. Update the bindings to match.

[Severity: Low]
This isn't a bug, but is this sentence missing the value 0 after #mbox-cells?
It currently reads as though the intended value was omitted, which makes the
description slightly confusing.

-- 
Sashiko AI review · https://sashiko.dev/#/patchset/20260714222338.2965707-1-dianders@chromium.org?part=1

Re: [PATCH 6/7] dt-bindings: mailbox: goog-mba: Add goog-mba mailbox bindings

[Krzysztof Kozlowski]

On 15/07/2026 00:21, Douglas Anderson wrote:
> 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>
> ---
> 
>  .../bindings/mailbox/google,mba.yaml          | 216 ++++++++++++++++++

Filename must match compatible.

>  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@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

Don't use generic fallback. Just the SoCs.


> +
> +  reg:
> +    minItems: 1
> +    items:
> +      - description: Host registers (not accessible to client)
> +      - description: Global registers (not present on newer IP blocks)

You have only one SoC. One SoC has only one IP block, no?

> +
> +  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.

This does not look like correct representation. You have one mailbox
controller with multiple mailboxes, not multiple mailbox controllers of
single channel boxes.


> +
> +    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@5240000 {

Drop all unused labels.


Best regards,
Krzysztof

Re: [PATCH 6/7] dt-bindings: mailbox: goog-mba: Add goog-mba mailbox bindings

[Doug Anderson]

Hi,

On Tue, Jul 14, 2026 at 9:51 PM Krzysztof Kozlowski <krzk@kernel.org> wrote:
>
> On 15/07/2026 00:21, Douglas Anderson wrote:
> > 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>
> > ---
> >
> >  .../bindings/mailbox/google,mba.yaml          | 216 ++++++++++++++++++
>
> Filename must match compatible.

Whoops! Will fix in v2.


> > +properties:
> > +  compatible:
> > +    items:
> > +      - enum:
> > +          - google,lga-mailbox-array
> > +      - const: google,mailbox-array
>
> Don't use generic fallback. Just the SoCs.

Sure, if you insist.

In general the "mba" hardware is designed with enough identification
registers that we should be able to autodetect which variant we're on.
Thus, my hope is to not ever need to reference the SoC-specific
variant in the driver itself. It's not the end of the world to use the
"google,lga-mailbox-array" as the generic, I guess...

I don't suppose I can change your mind here? If we take
"google,lga-mailbox-array" as the generic, then going foward a few
generations we end up with:

properties:
  compatible:
    oneOf:
      - const: google,lga-mailbox-array
      - items:
          - enum:
              - google,next-mailbox-array
              - google,nextnext-mailbox-array
              - google,another-mailbox-array
          - const: google,lga-mailbox-array

If we keep "google,mailbox-array" as the generic, then going forward a
few generations we end up with this, which seems nicer / less
confusing:

properties:
  compatible:
    items:
      - enum:
          - google,lga-mailbox-array
          - google,next-mailbox-array
          - google,nextnext-mailbox-array
          - google,another-mailbox-array
      - const: google,mailbox-array

Sure, it means that if someone unexpectedly makes a new Google
mailbox-array that's totally incompatible then the
"google,mailbox-array" sounds too generic, but that doesn't feel like
the end of the world. You could call the new mailbox array designed in
the year 2037 the "google,2037-mailbox-array" and things would overall
be less confusing than using the "google,lga-mailbox-array" as the
generic.


> > +  reg:
> > +    minItems: 1
> > +    items:
> > +      - description: Host registers (not accessible to client)
> > +      - description: Global registers (not present on newer IP blocks)
>
> You have only one SoC. One SoC has only one IP block, no?

Nope! There are several instances of the MBA IP block per SoC. I tried
to explain the situation exhaustively, but there's always the tradeoff
between explaining thoroughly and providing too much text.

To answer this specific question concretely, there is one MBA per
remote processor. Looking at the downstream DTS, I see at least these
MBA instances:
* AOC (Always On Compute)
* GSA (Google Security Anchor)
* GDMC (Google Debug Monitor Core)
* CPM (Central Power Manager)

Each of these 4 MBA instances has its own "global" registers.

To provide more context, each MBA instance can support communication
beyond just the AP (Apps Processor). For instance, the AOC's MBA
instance could be used to talk between the AOC and AP and also between
the AOC and CPM. Let's take this as an example. In this case:

* The AOC is the "host" of this MBA.
* The AP is a "client" of this MBA.
* The CPM is another "client" of this MBA.

The AOC is the only one with access to the "host" registers.

Everyone (AOC, AP, CPM in this case) has access to the read-only
"global" registers describing the MBA instance.

The clients have access to several banks of client registers, one per
mailbox they can access. The host (AOC in this case) also has access
to the client register spaces since that's where the shared message
memory is located.

The overall MBA instance is best identified by the address of the host
registers, even if the client (the AP in this case) can't access those
registers.

On newer versions of the IP block the "global" register bank was
removed and the read-only registers that were part of it were simply
copied to each client instance.

Does that clarify?


> > +
> > +  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.
>
> This does not look like correct representation. You have one mailbox
> controller with multiple mailboxes, not multiple mailbox controllers of
> single channel boxes.

I spent quite a bit of time debating this when rewriting the driver.
While we could certainly hack things into the existing "mailbox with a
bunch of channels", IMO it would be a worse representation of the
hardware.

I discussed this in the wall of text in this patch series, but
re-hashing it here:

Each "mailbox" in the mailbox array is more like a full-fledged
mailbox than a channel within a mailbox. Each (single-channel)
mailbox:
* Has its own client register space.
* Has its own interrupt.
* Can have a different amount of memory for messages.
* Can have its own conventions for communication.

If we tried to represent the mailbox array as a single mailbox with a
bunch of channels, each instance would have a different number of
"reg" entries and a different number of interrupts. We would also need
an array describing the communication conventions for each channel.
Can it be done? Yes. Is it ugly? Also, yes.

Further evidence that the hardware design intended "a bunch of
mailboxes" rather than "a mailbox with channels" is that the IP block
is called a "mailbox array". ;-)


> > +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@5240000 {
>
> Drop all unused labels.

Sounds good.

Re: [PATCH 6/7] dt-bindings: mailbox: goog-mba: Add goog-mba mailbox bindings

[Krzysztof Kozlowski]

On 15/07/2026 18:49, Doug Anderson wrote:
> Hi,
> 
> On Tue, Jul 14, 2026 at 9:51 PM Krzysztof Kozlowski <krzk@kernel.org> wrote:
>>
>> On 15/07/2026 00:21, Douglas Anderson wrote:
>>> 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>
>>> ---
>>>
>>>  .../bindings/mailbox/google,mba.yaml          | 216 ++++++++++++++++++
>>
>> Filename must match compatible.
> 
> Whoops! Will fix in v2.
> 
> 
>>> +properties:
>>> +  compatible:
>>> +    items:
>>> +      - enum:
>>> +          - google,lga-mailbox-array
>>> +      - const: google,mailbox-array
>>
>> Don't use generic fallback. Just the SoCs.
> 
> Sure, if you insist.
> 
> In general the "mba" hardware is designed with enough identification
> registers that we should be able to autodetect which variant we're on.
> Thus, my hope is to not ever need to reference the SoC-specific
> variant in the driver itself. It's not the end of the world to use the
> "google,lga-mailbox-array" as the generic, I guess...
> 
> I don't suppose I can change your mind here? If we take
> "google,lga-mailbox-array" as the generic, then going foward a few
> generations we end up with:
> 
> properties:
>   compatible:
>     oneOf:
>       - const: google,lga-mailbox-array
>       - items:
>           - enum:
>               - google,next-mailbox-array
>               - google,nextnext-mailbox-array
>               - google,another-mailbox-array
>           - const: google,lga-mailbox-array

This is the expected appriach.

> 
> If we keep "google,mailbox-array" as the generic, then going forward a
> few generations we end up with this, which seems nicer / less
> confusing:
> 
> properties:
>   compatible:
>     items:
>       - enum:
>           - google,lga-mailbox-array
>           - google,next-mailbox-array
>           - google,nextnext-mailbox-array
>           - google,another-mailbox-array
>       - const: google,mailbox-array

It is the discouraged approach. I already have a few real examples for
Qualcomm when people added such generic mailbox and after some time it
turned out not generic. So people wanted to add an another generic one...

> 
> Sure, it means that if someone unexpectedly makes a new Google
> mailbox-array that's totally incompatible then the
> "google,mailbox-array" sounds too generic, but that doesn't feel like
> the end of the world. You could call the new mailbox array designed in

And there is simple solution, just use SoC compatibles. Everything is
elegant, simple and accurate.

> the year 2037 the "google,2037-mailbox-array" and things would overall
> be less confusing than using the "google,lga-mailbox-array" as the
> generic.
> 
> 
>>> +  reg:
>>> +    minItems: 1
>>> +    items:
>>> +      - description: Host registers (not accessible to client)
>>> +      - description: Global registers (not present on newer IP blocks)
>>
>> You have only one SoC. One SoC has only one IP block, no?
> 
> Nope! There are several instances of the MBA IP block per SoC. I tried
> to explain the situation exhaustively, but there's always the tradeoff
> between explaining thoroughly and providing too much text.

That's ok, the "newer" is confusing.

> 
> To answer this specific question concretely, there is one MBA per
> remote processor. Looking at the downstream DTS, I see at least these
> MBA instances:
> * AOC (Always On Compute)
> * GSA (Google Security Anchor)
> * GDMC (Google Debug Monitor Core)
> * CPM (Central Power Manager)
> 
> Each of these 4 MBA instances has its own "global" registers.
> 
> To provide more context, each MBA instance can support communication
> beyond just the AP (Apps Processor). For instance, the AOC's MBA
> instance could be used to talk between the AOC and AP and also between
> the AOC and CPM. Let's take this as an example. In this case:
> 
> * The AOC is the "host" of this MBA.
> * The AP is a "client" of this MBA.
> * The CPM is another "client" of this MBA.
> 
> The AOC is the only one with access to the "host" registers.
> 
> Everyone (AOC, AP, CPM in this case) has access to the read-only
> "global" registers describing the MBA instance.
> 
> The clients have access to several banks of client registers, one per
> mailbox they can access. The host (AOC in this case) also has access
> to the client register spaces since that's where the shared message
> memory is located.
> 
> The overall MBA instance is best identified by the address of the host
> registers, even if the client (the AP in this case) can't access those
> registers.
> 
> On newer versions of the IP block the "global" register bank was
> removed and the read-only registers that were part of it were simply
> copied to each client instance.
> 
> Does that clarify?

Yeah, just s/on newer/on all/ ?

> 

> 
>>> +
>>> +  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.
>>
>> This does not look like correct representation. You have one mailbox
>> controller with multiple mailboxes, not multiple mailbox controllers of
>> single channel boxes.
> 
> I spent quite a bit of time debating this when rewriting the driver.
> While we could certainly hack things into the existing "mailbox with a
> bunch of channels", IMO it would be a worse representation of the
> hardware.
> 
> I discussed this in the wall of text in this patch series, but
> re-hashing it here:
> 
> Each "mailbox" in the mailbox array is more like a full-fledged
> mailbox than a channel within a mailbox. Each (single-channel)
> mailbox:
> * Has its own client register space.

That's nothing special yet. Many providers of multiple resources have
these resources in dedicated registers. Arguing this, each GPIO in a
GPIO controller as well has its own register space so is basically a
GPIO controller on its own.

> * Has its own interrupt.

Just like GPIOs...

> * Can have a different amount of memory for messages.
> * Can have its own conventions for communication.

Well, this could be. But you still have one child per channel (cells=0)
and all children address space is in parent's space, so that's clear
indication. It's one controller with multiple, although some different,
channels.

> 
> If we tried to represent the mailbox array as a single mailbox with a
> bunch of channels, each instance would have a different number of
> "reg" entries and a different number of interrupts. We would also need

No, you would have only one device node. Very clean solution instead of
100 children for each individual mailbox.

It's the same with clocks (TI) - you do not get device node per clock,
even if TI did it 10 years ago. You do not get here device node per channel.

> an array describing the communication conventions for each channel.
> Can it be done? Yes. Is it ugly? Also, yes.
> 
> Further evidence that the hardware design intended "a bunch of
> mailboxes" rather than "a mailbox with channels" is that the IP block
> is called a "mailbox array". ;-)
Best regards,
Krzysztof

Re: [PATCH 6/7] dt-bindings: mailbox: goog-mba: Add goog-mba mailbox bindings

[Doug Anderson]

Hi,

On Wed, Jul 15, 2026 at 10:47 PM Krzysztof Kozlowski <krzk@kernel.org> wrote:
>
> > I don't suppose I can change your mind here? If we take
> > "google,lga-mailbox-array" as the generic, then going foward a few
> > generations we end up with:
> >
> > properties:
> >   compatible:
> >     oneOf:
> >       - const: google,lga-mailbox-array
> >       - items:
> >           - enum:
> >               - google,next-mailbox-array
> >               - google,nextnext-mailbox-array
> >               - google,another-mailbox-array
> >           - const: google,lga-mailbox-array
>
> This is the expected appriach.
>
> >
> > If we keep "google,mailbox-array" as the generic, then going forward a
> > few generations we end up with this, which seems nicer / less
> > confusing:
> >
> > properties:
> >   compatible:
> >     items:
> >       - enum:
> >           - google,lga-mailbox-array
> >           - google,next-mailbox-array
> >           - google,nextnext-mailbox-array
> >           - google,another-mailbox-array
> >       - const: google,mailbox-array
>
> It is the discouraged approach. I already have a few real examples for
> Qualcomm when people added such generic mailbox and after some time it
> turned out not generic. So people wanted to add an another generic one...

OK, I'll change it to use "google,lga-mailbox-array" as the generic.


> >>> +  reg:
> >>> +    minItems: 1
> >>> +    items:
> >>> +      - description: Host registers (not accessible to client)
> >>> +      - description: Global registers (not present on newer IP blocks)
> >>
> >> You have only one SoC. One SoC has only one IP block, no?
> >
> > Nope! There are several instances of the MBA IP block per SoC. I tried
> > to explain the situation exhaustively, but there's always the tradeoff
> > between explaining thoroughly and providing too much text.
>
> That's ok, the "newer" is confusing.
>
> >
> > To answer this specific question concretely, there is one MBA per
> > remote processor. Looking at the downstream DTS, I see at least these
> > MBA instances:
> > * AOC (Always On Compute)
> > * GSA (Google Security Anchor)
> > * GDMC (Google Debug Monitor Core)
> > * CPM (Central Power Manager)
> >
> > Each of these 4 MBA instances has its own "global" registers.
> >
> > To provide more context, each MBA instance can support communication
> > beyond just the AP (Apps Processor). For instance, the AOC's MBA
> > instance could be used to talk between the AOC and AP and also between
> > the AOC and CPM. Let's take this as an example. In this case:
> >
> > * The AOC is the "host" of this MBA.
> > * The AP is a "client" of this MBA.
> > * The CPM is another "client" of this MBA.
> >
> > The AOC is the only one with access to the "host" registers.
> >
> > Everyone (AOC, AP, CPM in this case) has access to the read-only
> > "global" registers describing the MBA instance.
> >
> > The clients have access to several banks of client registers, one per
> > mailbox they can access. The host (AOC in this case) also has access
> > to the client register spaces since that's where the shared message
> > memory is located.
> >
> > The overall MBA instance is best identified by the address of the host
> > registers, even if the client (the AP in this case) can't access those
> > registers.
> >
> > On newer versions of the IP block the "global" register bank was
> > removed and the read-only registers that were part of it were simply
> > copied to each client instance.
> >
> > Does that clarify?
>
> Yeah, just s/on newer/on all/ ?

No. Although this driver only supports the "laguna" version of the
mailbox array, I tried to look forward to what was coming in the
future. On "laguna", the "global" register bank is needed. On SoCs
past "laguna" (AKA "newer" ones) there is no global register bank.
This is why the global register bank needs to be optional.

Yes, I could add some validation to tie it to a specific SoC version,
but that doesn't really buy anything. It's just as easy to say that if
the global register bank is defined in the device tree that it exists.
If the global register bank isn't defined, the info must be in the
per-client banks.

If you insist, I can make the "global" register space non-optional for
now and we can re-litigate when official support for newer SoCs is
proposed.


> >>> +patternProperties:
> >>> +  "^mailbox@[0-9a-f]+$":
> >>> +    type: object
> >>> +    description:
> >>> +      Each sub-node is a single-channel mailbox.
> >>
> >> This does not look like correct representation. You have one mailbox
> >> controller with multiple mailboxes, not multiple mailbox controllers of
> >> single channel boxes.
> >
> > I spent quite a bit of time debating this when rewriting the driver.
> > While we could certainly hack things into the existing "mailbox with a
> > bunch of channels", IMO it would be a worse representation of the
> > hardware.
> >
> > I discussed this in the wall of text in this patch series, but
> > re-hashing it here:
> >
> > Each "mailbox" in the mailbox array is more like a full-fledged
> > mailbox than a channel within a mailbox. Each (single-channel)
> > mailbox:
> > * Has its own client register space.
>
> That's nothing special yet. Many providers of multiple resources have
> these resources in dedicated registers. Arguing this, each GPIO in a
> GPIO controller as well has its own register space so is basically a
> GPIO controller on its own.
>
> > * Has its own interrupt.
>
> Just like GPIOs...

Sure, having a giant list of interrupts and register offsets isn't the
end of the world.


> > * Can have a different amount of memory for messages.
> > * Can have its own conventions for communication.

I notice you didn't respond to the above bullets. How would I deal
with different mailboxes in the array having different communication
conventions? Different mailboxes in the array might have different
"payload" sizes. Some mailboxes in the array might use "queue" mode
conventions and some might not. Do I need to devise some complex
scheme for describing which mailboxes in the array use which
convention?


> Well, this could be. But you still have one child per channel (cells=0)
> and all children address space is in parent's space, so that's clear
> indication. It's one controller with multiple, although some different,
> channels.

Sure, it's definitely one IP block and I'm not arguing against that.


> > If we tried to represent the mailbox array as a single mailbox with a
> > bunch of channels, each instance would have a different number of
> > "reg" entries and a different number of interrupts. We would also need
>
> No, you would have only one device node. Very clean solution instead of
> 100 children for each individual mailbox.

There are definitely not anywhere near 100 children. At most a given
instance of an MBA IP block could have 32 mailboxes. In practice, most
have fewer.


> It's the same with clocks (TI) - you do not get device node per clock,
> even if TI did it 10 years ago. You do not get here device node per channel.

Sure, the clock history is one thing to look at here. IMO, this is not
the right comparison, though. Trying to describe all of the complexity
of a clock tree in device tree is an exercise in futility. It's just
too complex to get it right, and there really are hundreds of clocks.
The mailbox array, on the other hand, is a much simpler beast.

I think regulators and PMICs are a better comparison here. When we
describe a PMIC in the device tree, do we have a single PMIC node and
then have clients refer to a "regulator ID" to index into which
specific regulator in the PMIC they want? No, we don't. We use
sub-nodes for each specific regulator. This gives us a nice place in
the device tree to put information about each individual regulator,
since each regulator in a PMIC is different.

Certainly if we had a mailbox controller with a bunch of identical
channels then describing them as sub-nodes wouldn't make sense.
Existing in-tree mailbox controllers have a bunch of homogenous
channels, and thus the existing solution of using a channel ID works
well. Here, the sub-nodes buy us something and provide for a cleaner
solution.

I don't understand the downside of my current proposal. It represents
the hardware better (both the HW designers' intentions and the reality
of its structure), avoids adding complexity to the device tree, and
feels clean.


-Doug

Re: [PATCH 1/7] dt-bindings: mailbox: Don't require #mbox-cells to be 1

[Rob Herring]

On Tue, Jul 14, 2026 at 03:21:40PM -0700, Douglas Anderson wrote:
> Existing mailboxes have #mbox-cells and this makes sense if a mailbox
> only exposes one channel. Update the bindings to match.
> 
> Signed-off-by: Douglas Anderson <dianders@chromium.org>
> ---
> I assume this is worth doing (?). As noted [1], mailbox bindings are
> already in the core schema, so what's here just provides extra context
> and descriptions.

We should update mbox-consumer.yaml and remove this file instead. 
There's only a couple of references to it.

We should either just add missing descriptions to mbox-consumer.yaml or 
change it to mbox.yaml and add #mbox-cells. The latter would only 
provide some completeness as we don't have any constraints 
on #mbox-cells (there's a global max of 8 already). 

Rob

Re: [PATCH 6/7] dt-bindings: mailbox: goog-mba: Add goog-mba mailbox bindings

[Rob Herring]

On Wed, Jul 15, 2026 at 09:49:14AM -0700, Doug Anderson wrote:
> Hi,
> 
> On Tue, Jul 14, 2026 at 9:51 PM Krzysztof Kozlowski <krzk@kernel.org> wrote:
> >
> > On 15/07/2026 00:21, Douglas Anderson wrote:
> > > 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>
> > > ---
> > >
> > >  .../bindings/mailbox/google,mba.yaml          | 216 ++++++++++++++++++
> >
> > Filename must match compatible.
> 
> Whoops! Will fix in v2.
> 
> 
> > > +properties:
> > > +  compatible:
> > > +    items:
> > > +      - enum:
> > > +          - google,lga-mailbox-array
> > > +      - const: google,mailbox-array
> >
> > Don't use generic fallback. Just the SoCs.
> 
> Sure, if you insist.
> 
> In general the "mba" hardware is designed with enough identification
> registers that we should be able to autodetect which variant we're on.
> Thus, my hope is to not ever need to reference the SoC-specific
> variant in the driver itself. It's not the end of the world to use the
> "google,lga-mailbox-array" as the generic, I guess...
> 
> I don't suppose I can change your mind here? If we take
> "google,lga-mailbox-array" as the generic, then going foward a few
> generations we end up with:
> 
> properties:
>   compatible:
>     oneOf:
>       - const: google,lga-mailbox-array
>       - items:
>           - enum:
>               - google,next-mailbox-array
>               - google,nextnext-mailbox-array
>               - google,another-mailbox-array
>           - const: google,lga-mailbox-array
> 
> If we keep "google,mailbox-array" as the generic, then going forward a
> few generations we end up with this, which seems nicer / less
> confusing:
> 
> properties:
>   compatible:
>     items:
>       - enum:
>           - google,lga-mailbox-array
>           - google,next-mailbox-array
>           - google,nextnext-mailbox-array
>           - google,another-mailbox-array
>       - const: google,mailbox-array

I find 4 strings nicer than 5 strings.

> Sure, it means that if someone unexpectedly makes a new Google
> mailbox-array that's totally incompatible then the
> "google,mailbox-array" sounds too generic, but that doesn't feel like
> the end of the world. You could call the new mailbox array designed in
> the year 2037 the "google,2037-mailbox-array" and things would overall
> be less confusing than using the "google,lga-mailbox-array" as the
> generic.

What exactly do we need to do to stop having this conversation? We've 
done this scheme and version numbers and it never ends well.

The reality is the h/w folks can't help themselves from changing things, 
so nothing remains unchanged for very many generations.

Rob

Re: [PATCH 6/7] dt-bindings: mailbox: goog-mba: Add goog-mba mailbox bindings

[Doug Anderson]

Hi,

On Wed, Jul 22, 2026 at 7:10 AM Rob Herring <robh@kernel.org> wrote:
>
> > Sure, it means that if someone unexpectedly makes a new Google
> > mailbox-array that's totally incompatible then the
> > "google,mailbox-array" sounds too generic, but that doesn't feel like
> > the end of the world. You could call the new mailbox array designed in
> > the year 2037 the "google,2037-mailbox-array" and things would overall
> > be less confusing than using the "google,lga-mailbox-array" as the
> > generic.
>
> What exactly do we need to do to stop having this conversation? We've
> done this scheme and version numbers and it never ends well.
>
> The reality is the h/w folks can't help themselves from changing things,
> so nothing remains unchanged for very many generations.

Stop having the conversation with me, or with everyone?

With me, I'll stop pushing since I think I understand pretty well
where you and Krzysztof stand on the matter now. Even here, I wasn't
pushing hard on the matter but I was trying to understand exactly
where the boundary was. As I understood it, things with enough
"identification" to disambiguate themselves could use something more
generic, especially if no preexisting binding existed. I clearly
misunderstood. Mea culpa for the noise on this one.

I'm not sure how to avoid repeating the conversation with the rest of
the world. I think this will always be a confusing topic.

-Doug

Re: [PATCH 6/7] dt-bindings: mailbox: goog-mba: Add goog-mba mailbox bindings

[Doug Anderson]

Hi,

On Thu, Jul 16, 2026 at 9:31 AM Doug Anderson <dianders@chromium.org> wrote:
>
> > >>> +patternProperties:
> > >>> +  "^mailbox@[0-9a-f]+$":
> > >>> +    type: object
> > >>> +    description:
> > >>> +      Each sub-node is a single-channel mailbox.
> > >>
> > >> This does not look like correct representation. You have one mailbox
> > >> controller with multiple mailboxes, not multiple mailbox controllers of
> > >> single channel boxes.
> > >
> > > I spent quite a bit of time debating this when rewriting the driver.
> > > While we could certainly hack things into the existing "mailbox with a
> > > bunch of channels", IMO it would be a worse representation of the
> > > hardware.
> > >
> > > I discussed this in the wall of text in this patch series, but
> > > re-hashing it here:
> > >
> > > Each "mailbox" in the mailbox array is more like a full-fledged
> > > mailbox than a channel within a mailbox. Each (single-channel)
> > > mailbox:
> > > * Has its own client register space.
> >
> > That's nothing special yet. Many providers of multiple resources have
> > these resources in dedicated registers. Arguing this, each GPIO in a
> > GPIO controller as well has its own register space so is basically a
> > GPIO controller on its own.
> >
> > > * Has its own interrupt.
> >
> > Just like GPIOs...
>
> Sure, having a giant list of interrupts and register offsets isn't the
> end of the world.
>
>
> > > * Can have a different amount of memory for messages.
> > > * Can have its own conventions for communication.
>
> I notice you didn't respond to the above bullets. How would I deal
> with different mailboxes in the array having different communication
> conventions? Different mailboxes in the array might have different
> "payload" sizes. Some mailboxes in the array might use "queue" mode
> conventions and some might not. Do I need to devise some complex
> scheme for describing which mailboxes in the array use which
> convention?
>
>
> > Well, this could be. But you still have one child per channel (cells=0)
> > and all children address space is in parent's space, so that's clear
> > indication. It's one controller with multiple, although some different,
> > channels.
>
> Sure, it's definitely one IP block and I'm not arguing against that.
>
>
> > > If we tried to represent the mailbox array as a single mailbox with a
> > > bunch of channels, each instance would have a different number of
> > > "reg" entries and a different number of interrupts. We would also need
> >
> > No, you would have only one device node. Very clean solution instead of
> > 100 children for each individual mailbox.
>
> There are definitely not anywhere near 100 children. At most a given
> instance of an MBA IP block could have 32 mailboxes. In practice, most
> have fewer.
>
>
> > It's the same with clocks (TI) - you do not get device node per clock,
> > even if TI did it 10 years ago. You do not get here device node per channel.
>
> Sure, the clock history is one thing to look at here. IMO, this is not
> the right comparison, though. Trying to describe all of the complexity
> of a clock tree in device tree is an exercise in futility. It's just
> too complex to get it right, and there really are hundreds of clocks.
> The mailbox array, on the other hand, is a much simpler beast.
>
> I think regulators and PMICs are a better comparison here. When we
> describe a PMIC in the device tree, do we have a single PMIC node and
> then have clients refer to a "regulator ID" to index into which
> specific regulator in the PMIC they want? No, we don't. We use
> sub-nodes for each specific regulator. This gives us a nice place in
> the device tree to put information about each individual regulator,
> since each regulator in a PMIC is different.
>
> Certainly if we had a mailbox controller with a bunch of identical
> channels then describing them as sub-nodes wouldn't make sense.
> Existing in-tree mailbox controllers have a bunch of homogenous
> channels, and thus the existing solution of using a channel ID works
> well. Here, the sub-nodes buy us something and provide for a cleaner
> solution.
>
> I don't understand the downside of my current proposal. It represents
> the hardware better (both the HW designers' intentions and the reality
> of its structure), avoids adding complexity to the device tree, and
> feels clean.

FWIW, I still feel fairly strongly about the fact that #mailbox-cells
shuld be 0 here and the fact that each mailbox in this mailbox array
is best expressed in the device-tree by its own node since. In other
words, the best model for this hardware is an array of single-channel
mailboxes, not one mailbox with many channels. The main reason is that
each mailbox in the array is _not_ homogeneous and is not intended to
be. The main argument is that every mailbox in the array can have a
different message-buffer size. While we can discover the
message-buffer size of each mailbox in the array at runtime by reading
hardware registers, the different message-buffer sizes suggest that
each mailbox in the array is designed to be able to use a different
message-passing convention. The message-passing convention is defined
by the firmware on the remote side and is _not_ discoverable, so we
need a place in the device tree to describe it for each mailbox. Each
mailbox in the array having its own node is the proper place to put
information about this convention.

Krzysztof: Do you still oppose this? I feel pretty strongly, so before
changing this to some awkward bindings, I'd love to get confirmation.
I'd also be interested if anyone else on the CC list has opinions on
the topic.

-Doug

Re: [PATCH 6/7] dt-bindings: mailbox: goog-mba: Add goog-mba mailbox bindings

[Jassi Brar]

Hi,
  Replying in one place to the two main points of contention ...

1) Compatible string :-
   I too think leaving it too generic is a bit bold ... we often think
it is final but more often it turns out to not be so. But I also don't
particularly like the idea of naming it after the SoC because
controller IPs are usually not tied to a SoC. So giving it a
controller version specific name should be good. I hope we treat all
controllers as potentially 3rd reusable blocks rather than a part of
SoC's identity.

2) Single-channel Controllers vs Multi-channel Controller :-
  Looking at the description of h/w, especially the separate and
optional register sets and the fact that we are not talking runtime
ad-hoc links between two endpoints, I lean towards single-channel
controllers implementation. That seems like tidier dts+code.

Regards,
Jassi

Re: [PATCH 6/7] dt-bindings: mailbox: goog-mba: Add goog-mba mailbox bindings

[Doug Anderson]

Hi,

On Wed, Jul 29, 2026 at 6:27 AM Jassi Brar <jassisinghbrar@gmail.com> wrote:
>
> Hi,
>   Replying in one place to the two main points of contention ...
>
> 1) Compatible string :-
>    I too think leaving it too generic is a bit bold ... we often think
> it is final but more often it turns out to not be so. But I also don't
> particularly like the idea of naming it after the SoC because
> controller IPs are usually not tied to a SoC. So giving it a
> controller version specific name should be good. I hope we treat all
> controllers as potentially 3rd reusable blocks rather than a part of
> SoC's identity.

Jassi: How strongly do you feel about the above? It seems like
Krzysztof and Rob both feel strongly that any type of generic
compatible string (including a versioned generic name) is not OK. They
seem to strongly believe it should be named after the first SoC that
was upstreamed that contained the IP block.

Will you object if I send a v2 with "google,lga-mailbox-array" as the
compatible string and no generic?

Personally, I don't think this is worth fighting more about, but if
you feel strongly about it then I guess we need to resolve things
between you and the DT maintainers before I can send a v2?


> 2) Single-channel Controllers vs Multi-channel Controller :-
>   Looking at the description of h/w, especially the separate and
> optional register sets and the fact that we are not talking runtime
> ad-hoc links between two endpoints, I lean towards single-channel
> controllers implementation. That seems like tidier dts+code.

Thanks for your opinion. Unless I hear more thoughts on this, I'd be
inclined to send v2 while keeping one node for each single-channel
mailbox.

Jassi: do you want to review anything else in this series before I
send a v2? ...or I can just send a v2 and we can do further review
there. :-)


-Doug

Re: [PATCH 1/7] dt-bindings: mailbox: Don't require #mbox-cells to be 1

[Doug Anderson]

Hi,

On Wed, Jul 22, 2026 at 7:02 AM Rob Herring <robh@kernel.org> wrote:
>
> On Tue, Jul 14, 2026 at 03:21:40PM -0700, Douglas Anderson wrote:
> > Existing mailboxes have #mbox-cells and this makes sense if a mailbox
> > only exposes one channel. Update the bindings to match.
> >
> > Signed-off-by: Douglas Anderson <dianders@chromium.org>
> > ---
> > I assume this is worth doing (?). As noted [1], mailbox bindings are
> > already in the core schema, so what's here just provides extra context
> > and descriptions.
>
> We should update mbox-consumer.yaml and remove this file instead.
> There's only a couple of references to it.
>
> We should either just add missing descriptions to mbox-consumer.yaml or
> change it to mbox.yaml and add #mbox-cells. The latter would only
> provide some completeness as we don't have any constraints
> on #mbox-cells (there's a global max of 8 already).

FWIW, I've posted up both a pull request in git hub to add missing
descriptions into dt-schema [1] and a patch against the kernel
repository to delete the old .txt file [2].

I'm still waiting for responses to other patches in this series before
sending a v2. When I send v2 I'll drop this patch from the series so
we can track it separately. :-)

[1] https://github.com/devicetree-org/dt-schema/pull/202
[2] http://lore.kernel.org/r/20260804133801.1.I8b3ff71c528133e7d6f81fe926fa39e6451d63fd@changeid

Re: [PATCH 7/7] mailbox: goog-mba: Introduce the goog-mba mailbox driver

[Doug Anderson]

Hi,

On Tue, Sep 22, 2026 at 5:23 PM Jassi Brar <jassisinghbrar@gmail.com> wrote:
>
> So I think clk_mailbox can acquire all 8 channels during probe and
> maintain a list of idle channels from which it picks one and uses it
> for an incoming clk_prepare(). If all channels are busy, the
> clk_prepare() will sleep/block on a wait-queue which is nudged by
> tx_done of a transfer after the channel is added back to the idle
> list.

Sorry for the delay in responding. I wanted to prototype the change
and needed time to look at it.

So I think the crux of your current suggestion is that we have a
non-idempotent "fw_xlate" function, right? We call it multiple times
with the same arguments and it returns a different channel each time?
In my prototype, it looked like this:

```C
static struct mbox_chan *goog_mba_fw_xlate(struct mbox_controller *mbox,
                                      const struct fwnode_reference_args *sp)
{
  int i;

  if (sp->nargs)
    return ERR_PTR(-EINVAL);

  for (i = 0; i < mbox->num_chans; i++) {
    if (!mbox->chans[i].cl)
      return &mbox->chans[i];
  }

  return ERR_PTR(-EBUSY);
}
```

Then the client loops around and requests the same channel over and
over again until it gets -EBUSY? Like:

```C
for (i = 0; i < FIFO_MAX; i++) {
  client
  chan[i] = mbox_request_channel(client[i], TX_CHAN);
  if (IS_ERR(chan[i]) && PTR_ERR(chan[i]) == -EBUSY)
    break;
}
fifo_depth = i;
```

I _guess_ that works, but it still feels like a bit of a hack to me.
You said you were worried about people abusing the "has_queue" API.
The above feels like it's abusing the "fw_xlate" API, turning it from
something that is normally a "lookup" into an allocator function.

+Rob, Saravana, and devicetree@vger.kernel.org. DT folks: is the above
something that looks right to you?


I researched whether other upstream drivers use of_xlate() /
fw_xlate() as an "allocator" like this. I did find "exynos-mailbox,"
which appears to be doing something similar. However, upon deeper
digging it seems like "exynos-mailbox" isn't using this dynamic
allocation for any compelling reason. It looks like, really,
"exynos-mailbox" should just be returning one channel. The client
(exynos-acpm) could just use the same channel for everything since:
* It actually gets the _real_ channel ID out of the data.
* It doesn't care about txdone.
* All it does is ring a doorbell and there's no queueing.


In any case, if using fw_xlate() as an allocator is truly the only way
to proceed, I'll finish my prototype and send a v2, but I'm still
skeptical that this is better than just adding queuing into the core.
Speaking of which, I actually want to go back to something you said
earlier. I asked a bit about this but I don't think I saw a response
(sorry if I missed it!):

> It is not the diff stat but about inserting a flag in the api to
> introduce special case behavior. It is like adding one person to the
> party introduces N-1 handshakes - the has_queue flag doesn't play well
> with other configurations and may allow future platforms to abuse
> has_queue to implement hacks.

Can you elaborate more on this?

1. How does "has_queue" not play well with other configurations?
Everything should behave the same if "has_queue" isn't set, right? Are
you saying that it will make the code too hard to understand, or
something?

2. How does this allow future programs to abuse "has_queue"? Won't
they need to submit mailbox controllers to the mailbox subsystem,
meaning they'll have to go through you? If someone is using
"has_queue" to do a hack, can't you just NAK them?


One other thing that my prototype turned up: If I do the "fw_xlate()
as an allocator" solution, I believe I need to change the DT bindings
by adding a "tx-payload-size" attribute, or I need to jump through a
pile of awkward hoops. The reason is that I suddenly need to know the
number of FIFO entries much earlier. The v1 of my patch simply figured
out the "tx-payload-size" based on the first message sent, but now we
need it earlier.

While that's maybe not the end of the world, it's always unfortunate
when we have to change the DT bindings to accommodate the software
design.

-Doug

Re: [PATCH 7/7] mailbox: goog-mba: Introduce the goog-mba mailbox driver

[Krzysztof Kozlowski]

On 28/09/2026 23:34, Doug Anderson wrote:
> 
> ```C
> static struct mbox_chan *goog_mba_fw_xlate(struct mbox_controller *mbox,
>                                       const struct fwnode_reference_args *sp)
> {
>   int i;
> 
>   if (sp->nargs)
>     return ERR_PTR(-EINVAL);
> 
>   for (i = 0; i < mbox->num_chans; i++) {
>     if (!mbox->chans[i].cl)
>       return &mbox->chans[i];
>   }
> 
>   return ERR_PTR(-EBUSY);
> }
> ```
> 
> Then the client loops around and requests the same channel over and
> over again until it gets -EBUSY? Like:
> 
> ```C
> for (i = 0; i < FIFO_MAX; i++) {
>   client
>   chan[i] = mbox_request_channel(client[i], TX_CHAN);
>   if (IS_ERR(chan[i]) && PTR_ERR(chan[i]) == -EBUSY)
>     break;
> }
> fifo_depth = i;
> ```
> 
> I _guess_ that works, but it still feels like a bit of a hack to me.
> You said you were worried about people abusing the "has_queue" API.
> The above feels like it's abusing the "fw_xlate" API, turning it from
> something that is normally a "lookup" into an allocator function.
> 
> +Rob, Saravana, and devicetree@vger.kernel.org. DT folks: is the above
> something that looks right to you?

There is no allocation in your xlate code above, so this is not that
terrible as we talked on LPC.

> 
> 
> I researched whether other upstream drivers use of_xlate() /
> fw_xlate() as an "allocator" like this. I did find "exynos-mailbox,"
> which appears to be doing something similar. However, upon deeper
> digging it seems like "exynos-mailbox" isn't using this dynamic
> allocation for any compelling reason. It looks like, really,
> "exynos-mailbox" should just be returning one channel. The client
> (exynos-acpm) could just use the same channel for everything since:
> * It actually gets the _real_ channel ID out of the data.
> * It doesn't care about txdone.
> * All it does is ring a doorbell and there's no queueing.
> 
> 
> In any case, if using fw_xlate() as an allocator is truly the only way
> to proceed, I'll finish my prototype and send a v2, but I'm still

Why fw_xlate() would be an allocator? Can you extend your code to show that?

I think doing any allocation in xlate() is calls is fundamentally wrong.
These should not modify the state of the device, so no allocations, no
device_link_add() etc.

Why? There is simply no corresponding xlate_destroy() call. It's also
confusing, because the meaning is to translate from one domain resource
to another, not perform actual resource allocation.

> skeptical that this is better than just adding queuing into the core.
> Speaking of which, I actually want to go back to something you said
> earlier. I asked a bit about this but I don't think I saw a response
> (sorry if I missed it!):

Best regards,
Krzysztof

Re: [PATCH 7/7] mailbox: goog-mba: Introduce the goog-mba mailbox driver

[Doug Anderson]

Hi,

On Thu, Oct 8, 2026 at 11:36 PM Krzysztof Kozlowski <krzk@kernel.org> wrote:
>
> On 28/09/2026 23:34, Doug Anderson wrote:
> >
> > ```C
> > static struct mbox_chan *goog_mba_fw_xlate(struct mbox_controller *mbox,
> >                                       const struct fwnode_reference_args *sp)
> > {
> >   int i;
> >
> >   if (sp->nargs)
> >     return ERR_PTR(-EINVAL);
> >
> >   for (i = 0; i < mbox->num_chans; i++) {
> >     if (!mbox->chans[i].cl)
> >       return &mbox->chans[i];
> >   }
> >
> >   return ERR_PTR(-EBUSY);
> > }
> > ```
> >
> > Then the client loops around and requests the same channel over and
> > over again until it gets -EBUSY? Like:
> >
> > ```C
> > for (i = 0; i < FIFO_MAX; i++) {
> >   client
> >   chan[i] = mbox_request_channel(client[i], TX_CHAN);
> >   if (IS_ERR(chan[i]) && PTR_ERR(chan[i]) == -EBUSY)
> >     break;
> > }
> > fifo_depth = i;
> > ```
> >
> > I _guess_ that works, but it still feels like a bit of a hack to me.
> > You said you were worried about people abusing the "has_queue" API.
> > The above feels like it's abusing the "fw_xlate" API, turning it from
> > something that is normally a "lookup" into an allocator function.
> >
> > +Rob, Saravana, and devicetree@vger.kernel.org. DT folks: is the above
> > something that looks right to you?
>
> There is no allocation in your xlate code above, so this is not that
> terrible as we talked on LPC.
>
> >
> >
> > I researched whether other upstream drivers use of_xlate() /
> > fw_xlate() as an "allocator" like this. I did find "exynos-mailbox,"
> > which appears to be doing something similar. However, upon deeper
> > digging it seems like "exynos-mailbox" isn't using this dynamic
> > allocation for any compelling reason. It looks like, really,
> > "exynos-mailbox" should just be returning one channel. The client
> > (exynos-acpm) could just use the same channel for everything since:
> > * It actually gets the _real_ channel ID out of the data.
> > * It doesn't care about txdone.
> > * All it does is ring a doorbell and there's no queueing.
> >
> >
> > In any case, if using fw_xlate() as an allocator is truly the only way
> > to proceed, I'll finish my prototype and send a v2, but I'm still
>
> Why fw_xlate() would be an allocator? Can you extend your code to show that?
>
> I think doing any allocation in xlate() is calls is fundamentally wrong.
> These should not modify the state of the device, so no allocations, no
> device_link_add() etc.

It's not _calling_ an allocator, it _is_ an allocator. It is walking
through the array of channels and returning the first free one. Then
that free channel is "allocated" to the client.


> Why? There is simply no corresponding xlate_destroy() call. It's also
> confusing, because the meaning is to translate from one domain resource
> to another, not perform actual resource allocation.

In this case, there is no leak because it's relying on knowledge of
how the mailbox core will be using fw_xlate() to finish the allocation
and then relying on the knowledge of the mailbox core to free. It
works like this (simplfied, see mbox_request_channel() for full code):

```
scoped_guard(mutex, &con_mutex) {
  list_for_each_entry(mbox, &mbox_cons, node) {
    if (device_match_fwnode(mbox->dev, fwspec.fwnode)) {
      // The below "allocates" the first free channel associated w/ the node.
      chan = mbox->fw_xlate(mbox, &fwspec);
      if (!IS_ERR(chan))
        break;
    }
  }
  if (!IS_ERR(chan))
    // This finishes the allocation.
    chan->cl = client;
}
```

Said more simply, in the mailbox driver, there is an array of channels
associated with a given "fw_node". These are "allocated" like this:
1. mbox_request_channel() grabs its global lock.
2. The mailbox driver's fw_xlate() is called to find the first "free"
channel associated with the fw_node (a channel with no "client").
3. mbox_request_channel() sets the "client" field in the channel to
finish allocation.
4. mbox_request_channel() drops its global lock.

Does that make sense?

Is that a design that looks good to you? If DT folks have no
objections to that, I'll send a new patch that works like that.

-Doug

Re: [PATCH 7/7] mailbox: goog-mba: Introduce the goog-mba mailbox driver

[Jassi Brar]

Hi Doug,

On Fri, Oct 9, 2026 at 3:42 AM Doug Anderson <dianders@chromium.org> wrote:
> > >
> > >   for (i = 0; i < mbox->num_chans; i++) {
> > >     if (!mbox->chans[i].cl)
> > >       return &mbox->chans[i];
> > >   }
> > >
> > >   return ERR_PTR(-EBUSY);
> > > }
> > > ```
> > >
> > > Then the client loops around and requests the same channel over and
> > > over again until it gets -EBUSY? Like:
> > >
> > > ```C
> > > for (i = 0; i < FIFO_MAX; i++) {
> > >   client
> > >   chan[i] = mbox_request_channel(client[i], TX_CHAN);
> > >   if (IS_ERR(chan[i]) && PTR_ERR(chan[i]) == -EBUSY)
> > >     break;
> > > }
> > > fifo_depth = i;
> > > ```
> > >
> > > I _guess_ that works, but it still feels like a bit of a hack to me.
> > > You said you were worried about people abusing the "has_queue" API.
> > > The above feels like it's abusing the "fw_xlate" API, turning it from
> > > something that is normally a "lookup" into an allocator function.
> > >
> > > +Rob, Saravana, and devicetree@vger.kernel.org. DT folks: is the above
> > > something that looks right to you?
> >
> > There is no allocation in your xlate code above, so this is not that
> > terrible as we talked on LPC.
> >
> > >
> > >
> > > I researched whether other upstream drivers use of_xlate() /
> > > fw_xlate() as an "allocator" like this. I did find "exynos-mailbox,"
> > > which appears to be doing something similar. However, upon deeper
> > > digging it seems like "exynos-mailbox" isn't using this dynamic
> > > allocation for any compelling reason. It looks like, really,
> > > "exynos-mailbox" should just be returning one channel. The client
> > > (exynos-acpm) could just use the same channel for everything since:
> > > * It actually gets the _real_ channel ID out of the data.
> > > * It doesn't care about txdone.
> > > * All it does is ring a doorbell and there's no queueing.
> > >
> > >
> > > In any case, if using fw_xlate() as an allocator is truly the only way
> > > to proceed, I'll finish my prototype and send a v2, but I'm still
> >
> > Why fw_xlate() would be an allocator? Can you extend your code to show that?
> >
> > I think doing any allocation in xlate() is calls is fundamentally wrong.
> > These should not modify the state of the device, so no allocations, no
> > device_link_add() etc.
>
> It's not _calling_ an allocator, it _is_ an allocator. It is walking
> through the array of channels and returning the first free one. Then
> that free channel is "allocated" to the client.
>
You mean _assigned_.
Allocation means when there are some resources reserved that must be
released at some point later .... which is what the mailbox controller
driver does in probe() and remove().
In xlate() the platform just decides which channel to assign to the
incoming request -- some platforms take the hint from device-tree,
your platform has flexibility and can simply assign the first free
found.

I will try to explain in detail your questions in your last post, but
I am still not convinced you need to modify the api.

Regards,
Jassi