# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/mailbox/arm-smc.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: ARM SMC Mailbox Interface

maintainers:
  - Peng Fan <peng.fan@nxp.com>

description: |
  This mailbox uses the ARM smc (secure monitor call) or hvc (hypervisor
  call) instruction to trigger a mailbox-connected activity in firmware,
  executing on the very same core as the caller. The value of r0/w0/x0
  the firmware returns after the smc call is delivered as a received
  message to the mailbox framework, so synchronous communication can be
  established. The exact meaning of the action the mailbox triggers as
  well as the return value is defined by their users and is not subject
  to this binding.

  One example use case of this mailbox is the SCMI interface, which uses
  shared memory to transfer commands and parameters, and a mailbox to
  trigger a function call. This allows SoCs without a separate management
  processor (or when such a processor is not available or used) to use
  this standardized interface anyway.

  This binding describes no hardware, but establishes a firmware interface.
  Upon receiving an SMC using the described SMC function identifier, the
  firmware is expected to trigger some mailbox connected functionality.
  The communication follows the ARM SMC calling convention.
  Firmware expects an SMC function identifier in r0 or w0. The supported
  identifier is listed in the the arm,func-id property as described below.
  The firmware can return one value in the first SMC result register,
  it is expected to be an error value, which shall be propagated to the
  mailbox client.

  Any core which supports the SMC or HVC instruction can be used, as long
  as a firmware component running in EL3 or EL2 is handling these calls.

properties:
  compatible:
    oneOf:
      - description:
          For implementations using ARM SMC instruction.
        const: arm,smc-mbox

      - description:
          For implementations using ARM HVC instruction.
        const: arm,hvc-mbox

  "#mbox-cells":
    const: 0

  arm,func-id:
    description: |
      An single 32-bit value specifying the function ID used by the mailbox.
      The function ID follows the ARM SMC calling convention standard.
    $ref: /schemas/types.yaml#/definitions/uint32

required:
  - compatible
  - "#mbox-cells"
  - arm,func-id

examples:
  - |
    sram@93f000 {
      compatible = "mmio-sram";
      reg = <0x0 0x93f000 0x0 0x1000>;
      #address-cells = <1>;
      #size-cells = <1>;
      ranges = <0x0 0x93f000 0x1000>;

      cpu_scp_lpri: scp-shmem@0 {
        compatible = "arm,scmi-shmem";
        reg = <0x0 0x200>;
      };
    };

    smc_tx_mbox: tx_mbox {
      #mbox-cells = <0>;
      compatible = "arm,smc-mbox";
      arm,func-id = <0xc20000fe>;
    };

    firmware {
      scmi {
        compatible = "arm,scmi";
        mboxes = <&smc_tx_mbox>;
        mbox-names = "tx";
        shmem = <&cpu_scp_lpri>;
      };
    };

...