Documentation/devicetree/bindings/interrupt-controller/fsl,mpic-msi.yaml

# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/interrupt-controller/fsl,mpic-msi.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: Freescale MSI interrupt controller

description: |
  The Freescale hypervisor and msi-address-64
  -------------------------------------------

  Normally, PCI devices have access to all of CCSR via an ATMU mapping.  The
  Freescale MSI driver calculates the address of MSIIR (in the MSI register
  block) and sets that address as the MSI message address.

  In a virtualized environment, the hypervisor may need to create an IOMMU
  mapping for MSIIR.  The Freescale ePAPR hypervisor has this requirement
  because of hardware limitations of the Peripheral Access Management Unit
  (PAMU), which is currently the only IOMMU that the hypervisor supports.
  The ATMU is programmed with the guest physical address, and the PAMU
  intercepts transactions and reroutes them to the true physical address.

  In the PAMU, each PCI controller is given only one primary window.  The
  PAMU restricts DMA operations so that they can only occur within a window.
  Because PCI devices must be able to DMA to memory, the primary window must
  be used to cover all of the guest's memory space.

  PAMU primary windows can be divided into 256 subwindows, and each
  subwindow can have its own address mapping ("guest physical" to "true
  physical").  However, each subwindow has to have the same alignment, which
  means they cannot be located at just any address.  Because of these
  restrictions, it is usually impossible to create a 4KB subwindow that
  covers MSIIR where it's normally located.

  Therefore, the hypervisor has to create a subwindow inside the same
  primary window used for memory, but mapped to the MSIR block (where MSIIR
  lives).  The first subwindow after the end of guest memory is used for
  this.  The address specified in the msi-address-64 property is the PCI
  address of MSIIR.  The hypervisor configures the PAMU to map that address to
  the true physical address of MSIIR.

maintainers:
  - J. Neuschäfer <j.ne@posteo.net>

properties:
  compatible:
    oneOf:
      - enum:
          - fsl,mpic-msi
          - fsl,mpic-msi-v4.3
          - fsl,ipic-msi
          - fsl,vmpic-msi
          - fsl,vmpic-msi-v4.3
      - items:
          - enum:
              - fsl,mpc8572-msi
              - fsl,mpc8610-msi
              - fsl,mpc8641-msi
          - const: fsl,mpic-msi

  reg:
    minItems: 1
    items:
      - description: Address and length of the shared message interrupt
          register set
      - description: Address of aliased MSIIR or MSIIR1 register for platforms
          that have such an alias. If using MSIIR1, the second region must be
          added because different MSI group has different MSIIR1 offset.

  interrupts:
    minItems: 1
    maxItems: 16
    description:
      Each one of the interrupts here is one entry per 32 MSIs, and routed to
      the host interrupt controller. The interrupts should be set as edge
      sensitive. If msi-available-ranges is present, only the interrupts that
      correspond to available ranges shall be present.

  msi-available-ranges:
    $ref: /schemas/types.yaml#/definitions/uint32-matrix
    items:
      items:
        - description: First MSI interrupt in this range
        - description: Number of MSI interrupts in this range
    description:
      Define which MSI interrupt can be used in the 256 MSI interrupts.
      If not specified, all the MSI interrupts can be used.
      Each available range must begin and end on a multiple of 32 (i.e. no
      splitting an individual MSI register or the associated PIC interrupt).

  msi-address-64:
    $ref: /schemas/types.yaml#/definitions/uint64
    description:
      64-bit PCI address of the MSIIR register. The MSIIR register is used for
      MSI messaging.  The address of MSIIR in PCI address space is the MSI
      message address.

      This property may be used in virtualized environments where the hypervisor
      has created an alternate mapping for the MSIR block.  See the top-level
      description for an explanation.

required:
  - compatible
  - reg
  - interrupts

allOf:
  - if:
      properties:
        compatible:
          contains:
            enum:
              - fsl,mpic-msi-v4.3
              - fsl,vmpic-msi-v4.3
    then:
      properties:
        interrupts:
          minItems: 16
          description:
            Version 4.3 implies that there are 16 shared interrupts, and they
            are configured through MSIIR1.

        # MPIC v4.3 does not support this property because the 32 interrupts of
        # an individual register are not continuous when using MSIIR1.
        msi-available-ranges: false

        reg:
          minItems: 2

    else:
      properties:
        interrupts:
          maxItems: 8
          description:
            In versions before 4.3, only 8 shared interrupts are available, and
            they are configured through MSIIR.

unevaluatedProperties: false

examples:
  - |
    msi@41600 {
            compatible = "fsl,mpc8610-msi", "fsl,mpic-msi";
            reg = <0x41600 0x80>;
            msi-available-ranges = <0 0x100>;
            interrupts = <0xe0 0>, <0xe1 0>, <0xe2 0>, <0xe3 0>,
                         <0xe4 0>, <0xe5 0>, <0xe6 0>, <0xe7 0>;
    };

  - |
    msi@41600 {
            compatible = "fsl,mpic-msi-v4.3";
            reg = <0x41600 0x200>, <0x44148 4>;
            interrupts = <0xe0 0 0 0>, <0xe1 0 0 0>, <0xe2 0 0 0>, <0xe3 0 0 0>,
                         <0xe4 0 0 0>, <0xe5 0 0 0>, <0xe6 0 0 0>, <0xe7 0 0 0>,
                         <0x100 0 0 0>, <0x101 0 0 0>, <0x102 0 0 0>, <0x103 0 0 0>,
                         <0x104 0 0 0>, <0x105 0 0 0>, <0x106 0 0 0>, <0x107 0 0 0>;
    };

...