| 1 | This document describes the generic device tree binding for describing the |
| 2 | relationship between PCI(e) devices and IOMMU(s). |
| 3 | |
| 4 | Each PCI(e) device under a root complex is uniquely identified by its Requester |
| 5 | ID (AKA RID). A Requester ID is a triplet of a Bus number, Device number, and |
| 6 | Function number. |
| 7 | |
| 8 | For the purpose of this document, when treated as a numeric value, a RID is |
| 9 | formatted such that: |
| 10 | |
| 11 | * Bits [15:8] are the Bus number. |
| 12 | * Bits [7:3] are the Device number. |
| 13 | * Bits [2:0] are the Function number. |
| 14 | * Any other bits required for padding must be zero. |
| 15 | |
| 16 | IOMMUs may distinguish PCI devices through sideband data derived from the |
| 17 | Requester ID. While a given PCI device can only master through one IOMMU, a |
| 18 | root complex may split masters across a set of IOMMUs (e.g. with one IOMMU per |
| 19 | bus). |
| 20 | |
| 21 | The generic 'iommus' property is insufficient to describe this relationship, |
| 22 | and a mechanism is required to map from a PCI device to its IOMMU and sideband |
| 23 | data. |
| 24 | |
| 25 | For generic IOMMU bindings, see |
| 26 | Documentation/devicetree/bindings/iommu/iommu.txt. |
| 27 | |
| 28 | |
| 29 | PCI root complex |
| 30 | ================ |
| 31 | |
| 32 | Optional properties |
| 33 | ------------------- |
| 34 | |
| 35 | - iommu-map: Maps a Requester ID to an IOMMU and associated iommu-specifier |
| 36 | data. |
| 37 | |
| 38 | The property is an arbitrary number of tuples of |
| 39 | (rid-base,iommu,iommu-base,length). |
| 40 | |
| 41 | Any RID r in the interval [rid-base, rid-base + length) is associated with |
| 42 | the listed IOMMU, with the iommu-specifier (r - rid-base + iommu-base). |
| 43 | |
| 44 | - iommu-map-mask: A mask to be applied to each Requester ID prior to being |
| 45 | mapped to an iommu-specifier per the iommu-map property. |
| 46 | |
| 47 | |
| 48 | Example (1) |
| 49 | =========== |
| 50 | |
| 51 | / { |
| 52 | #address-cells = <1>; |
| 53 | #size-cells = <1>; |
| 54 | |
| 55 | iommu: iommu@a { |
| 56 | reg = <0xa 0x1>; |
| 57 | compatible = "vendor,some-iommu"; |
| 58 | #iommu-cells = <1>; |
| 59 | }; |
| 60 | |
| 61 | pci: pci@f { |
| 62 | reg = <0xf 0x1>; |
| 63 | compatible = "vendor,pcie-root-complex"; |
| 64 | device_type = "pci"; |
| 65 | |
| 66 | /* |
| 67 | * The sideband data provided to the IOMMU is the RID, |
| 68 | * identity-mapped. |
| 69 | */ |
| 70 | iommu-map = <0x0 &iommu 0x0 0x10000>; |
| 71 | }; |
| 72 | }; |
| 73 | |
| 74 | |
| 75 | Example (2) |
| 76 | =========== |
| 77 | |
| 78 | / { |
| 79 | #address-cells = <1>; |
| 80 | #size-cells = <1>; |
| 81 | |
| 82 | iommu: iommu@a { |
| 83 | reg = <0xa 0x1>; |
| 84 | compatible = "vendor,some-iommu"; |
| 85 | #iommu-cells = <1>; |
| 86 | }; |
| 87 | |
| 88 | pci: pci@f { |
| 89 | reg = <0xf 0x1>; |
| 90 | compatible = "vendor,pcie-root-complex"; |
| 91 | device_type = "pci"; |
| 92 | |
| 93 | /* |
| 94 | * The sideband data provided to the IOMMU is the RID with the |
| 95 | * function bits masked out. |
| 96 | */ |
| 97 | iommu-map = <0x0 &iommu 0x0 0x10000>; |
| 98 | iommu-map-mask = <0xfff8>; |
| 99 | }; |
| 100 | }; |
| 101 | |
| 102 | |
| 103 | Example (3) |
| 104 | =========== |
| 105 | |
| 106 | / { |
| 107 | #address-cells = <1>; |
| 108 | #size-cells = <1>; |
| 109 | |
| 110 | iommu: iommu@a { |
| 111 | reg = <0xa 0x1>; |
| 112 | compatible = "vendor,some-iommu"; |
| 113 | #iommu-cells = <1>; |
| 114 | }; |
| 115 | |
| 116 | pci: pci@f { |
| 117 | reg = <0xf 0x1>; |
| 118 | compatible = "vendor,pcie-root-complex"; |
| 119 | device_type = "pci"; |
| 120 | |
| 121 | /* |
| 122 | * The sideband data provided to the IOMMU is the RID, |
| 123 | * but the high bits of the bus number are flipped. |
| 124 | */ |
| 125 | iommu-map = <0x0000 &iommu 0x8000 0x8000>, |
| 126 | <0x8000 &iommu 0x0000 0x8000>; |
| 127 | }; |
| 128 | }; |
| 129 | |
| 130 | |
| 131 | Example (4) |
| 132 | =========== |
| 133 | |
| 134 | / { |
| 135 | #address-cells = <1>; |
| 136 | #size-cells = <1>; |
| 137 | |
| 138 | iommu_a: iommu@a { |
| 139 | reg = <0xa 0x1>; |
| 140 | compatible = "vendor,some-iommu"; |
| 141 | #iommu-cells = <1>; |
| 142 | }; |
| 143 | |
| 144 | iommu_b: iommu@b { |
| 145 | reg = <0xb 0x1>; |
| 146 | compatible = "vendor,some-iommu"; |
| 147 | #iommu-cells = <1>; |
| 148 | }; |
| 149 | |
| 150 | iommu_c: iommu@c { |
| 151 | reg = <0xc 0x1>; |
| 152 | compatible = "vendor,some-iommu"; |
| 153 | #iommu-cells = <1>; |
| 154 | }; |
| 155 | |
| 156 | pci: pci@f { |
| 157 | reg = <0xf 0x1>; |
| 158 | compatible = "vendor,pcie-root-complex"; |
| 159 | device_type = "pci"; |
| 160 | |
| 161 | /* |
| 162 | * Devices with bus number 0-127 are mastered via IOMMU |
| 163 | * a, with sideband data being RID[14:0]. |
| 164 | * Devices with bus number 128-255 are mastered via |
| 165 | * IOMMU b, with sideband data being RID[14:0]. |
| 166 | * No devices master via IOMMU c. |
| 167 | */ |
| 168 | iommu-map = <0x0000 &iommu_a 0x0000 0x8000>, |
| 169 | <0x8000 &iommu_b 0x0000 0x8000>; |
| 170 | }; |
| 171 | }; |