From de05db1e2836d93124f6b38b1289d63e48e48f4e Mon Sep 17 00:00:00 2001 From: Sunil V L Date: Thu, 5 Sep 2024 12:21:43 +0530 Subject: [PATCH] Reorganize individual chapters as separate files Signed-off-by: Sunil V L --- Makefile | 47 ++---- src/bibliography.adoc | 8 +- src/intro.adoc | 6 + src/mapping-example.adoc | 19 +++ src/rimt-main.adoc | 275 +++++++++++++++++++++++++++++++ src/rimt-spec.adoc | 342 ++------------------------------------- src/terms.adoc | 12 ++ 7 files changed, 338 insertions(+), 371 deletions(-) create mode 100644 src/intro.adoc create mode 100644 src/mapping-example.adoc create mode 100644 src/rimt-main.adoc create mode 100644 src/terms.adoc diff --git a/Makefile b/Makefile index abbb6d6..a36cc09 100644 --- a/Makefile +++ b/Makefile @@ -12,27 +12,16 @@ # This Makefile is designed to automate the process of building and packaging # the Doc Template for RISC-V Extensions. -DOCS := \ - rimt-spec.adoc - DATE ?= $(shell date +%Y-%m-%d) -VERSION ?= 1.0.0-rc1 +VERSION ?= v1.0.0-rc1 REVMARK ?= Draft -DOCKER_IMG := riscvintl/riscv-docs-base-container-image:latest -ifneq ($(SKIP_DOCKER),true) - DOCKER_CMD := docker run --rm -v ${PWD}:/build -w /build \ - ${DOCKER_IMG} \ - /bin/sh -c - DOCKER_QUOTE := " -endif +DOCKER_RUN := docker run --rm -v ${PWD}:/build -w /build \ +riscvintl/riscv-docs-base-container-image:latest -SRC_DIR := src +SRC_DIR := ./src BUILD_DIR := build +HEADER_SOURCE := ${SRC_DIR}/rimt-spec.adoc -DOCS_PDF := $(DOCS:%.adoc=%.pdf) -DOCS_HTML := $(DOCS:%.adoc=%.html) - -XTRA_ADOC_OPTS := ASCIIDOCTOR_PDF := asciidoctor-pdf ASCIIDOCTOR_HTML := asciidoctor OPTIONS := --trace \ @@ -43,28 +32,16 @@ OPTIONS := --trace \ -a revdate=${DATE} \ -a pdf-fontsdir=docs-resources/fonts \ -a pdf-theme=docs-resources/themes/riscv-pdf.yml \ - $(XTRA_ADOC_OPTS) \ - -D build \ + -D $(BUILD_DIR) \ --failure-level=ERROR REQUIRES := --require=asciidoctor-bibtex \ --require=asciidoctor-diagram \ - --require=asciidoctor-lists \ --require=asciidoctor-mathematical -.PHONY: all build clean build-container build-no-container build-docs +.PHONY: all build clean build-container build-no-container all: build -build-docs: $(DOCS_PDF) $(DOCS_HTML) - -vpath %.adoc $(SRC_DIR) - -%.pdf: %.adoc - $(DOCKER_CMD) $(DOCKER_QUOTE) $(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) $< $(DOCKER_QUOTE) - -%.html: %.adoc - $(DOCKER_CMD) $(DOCKER_QUOTE) $(ASCIIDOCTOR_HTML) $(OPTIONS) $(REQUIRES) $< $(DOCKER_QUOTE) - build: @echo "Checking if Docker is available..." @if command -v docker >/dev/null 2>&1 ; then \ @@ -77,18 +54,16 @@ build: build-container: @echo "Starting build inside Docker container..." - $(MAKE) build-docs + $(DOCKER_RUN) /bin/sh -c "$(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) $(HEADER_SOURCE)" + $(DOCKER_RUN) /bin/sh -c "$(ASCIIDOCTOR_HTML) $(OPTIONS) $(REQUIRES) $(HEADER_SOURCE)" @echo "Build completed successfully inside Docker container." build-no-container: @echo "Starting build..." - $(MAKE) SKIP_DOCKER=true build-docs + $(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) $(HEADER_SOURCE) + $(ASCIIDOCTOR_HTML) $(OPTIONS) $(REQUIRES) $(HEADER_SOURCE) @echo "Build completed successfully." -# Update docker image to latest -docker-pull-latest: - docker pull ${DOCKER_IMG} - clean: @echo "Cleaning up generated files..." rm -rf $(BUILD_DIR) diff --git a/src/bibliography.adoc b/src/bibliography.adoc index 4cc3eb7..9259fa5 100644 --- a/src/bibliography.adoc +++ b/src/bibliography.adoc @@ -1,4 +1,8 @@ [bibliography] -== Bibliography +== References -bibliography::[] +* link:https://github.com/riscv-non-isa/riscv-iommu/releases/download/v1.0.0/riscv-iommu.pdf[RISC-V IOMMU Specification], v1.0.0 +* link:https://uefi.org/specs/ACPI/6.5/[ACPI Specification], Version: v6.5 + +// REVISIT +//bibliography::[] diff --git a/src/intro.adoc b/src/intro.adoc new file mode 100644 index 0000000..d5028f1 --- /dev/null +++ b/src/intro.adoc @@ -0,0 +1,6 @@ +== Introduction + +The RISC-V IO Mapping Table (RIMT) provides information about the RISC-V IOMMU and the relationship +between the IO topology and the IOMMU in ACPI based RISC-V platforms. The RIMT identifies which +components are behind IOMMU and how they are connected together. RISC-V IOMMU can be implemented as +either a PCI device or a platform device. diff --git a/src/mapping-example.adoc b/src/mapping-example.adoc new file mode 100644 index 0000000..d56752f --- /dev/null +++ b/src/mapping-example.adoc @@ -0,0 +1,19 @@ +[[Mapping-Examples]] +== ID Mapping Examples + +.PCIe device ID mapping example +[[pci_rc_id_mapping_2]] +[cols="2,2,2,4,1", width=95%, options="header"] +|=== +| *Source ID Base* | *Number of IDs* | *Destination Device ID Base* | *Destination IOMMU Offset* | *Flags* +| 0x0000 | 0x10 | 0x0 | IOMMU0_OFFSET_IN_RIMT | 0 +| 0x0100 | 0x10 | 0x10 | IOMMU0_OFFSET_IN_RIMT | 0 +|=== + +.Platform device ID mapping example +[[platform_id_mapping]] +[cols="2,2,2,4,1", width=95%, options="header"] +|=== +| *Source ID Base* | *Number of IDs* | *Destination Device ID Base* | *Destination IOMMU Offset* | *Flags* +| 0x0000 | 0x1 | 0x20 | IOMMU0_OFFSET_IN_RIMT | 0 +|=== diff --git a/src/rimt-main.adoc b/src/rimt-main.adoc new file mode 100644 index 0000000..534883a --- /dev/null +++ b/src/rimt-main.adoc @@ -0,0 +1,275 @@ +== RISC-V IO Mapping Table (RIMT) + +The <> shows the structure of RIMT. Apart from basic header, RIMT contains a number of RIMT +devices. Each device represents a component which can be an IOMMU, a PCI root complex or a namespace +device. + +.RISC-V IO Mapping Table +[[rimt]] +[cols="2,1,1,4", width=95%, options="header"] +|=== +| *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 | The revision of the structure + corresponding to the signature field + for this table. For the RIMT + confirming to this revision of the + specification, the revision is 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 devices | 4 | 36 | Number of devices in the RIMT device + array. +| Offset to RIMT device array | 4 | 40 | The offset from start of this table + to the first device in RIMT device + array. +| Reserved | 4 | 44 | Must be zero. +| RIMT device array | - | 48 | List of RIMT Devices in the + platform. Devices listed may be one + of the types listed in + <>. These + structure for device types is + defined in the following sections. +|=== + +=== RIMT device structure types +RIMT device structures can be broadly classified as two types. One is actual IOMMU device structure +and other is binding structures for devices bound to an IOMMU. The binding structures can be further +classified as PCI and platform devices bound to an IOMMU. For example, in a system with single +IOMMU, RIMT should have at least two entries. One for the IOMMU itself and other for the devices +behind this particular IOMMU. <> lists possible types to be used in those +structures. + +.RIMT Device Structure Types +[[rimt_device_structure]] +[cols="1,4", width=95%, options="header"] +|=== +| *Value* | *Description* +| 0 | RISC-V IOMMU Device Structure. See <> +| 1 | PCIe Root Complex Device Binding Structure. See <> +| 2 | Platform Device Binding Structure. See <> +| 3-255 | Reserved +|=== + +==== IOMMU Device Structure +The IOMMU may be implemented as a platform device or as a PCIe device. The IOMMU device structure is +the structure in RIMT used to report the configuration and capabilities of each IOMMU in the system. + +.IOMMU Device Structure +[[iommu_device_structure]] +[cols="2,1,1,4", width=95%, options="header"] +|=== +| *Field* | *Byte Length* | *Byte Offset* | *Description* +| Type | 1 | 0 | 0 - IOMMU device structure. +| Revision | 1 | 1 | 1 - Revision of this IOMMU + device structure. For structures + compliant to this version of the + specification, the Revision is 1. +| Length | 2 | 2 | The length of this structure in bytes + computed as (40 + 8 * N); where N is + the number of interrupt wires driven + by the IOMMU. +| Reserved | 2 | 4 | Must be zero. +| ID | 2 | 6 | Unique ID of this IOMMU. +| Hardware ID | 8 | 8 | ACPI ID. This field is valid only for + an IOMMU that is a platform device. +| 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 maybe discovered + from or programmed into the PCIe BAR + of the IOMMU. +| Flags | 4 | 24 +a| + +* 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 + device structure entry to the first + entry of the Interrupt Wire Array. + This field is valid only if "Number + of interrupt wires" is not 0. +4+|List of interrupt wires. +| Interrupt wire Array | 8 * N | 40 | Array of Interrupt Wire Structures. + See <>. +|=== + +.Interrupt Wire Structure +[[interrupt_wire_structure]] +[cols="2,1,1,4", width=95%, options="header"] +|=== +| *Field* | *Byte Length* | *Byte Offset* | *Description* +| Interrupt Number | 4 | 0 | Interrupt wire number. This should be a Global System Interrupt (GSI) number. +| Flags | 4 | 4 +a| + +* 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 Device Binding Structure +The PCIe root complex device binding structure is 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. + +.PCIe Root Complex Device Binding Structure +[[rc_device_structure]] +[cols="2,1,1,4", width=95%, options="header"] +|=== +| *Field* | *Byte Length* | *Byte Offset* | *Description* +|Type | 1 | 0 | 1 - PCIe Root Complex device binding + structure. +|Revision | 1 | 1 | 1 - Revision of this structure. For + structures compliant to this version of + the specification, the Revision is 1. +|Length | 2 | 2 | The length of this structure computed as + (20 + 20 * N). +|Reserved | 2 | 4 | Must be zero. +|ID | 2 | 6 | Unique ID. It can be simply the array + index in the RIMT devices array. +| Flags | 4 | 8 +a| + +* 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 PCI 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 device + to the start of the ID mapping array. +| Number of ID mappings | 2 | 18 | Number of elements in the ID mapping + array. +4+|List of ID mappings +| ID mapping array | 16 * N | 20 | Array of ID mapping structures. See + <>. +|=== + +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. 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 <> for example of ID mapping structures. + +.ID Mapping Structure +[[id_mapping_structure]] +[cols="2,1,1,4", width=95%, options="header"] +|=== +| *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. +| 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 + device node to the start of the RIMT + table. +| Flags | 4 | 16 +a| + +* 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 Binding Structure +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 +its own scheme to define the source IDs. Hence, those source IDs can be unique within the ACPI +device only. + +.Platform Device Binding Structure +[[platform_device_structure]] +[cols="2,1,1,4", width=95%, options="header"] +|=== +| *Field* | *Byte Length* | *Byte Offset* | *Description* +| Type | 1 | 0 | 2 - Platform Device Binding Structure. +| Revision | 1 | 1 | 1 - Revision of this structure. +| Length | 2 | 2 | The length of this structure + (12 + M + P + 20 * N). +| Reserved | 2 | 4 | Must be zero. +| ID | 2 | 6 | Unique ID of this device. +| ID mapping array offset | 2 | 8 | The offset from the start of this device + to the start of the ID mapping array. +| Number of ID mappings | 2 | 10 | Number of elements in the ID mapping array. +| Name | M | 12 | Null terminated ASCII string. Full path + to the device object in the ACPI namespace. +| Padding | P | 12 + M | Padding is to 32-bit word-aligned. +4+|List of ID mappings. +| ID Mapping Array | 20 * N | 12 + M + P | Array of ID mapping. See + <>. +|=== diff --git a/src/rimt-spec.adoc b/src/rimt-spec.adoc index d7899e9..2f0e35e 100644 --- a/src/rimt-spec.adoc +++ b/src/rimt-spec.adoc @@ -23,7 +23,7 @@ //:srcdir: src :bibtex-file: src/rimt.bib :bibtex-order: alphabetical -:bibtex-style: ieee +:bibtex-style: apa :icons: font :lang: en :listing-caption: Listing @@ -40,18 +40,6 @@ endif::[] :footnote: :xrefstyle: short -[preface] -== List of figures -list-of::image[hide_empty_section=true, enhanced_rendering=true] - -[preface] -== List of tables -list-of::table[hide_empty_section=true, enhanced_rendering=true] - -[preface] -== List of listings -list-of::listing[hide_empty_section=true, enhanced_rendering=true] - [WARNING] .This document is in the link:http://riscv.org/spec-state[Development state] ==== @@ -75,328 +63,16 @@ include::contributors.adoc[] [preface] include::changelog.adoc[] +[preface] +include::terms.adoc[] -== Introduction - -The RISC-V IO Mapping Table (RIMT) provides information about the RISC-V IOMMU and the relationship -between the IO topology and the IOMMU in ACPI based RISC-V platforms. The RIMT identifies which -components are behind IOMMU and how they are connected together. RISC-V IOMMU can be implemented as -either a PCI device or a platform device. - -== Terms and Abbreviations - -This specification uses the following terms and abbreviations: - -[cols="1,4", width=95%, options="header"] -|=== -| Term | Meaning - -| ACPI | Advanced Configuration and Power Interface Specification -| IOMMU | Input-Output Memory Management Unit -| RCiEP | Root Complex Integrated End Point -|=== - -== RISC-V IO Mapping Table (RIMT) - -The <> shows the structure of RIMT. Apart from basic header, RIMT contains a number of RIMT -devices. Each device represents a component which can be an IOMMU, a PCI root complex or a namespace -device. - -.RISC-V IO Mapping Table -[[rimt]] -[cols="2,1,1,4", width=95%, options="header"] -|=== -| *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 | The revision of the structure - corresponding to the signature field - for this table. For the RIMT - confirming to this revision of the - specification, the revision is 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 devices | 4 | 36 | Number of devices in the RIMT device - array. -| Offset to RIMT device array | 4 | 40 | The offset from start of this table - to the first device in RIMT device - array. -| Reserved | 4 | 44 | Must be zero. -| RIMT device array | - | 48 | List of RIMT Devices in the - platform. Devices listed may be one - of the types listed in - <>. These - structure for device types is - defined in the following sections. -|=== - -=== RIMT device structure types -RIMT device structures can be broadly classified as two types. One is actual IOMMU device structure -and other is binding structures for devices bound to an IOMMU. The binding structures can be further -classified as PCI and platform devices bound to an IOMMU. For example, in a system with single -IOMMU, RIMT should have at least two entries. One for the IOMMU itself and other for the devices -behind this particular IOMMU. <> lists possible types to be used in those -structures. - -.RIMT Device Structure Types -[[rimt_device_structure]] -[cols="1,4", width=95%, options="header"] -|=== -| *Value* | *Description* -| 0 | RISC-V IOMMU Device Structure. See <> -| 1 | PCIe Root Complex Device Binding Structure. See <> -| 2 | Platform Device Binding Structure. See <> -| 3-255 | Reserved -|=== - -==== IOMMU Device Structure -The IOMMU may be implemented as a platform device or as a PCIe device. The IOMMU device structure is -the structure in RIMT used to report the configuration and capabilities of each IOMMU in the system. - -.IOMMU Device Structure -[[iommu_device_structure]] -[cols="2,1,1,4", width=95%, options="header"] -|=== -| *Field* | *Byte Length* | *Byte Offset* | *Description* -| Type | 1 | 0 | 0 - IOMMU device structure. -| Revision | 1 | 1 | 1 - Revision of this IOMMU - device structure. For structures - compliant to this version of the - specification, the Revision is 1. -| Length | 2 | 2 | The length of this structure in bytes - computed as (40 + 8 * N); where N is - the number of interrupt wires driven - by the IOMMU. -| Reserved | 2 | 4 | Must be zero. -| ID | 2 | 6 | Unique ID of this IOMMU. -| Hardware ID | 8 | 8 | ACPI ID. This field is valid only for - an IOMMU that is a platform device. -| 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 maybe discovered - from or programmed into the PCIe BAR - of the IOMMU. -| Flags | 4 | 24 -a| - -* 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 - device structure entry to the first - entry of the Interrupt Wire Array. - This field is valid only if "Number - of interrupt wires" is not 0. -4+|List of interrupt wires. -| Interrupt wire Array | 8 * N | 40 | Array of Interrupt Wire Structures. - See <>. -|=== - -.Interrupt Wire Structure -[[interrupt_wire_structure]] -[cols="2,1,1,4", width=95%, options="header"] -|=== -| *Field* | *Byte Length* | *Byte Offset* | *Description* -| Interrupt Number | 4 | 0 | Interrupt wire number. This should be a Global System Interrupt (GSI) number. -| Flags | 4 | 4 -a| - -* 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 Device Binding Structure -The PCIe root complex device binding structure is 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. - -.PCIe Root Complex Device Binding Structure -[[rc_device_structure]] -[cols="2,1,1,4", width=95%, options="header"] -|=== -| *Field* | *Byte Length* | *Byte Offset* | *Description* -|Type | 1 | 0 | 1 - PCIe Root Complex device binding - structure. -|Revision | 1 | 1 | 1 - Revision of this structure. For - structures compliant to this version of - the specification, the Revision is 1. -|Length | 2 | 2 | The length of this structure computed as - (20 + 20 * N). -|Reserved | 2 | 4 | Must be zero. -|ID | 2 | 6 | Unique ID. It can be simply the array - index in the RIMT devices array. -| Flags | 4 | 8 -a| - -* 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 PCI 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 device - to the start of the ID mapping array. -| Number of ID mappings | 2 | 18 | Number of elements in the ID mapping - array. -4+|List of ID mappings -| ID mapping array | 16 * N | 20 | Array of ID mapping structures. See - <>. -|=== - -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. 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 <> for example of ID mapping structures. - -.ID Mapping Structure -[[id_mapping_structure]] -[cols="2,1,1,4", width=95%, options="header"] -|=== -| *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. -| 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 - device node to the start of the RIMT - table. -| Flags | 4 | 16 -a| - -* 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 Binding Structure -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 -its own scheme to define the source IDs. Hence, those source IDs can be unique within the ACPI -device only. - -.Platform Device Binding Structure -[[platform_device_structure]] -[cols="2,1,1,4", width=95%, options="header"] -|=== -| *Field* | *Byte Length* | *Byte Offset* | *Description* -| Type | 1 | 0 | 2 - Platform Device Binding Structure. -| Revision | 1 | 1 | 1 - Revision of this structure. -| Length | 2 | 2 | The length of this structure - (12 + M + P + 20 * N). -| Reserved | 2 | 4 | Must be zero. -| ID | 2 | 6 | Unique ID of this device. -| ID mapping array offset | 2 | 8 | The offset from the start of this device - to the start of the ID mapping array. -| Number of ID mappings | 2 | 10 | Number of elements in the ID mapping array. -| Name | M | 12 | Null terminated ASCII string. Full path - to the device object in the ACPI namespace. -| Padding | P | 12 + M | Padding is to 32-bit word-aligned. -4+|List of ID mappings. -| ID Mapping Array | 20 * N | 12 + M + P | Array of ID mapping. See - <>. -|=== - -[[Mapping-Examples]] -== ID Mapping Examples - -.PCIe device ID mapping example -[[pci_rc_id_mapping_2]] -[cols="2,2,2,4,1", width=95%, options="header"] -|=== -| *Source ID Base* | *Number of IDs* | *Destination Device ID Base* | *Destination IOMMU Offset* | *Flags* -| 0x0000 | 0x10 | 0x0 | IOMMU0_OFFSET_IN_RIMT | 0 -| 0x0100 | 0x10 | 0x10 | IOMMU0_OFFSET_IN_RIMT | 0 -|=== - -.Platform device ID mapping example -[[platform_id_mapping]] -[cols="2,2,2,4,1", width=95%, options="header"] -|=== -| *Source ID Base* | *Number of IDs* | *Destination Device ID Base* | *Destination IOMMU Offset* | *Flags* -| 0x0000 | 0x1 | 0x20 | IOMMU0_OFFSET_IN_RIMT | 0 -|=== +include::intro.adoc[] -== References +include::rimt-main.adoc[] -* link:https://github.com/riscv-non-isa/riscv-iommu/releases/download/v1.0.0/riscv-iommu.pdf[RISC-V IOMMU Specification], v1.0.0 -* link:https://uefi.org/specs/ACPI/6.5/[ACPI Specification], Version: v6.5 +include::mapping-example.adoc[] // The index must precede the bibliography -//include::index.adoc[] -//include::bibliography.adoc[] +include::index.adoc[] + +include::bibliography.adoc[] diff --git a/src/terms.adoc b/src/terms.adoc new file mode 100644 index 0000000..9570f1c --- /dev/null +++ b/src/terms.adoc @@ -0,0 +1,12 @@ +== Terms and Abbreviations + +This specification uses the following terms and abbreviations: + +[cols="1,4", width=95%, options="header"] +|=== +| Term | Meaning + +| ACPI | Advanced Configuration and Power Interface Specification +| IOMMU | Input-Output Memory Management Unit +| RCiEP | Root Complex Integrated End Point +|===