dts/upstream/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.

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