repository·main·Indexed 41 days ago
https://github.com/riscv-non-isa/riscv-iommuThe ratified RISC-V IOMMU specification, including source files for PDF documentation and a reference model. The project provides libiommu.a for specification implementation and libtables.a for building page and directory tables (G-stage, S-stage, and VS-stage). It includes APIs for test bench implementation, register access, and address translation from Guest Physical Address (GPA) to System Physical Address (SPA).
The RISC-V IOMMU architecture is defined by a Base Architecture Specification and several standard extensions. As of version 20260222, the following components are included in the ratified specification:
iohgatp.MODE is set to Bare, the msiptp.MODE must be set to Off. This is a non-strictly backward-compatible requirement introduced in version 20260222.The ta field within a Process-context (PC) defines access permissions and identity. The PC is valid only if PC.ta.V == 1.
V (Valid): Must be 1 for the PC to be used.ENS (Enable-Supervisory-access): If 1, transactions requesting supervisor privilege are allowed. If 0, they are treated as unsupported.SUM (Permit Supervisor User Memory access): When ENS is 1, this bit controls if supervisor transactions can access pages where the PTE U bit is set to 1. If SUM is 0, such access is disallowed.PSCID (Process soft-context ID): Acts as the address space ID for the process when first-stage translation is not Bare.Translation attributes (ta) layout:
[bits: 1] V
[bits: 1] ENS
[bits: 1] SUM
[bits: 9] reserved
[bits: 20] PSCID
[bits: 32] reservedVersion 1.0 of the RISC-V IOMMU specification supports several key features for device and process isolation and address translation. Developers can discover the specific features supported by a particular hardware implementation by reading the capabilities register.
/* Use the capabilities register to discover supported features */
read_register(CAP);The Process Directory Table (PDT) uses a hierarchical structure to locate Process Contexts (PC). Entries can be either non-leaf or leaf entries.
A valid non-leaf entry (V==1) contains the Physical Page Number (PPN) of the next-level PDT.
The leaf PDT page is indexed by PDI[0] and contains the 16-byte Process-context (PC).
Non-leaf process-directory-table entry:
[bits: 1] V (Valid)
[bits: 9] reserved
[bits: 44] PPN
[bits: 10] reserved
Leaf PDT entry (Process-context):
[bits: 64] Translation-attributes (ta)
[bits: 64] First-stage-context (fsc)To mitigate the performance overhead of walking page tables in memory, the IOMMU employs an IOMMU Address Translation Cache (IOATC).
To optimize the cache and simplify invalidation, software can use:
GSCID (Guest soft-context identifier): Identifies a collection of devices assigned to the same VM. The IOMMU uses this to tag IOATC entries.PSCID (Process soft-context identifier): Identifies a collection of processes sharing a virtual address space.Additionally, some devices support Address Translation Services (ATS), providing a device-side cache called a DevATC. This allows the device to share the caching responsibility and reduce IOATC 'thrashing' by prefetching translations.
The IOMMU may implement a RAS architecture to enable error detection, logging (severity, nature, and location), and error reporting.
ddtp, cqb registers) may lead to a failed state. In this state, the IOMMU may request the IO bridge to abort all incoming transactions.If an error affects only the current transaction but allows the IOMMU to continue service, the IOMMU should abort the transaction and queue a fault record in the FQ. For PCIe, a Completer Abort (CA) response is appropriate. Use the following cause codes for reporting:
| Cause Code | Description |
|---|---|
268 | DDT data corruption |
269 | PDT data corruption |
270 | MSI PT data corruption |
271 | MSI MRIF data corruption |
272 | Internal data-path error |
274 | First/second-stage PT data corruption |
Note: If the IO bridge cannot uniquely signal deferred errors, the IOMMU may report them as general access faults instead of using these specific cause codes.
When MSI address translation is enabled (DC.msiptp.MODE != Off), the IOMMU identifies incoming writes as MSIs if they target a virtual interrupt file.
Translation Modes for MSI PTEs:
M == 3): The translated address is msipte.PPN << 12 | A[11:0].M == 1): Used for Message Redirect Interrupt Files. The IOMMU identifies the destination MRIF address and the notice MSI data value. This mode requires capabilities.MSI_MRIF == 1.Note: MSI PTEs do not have Accessed (A) or Dirty (D) bits. The IOMMU may treat them as always set.
The IOMMU uses a two-stage translation process to convert an I/O Virtual Address (IOVA) to a Supervisor Physical Address (SPA). Each stage can be configured with a specific virtual memory scheme. A scheme set to Bare performs no translation or protection.
Depending on the configuration of the two stages, the IOVA represents different address types:
| IOVA Type | 1st Stage | 2nd Stage | Description |
|---|---|---|---|
| SPA | Bare | Bare | No translation or protection performed. |
| GPA | Bare | Active | 1st stage is disabled; 2nd stage translates Guest Physical Address to SPA. |
| VA | Active | Bare | 2nd stage is disabled; 1st stage translates Virtual Address to SPA. |
| VA | Active | Active | Two-stage translation: 1st stage translates VA to GPA, 2nd stage translates GPA to SPA. |
This model allows for different use cases, such as a native OS (VA to SPA) or a hypervisor providing direct device assignment to a VM (GPA to SPA).
The IOMMU interacts with software using three circular buffer in-memory queues. Each queue uses a head (controlled by the consumer) and a tail (controlled by the producer) to manage data flow.
head == tail.tail == (head - 1) (Effective size is $N-1$ for a queue of size $N$).The fsc field controls first-stage address translation and protection.
MODE: Determines the paged virtual-memory scheme (e.g., Sv39, Sv48, Sv57, Sv32, or Bare). The supported modes are constrained by the DC.tc.SXL field.PPN: If MODE is not Bare, this field holds the PPN of the root page of the first-stage page table. In two-stage translation, this is a Guest PPN.First-Stage context (fsc) layout:
[bits: 44] PPN
[bits: 16] reserved
[bits: 4] MODEThe Input-Output Memory Management Unit (IOMMU) connects DMA-capable I/O devices to system memory. It uses unique identifiers to locate device contexts and process contexts in software-supplied data structures.
Key identifiers include:
device_id: A unique identifier (up to 24-bit) for the originating device. In PCIe, this is the Routing Identifier (RID), consisting of a 8-bit Bus number, 5-bit Device number, and 3-bit Function number (optionally including an 8-bit Segment number).process_id: A unique identifier (up to 20-bit) used for Shared Virtual Addressing (SVA). In PCIe, this is the Process Address Space Identifier (PASID).Software uses these IDs to traverse Device-directory-tables (DDT) and Process-directory-tables (PDT) to find the appropriate translation rules.