Prettify. The point of this is to easily visually parse the spec.

Use `` for identifiers (code identifiers, structure fields, register names, requirements within the spec)
Use __ for spec names, chapter/section names (e.g. when referenced)

Use ** for emphasis.

Names of stuff (Processor Properties Table, UEFI, ACPI) are left as-is.

Signed-off-by: Andrei Warkentin <[email protected]>

acpi-id.adoc

@@ -1,19 +1,19 @@
 [[acpi-ids]]
 === RVI-specific ACPI IDs
 
-ACPI ID is used in the _HID (Hardware ID), _CID (Compatibility ID) or
-_SUB (Subsystem ID) objects as described in the ACPI Specification for
+ACPI ID is used in the `_HID` (Hardware ID), `_CID` (Compatibility ID) or
+`_SUB` (Subsystem ID) objects as described in the ACPI Specification for
 devices, that do not have a standard enumeration mechanism. The ACPI ID
-consists of two parts: a Vendor ID followed by a product identifier.
+consists of two parts: a vendor identifier followed by a product identifier.
 
 Vendor IDs consist of 4 characters, each character being either an
-uppercase letter (A-Z) or a numeral (0-9). The Vendor ID SHOULD be
+uppercase letter (A-Z) or a numeral (0-9). The vendor ID SHOULD be
 unique across the Industry and registered by the UEFI forum. For RVI
-standard devices, `RSCV` is the Vendor ID registered. Vendor-specific
-devices can use an appropriate Vendor ID registered for the manufacturer.
+standard devices, `RSCV` is the vendor ID registered. Vendor-specific
+devices can use an appropriate vendor ID registered for the manufacturer.
 
-Product Identifiers are always four-character hexadecimal numbers (0-9
-and A-F). The Device Manufacturer is responsible for assigning this
+Product IDs are always four-character hexadecimal numbers (0-9
+and A-F). The device manufacturer is responsible for assigning this
 identifier to each product model.
 
 This document contains the canonical list of ACPI IDs for the namespace
@@ -27,6 +27,6 @@ ACPI ID for any new device.
 | ACPI ID     ^| Device
 | `RSCV0001`     | RISC-V Platform-Level Interrupt Controller (PLIC)
 | `RSCV0002`     | RISC-V Advanced Platform-Level Interrupt Controller (APLIC)
-| `RSCV0003`     | NS16550-compatible UART compatible with a Type 0x12 SPCR definition
+| `RSCV0003`     | NS16650 UART compatible with an SPCR definition using `Interface Type` 0x12
 2+| _Also see <<acpi-props-uart>>._
 |===

acpi-prop.adoc

@@ -1,7 +1,7 @@
 [[acpi-props]]
 === RVI-specific ACPI Device Properties
 
-This section defines the _DSD device properties cite:[DSD] in the `rscv-` namespace.
+This section defines the `_DSD` device properties cite:[DSD] in the `rscv-` namespace.
 
 Where explicit values are provided in a property definition, only these values must be used. System behavior with any other values is undefined.
 
@@ -20,6 +20,6 @@ to configure a disabled device._
 | `reg-shift` | Integer | Quantity to shift the register offsets by.
 | `reg-io-width` | Integer | The size (in bytes) of the register accesses that should be performed on the device.
 3+| _1, 2, 4 or 8._
-| `rx-fifo-size` | Integer | The RX FIFO size (in bytes).
+| `rx-fifo-size` | Integer | The receive FIFO size (in bytes).
 |===
 

acpi.adoc

@@ -1,12 +1,12 @@
 [[acpi]]
 == BRS-I ACPI Requirements
 
-The Advanced Configuration and Power Interface specification provides the OS-centric view of system configuration, various hardware resources, events and power management.
+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 existing cite:[ACPI] and cite:[UEFI]
 specification requirements. Additional non-normative guidance may be
-found in the <<acpi-guidance, Firmware Implementation Guidance>>
+found in the <<acpi-guidance, firmware implementation guidance>>
 section.
 
 IMPORTANT: All content in this section is optional and recommended for BRS-B.
@@ -15,27 +15,27 @@ IMPORTANT: All content in this section is optional and recommended for BRS-B.
 [%header, cols="5,25"]
 |===
 | ID#     ^| Requirement
-| [[acpi-64bit-clean]]ACPI_010 a| Be 64-bits clean.
+| [[acpi-64bit-clean]]`ACPI_010` a| Be 64-bits clean.
 
-  * RSDT MUST NOT be implemented, with RsdtAddress in RSDP set to 0.
+  * RSDT MUST NOT be implemented, with `RsdtAddress` in RSDP set to 0.
   * 32-bit address fields MUST be 0.
 2+| _<<acpi-guidance-64bit-clean, See additional guidance>>._
-| [[acpi-hw-reduced]]ACPI_020 a| Implement the HW-Reduced ACPI Mode (no FACS table).
+| [[acpi-hw-reduced]]`ACPI_020` a| Implement the hardware-reduced ACPI mode (no FACS table).
 2+| _<<acpi-guidance-hw-reduced, See additional guidance>>._
-| [[acpi-pptt]]ACPI_030 | The Processor Properties Table (PPTT) MUST be implemented, even on systems with a simple hart topology.
-| [[acpi-mcfg]]ACPI_040 | The PCI Memory-mapped Configuration Space (MCFG) table MUST NOT be present if it violates cite:[PCIFW].
+| [[acpi-pptt]]`ACPI_030` | The Processor Properties Table (PPTT) MUST be implemented, even on systems with a simple hart topology.
+| [[acpi-mcfg]]`ACPI_040` | The PCI Memory-mapped Configuration Space (MCFG) table MUST NOT be present if it violates cite:[PCIFW].
 2+| _Only compatible PCIe segments, exposed via ECAM (Enhanced Configuration Access Mechanism), may be described in the MCFG. The MCFG MUST NOT require vendor-specific OS support. See PCI Services (cite:[ACPI], Section 4) for more ACPI requirements relating to PCIe support. <<acpi-guidance-pcie, See additional guidance>>._
