diff --git a/Makefile b/Makefile index f79e454..e2e0ab9 100644 --- a/Makefile +++ b/Makefile @@ -14,7 +14,7 @@ DATE ?= $(shell date +%Y-%m-%d) VERSION ?= v0.0.0 -REVMARK ?= Draft +REVMARK ?= \"This document is in development. Assume everything can change. See http://riscv.org/spec-state for details.\" DOCKER_RUN := docker run --rm -v ${PWD}:/build -w /build \ riscvintl/riscv-docs-base-container-image:latest diff --git a/about.adoc b/about.adoc deleted file mode 100644 index c57febc..0000000 --- a/about.adoc +++ /dev/null @@ -1,23 +0,0 @@ -[[about]] -== About this Document -=== Glossary -.Terms and definitions -[width=90%] -[%header, cols="5,20"] -|=== -| Term ^| Definition -| ACPI | Advanced Configuration and Power Interface Specification cite:[ACPI]. -| BRS | RISC-V Boot and Runtime Services. This document. -| BRS-I | Boot and Runtime Services Recipe targeting interoperation across different software suppliers. -| BRS-B | Boot and Runtime Services Recipe using a bespoke solution. -| DT | DeviceTree cite:[DT]. -| EBBR | Embedded Base Boot Requirements Specification cite:[EBBR]. -| OSV | Operating System Vendor. -| OS | Operating System or Hypervisor. -| Profile | RISC-V Profile cite:[Profile]. -| SBI | RISC-V Supervisor Binary Interface Specification cite:[SBI]. -| SMBIOS | System Management BIOS cite:[SMBIOS]. -| SoC | System on a chip, a combination of processor and supporting chipset logic in single package. -| System | A system is the entirety of a computing entity, including all elements in a platform (hardware, firmware) and software (hypervisor, operating system, user applications, user data). A system can be thought of both as a logical construct (e.g. a software stack) or physical construct (e.g. a notebook, a desktop, a server, a network switch, etc). -| UEFI | Unified Extensible Firmware Interface Specification cite:[UEFI]. -|=== diff --git a/acpi.adoc b/acpi.adoc index 20de1d2..a2512bc 100644 --- a/acpi.adoc +++ b/acpi.adoc @@ -3,67 +3,37 @@ The Advanced Configuration and Power Interface specification provides the OS-centric view of system configuration, various hardware resources, events and power management. -This section defines the BRS-I mandatory and optional ACPI requirements on top of cite:[ACPI] and cite:[UEFI]. Additional non-normative guidance may be found in the <>. - -A compliant system must: - -* [[acpi-64bit-clean]]Be 64-bits clean. -** RSDT must not be implemented, with RsdtAddress in RSDP set to 0. -** 32-bit address fields must be 0. -** <>. -* [[acpi-hw-reduced]]Implement the HW-Reduced ACPI Mode. -** No FACS table. -** <>. - -=== Additional ACPI Table Requirements - -This section lists additional requirements for the mandatory and -conditionally-required ACPI tables in a compliant system. - -[[acpi-pptt]] -==== PPTT (Processor Properties Table). - -The PPTT is mandatory even for systems with a simple hart topology. - -==== Conditionally Required ACPI Tables - -This section lists requirements for ACPI tables that depend on -features that may not be present in compliant systems. For example, -some systems may not have PCIe busses or a serial port. - -[[acpi-mcfg]] -===== MCFG - -The PCI Memory-mapped Configuration Space (MCFG) table cite:[PCIFW] must only be present -if and only if cite:[PCIFW] compatible non-hot-removable PCIe segments are made available -to the OS. - -* PCIe configuration space must be exposed to the OS in an ECAM-compatible (Enhanced Configuration Access Mechanism) manner. -* MCFG table must not require a custom vendor-specific PCIe root complex OS driver. - -Please see PCI Services in ACPI (cite:[ACPI], Section 4) for more ACPI requirements relating to PCIe support. - -<>. - -[[acpi-spcr]] -===== SPCR - -The Serial Port Console Redirection Table cite:[SPCR] is required on -systems where the graphics hardware is not present or not made -available to an OS loader via the standard UEFI -EFI_GRAPHICS_OUTPUT_PROTOCOL interface. In these cases, the table -provides essential configuration for an early OS boot console. - -Additional requirements: - -// Version 4 is WIP https://github.com/andreiw/ms-acpi-tables-for-riscv/tree/riscv_plus_improvements -* Revision 4 or later of SPCR. -* For NS16550-compatible UARTs: -** Use Interface Type 0x12 (16550-compatible with parameters defined in -Generic Address Structure). -** There must be a matching AML device object. - -<>. +This section defines the BRS-I mandatory and optional ACPI requirements on top of cite:[ACPI] and cite:[UEFI]. Additional non-normative guidance may be found in the <> section. + +[width=100%] +[%header, cols="5,25"] +|=== +| ID# ^| Requirement +| [[acpi-64bit-clean]]ACPI_010 a| Be 64-bits clean. + + * RSDT must not be implemented, with RsdtAddress in RSDP set to 0. + * 32-bit address fields must be 0. +2+| _<>._ +| [[acpi-hw-reduced]]ACPI_020 a| Implement the HW-Reduced ACPI Mode (no FACS table). +2+| _<>._ +| [[acpi-pptt]]ACPI_030 | The Processor Properties Table (PPTT) MUST be implemented, even on systems with a simple hart topology. +| ACPI_040 | The PCI Memory-mapped Configuration Space (MCFG) table cite:[PCIFW] MUST be present if and only if compatible non-hot-removable PCIe segments are made available to the OS. +| [[acpi-mcfg]]ACPI_050 a| An MCFG table, if present, MUST meet the following requirements: + + * PCIe configuration space must be exposed to the OS in an ECAM-compatible (Enhanced Configuration Access Mechanism) manner. + * MCFG table must not require a custom vendor-specific PCIe root complex OS driver. +2+| _See PCI Services in ACPI (cite:[ACPI], Section 4) for more ACPI requirements relating to PCIe support. <>._ +| ACPI_060 | A Serial Port Console Redirection Table cite:[SPCR] MUST be present on systems, where where the graphics hardware is not present or not made +available to an OS loader via the standard UEFI EFI_GRAPHICS_OUTPUT_PROTOCOL interface. +2+|_In these cases, the table provides essential configuration for an early OS boot console._ +| [[acpi-spcr]]ACPI_070 a| An SPCR table, if present, MUST meet the following requirements: + + * Revision 4 or later of SPCR. + * For NS16550-compatible UARTs: + ** Use Interface Type 0x12 (16550-compatible with parameters defined in Generic Address Structure). + ** There must be a matching AML device object. +2+| _<>_. +|=== [[acpi-aml]] === ACPI Methods and Objects @@ -73,37 +43,29 @@ objects. <>. -==== Device Methods and Objects -* _CCA: Cache Coherency Attribute. This object provides information +[width=100%] +[%header, cols="5,25"] +|=== +| ID# ^| Requirement +| AML_010 | The Cache Coherency Attribute (_CCA) device method MUST be implemented. +2+| _This object provides information about whether a device has to manage cache coherency and about hardware support. This object is mandatory for all devices that - can access CPU-visible memory. (cite:[ACPI] Section 6.2.17) -* _PRS: Possible Resource Settings. Not supported. -* _SRS: Set Resource Settings. Not supported. - -===== Harts and Hart Performance Control - -Harts must be defined under \_SB (System Bus) namespace and not in the deprecated \_PR (Processors) namespace. - -If the platform provides support for OS-directed hart performance control and power management, -then it must be exposed using Collaborative Processor Performance Control (CPPC, cite:[ACPI] Section 8.4.6). -Processor idle states must be described using Low Power Idle (LPI, cite:[ACPI] Section 8.4.3). - -===== PCIe Root Complex Devices - -* _CRS: Current Resource Settings -** PCIe Root Complex descriptors must not contain resources of type DWordIO, QWordIO or ExtendedIO as the legacy PCI I/O port space is not supported. - -[[acpi-tad]] -===== Time and Alarm Device - -UEFI Runtime Service should be used to provide time services to the -OS, unless the RTC is subject to arbitration issues between concurrent -OS and UEFI accesses to the underlying hardware. See <>. - -In situations where the Time and Alarm Device (TAD) depends on a + can access CPU-visible memory. (cite:[ACPI] Section 6.2.17)._ +| AML_020 | The Current Resource Setting (_CRS) device method for a PCIe Root Complex SHOULD NOT contain resources of type DWordIO, QWordIO or ExtendedIO. +2+| _Legacy PCI I/O BARs are uncommon in modern PCIe devices and support for PCI I/O space may complicate configuration of PCIe RC hardware in a compliant manner._ +| AML_030 | The Possible Resource Settings (_PRS) and Set Resource Settings (_SRS) device method SHOULD NOT be implemented. +2+| _ACPI resource descriptors are typically used to describe devices with fixed CSR regions that do not change. Flexible resource assignment is not supported by most modern ACPI OSes._ +| AML_040 | Per-hart device objects MUST be defined under \_SB (System Bus) namespace and not in the deprecated \_PR (Processors) namespace. +| AML_050 | Systems supporting OS-directed hart performance control and power management MUST expose these via Collaborative Processor Performance Control (CPPC, cite:[ACPI] Section 8.4.6). +| AML_060 | Processor idle states must be described using Low Power Idle (LPI, cite:[ACPI] Section 8.4.3). +| [[acpi-tad]] AML_070 | Systems with a Real-Time Clock on an OS-managed bus (e.g. I2C, subject to arbiration issues due to access to the bus by the OS) MUST implement the Time and Alarm Device (TAD). +2+| _Also see <>_. +| AML_080 | Systems implementing a TAD must be functional without additional system-specific OS drivers. +2+| _In situations where the Time and Alarm Device (TAD) depends on a vendor-specific OS driver for correct function (SPI, I2C, etc), the TAD must be functional if the OS driver is not loaded. That is, when a dependent driver is loaded, an AML method switches further accesses to go -through the driver-backed OperationRegion. +through the driver-backed OperationRegion._ +|=== diff --git a/appendices.adoc b/appendices.adoc deleted file mode 100644 index 34213e1..0000000 --- a/appendices.adoc +++ /dev/null @@ -1,22 +0,0 @@ -[[appendices]] -== Appendices -=== Firmware Implementation Guidance - -The guidance section is non-normative, and covers certain -implementation choices, suggestions, historical context, etc. - -[[recipes-guidance]] -==== Recipes Guidance -include::non-normative/recipes.adoc[] - -[[uefi-guidance]] -==== UEFI Implementation Guidance -include::non-normative/uefi.adoc[] - -[[acpi-guidance]] -==== ACPI Implementation Guidance -include::non-normative/acpi.adoc[] - -[[smbios-guidance]] -==== SMBIOS Implementation Guidance -include::non-normative/smbios.adoc[] diff --git a/brs.bib b/brs.bib index b3c3000..1b70cfd 100644 --- a/brs.bib +++ b/brs.bib @@ -57,4 +57,38 @@ @electronic{TcgAcpi @electronic{MSUefiCaRequirements, title = {UEFI memory mitigations}, url = {https://learn.microsoft.com/en-us/windows-hardware/drivers/bringup/uefi-ca-memory-mitigation-requirements}, +} +@electronic{RFC_2119, + title = {Key words for use in RFCs to Indicate Requirement Levels}, + url = {https://datatracker.ietf.org/doc/html/rfc2119} +} +@electronic{PCI, + title = {PCI Express® Base Specification Revision 6.0}, + url = {https://pcisig.com/pci-express-6.0-specification}, + year = {} +} +@electronic{Sstc, + title = {RISC-V "stimecmp / vstimecmp" Extension}, + url = {https://github.com/riscv/riscv-time-compare}, + year = {2021} +} +@electronic{Aia, + title = {The RISC-V Advanced Interrupt Architecture}, + url = {https://github.com/riscv/riscv-aia}, + year = {2023} +} +@electronic{Sscsrind, + title = {RISC-V Indirect CSR Access (Smcsrind/Sscsrind)}, + url = {https://github.com/riscv/riscv-indirect-csr-access}, + year = {2023} +} +@electronic{Smcdeleg, + title = {RISC-V Supervisor Counter Delegation Specification (Smcdeleg/Ssccfg)}, + url = {https://github.com/riscv/riscv-smcdeleg-ssccfg}, + year = {2024} +} +@electronic{PerfAnalysis, + title = {SIG: Performance Analysis}, + url = {https://lists.riscv.org/g/sig-perf-analysis}, + year = {2024} } \ No newline at end of file diff --git a/contributors.adoc b/contributors.adoc index bf10696..0200112 100644 --- a/contributors.adoc +++ b/contributors.adoc @@ -3,12 +3,5 @@ This RISC-V specification has been contributed to directly or indirectly by (in alphabetical order): [%hardbreaks] -* Aaron Durbin -* Andrew Jones -* Jared McNeill -* Heinrich Schuchardt -* Sunil V L -* Paul Walmsley -* Andrei Evgenievich Warkentin - -We express our gratitude to everyone that contributed to, reviewed, or improved the document through their comments and questions. +Aaron Durbin, Andrei Warkentin, Andrew Jones, Heinrich Schuchardt, +Jared McNeill, Paul Walmsley, Sunil V L diff --git a/hart.adoc b/hart.adoc index 7d544d9..2b0df03 100644 --- a/hart.adoc +++ b/hart.adoc @@ -1,9 +1,15 @@ [[hart]] == Hart Requirements -The BRS specification is minimally prescriptive on the RISC-V hart requirements. It is anticipated that detailed requirements will be driven by target market segment and product/solution requirements. The SEE mandates the minimal set required for a compliant system implementation of the BRS. -The BRS requires harts to least be compliant to: +A compliant system includes a RISC-V application processor and the requirements in this section apply solely to harts in the application processors of a system. + +The BRS specification is minimally prescriptive on the RISC-V hart requirements. It is anticipated that detailed requirements will be driven by target market segment and product/solution requirements. The SEE mandates the minimal set required for a compliant system implementation of the BRS. -* RVA20S64 Profile cite:[Profile], as BRS governs the interactions between 64-bit OS supervisor-mode software and 64-bit firmware, when employed. +[width=100%] +[%header, cols="5,25"] +|=== +| ID# ^| Requirement +| HR_010 | The RISC-V application processor harts MUST be compliant to RVA20S64 Profile cite:[Profile]. +2+| _The BRS governs the interactions between 64-bit OS supervisor-mode software and 64-bit firmware. These are minimum requirements allowing for the wide variety of existing and future hart implementations to be supported. It is expected that operating systems and hypervisors may impose additional profile/ISA requirements, depending on the use-case and application._ -These are minimum requirements allowing for the wide variety of existing and future hart implementations to be supported. It is expected that operating systems and hypervisors may impose additional profile/ISA requirements, depending on the use-case and application. +|=== diff --git a/header.adoc b/header.adoc index 40ce516..09b7a47 100644 --- a/header.adoc +++ b/header.adoc @@ -1,9 +1,6 @@ [[header]] :description: RISC-V Boot and Runtime Services Specification Document (BRS) :company: RISC-V.org -:revdate: 2/2023 -:revnumber: 1.0 -:revremark: This document is in development. Assume everything can change. See http://riscv.org/spec-state for details. :url-riscv: http://riscv.org :doctype: book :preface-title: Preamble @@ -14,11 +11,9 @@ // Settings: :experimental: :reproducible: -// needs to be changed? bug discussion started -//:WaveDromEditorApp: app/wavedrom-editor.app :imagesoutdir: images :bibtex-file: brs.bib -:bibtex-order: alphabetical +:bibtex-order: appearance :bibtex-style: ieee :icons: font :lang: en @@ -37,7 +32,7 @@ endif::[] :xrefstyle: short = RISC-V Boot and Runtime Services Specification (BRS) -Aaron Durbin; Andrei Warkentin; OS-A SEE Task Group +OS-A SEE Task Group // Preamble [WARNING] @@ -60,7 +55,6 @@ Copyright 2023 by RISC-V International. [preface] include::contributors.adoc[] -include::about.adoc[] include::intro.adoc[] include::recipes.adoc[] include::hart.adoc[] @@ -68,7 +62,7 @@ include::sbi.adoc[] include::uefi.adoc[] include::acpi.adoc[] include::smbios.adoc[] -include::appendices.adoc[] +include::non-normative/guidance.adoc[] //the index must precede the bibliography include::index.adoc[] diff --git a/intro.adoc b/intro.adoc index 247cbb4..d84ede6 100644 --- a/intro.adoc +++ b/intro.adoc @@ -1,10 +1,12 @@ [[intro]] == Introduction -The Boot and Runtime Services (BRS) specification provides the software requirements for system vendors and Operating System Vendors (OSVs) to interoperate with one another by providing expectations for the Operating System (OS) to utilize in acts of device discovery, system management, and other rich operations provided in this specification. The approach taken is to leverage industry standards as well as RISC-V ratified specifications. +The Boot and Runtime Services (BRS) specification defines a standardized set of software capabilities, that portable system software, such as operating systems and hypervisors, can rely on being present in an implementation to utilize in acts of device discovery, OS boot and hand-off, system management, and other operations. The BRS specification is targeting systems that implement S/U privilege modes, and optionally the HS privilege mode. This is the expected deployment for OSVs and system vendors in a typical ecosystem covering client systems up through server systems where software is provided by different vendors than the system vendor. +This specification standardizes the requires for software interfaces and capabilities by building on top of relevant industry and ratified RISC-V standards. + === Releases It is expected that the Boot and Runtime Services specification will periodically release a new specification. The determination of a new release will be based on the evaluation of significant changes to its underlying dependencies. @@ -15,4 +17,52 @@ The Boot and Runtime Services specification focuses on two solutions in the form === Testing and Conformance -There will be a set of tests to help aid with conformance of the Boot and Runtime Services specification. It can be found... +To be compliant with this specification, an implementation MUST support all mandatory requirements and MUST support the listed versions of the specifications. This standard set of capabilities MAY be extended by a specific implemenation with additional standard on custom capabilities, including compatible later versions of listed standard specifications. Portable system software MUST support the specified mandatory capabilities to the compliant with this specification. + +The requirements in this specification use the following format: + +[width=100%] +[%header, cols="5,20"] +|=== +| ID# ^| Requirement +| CAT_NNN | The `CAT` is a category prefix that logically groups the + requirements and is followed by 3 digits - `NNN` - assigning a + numeric ID to the requirement. + + + + The requirements use the key words "MUST", "MUST NOT", + "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", + "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" that are + to be interpreted as described in RFC 2119 cite:[RFC_2119] when, + and only when, they appear in all capitals, as shown here. When + these words are not capitalized, they have their normal English + meanings. +2+| _A requirement or a group of requirements may be followed by non-normative + text providing context or justification for the requirement. The + non-normative text may also be used to reference sources that are the + origin of the requirement._ +|=== + +=== Glossary + +Most terminology has the standard RISC-V meaning. This table captures other terms used in the document. Terms in the document prefixed by 'PCIe' have the meaning defined in the PCI Express (PCIe) Base Specification cite:[PCI] (even if they are not in this table). + +.Terms and definitions +[width=90%] +[%header, cols="5,20"] +|=== +| Term ^| Definition +| ACPI | Advanced Configuration and Power Interface Specification cite:[ACPI]. +| BRS | RISC-V Boot and Runtime Services. This document. +| BRS-I | Boot and Runtime Services Recipe targeting interoperation across different software suppliers. +| BRS-B | Boot and Runtime Services Recipe using a bespoke solution. +| DT | DeviceTree cite:[DT]. +| EBBR | Embedded Base Boot Requirements Specification cite:[EBBR]. +| OSV | Operating System Vendor. +| OS | Operating System or Hypervisor. +| Profile | RISC-V Profile cite:[Profile]. +| SBI | RISC-V Supervisor Binary Interface Specification cite:[SBI]. +| SMBIOS | System Management BIOS cite:[SMBIOS]. +| SoC | System on a chip, a combination of processor and supporting chipset logic in single package. +| System | A system is the entirety of a computing entity, including all elements in a platform (hardware, firmware) and software (hypervisor, operating system, user applications, user data). A system can be thought of both as a logical construct (e.g. a software stack) or physical construct (e.g. a notebook, a desktop, a server, a network switch, etc). +| UEFI | Unified Extensible Firmware Interface Specification cite:[UEFI]. +|=== diff --git a/non-normative/acpi.adoc b/non-normative/acpi.adoc index 3f1ec16..7e7cc92 100644 --- a/non-normative/acpi.adoc +++ b/non-normative/acpi.adoc @@ -6,7 +6,7 @@ The Operating System uses this address to locate all other ACPI tables. Certain implementations may make use of the RISC-V Functional Fixed hardware Specification cite:[FFH]. [[acpi-guidance-64bit-clean]] -===== 64-bits Clean +==== 64-bits Clean ACPI started as a specification for 32-bit systems, so certain tables with physical address pointers (e.g. RSDP, FADT) allow for reporting @@ -17,14 +17,14 @@ as the XSDT is a direct replacement). Thus, the ACPI tables are allowed to be located in any part of the physical address space. [[acpi-guidance-hw-reduced]] -===== Hardware-Reduced ACPI +==== Hardware-Reduced ACPI Compliant RISC-V systems only implement the HW-Reduced ACPI Model cite:[ACPI] (Section 4.1). This means the hardware portion of cite:[ACPI] (Section 4) is not required or supported. All functionality is instead provided through equivalent software-defined interfaces and the complexity in supporting ACPI is reduced. -===== Table Guidance +==== Table Guidance <> summarizes the minimum set of structures that must exist to support basic booting of RISC-V system with ACPI support. <> lists additional possible ACPI @@ -68,7 +68,7 @@ information about certain capabilities like ISA string, cache and MMU info. |=== [[acpi-guidance-aml]] -===== DSDT and SSDTs +==== DSDT and SSDTs The ACPI name space describes devices which cannot be enumerated by any other standard ways. These typically include SoC embedded memory-mapped I/O devices, such as UARTs, <> or CXL root complexes, GPIO controllers, etc. @@ -85,7 +85,7 @@ may choose to use SSDTs to: // Provide guidance here for PCIe RCs, perhaps leverage some of https://www.infradead.org/~mchehab/rst_conversion/PCI/acpi-info.html [[acpi-guidance-fadt]] -===== FADT +==== FADT cite:[ACPI] (Section 5.2.9) provides guidance on filling the Fixed ACPI Description Table for HW-reduced ACPI. @@ -93,7 +93,7 @@ Fixed ACPI Description Table for HW-reduced ACPI. Don't forget to select an appropriate Preferred PM Profile. [[acpi-guidance-madt]] -===== MADT +==== MADT RINTC (per-hart) structures are mandatory. Depending on the interrupt controller implemented by the system, the MADT will also contain either PLIC or IMSIC/APLIC structures. @@ -105,7 +105,7 @@ The PPTT Processor Properties Topology Table (PPTT) is to be used to describe affinities. [[acpi-guidance-pcie]] -===== PCIe +==== PCIe On some architectures, it became an industry accepted norm to describe PCIe implementations not compliant to the PCI Firmware Specification cite:[PCIFW] using specification-defined ACPI tables and objects. RISC-V systems compliant to the BRS must only expose ECAM-compatible implementations using the @@ -122,7 +122,7 @@ a DSDT/SSDT MMIO device object without making the OS aware of the underlying PCI // Provide guidance here on AML object used, including interrupt routing, why I/O space is not included. [[acpi-guidance-spcr]] -===== SPCR +==== SPCR Early serial console can be implemented using either an NS16550 UART (SPCR Interface Type 0x12) or SBI console (SPCR Interface Type 0x15). When SPCR describes SBI console, the OS must use diff --git a/non-normative/guidance.adoc b/non-normative/guidance.adoc new file mode 100644 index 0000000..983299d --- /dev/null +++ b/non-normative/guidance.adoc @@ -0,0 +1,21 @@ +[[guidance]] +== Firmware Implementation Guidance + +The guidance section is non-normative, and covers certain +implementation choices, suggestions, historical context, etc. + +[[recipes-guidance]] +=== Recipes Guidance +include::recipes.adoc[] + +[[uefi-guidance]] +=== UEFI Implementation Guidance +include::uefi.adoc[] + +[[acpi-guidance]] +=== ACPI Implementation Guidance +include::acpi.adoc[] + +[[smbios-guidance]] +=== SMBIOS Implementation Guidance +include::smbios.adoc[] diff --git a/non-normative/recipes.adoc b/non-normative/recipes.adoc index f9839eb..60a9780 100644 --- a/non-normative/recipes.adoc +++ b/non-normative/recipes.adoc @@ -1,5 +1,5 @@ [[recipe-brs-i-guidance]] -===== BRS-I Recipe Guidance +==== BRS-I Recipe Guidance Systems compliant to BRS-I can successfully boot an existing generic operating system image without system-specific customizations, yet diff --git a/non-normative/uefi.adoc b/non-normative/uefi.adoc index dd52c2e..802faeb 100644 --- a/non-normative/uefi.adoc +++ b/non-normative/uefi.adoc @@ -1,7 +1,7 @@ UEFI implementations run in 64-bit S-Mode, VS-Mode or HS-Mode, depending on whether virtualization is supported or used. -===== Privilege Levels +==== Privilege Levels Different portions of system firmware might target a specific privilege level. In contrast, UEFI drivers, OS loaders and @@ -14,21 +14,14 @@ start execution in M-Mode. However it must switch to supervisor mode as part of initializing boot and runtime services for UEFI drivers and applications. -[[uefi-guidance-security]] -===== Security Requirements - -The Security and Security2 Architectural Protocols are overridden by some -bootloaders (e.g. systemd-boot) to validate EFI binaries that cannot be -validated against the UEFI security database. - [[uefi-guidance-firmware-update]] -===== Firmware Update +==== Firmware Update UpdateCapsule() is only required before ExitBootServices() is called. The UpdateCapsule() implementation is expected to be suitable for use by generic firmware update services like fwupd and Windows Update. Both fwupd and Windows Update read the ESRT table to determine what firmware can be updated and use an EFI helper application to call UpdateCapsule() before ExitBootServices() is called. [[uefi-guidance-pcie]] -====== PCIe +==== PCIe Every implementation of the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL provides the correct Address Translation Offset field to translate between the hart @@ -40,17 +33,3 @@ register maps. In the cases where there are unpopulated PCIe slots behind a root bridge, EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_CONFIGURATION reports valid resources assigned (e.g. for hot plug), or reports no resources assigned. - -====== Graphics Output Protocol - -EFI_GRAPHICS_OUTPUT_PROTOCOL is recommended to be implemented with the -frame buffer of the graphics adapters directly accessible (i.e. -EFI_GRAPHICS_PIXEL_FORMAT is not PixelBltOnly). The -FrameBufferBase must be reported as a hart MMIO address, not as a -bus address (e.g. for a PCIe video device). - -[[uefi-guidance-harts]] -====== Hart Management - -If the harts are being started or stopped internally by a firmware implementation, this should happen before completing the EFI_EVENT_GROUP_READY_TO_BOOT event, and all secondary harts should remain offline from that point on. This ensures an OS loader is entered with an OS-compatible state for the harts. - diff --git a/sbi.adoc b/sbi.adoc index 469ddf0..33e0598 100644 --- a/sbi.adoc +++ b/sbi.adoc @@ -6,36 +6,26 @@ between the supervisor mode and the next higher privilege mode. This section defines the mandatory SBI version and extensions implemented by the higher privilege mode in order to be compatible with this specification. -=== Minimum SBI version -The SBI implementation must conform to SBI v1.0. - -=== Mandatory SBI extensions - -The SBI v1.0 specification allows optional SBI extensions. However, the -following optional extensions are mandatory for a compliant system. - -* SBI Hart State Management (HSM) -** HSM is used by an OS for starting up, stopping, suspending and querying the status of secondary harts. -** <>. - -* SBI System Reset (SRST) -** See <> for additional notes on SRST use by a UEFI implementation and by an OS. - -In addition to this, the following SBI extensions are only mandatory if required -ISA extension is not available in the platform. - -* SBI TIME -** This extension is mandatory only if SSTC ISA extension is not available. -* SBI IPI -** This extension is mandatory only if the platform doesn't implement - Incoming MSI Controller (IMSIC). -* SBI RFENCE -** This extension is mandatory only if the platform doesn't implement - Incoming MSI Controller (IMSIC). -* SBI Performance Monitoring (PMU) -** This extension is mandatory only if the counter delegation related extensions -(S*csrind, Smcdeleg, Ssccfg) are not present. - -NOTE: The above extension are currently being developed by the performance -analsys TG. - +[width=100%] +[%header, cols="5,25"] +|=== +| ID# ^| Requirement +| SBI_010 | The SBI implementation MUST conform to SBI v1.0. +| SBI_020 | The SBI implementation MUST implement the Hart State Management (HSM) extension. +2+| _HSM is used by an OS for starting up, stopping, suspending and querying the status of secondary harts. +| SBI_030 | The System Reset (SRST) extension MUST be implemented. +2+| _See <> for additional notes on SRST use by a UEFI and OS._ +|=== + +Certain requirements are conditional on the presence of RISC-V ISA extensions or system features. + +[width=100%] +[%header, cols="5,25"] +|=== +| ID# ^| Requirement +| SBI_040 | The Timer (TIME) extension MUST be implemented, if the RISC-V "stimecmp / vstimecmp" Extension (Sstc) cite: [Sstc] is not available. +| SBI_050 | The S-Mode IPI (IPI) extension MUST be implemented, if the Incoming MSI Controller (IMSIC) cite: [Aia] is not available. +| SBI_060 | The RFENCE (RFNC) extension MUST be implemented, if the Incoming MSI Controller (IMSIC) cite: [Aia] is not available. +| SBI_070 | The Performance Monitoring (PMU) extension MUST be implemented, if the counter delegation-related ISA extensions (S*csrind cite: [Sscsrind], Smcdeleg cite: [Smcdeleg], Ssccfg cite: [Smcdeleg]) are not present. +2+| _NOTE: The PMU extension is currently being developed by the performance analysis TG cite: [PerfAnalysis]._ +|=== diff --git a/smbios.adoc b/smbios.adoc index 0db3412..a53042d 100644 --- a/smbios.adoc +++ b/smbios.adoc @@ -4,29 +4,32 @@ The System Management BIOS (SMBIOS) specification defines a standard format for presenting management information about an implentation, mostly focusing on hardware components. This section defines the BRS-I mandatory and optional SMBIOS requirements -on top of cite:[SMBIOS], and is optional and recommended for BRS-B. Additional non-normative guidance may be found in the <>. +on top of cite:[SMBIOS], and is optional and recommended for BRS-B. Additional non-normative guidance may be found in the <> section. -.*SMBIOS structures in a conforming implementation* -[cols="1,3,2,4", width=95%, align="center", options="header"] +[width=100%] +[%header, cols="5,25"] |=== -| Type | SMBIOS Structure | Status | Note -| 02 | Baseboard/Module Information | Recommended | -| 03 | System Enclosure/Chassis | Recommended | Relaxes DMTF requirement. -| 08 | Port Connector Information | Recommended | When physical ports present. -| 09 | System Slots | Conditional | Required when expansion slots present. -| 11 | OEM Strings | Recommended | -| 13 | BIOS Language Information | Recommended | -| 14 | Group Associations | Recommended | To describe associations between SMBIOS types. -| 38 | IPMI Device Information | Conditional | Required when IPMIv1.0 host interface present. -| 39 | System Power Supplies | Recommended | For servers. -| 41 | Onboard Devices Extended Information | Recommended | -| 42 | Redfish Host Interface | Conditional | Required when Redfish host interface present. -| 43 | TPM Device | Conditional | Required when TPM present. -| 44 | Processor Additional Information | Required | -| 45 | Firwmare Inventory Information | Recommended | -| 46 | String Property | Recommended | +| ID# ^| Requirement +| SMBIOS_010 | A Baseboard/Module Information (Type 02) structure SHOULD be implemented. +| SMBIOS_020 | A System Enclosure/Chassis (Type 03) structure SHOULD be implemented. +2+|_This relaxes the DMTF specification requirement._ +| SMBIOS_030 | A Port Connector Information (Type 08) SHOULD be implemented. +| SMBIOS_040 | A System Slots (Type 09) structure MUST be implemented, when expansion slots are present. +| SMBIOS_050 | An OEM Strings (Type 11) structure SHOULD be implemented. +| SMBIOS_060 | A BIOS Language Information (Type 13) structure SHOULD be implemented. +| SMBIOS_070 | A Group Associations (Type 14) structure SHOULD be implemented. +| SMBIOS_080 | An IPMI Device Information (Type 38) structure MUST be implemented, when an IPMIv1.0 host interface is present. +| SMBIOS_090 | A System Power Supplies (Type 39) structure SHOULD be implemented. +| SMBIOS_100 | An Onboard Devices Extended Information (Type 41) structure SHOULD be implemented. +| SMBIOS_110 | A Redfish Host Interface (Type 42) structure MUST be implmented, when a Redfish host interface is present. +| SMBIOS_120 | A TPM Device (Type 43) structure MUST be implmented, when a TPM is present. +| SMBIOS_130 | A Processor Additional Information (Type 44) structure MUST be implemented. +2+| _See the <>_. +| SMBIOS_140 | A Firwmare Inventory Information (Type 45) structure SHOULD be implemented. +| SMBIOS_150 | A String Property (Type 46) structure SHOULD be implemented. |=== +[[smbios-type44]] === Type 44 Processor-Specific Data The processor-specific data structure fields are defined to follow the standard Processor-Specific Block fields (cite:[SMBIOS], Section 7.45.1). diff --git a/uefi.adoc b/uefi.adoc index 43ea8fd..f22ed5d 100644 --- a/uefi.adoc +++ b/uefi.adoc @@ -3,118 +3,102 @@ The Unified Extensible Firmware Interface (UEFI) specification describes the interface between the OS and the supervisor-mode firmware. -This section defines the BRS-I mandatory and optional UEFI requirements on top of cite:[UEFI], and is optional and recommended for BRS-B. Additional non-normative guidance may be found in the <>. +This section defines the BRS-I mandatory and optional UEFI requirements on top of cite:[UEFI], and is optional and recommended for BRS-B. Additional non-normative guidance may be found in the <> section. -A compliant system must: - -* Implement a 64-bit UEFI firmware. -* Meet the 3rd Party UEFI Certificate Authority (CA) requirements on UEFI memory mitigations cite:[MSUefiCaRequirements]. -* Meet the following UEFI memory map requirements: -** The default memory space attribute must be EFI_MEMORY_WB. -** Enable address translation. -** Only use EfiRuntimeServicesData memory type for describing any SMBIOS data structures. -* Declare a EFI_CONFORMANCE_PROFILES_UEFI_SPEC_GUID conformance profile, as the BRS requirements are a superset of UEFI cite:[UEFI] (Section 2.6). -* Declare EFI_CONFORMANCE_PROFILE_BRS_1_0_SPEC_GUID conformance profile ({ 0x05453310, 0x0545, 0x0545, { 0x05, 0x45, 0x33, 0x05, 0x45, 0x33, 0x05, 0x45 }}). - -The BRS does not require complying with the UEFI Platform Initialization Specification cite:[UEFI-PI]. - -Only a system fully compliant to the requirements in this section -may declare the EFI_CONFORMANCE_PROFILE_BRS_1_0_SPEC_GUID conformance profile. +[width=100%] +[%header, cols="5,25"] +|=== +| ID# ^| Requirement +| UEFI_010 | Implement a 64-bit UEFI firmware. +| UEFI_020 | Meet the 3rd Party UEFI Certificate Authority (CA) requirements on UEFI memory mitigations cite:[MSUefiCaRequirements]. +| UEFI_030 a| Meet BRS-I specific memory map requirements: + + * The default memory space attribute must be EFI_MEMORY_WB. + * Enable address translation. + * Only use EfiRuntimeServicesData memory type for describing any SMBIOS data structures. +| UEFI_040 | An implemenation MAY comply with the UEFI Platform Initialization Specification cite:[UEFI-PI]. +| UEFI_050 | All hart manipulation internal to a firmware implementation SHOULD be done before completion of the EFI_EVENT_GROUP_READY_TO_BOOT event, with all secondary harts remaining offline from that point on. +2+| _This ensures an OS loader is entered with an OS-compatible state for all harts._ +| UEFI_060 | Declare a EFI_CONFORMANCE_PROFILES_UEFI_SPEC_GUID conformance profile. +2+| _The EFI_CONFORMANCE_PROFILES_UEFI_SPEC_GUID conformance profile must be declared, as the BRS requirements are a superset of UEFI cite:[UEFI] (Section 2.6)._ +| UEFI_070 | Declare EFI_CONFORMANCE_PROFILE_BRS_1_0_SPEC_GUID conformance profile ({ 0x05453310, 0x0545, 0x0545, { 0x05, 0x45, 0x33, 0x05, 0x45, 0x33, 0x05, 0x45 }}). +2+| _Only a system fully compliant to the requirements in this section may declare the EFI_CONFORMANCE_PROFILE_BRS_1_0_SPEC_GUID conformance profile._ +|=== === Security Requirements -Systems implementing secure boot must support the following UEFI Platform Initialization Specification cite:[UEFI-PI] protocols: - -* EFI_SECURITY_ARCH_PROTOCOL -* EFI_SECURITY2_ARCH_PROTOCOL - -Systems implementing a TPM must implement the TCG +[width=100%] +[%header, cols="5,25"] +|=== +| ID# ^| Requirement +| USEC_010 | Systems implementing UEFI Secure Boot MUST implement the EFI_SECURITY_ARCH_PROTOCOL and EFI_SECURITY2_ARCH_PROTOCOL protocols cite:[UEFI-PI]. +2+| _The Security and Security2 Architectural Protocols are overridden by some bootloaders (e.g. systemd-boot) to validate EFI binaries that cannot be validated against the UEFI security database._ +| USEC_020 | Systems implementing a TPM MUST implement the TCG EFI Protocol Specification cite:[TcgEfiPlat]. +|=== -<> - -<>. - -=== PCIe +See additional <>. -Systems implementing PCIe must always initialize all root complex -hardware and perform resource assignment for all endpoints and usable -hotplug-capable switches in the system, even in a "rapid boot" -scenario from a non-PCIe boot device. This is a stronger requirement -than the PCI Firmware Specification firmware/OS device hand-off state -(cite:[PCIFW] Section 3.5). +=== I/O-specific Requirements -<>. +[width=100%] +[%header, cols="5,25"] +|=== +| ID# ^| Requirement +| UIO_010 | Systems implementing PCIe MUST always initialize all root complex hardware and perform resource assignment for all endpoints and usable hotplug-capable switches in the system, even in a boot scenario from a non-PCIe boot device. +2+| _This is a stronger requirement than the PCI Firmware Specification firmware/OS device hand-off state (cite:[PCIFW] Section 3.5). <>._ +| UIO_020 | Systems implementing EFI_GRAPHICS_OUTPUT_PROTOCOL SHOULD configure the frame buffer to be directly accessible. +2+| _That is, EFI_GRAPHICS_PIXEL_FORMAT is not PixelBltOnly and FrameBufferBase is reported as a valid hart MMIO address._ +|=== +[[uefi-rt]] === UEFI Runtime Services -[[uefi-rtc]] -==== Real-Time Clock (RTC) - -The RTC is usually exposed via the UEFI GetTime and SetTime runtime services. - -===== Systems without an RTC - -* GetTime must be implemented (e.g. in terms of CPU cycle counter). -* SetTime must return EFI_UNSUPPORTED, and be appropriately described in EFI_RT_PROPERTIES_TABLE. - -===== Systems with an RTC - -Where the RTC is on an OS-managed bus (e.g. I2C, subject to arbiration issues due to access to the bus by the OS): - -* The ACPI Time and Alarm Device <>. -* GetTime and SetTime must return EFI_UNSUPPORTED, when called after the UEFI boot services have been exited. -* GetTime and SetTime must be appropriately described in EFI_RT_PROPERTIES_TABLE. - -[[uefi-resetsystem]] -==== UEFI Reset and Shutdown - -The UEFI ResetSystem() runtime service must be implemented using the SBI System Reset (SRST) extension. The following table maps the UEFI RT and SRST call parameters: - -[%autowidth] +[width=100%] +[%header, cols="5,25"] |=== -|ResetSystem() ResetType|sbi_system_reset type - -|EfiResetShutdown -|0x00000000 (Shutdown) - -|EfiResetCold -|0x00000001 (Cold reboot) - -|EfiResetWarm -|0x00000002 (Warm reboot) - -|EfiResetPlatformSpecific -|0xF0000000 - 0xFFFFFFFF (Vendor or platform specific reset type) +| ID# ^| Requirement +| URT_010 a| Systems without a Real-Time Clock (RTC) MUST meet the following requirements: + + * GetTime must be implemented (e.g. in terms of CPU cycle counter). + * SetTime must return EFI_UNSUPPORTED, and be appropriately described in EFI_RT_PROPERTIES_TABLE. +| [[uefi-rtc]] URT_020 a| Systems with a Real-Time Clock on an OS-managed bus (e.g. I2C, subject to arbiration issues due to access to the bus by the OS) MUST meet the following requirements: + + * GetTime and SetTime must return EFI_UNSUPPORTED, when called after the UEFI boot services have been exited. + * GetTime and SetTime must be appropriately described in EFI_RT_PROPERTIES_TABLE. +2+|_Also see <>_. +| [[uefi-resetsystem]] URT_030 a| The UEFI ResetSystem() runtime service MUST be implemented using the SBI SRST extension. The following table maps the UEFI RT and SRST call parameters: +[width=100%] +[%header] +!=== +!ResetSystem() ResetType ^! sbi_system_reset type +!EfiResetShutdown ! 0x00000000 (Shutdown) +!EfiResetCold ! 0x00000001 (Cold reboot) +!EfiResetWarm ! 0x00000002 (Warm reboot) +!EfiResetPlatformSpecific ! 0xF0000000 - 0xFFFFFFFF (Vendor or platform specific reset type) +!=== +2+| _The OS MUST call the ResetSystem() runtime service call to reset the system, preferring this to SBI SRST or other platform-specific mechanisms. This allows for systens to perform any required platform tasks on the way out (e.g. servicing UpdateCapsule() or persisting non-volatile variables in some systems)._ +| URT_040 | Non-volatile UEFI variables MUST persist across calls to the Reset System() runtime service call. +| URT_050 | UEFI Runtime Services MUST be able to update the variables directly without the aid of an OS. +| URT_060 a| The following requirements MUST be met for systems with UEFI Secure Boot: + + * Must support a minimum of 128 KB of non-volatile storage for UEFI variables. + * The maximum supported variable size must be at least 64 KB. + * The 'db' signature database variable EFI_IMAGE_SECURITY_DATABASE must be created with EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS, to prevent rollback attacks. + * The 'dbx' signature database variable EFI_IMAGE_SECURITY_DATABASE1 must be created with EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS, to prevent rollback. |=== -The OS must call the ResetSystem() runtime service call to reset the system, -preferring this to SBI SRST or other platform-specific mechanisms. This -allows for UEFI implementations to perform any required platform tasks on the way out (e.g. servicing UpdateCapsule() or persisting non-volatile variables in some implementations). - -[[uefi-variable]] -==== Variable Services - -* Non-volatile UEFI variables must persist across EFI ResetSystem() calls. -* The UEFI Runtime Services must be able to update the variables directly without the aid of the operating system. -* For systems implementing secure boot: -** Must support a minimum of 128 KB of non-volatile storage for UEFI variables. -** The maximum supported variable size must be at least 64 KB. -** The 'db' signature database variable EFI_IMAGE_SECURITY_DATABASE must -be created with EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS, to -prevent rollback attacks. -** The dbx signature database variable EFI_IMAGE_SECURITY_DATABASE1 -must be created with EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS, -to prevent rollback. - === Firmware Update -Systems with updatable firmware must implement either an in-band (firmware on hart updates itself) or an out-of-band firmware update mechanism (for example, by a Base Management Controller, BMC)). - -In-band firmware updates must be implemented in one of two ways: - -* UpdateCapsule() UEFI runtime service (cite:[UEFI] Section 8.5.3). -** Firmware must accept updates in the "Firmware Management Protocol Data Capsule Structure" format as described in "Delivering Capsules Containing Updates to Firmware Management Protocol" cite:[UEFI] (Section 23.3). -** Must provide an ESRT cite:[UEFI] (Section 23.4) describing every firmware image that is updated in-band. -** UpdateCapsule() is allowed to return EFI_UNSUPPORTED, when called after the UEFI boot services have been exited. <>. -* Delivery of Capsules via file on Mass Storage Device (cite:[UEFI] Section 8.5.5). +[width=100%] +[%header, cols="5,25"] +|=== +| ID# ^| Requirement +| UFU_010 | Systems with updatable firmware MUST implement either an in-band or an out-of-band firmware update mechanism. +2+| _In-band means the firmware running on a hart updates itself. Out-of-band means the update mechanism is located on an auxiliary processor, such as a Base Management Controller (BMC)._ +| UFU_020 | Systems with in-band firmware updates MUST do so either via UpdateCapsule() UEFI runtime service (cite:[UEFI] Section 8.5.3) or Delivery of Capsules via file on Mass Storage Device (cite:[UEFI] Section 8.5.5). +| UFU_030 | Systems implementing in-band firmware updates via UpdateCapsule MUST accept updates in the "Firmware Management Protocol Data Capsule Structure" format as described in "Delivering Capsules Containing Updates to Firmware Management Protocol" cite:[UEFI] (Section 23.3). +| UFU_040 | Systems implementing in-band firmware updates via UpdateCapsule MUST provide an ESRT cite:[UEFI] (Section 23.4) describing every firmware image that is updated in-band. +| UFU_050 | Systems implementing in-band firmware updates via UpdateCapsule MAY return EFI_UNSUPPORTED, when called after the UEFI boot services have been exited. +2+| _<>_. +|===