Documentation/devicetree/bindings/pci/pci-iommu.txt

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