rimt-main.adoc

RISC-V IO Mapping Table (RIMT)

The RISC-V IO Mapping Table shows the structure of RIMT. Apart from the basic header, RIMT can contain several nodes. Each node represents a component which can be an IOMMU, a PCIe root complex or a platform device.

Table 1. RISC-V IO Mapping Table

Field	Byte Length	Byte Offset	Description
Signature	4	0	'RIMT' signature for the RISC-V IO Mapping Table.
Length	4	4	The length of the table, in bytes, of the entire RIMT.
Revision	1	8	1
Checksum	1	9	The entire table must sum to zero.
OEMID	6	10	OEM ID.
OEM Table ID	8	16	For the RIMT, the table ID is the manufacturer model ID.
OEM Revision	4	24	OEM revision of the RIMT for the supplied OEM Table ID.
Creator ID	4	28	The vendor ID of the utility that created the table.
Creator Revision	4	32	The revision of the utility that created the table.
Number of RIMT Nodes	4	36	Number of nodes in the RIMT nodes array.
Offset to RIMT Node Array	4	40	The offset from the start of this table to the first node in RIMT node array.
Reserved	4	44	Must be zero.
RIMT Node Array	-	48	List of RIMT nodes in the platform. Nodes listed may be one of the types listed in RIMT Node Types. This structure for node types is defined in the following sections.

RIMT node structure types

RIMT node structures can be broadly classified as two types: one is the actual IOMMU node structure and the other is the device node structure for devices bound to an IOMMU. The device node structure can be further classified as PCIe root complex and platform device structures bound to an IOMMU. For example, in a system with a single IOMMU, RIMT should have at least two nodes. One for the IOMMU itself and another for the devices behind this particular IOMMU. RIMT Node Types lists possible types for those structures.

Table 2. RIMT Node Types

Value	Description
0	RISC-V IOMMU Node. See IOMMU Node
1	PCIe Root Complex Node. See PCIe Root Complex Node
2	Platform Device Node. See Platform Device Node
3-255	Reserved

IOMMU Node

The IOMMU may be implemented as a platform device or as a PCIe device. The IOMMU node is the structure in RIMT used to report the configuration and capabilities of each IOMMU in the system.

Table 3. IOMMU Node

Field	Byte Length	Byte Offset	Description
Type	1	0	0 - IOMMU Node.
Revision	1	1	1
Length	2	2	The length of this structure.
Reserved	2	4	Must be zero.
ID	2	6	Unique ID of this node in the RIMT which can be used to locate it in the RIMT node array. It can be simply the array index in the RIMT node array.
Hardware ID	8	8	ACPI ID of the IOMMU when it is a platform device or PCIe ID (Vendor ID + Device ID) for the PCIe IOMMU device. This field adheres to the _HID format described by the ACPI cite:[ACPI-SPEC] specification.
Base Address	8	16	Base address of the IOMMU registers. This field is valid only for an IOMMU that is a platform device. If IOMMU is a PCIe device, the base address of the IOMMU registers may be discovered from or programmed into the PCIe BAR of the IOMMU.
Flags	4	24	Bit 0: IOMMU is a PCIe device 1: The IOMMU is implemented as a PCIe device. 0: The IOMMU is implemented as a platform device. Bit 1: Proximity Domain valid 1: The Proximity Domain field has a valid value. 0: The Proximity Domain field does not have a valid value. Bit [31-2]: Reserved, must be zero
Proximity Domain	4	28	The Proximity Domain to which this IOMMU belongs. This is valid only when the "Proximity Domain Valid" flag is set. For optimal IOMMU performance, the in-memory data structures used by the IOMMU may be located in memory from this proximity domain.
PCIe Segment number	2	32	If the IOMMU is implemented as a PCIe device (Bit 0 of Flags is 1), then this field holds the PCIe segment on which this IOMMU is located.
PCIe B/D/F	2	34	If the IOMMU is implemented as a PCIe device (Bit 0 of Flags is 1), then this field provides the Bus/Device/Function of the IOMMU.
Number of interrupt wires	2	36	An IOMMU may signal IOMMU initiated interrupts using wires or as message signaled interrupts (MSI). When the IOMMU supports signaling interrupts using wires, this field provides the number of interrupt wires. This field must be 0 if the IOMMU does not support wire-based interrupt generation.
Interrupt wire array offset	2	38	The offset from the start of this node entry to the first entry of the Interrupt Wire Array. This field is valid only if "Number of interrupt wires" is not 0.
List of interrupt wires.
Interrupt wire array	8 * N	40	Array of Interrupt Wire Structures where N is the number of elements in the array. See Interrupt Wire Structure.

Table 4. Interrupt Wire Structure

Field	Byte Length	Byte Offset	Description
Interrupt Number	4	0	Interrupt number. This should be a Global System Interrupt (GSI) number. These are wired interrupts with GSI numbers mapping to a particular PLIC or APLIC. The OSPM determines the mapping of the Global System Interrupts by determining how many interrupt inputs each PLIC or APLIC supports and by determining the global system interrupt base for each PLIC / APLIC.
Flags	4	4	Bit 0: Interrupt Mode 0: Edge Triggered. 1: Level Triggered. Bit 1: Interrupt Polarity 0: Active Low. 1: Active High. Bit [31-2]: Reserved, must be zero

