Documentation/devicetree/bindings/iommu/iommu.txt

   1 This document describes the generic device tree binding for IOMMUs and their
   2 master(s).
   3
   4
   5 IOMMU device node:
   6 ==================
   7
   8 An IOMMU can provide the following services:
   9
  10 * Remap address space to allow devices to access physical memory ranges that
  11   they otherwise wouldn't be capable of accessing.
  12
  13   Example: 32-bit DMA to 64-bit physical addresses
  14
  15 * Implement scatter-gather at page level granularity so that the device does
  16   not have to.
  17
  18 * Provide system protection against "rogue" DMA by forcing all accesses to go
  19   through the IOMMU and faulting when encountering accesses to unmapped
  20   address regions.
  21
  22 * Provide address space isolation between multiple contexts.
  23
  24   Example: Virtualization
  25
  26 Device nodes compatible with this binding represent hardware with some of the
  27 above capabilities.
  28
  29 IOMMUs can be single-master or multiple-master. Single-master IOMMU devices
  30 typically have a fixed association to the master device, whereas multiple-
  31 master IOMMU devices can translate accesses from more than one master.
  32
  33 The device tree node of the IOMMU device's parent bus must contain a valid
  34 "dma-ranges" property that describes how the physical address space of the
  35 IOMMU maps to memory. An empty "dma-ranges" property means that there is a
  36 1:1 mapping from IOMMU to memory.
  37
  38 Required properties:
  39 --------------------
  40 - #iommu-cells: The number of cells in an IOMMU specifier needed to encode an
  41   address.
  42
  43 The meaning of the IOMMU specifier is defined by the device tree binding of
  44 the specific IOMMU. Below are a few examples of typical use-cases:
  45
  46 - #iommu-cells = <0>: Single master IOMMU devices are not configurable and
  47   therefore no additional information needs to be encoded in the specifier.
  48   This may also apply to multiple master IOMMU devices that do not allow the
  49   association of masters to be configured. Note that an IOMMU can by design
  50   be multi-master yet only expose a single master in a given configuration.
  51   In such cases the number of cells will usually be 1 as in the next case.
  52 - #iommu-cells = <1>: Multiple master IOMMU devices may need to be configured
  53   in order to enable translation for a given master. In such cases the single
  54   address cell corresponds to the master device's ID. In some cases more than
  55   one cell can be required to represent a single master ID.
  56 - #iommu-cells = <4>: Some IOMMU devices allow the DMA window for masters to
  57   be configured. The first cell of the address in this may contain the master
  58   device's ID for example, while the second cell could contain the start of
  59   the DMA window for the given device. The length of the DMA window is given
  60   by the third and fourth cells.
  61
  62 Note that these are merely examples and real-world use-cases may use different
  63 definitions to represent their individual needs. Always refer to the specific
  64 IOMMU binding for the exact meaning of the cells that make up the specifier.
  65
  66
  67 IOMMU master node:
  68 ==================
  69
  70 Devices that access memory through an IOMMU are called masters. A device can
  71 have multiple master interfaces (to one or more IOMMU devices).
  72
  73 Required properties:
  74 --------------------
  75 - iommus: A list of phandle and IOMMU specifier pairs that describe the IOMMU
  76   master interfaces of the device. One entry in the list describes one master
  77   interface of the device.
  78
  79 When an "iommus" property is specified in a device tree node, the IOMMU will
  80 be used for address translation. If a "dma-ranges" property exists in the
  81 device's parent node it will be ignored. An exception to this rule is if the
  82 referenced IOMMU is disabled, in which case the "dma-ranges" property of the
  83 parent shall take effect. Note that merely disabling a device tree node does
  84 not guarantee that the IOMMU is really disabled since the hardware may not
  85 have a means to turn off translation. But it is invalid in such cases to
  86 disable the IOMMU's device tree node in the first place because it would
  87 prevent any driver from properly setting up the translations.
  88
  89
  90 Notes:
  91 ======
  92
  93 One possible extension to the above is to use an "iommus" property along with
  94 a "dma-ranges" property in a bus device node (such as PCI host bridges). This
  95 can be useful to describe how children on the bus relate to the IOMMU if they
  96 are not explicitly listed in the device tree (e.g. PCI devices). However, the
  97 requirements of that use-case haven't been fully determined yet. Implementing
  98 this is therefore not recommended without further discussion and extension of
  99 this binding.
 100
 101
 102 Examples:
 103 =========
 104
 105 Single-master IOMMU:
 106 --------------------
 107
 108         iommu {
 109                 #iommu-cells = <0>;
 110         };
 111
 112         master {
 113                 iommus = <&{/iommu}>;
 114         };
 115
 116 Multiple-master IOMMU with fixed associations:
 117 ----------------------------------------------
 118
 119         /* multiple-master IOMMU */
 120         iommu {
 121                 /*
 122                  * Masters are statically associated with this IOMMU and share
 123                  * the same address translations because the IOMMU does not
 124                  * have sufficient information to distinguish between masters.
 125                  *
 126                  * Consequently address translation is always on or off for
 127                  * all masters at any given point in time.
 128                  */
 129                 #iommu-cells = <0>;
 130         };
 131
 132         /* static association with IOMMU */
 133         master@1 {
 134                 reg = <1>;
 135                 iommus = <&{/iommu}>;
 136         };
 137
 138         /* static association with IOMMU */
 139         master@2 {
 140                 reg = <2>;
 141                 iommus = <&{/iommu}>;
 142         };
 143
 144 Multiple-master IOMMU:
 145 ----------------------
 146
 147         iommu {
 148                 /* the specifier represents the ID of the master */
 149                 #iommu-cells = <1>;
 150         };
 151
 152         master@1 {
 153                 /* device has master ID 42 in the IOMMU */
 154                 iommus = <&{/iommu} 42>;
 155         };
 156
 157         master@2 {
 158                 /* device has master IDs 23 and 24 in the IOMMU */
 159                 iommus = <&{/iommu} 23>, <&{/iommu} 24>;
 160         };
 161
 162 Multiple-master IOMMU with configurable DMA window:
 163 ---------------------------------------------------
 164
 165         / {
 166                 iommu {
 167                         /*
 168                          * One cell for the master ID and one cell for the
 169                          * address of the DMA window. The length of the DMA
 170                          * window is encoded in two cells.
 171                          *
 172                          * The DMA window is the range addressable by the
 173                          * master (i.e. the I/O virtual address space).
 174                          */
 175                         #iommu-cells = <4>;
 176                 };
 177
 178                 master {
 179                         /* master ID 42, 4 GiB DMA window starting at 0 */
 180                         iommus = <&{/iommu}  42  0  0x1 0x0>;
 181                 };
 182         };