Re: [PATCH v2] Base boot and runtime requirements - initial commit

Abner Chang

My reviews are inline below which is apart from the below recommendations if you don't think that is better.

We have Linux2022 as the base feature set for all kinds of platform, however, there are many external references to EBBR in this section and EBBR is in the reduced UEFI scope and the base requirement is mainly for the embedded platform  We also have Embedded2022 section specifically to embedded system and there is a Base sub-section for it. The above confuses me.
Could we just have a simple and generic description in Linux2022 that replaces all of EBBR references, then point to Embede2022 in Linux2022 for the detailed implementation of the embedded platform? Also, have the references to EBBR in Embede2022. Is this clear than the current layout of spec?

For example, 
+===== Firmware
+- For compliance with base specification platform must implement
+link:[EBBR - UEFI Required Elements],
Below would be implemented for UEFI firmware system for the compliance with base specification, just some implementations may be omitted based on the requirements of different RISC-V platforms
- Required EFI protocols for the base specification.
- Required EFI protocols for the platform.
Refer to Embedded2022 for the detailed implementations of the above requirements.
Refer to Server2022 for the detailed implementations of the above requirements.

In Embedded2022 section, put links to refer to EBBR.
In Server section, we can just refer to UEFI spec if the requirement needs full UEFI scope support.

This reduces the confusion and increases the readability to the audience. Otherwise, it would be hard to read for the Server platform because Server2022 would base on Linux2022 plus the extensions. And some of the requirements that refer to EBBR would be overridden because of the deviations for the server platform.

Rahul Pathak <rpathak@...> 於 2021年4月20日 週二 下午8:23寫道:
Initial changes for the Base Boot & Runtime requirements.
The sections which are currently in-progress are marked as TBD.
These changes can serve as the starting point and more details/changes
can be done tailored for RISC-V.
This is the main patch, there are minor changes in the contributors file
and the changelog which are not relevant for now so I am not sending those.

Signed-off-by: Rahul Pathak <rpathak@...>
 riscv-platform-spec.adoc | 125 ++++++++++++++++++++++++++++++++++++---
 1 file changed, 118 insertions(+), 7 deletions(-)

diff --git a/riscv-platform-spec.adoc b/riscv-platform-spec.adoc
index 5d3b9c3..601fb61 100644
--- a/riscv-platform-spec.adoc
+++ b/riscv-platform-spec.adoc
@@ -32,6 +32,36 @@ include::profiles.adoc[]
 // Linux-2022 Platform
 == Linux-2022 Platform

+=== Terminology
+[cols="1,2", width=80%, align="left", options="header"]
+|SBI       | Supervisor Binary Interface   
+|UEFI      | Unified Extensible Firmware Interface
+|ACPI      | Advanced Configuration and Power Interface
+|SMBIOS    | System Management Basic I/O System
+|DTS       | Devicetree source file   
+|DTB       | Devicetree binary
+|RVA22     | RISC-V Application 2022
+|RV32GC    | RISC-V 32-bit general purpose ISA described as RV32IMAFDC.
+|RV64GC    | RISC-V 64-bit general purpose ISA described as RV64IMAFDC.     
+=== Specifications
+[cols="1,2", width=80%, align="left", options="header"]
+|link:[UEFI Specification]         | v2.9   
+|link:[Devicetree Specification]  | v0.3
+|link:[SBI Specification]                    | v0.3-rc0
+|link:[RVA22 Specification]                                                                                   | TBD
+|link:[EBBR Specification]                                                | v2.0.0-pre1   
+|link:[ACPI Specification]              | v6.4
+|link:[SMBIOS Specification]    | v3.4.0
+|link:[Platform Policy]                                                                                       | TBD
 // Base feature set for Linux-2022 Platform
 === Base
 ==== Architecture
@@ -57,14 +87,95 @@ include::profiles.adoc[]
 * Timers
 * Watchdog Timers