PCIe Root Complex Node

The PCIe root complex node is the logical PCIe root complex which can be used to represent an entire physical root complex, an RCiEP/set of RCiEPs, a standalone PCIe device or the hierarchy below a PCIe host bridge.

Table 5. PCIe Root Complex Node

Field	Byte Length	Byte Offset	Description
Type	1	0	1 - PCIe Root Complex Node.
Revision	1	1	1
Length	2	2	The length of this structure.
Reserved	2	4	Must be zero.
ID	2	6	Unique ID of this node in the RIMT which can be used to locate it in the RIMT node array. It can be simply the array index in the RIMT node array.
Flags	4	8	Bit 0: ATS support 0: ATS is not supported in this root complex. 1: ATS supported in this root complex. Bit 1: PRI support 0: PRI is not supported in this root complex. 1: PRI is supported in this root complex. Bit [31-2]: Reserved, must be zero
Reserved	2	12	Must be zero.
PCIe Segment number	2	14	The PCIe segment number, as in MCFG and as returned by _SEG method in the ACPI namespace.
ID mapping array offset	2	16	The offset from the start of this node to the start of the ID mapping array.
Number of ID mappings	2	18	Number of elements in the ID mapping array.
List of ID mappings
ID mapping array	20 * N	20	Array of ID mapping structures where N is the number of ID mapping structures. See ID Mapping Structure.

The ID mapping structure provides information on how devices are connected to an IOMMU. The devices may be natively identified by a source ID but the platform may use a remapped ID to identify transactions from the device to the IOMMU.

For PCIe devices, source ID is the 16-bit triplet of PCIe bus number (8-bit), device number (5-bit), and function number (3-bit) (collectively known as routing identifier or RID). A range of source IDs must map to a single IOMMU only. If there are multiple root complexes with the same PCIe segment number, then their source ID ranges must not overlap. For each ACPI device object of the root complex which belongs to the same PCIe segment, the firmware must include the Device Specific Method (_DSM), Function Index 5, for preserving boot configurations as defined by the PCI Firmware Specification cite:[PCI-FW-SPEC]. The _DSM method must return zero to indicate that the Operating System must preserve PCIe resource assignments made by the firmware at boot time.

For platform devices, it is the implementation specific ID and managed by the device driver. Each ID mapping array entry provides a mapping from a range of source IDs to the corresponding device IDs that will be used at the input to the IOMMU. See [Mapping-Examples] for an example of ID mapping structures.

Table 6. ID Mapping Structure

Field	Byte Length	Byte Offset	Description
Source ID Base	4	0	The base of a range of source IDs mapped by this entry to a range of device IDs that will be used at input to the IOMMU.
Number of IDs	4	4	Number of IDs in the range. The range must include the IDs of devices that may be enumerated later during OS boot (For example, SR-IOV Virtual Functions).
Destination Device ID Base	4	8	The base of the destination ID range as mapped by this entry. This is the device_id as defined by the RISC-V IOMMU specification cite:[IOMMU-SPEC]
Destination IOMMU Offset	4	12	The destination IOMMU with which the these IDs are associated. This field is the offset of the RISC-V IOMMU node from the start of the RIMT table.
Flags	4	16	Bit 0: ATS Required 0: ATS does not need to be enabled for the device to function. 1: ATS needs to be enabled for the device to function. Bit 1: PRI Required 0: PRI does not need to be enabled for the device to function. 1: PRI needs to be enabled for the device to function. Bit [31-2]: Reserved, must be zero

Platform Device Node

There may be non-PCIe platform devices which are enumerated using Differentiated System Description Table(DSDT). These devices may have one or more source IDs in the mapping table, but they can have their own scheme to define the source IDs. Hence, those source IDs can only be unique to the ACPI platform device. The interpretation of those source IDs is expected to be managed by the platform device’s device driver.

Table 7. Platform Device Node

Field	Byte Length	Byte Offset	Description
Type	1	0	2 - Platform Device Node.
Revision	1	1	1
Length	2	2	The length of this structure.
Reserved	2	4	Must be zero.
ID	2	6	Unique ID of this node in the RIMT which can be used to locate it in the RIMT node array. It can be simply the array index in the RIMT node array.
ID mapping array offset	2	8	The offset from the start of this node to the start of the ID mapping array.
Number of ID mappings	2	10	Number of elements in the ID mapping array.
Device Object Name	M	12	Null terminated ASCII string. Full path to the device object in the ACPI namespace.
Padding	P	12 + M	Pad with zeros to align the ID mapping array at 4-byte offset.
List of ID mappings.
ID Mapping Array	20 * N	12 + M + P	Array of ID mapping structures where N is the number of ID mapping structures. See ID Mapping Structure.