-| ACPI_050 | A Serial Port Console Redirection Table cite:[SPCR] MUST be present 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.
+| `ACPI_050` | A Serial Port Console Redirection Table cite:[SPCR] MUST be present 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.
 2+|_In these cases, the table provides essential configuration for an early OS boot console._
-| [[acpi-spcr]]ACPI_060 a| An SPCR table, if present, MUST meet the following requirements:
+| [[acpi-spcr]]`ACPI_060` 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).
+ ** Use `Interface Type` 0x12 (16550-compatible with parameters defined in Generic Address Structure).
  ** There MUST be a matching AML device object with compatible ID `RSCV0003`.
 2+| _See <<acpi-guidance-spcr, additional guidance>>_.
-| [[acpi-namespace-dev]]ACPI_080 | Depending on the interrupt controller
+| [[acpi-namespace-dev]]`ACPI_080` | Depending on the interrupt controller
 implemented by the system, PLIC or APLIC namespace devices MUST be
 present in the ACPI namespace along with MADT entries. <<acpi-ids,
 See RVI ACPI IDs>>.
@@ -54,35 +54,35 @@ objects.
 [%header, cols="5,25"]
 |===
 | ID#     ^| Requirement
-| AML_010 | The Cache Coherency Attribute (_CCA) device method MUST be implemented.
+| `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)._
-| 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 arbitration issues due to access to the bus by the OS) MUST implement the Time and Alarm Device (TAD).
-2+| _Also see <<uefi-rtc, URT_020>>_.
-| AML_080 | Systems implementing a TAD MUST be functional without additional system-specific OS drivers.
+| `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 Root Complex 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 I/O 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 arbitration issues due to access to the bus by the OS) MUST implement the Time and Alarm Device (TAD).
+2+| _Also see <<uefi-rtc, `URT_020`>>_.
+| `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._
-| [[acpi-irq-gsb]] AML_090 | PLIC and APLIC device objects MUST support
-the Global System Interrupt Base (_GSB, cite:[ACPI] Section 6.2.7) object.
+through the driver-backed `OperationRegion`._
+| [[acpi-irq-gsb]] `AML_090` | PLIC and APLIC device objects MUST support
+the Global System Interrupt Base (`_GSB`, cite:[ACPI] Section 6.2.7) object.
 <<acpi-guidance-gsi-namespace, See additional guidance>>.
-| [[acpi-irq-dep]] AML_100 | Devices with Global System
+| [[acpi-irq-dep]] `AML_100` | Devices with Global System
 Interrupt (GSI, aka wired interrupt) resources MUST indicate the dependency on the corresponding
-interrupt controller using Operation Region Dependencies (_DEP,
+interrupt controller using Operation Region Dependencies (`_DEP`,
 cite:[ACPI] Section 6.5.8).
 <<acpi-guidance-gsi-namespace, See additional guidance>>.
-| AML_110 | UART device objects with ID `RSCV0003` MUST implement <<acpi-props-uart, Properties for UART Devices>>.
+| `AML_110` | UART device objects with ID `RSCV0003` MUST implement <<acpi-props-uart, Properties for UART Devices>>.
 |===
 
 include::acpi-id.adoc[]

hart.adoc

@@ -9,7 +9,7 @@ The BRS specification is minimally prescriptive on the RISC-V hart requirements.
 [%header, cols="5,25"]
 |===
 | ID#     ^| Requirement
-| HR_010  | The RISC-V application processor harts MUST be compliant to RVA20S64 Profile cite:[Profile].
+| `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._
 
 |===

intro.adoc

@@ -1,19 +1,19 @@
 [[intro]]
 == Introduction
 
-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 _RISC-V Boot and Runtime Services Specification_ (BRS) 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.
+It is expected that the BRS 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.
 
 === Approach to Solutions
 
-The Boot and Runtime Services specification focuses on two solutions in the form of what is deemed a recipe. Each recipe contains the requirements needed to fulfill each solution. The requirements of each recipe will be marked accordingly with an unique identifier. The recipe names are named BRS-I and BRS-B, Interoperable and Bespoke, respectively.
+The BRS focuses on two solutions in the form of what is deemed a recipe. Each recipe contains the requirements needed to fulfill each solution. The requirements of each recipe will be marked accordingly with an unique identifier. The recipes are BRS-I (Interoperable) and BRS-B (Bespoke).
 
 === Testing and Conformance
 
@@ -25,7 +25,7 @@ The requirements in this specification use the following format:
 [%header, cols="5,20"]
 |===
 | ID#     ^| Requirement
-| CAT_NNN  | The `CAT` is a category prefix that logically groups the
+| `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.                                   +
                                                                               +
@@ -44,25 +44,25 @@ The requirements in this specification use the following format:
 
 === 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).
+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 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.
+| ACPI            | _Advanced Configuration and Power Interface Specification_ cite:[ACPI].
+| BRS             | _RISC-V Boot and Runtime Services Specification_. 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].
+| 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].
+| SBI             | _RISC-V Supervisor Binary Interface Specification_ cite:[SBI].
+| SMBIOS          | _System Management BIOS (SMBIOS) Reference Specification_ 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 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].
+| UEFI            | _Unified Extensible Firmware Interface Specification_ cite:[UEFI].
 |===