Define AML device ID/props for SPCR type 0x12 devices

#24

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

acpi-id.adoc

@@ -9,7 +9,7 @@ consists of two parts: a Vendor ID 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
 unique across the Industry and registered by the UEFI forum. For RVI
-standard devices, **"RSCV"** is the Vendor ID registered. Vendor-specific
+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
@@ -25,6 +25,8 @@ ACPI ID for any new device.
 [%header, cols="5,25"]
 |===
 | ACPI ID     ^| Device
-| RSCV0001     | RISC-V Platform-Level Interrupt Controller (PLIC)
-| RSCV0002     | RISC-V Advanced Platform-Level Interrupt Controller (APLIC)
+| `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
+2+| _Also see <<acpi-props-uart>>._
 |===

acpi-prop.adoc

@@ -0,0 +1,25 @@
+[[acpi-props]]
+=== RVI-specific ACPI Device Properties
+
+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.
+
+Request for additional property names in the `rscv-` namespace should be made as a git pull request to this document.
+
+[[acpi-props-uart]]
+==== Properties for UART Devices
+
+[width=100%]
+[%header, cols="10,5,25"]
+|===
+|  Property (`rscv-uart-*`) ^| Type | Description
+| `clock-frequency` | Integer | Clock feeding the IP block in Hz.
+3+| _A value of zero will preclude the ability to set the baud rate, or
+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).
+|===
+

acpi.adoc

@@ -33,8 +33,8 @@ available to an OS loader via the standard UEFI EFI_GRAPHICS_OUTPUT_PROTOCOL int
  * 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-guidance-spcr, See additional guidance>>_.
+ ** 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
 implemented by the system, PLIC or APLIC namespace devices MUST be
 present in the ACPI namespace along with MADT entries. <<acpi-ids,
@@ -82,6 +82,8 @@ Interrupt (GSI, aka wired interrupt) resources MUST indicate the dependency on t
 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>>.
 |===
 
 include::acpi-id.adoc[]
+include::acpi-prop.adoc[]

brs.bib

@@ -22,6 +22,10 @@ @electronic{DT
   title = {DeviceTree},
   url = {https://www.devicetree.org/}
 }
+@electronic{DSD,
+  title = {_DSD (Device Specific Data) Implementation Guide},
+  url = {https://github.com/UEFI/DSD-Guide/blob/main/dsd-guide.pdf}
+}
 @electronic{RSPS,
   title = {RISC-V Server Platform Specification},
   url = {https://github.com/riscv-non-isa/riscv-server-platform}