-==== Boot Process
-* Firmware
-* Boot-Loader
-* Discovery Mechanisms
+==== Boot and Runtime Requirements
+- The base specification defines the interface between the firmware and the
+operating system suitable for the RISC-V platforms with rich operating
+- These requirements specifies the required boot and runtime services, device
+discovery mechanism, etc.
+- The requirements are operating system agnostic, specific firmware/bootloader
+implementation agnostic.
+- The base boot specification depends on the RVA22 profile and all requirements
+from the RVA22 profile must be implemented.
+- The base runtime specification depends on the RISC-V SBI specification and
+all requirements from the SBI spec must be implemented.
+- Any RV32GC or RV64GC system with Machine, Supervisor and User Mode can comply
+with the base specification. Hypervisor Extension is optional.
+_**Will be defined in this spec if the RVA22 spec does not mention it.**_
+- For the generic mandatory requirements this base specification will refer to
+the EBBR Specification. Any deviation from the EBBR will be explicitly
+mentioned in the requirements.
+- Specifications followed are mentioned in the 
+<<Specifications,Specification Section>>
+- For more on scope of MANDATORY, DEPRECATED, COMPATIBILITY refer Platform
+Policy Specification.
+===== Firmware
+- UEFI Platform must meet RISC-V Platform requirements on calling conventions,
+ABI support specific to RISC-V. Refer Chapter - 2.3.7 RISC-V Platforms of UEFI
+- For compliance with base specification platform must implement
+link:[EBBR - UEFI Required Elements],

+link:[EBBR - UEFI Platform Specific Elements]
+and support the following

+link:[EBBR - Global Variables].
+====== Block Device Partition Format
Better to name it as  "Firmware Block Device Partition Format" becasue the link to EBBR is specifically talks about how to store firmware image.

+- Firmware must implement the support for GPT Partitioning and meet the
+requirements as per the
+link:[EBBR Firmware Storage].
This is what I said it may confuse audiences becasue UEFI PI spec volume3 also defines the format of firmware image which is used by edk2 and which is very different than the one defined in EBBR.
Can we add the below sentence,
Firmware must implement the require EFI protocols if the firmware image is stored in the format which complaint with section 2 "Firmware Storage Design Discussion" in UEFI PI specification volume3.
+===== Boot Services
+- Base specification compliant firmware must implement all UEFI functions
+====== Startup Protocol
+- UEFI firmware could be executed in either Machine mode or Supervisor mode
+during the entire POST, according to the hart capability and the platform
+design. For firmware privilege mode requirements, mode switch and the handover
+of control to S-Mode refer UEFI chapter 2.3.7 RISC-V Platforms.
+- Before yielding control to S-Mode stage, firmware must configure the M-Mode
+state. Refer the RISC-V SBI specification for details.
+- If the Hypervisor Extension is implemented. **TBD**.
+====== Memory Map
+- UEFI environment must provide a system memory map and meet the requirements
+for link:[EBBR - Memory Map].
+===== Boot-Loader
+===== Discovery Mechanisms
+- The base specification mandates the use of Devicetree for system description.
+- System must meet link:[EBBR - Devicetree requirements]
+to comply with this base specification. Also refer Devicetree tables section
+in chapter - 4.6 EFI Configuration Table & Properties Table of UEFI
 Could we add something regarding to SMBIOS?
"If platform requires SMBIOS on UEFI system, the SMBIOS table must be installed to EFI Configuration Table according to 4.6 EFI Configuration Table & Properties Table of UEFI


-==== Runtime services
-* SBI
+===== Runtime Services
+====== SBI
+- Firmware must implement the runtime services/extensions specified by the
+RISC-V SBI Specification.
+- Wherever applicable firmware must implement UEFI interfaces over similar
+interfaces and services present in the SBI specification. For example, UEFI
+runtime services must implement ResetSystem() via SBI Reset extension.
+- Legacy Extensions from the SBI Specification are deprecated and must not be
+====== UEFI
+- Firmware must conform to the
+link:[EBBR - UEFI EFI_RUNTIME_SERVICES requirements].
+- Firmware must meet the requirements for
+link:[EBBR - Runtime Device Mappings]
+to avoid conflict between the firmware and OS when accessing the mapped
+- Compliant UEFI runtime environment must meet the requirements for the
+link:[EBBR - Runtime Variable Access].
+- Compliant implementation must meet the Realtime Clock requirements
+link:[EBBR - UEFI RTC interface]
+if RTC is present in the system.

 // Server extension for Linux-2022 Platform
 === Server Extension

Join { to automatically receive all group messages.