fsl,mpic-msi.yaml

  1# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
  2%YAML 1.2
  3---
  4$id: http://devicetree.org/schemas/interrupt-controller/fsl,mpic-msi.yaml#
  5$schema: http://devicetree.org/meta-schemas/core.yaml#
  6
  7title: Freescale MSI interrupt controller
  8
  9description: |
 10  The Freescale hypervisor and msi-address-64
 11  -------------------------------------------
 12
 13  Normally, PCI devices have access to all of CCSR via an ATMU mapping.  The
 14  Freescale MSI driver calculates the address of MSIIR (in the MSI register
 15  block) and sets that address as the MSI message address.
 16
 17  In a virtualized environment, the hypervisor may need to create an IOMMU
 18  mapping for MSIIR.  The Freescale ePAPR hypervisor has this requirement
 19  because of hardware limitations of the Peripheral Access Management Unit
 20  (PAMU), which is currently the only IOMMU that the hypervisor supports.
 21  The ATMU is programmed with the guest physical address, and the PAMU
 22  intercepts transactions and reroutes them to the true physical address.
 23
 24  In the PAMU, each PCI controller is given only one primary window.  The
 25  PAMU restricts DMA operations so that they can only occur within a window.
 26  Because PCI devices must be able to DMA to memory, the primary window must
 27  be used to cover all of the guest's memory space.
 28
 29  PAMU primary windows can be divided into 256 subwindows, and each
 30  subwindow can have its own address mapping ("guest physical" to "true
 31  physical").  However, each subwindow has to have the same alignment, which
 32  means they cannot be located at just any address.  Because of these
 33  restrictions, it is usually impossible to create a 4KB subwindow that
 34  covers MSIIR where it's normally located.
 35
 36  Therefore, the hypervisor has to create a subwindow inside the same
 37  primary window used for memory, but mapped to the MSIR block (where MSIIR
 38  lives).  The first subwindow after the end of guest memory is used for
 39  this.  The address specified in the msi-address-64 property is the PCI
 40  address of MSIIR.  The hypervisor configures the PAMU to map that address to
 41  the true physical address of MSIIR.
 42
 43maintainers:
 44  - J. Neuschäfer <j.ne@posteo.net>
 45
 46properties:
 47  compatible:
 48    oneOf:
 49      - enum:
 50          - fsl,mpic-msi
 51          - fsl,mpic-msi-v4.3
 52          - fsl,ipic-msi
 53          - fsl,vmpic-msi
 54          - fsl,vmpic-msi-v4.3
 55      - items:
 56          - enum:
 57              - fsl,mpc8572-msi
 58              - fsl,mpc8610-msi
 59              - fsl,mpc8641-msi
 60          - const: fsl,mpic-msi
 61
 62  reg:
 63    minItems: 1
 64    items:
 65      - description: Address and length of the shared message interrupt
 66          register set
 67      - description: Address of aliased MSIIR or MSIIR1 register for platforms
 68          that have such an alias. If using MSIIR1, the second region must be
 69          added because different MSI group has different MSIIR1 offset.
 70
 71  interrupts:
 72    minItems: 1
 73    maxItems: 16
 74    description:
 75      Each one of the interrupts here is one entry per 32 MSIs, and routed to
 76      the host interrupt controller. The interrupts should be set as edge
 77      sensitive. If msi-available-ranges is present, only the interrupts that
 78      correspond to available ranges shall be present.
 79
 80  msi-available-ranges:
 81    $ref: /schemas/types.yaml#/definitions/uint32-matrix
 82    items:
 83      items:
 84        - description: First MSI interrupt in this range
 85        - description: Number of MSI interrupts in this range
 86    description:
 87      Define which MSI interrupt can be used in the 256 MSI interrupts.
 88      If not specified, all the MSI interrupts can be used.
 89      Each available range must begin and end on a multiple of 32 (i.e. no
 90      splitting an individual MSI register or the associated PIC interrupt).
 91
 92  msi-address-64:
 93    $ref: /schemas/types.yaml#/definitions/uint64
 94    description:
 95      64-bit PCI address of the MSIIR register. The MSIIR register is used for
 96      MSI messaging.  The address of MSIIR in PCI address space is the MSI
 97      message address.
 98
 99      This property may be used in virtualized environments where the hypervisor
100      has created an alternate mapping for the MSIR block.  See the top-level
101      description for an explanation.
102
103required:
104  - compatible
105  - reg
106  - interrupts
107
108allOf:
109  - if:
110      properties:
111        compatible:
112          contains:
113            enum:
114              - fsl,mpic-msi-v4.3
115              - fsl,vmpic-msi-v4.3
116    then:
117      properties:
118        interrupts:
119          minItems: 16
120          description:
121            Version 4.3 implies that there are 16 shared interrupts, and they
122            are configured through MSIIR1.
123
124        # MPIC v4.3 does not support this property because the 32 interrupts of
125        # an individual register are not continuous when using MSIIR1.
126        msi-available-ranges: false
127
128        reg:
129          minItems: 2
130
131    else:
132      properties:
133        interrupts:
134          maxItems: 8
135          description:
136            In versions before 4.3, only 8 shared interrupts are available, and
137            they are configured through MSIIR.
138
139unevaluatedProperties: false
140
141examples:
142  - |
143    msi@41600 {
144            compatible = "fsl,mpc8610-msi", "fsl,mpic-msi";
145            reg = <0x41600 0x80>;
146            msi-available-ranges = <0 0x100>;
147            interrupts = <0xe0 0>, <0xe1 0>, <0xe2 0>, <0xe3 0>,
148                         <0xe4 0>, <0xe5 0>, <0xe6 0>, <0xe7 0>;
149    };
150
151  - |
152    msi@41600 {
153            compatible = "fsl,mpic-msi-v4.3";
154            reg = <0x41600 0x200>, <0x44148 4>;
155            interrupts = <0xe0 0 0 0>, <0xe1 0 0 0>, <0xe2 0 0 0>, <0xe3 0 0 0>,
156                         <0xe4 0 0 0>, <0xe5 0 0 0>, <0xe6 0 0 0>, <0xe7 0 0 0>,
157                         <0x100 0 0 0>, <0x101 0 0 0>, <0x102 0 0 0>, <0x103 0 0 0>,
158                         <0x104 0 0 0>, <0x105 0 0 0>, <0x106 0 0 0>, <0x107 0 0 0>;
159    };
160
161...