183 lines
6 KiB
Plaintext
183 lines
6 KiB
Plaintext
This document describes the generic device tree binding for IOMMUs and their
|
|
master(s).
|
|
|
|
|
|
IOMMU device node:
|
|
==================
|
|
|
|
An IOMMU can provide the following services:
|
|
|
|
* Remap address space to allow devices to access physical memory ranges that
|
|
they otherwise wouldn't be capable of accessing.
|
|
|
|
Example: 32-bit DMA to 64-bit physical addresses
|
|
|
|
* Implement scatter-gather at page level granularity so that the device does
|
|
not have to.
|
|
|
|
* Provide system protection against "rogue" DMA by forcing all accesses to go
|
|
through the IOMMU and faulting when encountering accesses to unmapped
|
|
address regions.
|
|
|
|
* Provide address space isolation between multiple contexts.
|
|
|
|
Example: Virtualization
|
|
|
|
Device nodes compatible with this binding represent hardware with some of the
|
|
above capabilities.
|
|
|
|
IOMMUs can be single-master or multiple-master. Single-master IOMMU devices
|
|
typically have a fixed association to the master device, whereas multiple-
|
|
master IOMMU devices can translate accesses from more than one master.
|
|
|
|
The device tree node of the IOMMU device's parent bus must contain a valid
|
|
"dma-ranges" property that describes how the physical address space of the
|
|
IOMMU maps to memory. An empty "dma-ranges" property means that there is a
|
|
1:1 mapping from IOMMU to memory.
|
|
|
|
Required properties:
|
|
--------------------
|
|
- #iommu-cells: The number of cells in an IOMMU specifier needed to encode an
|
|
address.
|
|
|
|
The meaning of the IOMMU specifier is defined by the device tree binding of
|
|
the specific IOMMU. Below are a few examples of typical use-cases:
|
|
|
|
- #iommu-cells = <0>: Single master IOMMU devices are not configurable and
|
|
therefore no additional information needs to be encoded in the specifier.
|
|
This may also apply to multiple master IOMMU devices that do not allow the
|
|
association of masters to be configured. Note that an IOMMU can by design
|
|
be multi-master yet only expose a single master in a given configuration.
|
|
In such cases the number of cells will usually be 1 as in the next case.
|
|
- #iommu-cells = <1>: Multiple master IOMMU devices may need to be configured
|
|
in order to enable translation for a given master. In such cases the single
|
|
address cell corresponds to the master device's ID. In some cases more than
|
|
one cell can be required to represent a single master ID.
|
|
- #iommu-cells = <4>: Some IOMMU devices allow the DMA window for masters to
|
|
be configured. The first cell of the address in this may contain the master
|
|
device's ID for example, while the second cell could contain the start of
|
|
the DMA window for the given device. The length of the DMA window is given
|
|
by the third and fourth cells.
|
|
|
|
Note that these are merely examples and real-world use-cases may use different
|
|
definitions to represent their individual needs. Always refer to the specific
|
|
IOMMU binding for the exact meaning of the cells that make up the specifier.
|
|
|
|
|
|
IOMMU master node:
|
|
==================
|
|
|
|
Devices that access memory through an IOMMU are called masters. A device can
|
|
have multiple master interfaces (to one or more IOMMU devices).
|
|
|
|
Required properties:
|
|
--------------------
|
|
- iommus: A list of phandle and IOMMU specifier pairs that describe the IOMMU
|
|
master interfaces of the device. One entry in the list describes one master
|
|
interface of the device.
|
|
|
|
When an "iommus" property is specified in a device tree node, the IOMMU will
|
|
be used for address translation. If a "dma-ranges" property exists in the
|
|
device's parent node it will be ignored. An exception to this rule is if the
|
|
referenced IOMMU is disabled, in which case the "dma-ranges" property of the
|
|
parent shall take effect. Note that merely disabling a device tree node does
|
|
not guarantee that the IOMMU is really disabled since the hardware may not
|
|
have a means to turn off translation. But it is invalid in such cases to
|
|
disable the IOMMU's device tree node in the first place because it would
|
|
prevent any driver from properly setting up the translations.
|
|
|
|
|
|
Notes:
|
|
======
|
|
|
|
One possible extension to the above is to use an "iommus" property along with
|
|
a "dma-ranges" property in a bus device node (such as PCI host bridges). This
|
|
can be useful to describe how children on the bus relate to the IOMMU if they
|
|
are not explicitly listed in the device tree (e.g. PCI devices). However, the
|
|
requirements of that use-case haven't been fully determined yet. Implementing
|
|
this is therefore not recommended without further discussion and extension of
|
|
this binding.
|
|
|
|
|
|
Examples:
|
|
=========
|
|
|
|
Single-master IOMMU:
|
|
--------------------
|
|
|
|
iommu {
|
|
#iommu-cells = <0>;
|
|
};
|
|
|
|
master {
|
|
iommus = <&{/iommu}>;
|
|
};
|
|
|
|
Multiple-master IOMMU with fixed associations:
|
|
----------------------------------------------
|
|
|
|
/* multiple-master IOMMU */
|
|
iommu {
|
|
/*
|
|
* Masters are statically associated with this IOMMU and share
|
|
* the same address translations because the IOMMU does not
|
|
* have sufficient information to distinguish between masters.
|
|
*
|
|
* Consequently address translation is always on or off for
|
|
* all masters at any given point in time.
|
|
*/
|
|
#iommu-cells = <0>;
|
|
};
|
|
|
|
/* static association with IOMMU */
|
|
master@1 {
|
|
reg = <1>;
|
|
iommus = <&{/iommu}>;
|
|
};
|
|
|
|
/* static association with IOMMU */
|
|
master@2 {
|
|
reg = <2>;
|
|
iommus = <&{/iommu}>;
|
|
};
|
|
|
|
Multiple-master IOMMU:
|
|
----------------------
|
|
|
|
iommu {
|
|
/* the specifier represents the ID of the master */
|
|
#iommu-cells = <1>;
|
|
};
|
|
|
|
master@1 {
|
|
/* device has master ID 42 in the IOMMU */
|
|
iommus = <&{/iommu} 42>;
|
|
};
|
|
|
|
master@2 {
|
|
/* device has master IDs 23 and 24 in the IOMMU */
|
|
iommus = <&{/iommu} 23>, <&{/iommu} 24>;
|
|
};
|
|
|
|
Multiple-master IOMMU with configurable DMA window:
|
|
---------------------------------------------------
|
|
|
|
/ {
|
|
iommu {
|
|
/*
|
|
* One cell for the master ID and one cell for the
|
|
* address of the DMA window. The length of the DMA
|
|
* window is encoded in two cells.
|
|
*
|
|
* The DMA window is the range addressable by the
|
|
* master (i.e. the I/O virtual address space).
|
|
*/
|
|
#iommu-cells = <4>;
|
|
};
|
|
|
|
master {
|
|
/* master ID 42, 4 GiB DMA window starting at 0 */
|
|
iommus = <&{/iommu} 42 0 0x1 0x0>;
|
|
};
|
|
};
|