1This document describes the generic device tree binding for describing the 2relationship between PCI(e) devices and IOMMU(s). 3 4Each PCI(e) device under a root complex is uniquely identified by its Requester 5ID (AKA RID). A Requester ID is a triplet of a Bus number, Device number, and 6Function number. 7 8For the purpose of this document, when treated as a numeric value, a RID is 9formatted 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 16IOMMUs may distinguish PCI devices through sideband data derived from the 17Requester ID. While a given PCI device can only master through one IOMMU, a 18root complex may split masters across a set of IOMMUs (e.g. with one IOMMU per 19bus). 20 21The generic 'iommus' property is insufficient to describe this relationship, 22and a mechanism is required to map from a PCI device to its IOMMU and sideband 23data. 24 25For generic IOMMU bindings, see 26Documentation/devicetree/bindings/iommu/iommu.txt. 27 28 29PCI root complex 30================ 31 32Optional 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 48Example (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 75Example (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 103Example (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 131Example (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}; 172