Documentation/devicetree/bindings/mailbox/riscv,rpmi-shmem-mbox.yaml

# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/mailbox/riscv,rpmi-shmem-mbox.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: RISC-V Platform Management Interface (RPMI) shared memory mailbox

maintainers:
  - Anup Patel <anup@brainfault.org>

description: |
  The RISC-V Platform Management Interface (RPMI) [1] defines a common shared
  memory based RPMI transport. This RPMI shared memory transport integrates as
  mailbox controller in the SBI implementation or supervisor software whereas
  each RPMI service group is mailbox client in the SBI implementation and
  supervisor software.

  ===========================================
  References
  ===========================================

  [1] RISC-V Platform Management Interface (RPMI) v1.0 (or higher)
      https://github.com/riscv-non-isa/riscv-rpmi/releases

properties:
  compatible:
    const: riscv,rpmi-shmem-mbox

  reg:
    minItems: 2
    items:
      - description: A2P request queue base address
      - description: P2A acknowledgment queue base address
      - description: P2A request queue base address
      - description: A2P acknowledgment queue base address
      - description: A2P doorbell address

  reg-names:
    minItems: 2
    items:
      - const: a2p-req
      - const: p2a-ack
      - enum: [ p2a-req, a2p-doorbell ]
      - const: a2p-ack
      - const: a2p-doorbell

  interrupts:
    maxItems: 1
    description:
      The RPMI shared memory transport supports P2A doorbell as a wired
      interrupt and this property specifies the interrupt source.

  msi-parent:
    description:
      The RPMI shared memory transport supports P2A doorbell as a system MSI
      and this property specifies the target MSI controller.

  riscv,slot-size:
    $ref: /schemas/types.yaml#/definitions/uint32
    minimum: 64
    description:
      Power-of-2 RPMI slot size of the RPMI shared memory transport.

  riscv,a2p-doorbell-value:
    $ref: /schemas/types.yaml#/definitions/uint32
    default: 0x1
    description:
      Value written to the 32-bit A2P doorbell register.

  riscv,p2a-doorbell-sysmsi-index:
    $ref: /schemas/types.yaml#/definitions/uint32
    description:
      The RPMI shared memory transport supports P2A doorbell as a system MSI
      and this property specifies system MSI index to be used for configuring
      the P2A doorbell MSI.

  "#mbox-cells":
    const: 1
    description:
      The first cell specifies RPMI service group ID.

required:
  - compatible
  - reg
  - reg-names
  - riscv,slot-size
  - "#mbox-cells"

anyOf:
  - required:
      - interrupts
  - required:
      - msi-parent

additionalProperties: false

examples:
  - |
    // Example 1 (RPMI shared memory with only 2 queues):
    mailbox@10080000 {
        compatible = "riscv,rpmi-shmem-mbox";
        reg = <0x10080000 0x10000>,
              <0x10090000 0x10000>;
        reg-names = "a2p-req", "p2a-ack";
        msi-parent = <&imsic_mlevel>;
        riscv,slot-size = <64>;
        #mbox-cells = <1>;
    };
  - |
    // Example 2 (RPMI shared memory with only 4 queues):
    mailbox@10001000 {
        compatible = "riscv,rpmi-shmem-mbox";
        reg = <0x10001000 0x800>,
              <0x10001800 0x800>,
              <0x10002000 0x800>,
              <0x10002800 0x800>,
              <0x10003000 0x4>;
        reg-names = "a2p-req", "p2a-ack", "p2a-req", "a2p-ack", "a2p-doorbell";
        msi-parent = <&imsic_mlevel>;
        riscv,slot-size = <64>;
        riscv,a2p-doorbell-value = <0x00008000>;
        #mbox-cells = <1>;
    };