Documentation/devicetree/bindings/iommu/iommu.txt

Source file repositories/reference/linux-study-clean/Documentation/devicetree/bindings/iommu/iommu.txt

File Facts

System
Linux kernel
Corpus path
Documentation/devicetree/bindings/iommu/iommu.txt
Extension
.txt
Size
7440 bytes
Lines
207
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

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

Annotation

Implementation Notes