linux/Documentation/devicetree/bindings/mailbox/xlnx,zynqmp-ipi-mailbox.yaml

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

title: Xilinx IPI(Inter Processor Interrupt) mailbox controller

description: |
  The Xilinx IPI(Inter Processor Interrupt) mailbox controller is to manage
  messaging between two Xilinx Zynq UltraScale+ MPSoC IPI agents. Each IPI
  agent owns registers used for notification and buffers for message.

  For Versal devices, there are two types of IPI channels:
    - Buffered channels: Support message passing and require the "msg"
    register region to be present on both the host and remote IPI agents.
    - Buffer-less channels: Support notification only and do not require the
    "msg" register region. For these channels, the "msg" region should be
    omitted.

  For message passing, both the host and remote IPI agents must define the "msg"
  register region. If either agent omits the "msg" region, only notification
  based communication is possible.

               +-------------------------------------+
               | Xilinx ZynqMP IPI Controller        |
               +-------------------------------------+
    +--------------------------------------------------+
  TF-A                   |                     |
                         |                     |
                         |                     |
    +--------------------------+               |
                         |                     |
                         |                     |
    +--------------------------------------------------+
              +------------------------------------------+
              |  +----------------+   +----------------+ |
  Hardware    |  |  IPI Agent     |   |  IPI Buffers   | |
              |  |  Registers     |   |                | |
              |  |                |   |                | |
              |  +----------------+   +----------------+ |
              |                                          |
              | Xilinx IPI Agent Block                   |
              +------------------------------------------+

maintainers:
  - Shubhrajyoti Datta <shubhrajyoti.datta@amd.com>

properties:
  compatible:
    enum:
      - xlnx,zynqmp-ipi-mailbox
      - xlnx,versal-ipi-mailbox

  method:
    description: |
      The method of calling the PM-API firmware layer.
      Permitted values are.
      - "smc" : SMC #0, following the SMCCC
      - "hvc" : HVC #0, following the SMCCC

    $ref: /schemas/types.yaml#/definitions/string
    enum:
      - smc
      - hvc
    default: smc

  '#address-cells':
    const: 2

  '#size-cells':
    const: 2

  reg:
    maxItems: 2

  reg-names:
    maxItems: 2

  xlnx,ipi-id:
    description: |
      Remote Xilinx IPI agent ID of which the mailbox is connected to.
    $ref: /schemas/types.yaml#/definitions/uint32

  interrupts:
    maxItems: 1

  ranges: true

patternProperties:
  '^mailbox@[0-9a-f]+$':
    description: Internal ipi mailbox node
    type: object  # DT nodes are json objects
    additionalProperties: false
    properties:

      compatible:
        enum:
          - xlnx,zynqmp-ipi-dest-mailbox
          - xlnx,versal-ipi-dest-mailbox

      reg:
        minItems: 1
        maxItems: 4

      reg-names:
        minItems: 1
        maxItems: 4

      xlnx,ipi-id:
        description:
          Remote Xilinx IPI agent ID of which the mailbox is connected to.
        $ref: /schemas/types.yaml#/definitions/uint32

      '#mbox-cells':
        const: 1
        description:
          It contains tx(0) or rx(1) channel IPI id number.

    allOf:
      - if:
          properties:
            compatible:
              contains:
                enum:
                  - xlnx,zynqmp-ipi-dest-mailbox
        then:
          properties:
            reg:
              maxItems: 4

            reg-names:
              items:
                - const: local_request_region
                - const: local_response_region
                - const: remote_request_region
                - const: remote_response_region
        else:
          properties:
            reg:
              minItems: 1
              items:
                - description: Remote IPI agent control register region
                - description: Remote IPI agent optional message buffers

            reg-names:
              minItems: 1
              items:
                - const: ctrl
                - const: msg

    required:
      - compatible
      - reg
      - reg-names
      - '#mbox-cells'
      - xlnx,ipi-id

required:
  - compatible
  - interrupts
  - '#address-cells'
  - '#size-cells'
  - xlnx,ipi-id

allOf:
  - if:
      properties:
        compatible:
          contains:
            enum:
              - xlnx,zynqmp-ipi-mailbox
    then:
      properties:
        reg: false
        reg-names: false

    else:
      properties:
        reg:
          items:
            - description: Host IPI agent control register region
            - description: Host IPI agent optional message buffers

        reg-names:
          items:
            - const: ctrl
            - const: msg

      required:
        - reg
        - reg-names

additionalProperties: false

examples:
  - |
    #include<dt-bindings/interrupt-controller/arm-gic.h>

    amba {
      #address-cells = <0x2>;
      #size-cells = <0x2>;
      zynqmp-mailbox {
        compatible = "xlnx,zynqmp-ipi-mailbox";
        interrupts = <GIC_SPI 29 IRQ_TYPE_LEVEL_HIGH>;
        xlnx,ipi-id = <0>;
        #address-cells = <2>;
        #size-cells = <2>;
        ranges;

        mailbox: mailbox@ff9905c0 {
          compatible = "xlnx,zynqmp-ipi-dest-mailbox";
          reg = <0x0 0xff9905c0 0x0 0x20>,
                <0x0 0xff9905e0 0x0 0x20>,
                <0x0 0xff990e80 0x0 0x20>,
                <0x0 0xff990ea0 0x0 0x20>;
          reg-names = "local_request_region",
                      "local_response_region",
                      "remote_request_region",
                      "remote_response_region";
          #mbox-cells = <1>;
          xlnx,ipi-id = <4>;
        };
      };
    };

  - |
    #include<dt-bindings/interrupt-controller/arm-gic.h>

    bus {
      #address-cells = <2>;
      #size-cells = <2>;
      mailbox@ff300000 {
        compatible = "xlnx,versal-ipi-mailbox";
        interrupts = <GIC_SPI 29 IRQ_TYPE_LEVEL_HIGH>;
        #address-cells = <2>;
        #size-cells = <2>;
        reg = <0x0 0xff300000 0x0 0x1000>,
              <0x0 0xff990000 0x0 0x1ff>;
        reg-names = "ctrl", "msg";
        xlnx,ipi-id = <0>;
        ranges;

        /* buffered IPI */
        mailbox@ff340000 {
          compatible = "xlnx,versal-ipi-dest-mailbox";
          reg = <0x0 0xff340000 0x0 0x1000>,
                <0x0 0xff990400 0x0 0x1ff>;
          reg-names = "ctrl", "msg";
          #mbox-cells = <1>;
          xlnx,ipi-id = <4>;
        };

        /* bufferless IPI */
        mailbox@ff370000 {
          compatible = "xlnx,versal-ipi-dest-mailbox";
          reg = <0x0 0xff370000 0x0 0x1000>;
          reg-names = "ctrl";
          #mbox-cells = <1>;
          xlnx,ipi-id = <7>;
        };
      };
    };
...