[PATCH v2 3/6] dt-bindings: mailbox: Add AMD PL Mailbox IP

[Ben Levinsky]

Document the AMD programmable-logic Mailbox IP used for bidirectional
FIFO communication between two processor-facing interfaces.

The Mailbox is a soft IP core instantiated in programmable logic, and the
same SoC can carry different versions of it, so it is not a SoC block.
Like other PL soft IP bindings, use a single compatible that names the IP
core and its version, amd,pl-mailbox-2.1. "pl" distinguishes it from the
IPI hardware that can also act as a mailbox.

Define the transmit and receive channel indices together with the register
aperture, interrupt, and interface clock. Describe the FIFO depth chosen
for each IP instance when the design is synthesized. It cannot be read
from the registers, and the driver needs it to size received messages.

Assisted-by: Claude:claude-opus-5.5
Signed-off-by: Ben Levinsky <ben.levinsky@xxxxxxx>
---
 .../bindings/mailbox/amd,pl-mailbox-2.1.yaml  | 73 +++++++++++++++++++
 MAINTAINERS                                   |  6 ++
 2 files changed, 79 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/mailbox/amd,pl-mailbox-2.1.yaml

diff --git a/Documentation/devicetree/bindings/mailbox/amd,pl-mailbox-2.1.yaml b/Documentation/devicetree/bindings/mailbox/amd,pl-mailbox-2.1.yaml
new file mode 100644
index 000000000000..dc16a2e1142b
--- /dev/null
+++ b/Documentation/devicetree/bindings/mailbox/amd,pl-mailbox-2.1.yaml
@@ -0,0 +1,73 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mailbox/amd,pl-mailbox-2.1.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: AMD Programmable Logic Mailbox IP
+
+maintainers:
+  - Ben Levinsky <ben.levinsky@xxxxxxx>
+
+description: |
+  The AMD Programmable Logic Mailbox IP provides bidirectional message passing
+  between two processor-facing interfaces. Each interface writes messages to
+  a send FIFO and reads messages from a receive FIFO. The register aperture,
+  interrupt, and clock described by a node belong to one processor-facing
+  interface. Channel 0 represents transmit and channel 1 represents receive
+  for that interface.
+
+  The Mailbox is a soft IP core instantiated in programmable logic, not a
+  SoC block, so the compatible names the IP core and its version (2.1).
+  The "pl" part distinguishes it from the IPI hardware that can also be
+  used as a mailbox.
+
+properties:
+  compatible:
+    const: amd,pl-mailbox-2.1
+
+  reg:
+    maxItems: 1
+
+  interrupts:
+    maxItems: 1
+
+  clocks:
+    maxItems: 1
+
+  amd,pl-mailbox-depth:
+    $ref: /schemas/types.yaml#/definitions/uint32
+    minimum: 16
+    maximum: 8192
+    default: 16
+    description:
+      Depth of the send and receive FIFOs in 32-bit words. The depth is the
+      C_MAILBOX_DEPTH parameter chosen for each IP instance when the design
+      is synthesized, so instances in one design can differ, and it cannot
+      be read from the registers. Must match the synthesized depth.
+
+  '#mbox-cells':
+    const: 1
+
+required:
+  - compatible
+  - reg
+  - interrupts
+  - clocks
+  - '#mbox-cells'
+
+additionalProperties: false
+
+examples:
+  - |
+    #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+    mailbox@b2060000 {
+        compatible = "amd,pl-mailbox-2.1";
+        reg = <0xb2060000 0x10000>;
+        interrupts = <GIC_SPI 106 IRQ_TYPE_LEVEL_HIGH>;
+        clocks = <&pl_clk>;
+        amd,pl-mailbox-depth = <16>;
+        #mbox-cells = <1>;
+    };
+...
diff --git a/MAINTAINERS b/MAINTAINERS
index 1e3f9f2751fe..3722a66b9960 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -1306,6 +1306,12 @@ S:	Supported
 T:	git https://gitlab.freedesktop.org/agd5f/linux.git
 F:	drivers/gpu/drm/amd/pm/
 
+AMD PROGRAMMABLE LOGIC MAILBOX DRIVER
+M:	Ben Levinsky <ben.levinsky@xxxxxxx>
+L:	linux-kernel@xxxxxxxxxxxxxxx
+S:	Maintained
+F:	Documentation/devicetree/bindings/mailbox/amd,pl-mailbox-2.1.yaml
+
 AMD PSTATE DRIVER
 M:	Huang Rui <ray.huang@xxxxxxx>
 M:	Mario Limonciello <mario.limonciello@xxxxxxx>
-- 
2.34.1