docs: Add platform requirements document

We add platform requirements document to clarify OpenSBI
expectations from a RISC-V platform.

Signed-off-by: Anup Patel <anup.patel@wdc.com>
Reviewed-by: Atish Patra <atish.patra@wdc.com>
Reviewed-by: Bin Meng <bin.meng@windriver.com>

diff --git a/README.md b/README.md
index 2395012..88367b7 100644 (file)
--- a/README.md
+++ b/README.md
@@ -218,6 +218,7 @@ Detailed documentation of various aspects of OpenSBI can be found under the
 
 * [Contribution Guideline]: Guideline for contributing code to OpenSBI project
 * [Library Usage]: API documentation of OpenSBI static library *libsbi.a*
+* [Platform Requirements]: Requirements for using OpenSBI on a platform
 * [Platform Support Guide]: Guideline for implementing support for new platforms
 * [Platform Documentation]: Documentation of the platforms currently supported.
 * [Firmware Documentation]: Documentation for the different types of firmware
@@ -270,6 +271,7 @@ make I=<install_directory> install_docs
 [Contribution Guideline]: docs/contributing.md
 [Contributors List]: CONTRIBUTORS.md
 [Library Usage]: docs/library_usage.md
+[Platform Requirements]: docs/platform_requirements.md
 [Platform Support Guide]: docs/platform_guide.md
 [Platform Documentation]: docs/platform/platform.md
 [Firmware Documentation]: docs/firmware/fw.md

diff --git a/docs/doxygen.cfg b/docs/doxygen.cfg
index 8ab53ed..52346be 100644 (file)
--- a/docs/doxygen.cfg
+++ b/docs/doxygen.cfg
@@ -793,6 +793,7 @@ WARN_LOGFILE           =
 INPUT                  = @@SRC_DIR@@/README.md \
                          @@SRC_DIR@@/docs/contributing.md \
                          @@SRC_DIR@@/docs/platform_guide.md \
+                         @@SRC_DIR@@/docs/platform_requirements.md \
                          @@SRC_DIR@@/docs/library_usage.md \
                          @@SRC_DIR@@/docs/firmware \
                          @@SRC_DIR@@/docs/platform \

diff --git a/docs/platform_requirements.md b/docs/platform_requirements.md
new file mode 100644 (file)
index 0000000..68dc393
--- /dev/null
+++ b/docs/platform_requirements.md
@@ -0,0 +1,44 @@
+OpenSBI Platform Requirements
+=============================
+
+The RISC-V platform requirements for OpenSBI can change over time
+with advances in RISC-V specifications and ecosystem.
+
+To handle this, we have two types of RISC-V platform requirements:
+
+1. **Base platform requirements** which apply to all OpenSBI releases
+2. **Release specific platform requirements** which apply to a OpenSBI
+   release and later releases
+
+Currently, we don't have any **Release specific platform requirements**
+but such platform requirements will be added in future.
+
+Base Platform Requirements
+--------------------------
+
+The base RISC-V platform requirements for OpenSBI are as follows:
+
+1. At least rv32ima or rv64ima required on all HARTs
+2. At least one HART should have S-mode support because:
+
+     * SBI calls are meant for RISC-V S-mode (Supervisor mode)
+     * OpenSBI implements SBI calls for S-mode software
+
+3. The MTVEC CSR on all HARTs must support direct mode
+4. The PMP CSRs are optional. If PMP CSRs are not implemented then
+   OpenSBI cannot protect M-mode firmware and secured memory regions
+5. The TIME CSR is optional. If TIME CSR is not implemented in
+   hardware then a 64-bit MMIO counter is required to track time
+   and emulate TIME CSR
+6. Hardware support for injecting M-mode software interrupts on
+   a multi-HART platform
+
+The RISC-V extensions not covered by rv32ima or rv64ima are optional
+for OpenSBI. Although, OpenSBI will detect and handle some of these
+optional RISC-V extensions at runtime.
+
+The optional RISC-V extensions handled by OpenSBI at runtime are:
+
+* D-extension: Double precision floating point
+* F-extension: Single precision floating point
+* H-extension: Hypervisor