[edk2-platforms][PATCH v3 0/3] Revise Readme for RISC-V updates

[edk2-platforms][PATCH v3 0/3] Revise Readme for RISC-V updates

[Abner Chang]

Update below Readme.md,
 - edk2-platforms/Readme.md
 - Platform/RISC-V/PlatformPkg/Readme.md
 - Platform/SiFive/U5SeriesPkg/Readme.md

Abner Chang (3):
  edk2-platforms: Revise Readme.md
  RISC-V/PlatformPkg: Revise Readme.md
  Platform/U5SeriesPkg: Revise Readme.md

 Platform/RISC-V/PlatformPkg/Readme.md |  88 ++++++++++--------
 Platform/SiFive/U5SeriesPkg/Readme.md | 124 +++++++++++++++-----------
 Readme.md                             |   1 +
 3 files changed, 125 insertions(+), 88 deletions(-)

-- 
2.25.0

[edk2-platforms][PATCH v3 1/3] edk2-platforms: Revise Readme.md

[Abner Chang]

Mention to update submodule under for edk2-platforms. It is for RISC-V OpenSBI library.

Signed-off-by: Abner Chang <abner.chang@hpe.com>
Co-authored-by: Daniel Schaefer <daniel.schaefer@hpe.com>
Reviewed-by: Leif Lindholm <leif@nuviainc.com>

Cc: Leif Lindholm <leif@nuviainc.com>
Cc: Michael D Kinney <michael.d.kinney@intel.com>
---
 Readme.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Readme.md b/Readme.md
index 0675685fb7..d896b2c5fc 100644
--- a/Readme.md
+++ b/Readme.md
@@ -97,6 +97,7 @@ target-specific binutils. These are included with any prepackaged GCC toolchain
    $ git submodule update --init
    ...
    $ git clone https://github.com/tianocore/edk2-platforms.git
+   $ git submodule update --init
    ...
    $ git clone https://github.com/tianocore/edk2-non-osi.git
    ```
-- 
2.25.0

[edk2-platforms][PATCH v3 2/3] RISC-V/PlatformPkg: Revise Readme.md

[Abner Chang]

Update RISC-V PlatformPkg Readme.md to align with the latest implementation.

Signed-off-by: Abner Chang <abner.chang@hpe.com>
Co-authored-by: Daniel Schaefer <daniel.schaefer@hpe.com>
Reviewed-by: Daniel Schaefer <daniel.schaefer@hpe.com>

Cc: Leif Lindholm <leif@nuviainc.com>
Cc: Michael D Kinney <michael.d.kinney@intel.com>
Cc: Daniel Schaefer <daniel.schaefer@hpe.com>
---
 Platform/RISC-V/PlatformPkg/Readme.md | 88 ++++++++++++++++-----------
 1 file changed, 52 insertions(+), 36 deletions(-)

diff --git a/Platform/RISC-V/PlatformPkg/Readme.md b/Platform/RISC-V/PlatformPkg/Readme.md
index 2632ebeb28..4b933a2e0f 100644
--- a/Platform/RISC-V/PlatformPkg/Readme.md
+++ b/Platform/RISC-V/PlatformPkg/Readme.md
@@ -1,49 +1,62 @@
 # Introduction
 
-## EDK2 RISC-V Platform Packages
-RISC-V platform package provides the generic and common modules for RISC-V
-platforms. RISC-V platform package could include RiscPlatformPkg.dec to
-use the common drivers, libraries, definitions, PCDs and etc. for the
-platform development.
+## EDK2 RISC-V Platform Project
 
-There are two packages to support RISC-V:
-- `edk2-platforms/Silicon/RISC-V/ProcessorPkg/RiscVProcessorPkg.dec`
-- `edk2-platforms/Platform/RISC-V/PlatformPkg/RiscVPlatformPkg.dec`
+### EDK2 Build Architecture for RISC-V
+The edk2 build architecture which is supported and verified on edk2 code base for
+RISC-V platforms is `RISCV64`.
 
-`RiscVPlatformPkg` provides SEC phase and NULL libs.
-`RiscVProcessorPkg` provides many libraries, PEIMs and DXE drivers.
+### Toolchain for RISC-V
+The toolchain is on RISC-V GitHub (https://github.com/riscv/riscv-gnu-toolchain)
+for building edk2 RISC-V binary. The corresponding edk2 Toolchain tag for building
+RISC-V platform is "GCC5" declared in `tools_def.txt`.
 
-### Download the sources ###
+### Packages
+There are two packages to support RISC-V edk2 platforms:
+- `Silicon/RISC-V/ProcessorPkg/RiscVProcessorPkg.dec`
+- `Platform/RISC-V/PlatformPkg/RiscVPlatformPkg.dec`
+
+`RiscVPlatformPkg` currently provides the generic SEC driver for all RISC-V platforms,
+and some platform level libraries.
+`RiscVProcessorPkg` currently provides RISC-V processor related libraries, PEI modules,
+DXE drivers and industrial standard header files.
+
+## EDK2 RISC-V Platform Package
+RISC-V platform package provides the common modules for RISC-V platforms. RISC-V
+platform vendors could include RiscPlatformPkg.dec to use the common drivers, libraries,
+definitions, PCDs and etc. for the RISC-V platforms development.
+
+### Download the Source Code ###
 ```
 git clone https://github.com/tianocore/edk2.git
+git clone https://github.com/tianocore/edk2-platforms.git
 
-git clone https://github.com/changab/edk2-platforms.git
-# Check out branch: riscv-smode-lib
 ```
 
-To build it, you have to follow the regular steps for EDK2 and additionally set
-an environmen variable to point to your RISC-V toolchain installation,
-including the binary prefixes:
-
+You have to follow the build steps for
+EDK2 (https://github.com/tianocore/tianocore.github.io/wiki/Getting-Started-with-EDK-II)
+and additionally set an environment variable to point to your RISC-V toolchain binaries
+for building RISC-V platforms,
 ```
+# e.g. If the toolchain binaries are under /riscv-gnu-toolchain-binaries/bin
 export GCC5_RISCV64_PREFIX=/riscv-gnu-toolchain-binaries/bin/riscv64-unknown-elf-
 ```
 
-Then you can build the image for the SiFive HifiveUnleashed platform:
+Then you can build the edk2 firmware image for RISC-V platforms.
 
 ```
+# e.g. For building SiFive Hifive Unleashed platform:
 build -a RISCV64 -t GCC5 -p Platform/SiFive/U5SeriesPkg/FreedomU540HiFiveUnleashedBoard/U540.dsc
 ```
 
-### EDK2 project
-All changes in edk2 are upstream, however, most of the RISC-V code is in
-edk2-platforms. Therefore you have to check out the branch `riscv-smode-lib` on
-`github.com/changab/edk2-platforms`.
-
-The build architecture which is supported and verified so far is `RISCV64`.
-The latest master of the RISC-V toolchain https://github.com/riscv/riscv-gnu-toolchain
-should work but the latest verified commit is `b468107e701433e1caca3dbc8aef8d40`.
-Toolchain tag is "GCC5" declared in `tools_def.txt`
+## RISC-V OpenSBI Library
+RISC-V [OpenSBI](https://github.com/riscv/opensbi) is the implementation of
+[RISC-V SBI (Supervisor Binary Interface) specification](https://github.com/riscv/riscv-sbi-doc).
+For EDK2 UEFI firmware solution, RISC-V OpenSBI is integrated as a library
+[(submoudule)](Silicon/RISC-V/ProcessorPkg/Library/RiscVOpensbiLib/opensbi) in EDK2
+RISC-V Processor Package. The RISC-V OpenSBI library is built in SEC driver without
+any modifications and provides the interfaces for supervisor mode execution environment
+to execute privileged operations.
 
 ## RISC-V Platform PCD settings
 ### EDK2 Firmware Volume Settings
@@ -54,9 +67,9 @@ EDK2 Firmware volume related PCDs which declared in platform FDF file.
 |PcdRiscVSecFvBase| The base address of SEC Firmware Volume|
 |PcdRiscVSecFvSize| The size of SEC Firmware Volume|
 |PcdRiscVPeiFvBase| The base address of PEI Firmware Volume|
-|PcdRiscVPeiFvSize| The size of SEC Firmware Volume|
+|PcdRiscVPeiFvSize| The size of PEI Firmware Volume|
 |PcdRiscVDxeFvBase| The base address of DXE Firmware Volume|
-|PcdRiscVDxeFvSize| The size of SEC Firmware Volume|
+|PcdRiscVDxeFvSize| The size of DXE Firmware Volume|
 
 ### EDK2 EFI Variable Region Settings
 The PCD settings regard to EFI Variable
@@ -84,21 +97,24 @@ Below PCDs could be set in platform FDF file.
 |--------------|---------|
 |PcdHartCount| Number of RISC-V HARTs, the value is processor-implementation specific|
 |PcdBootHartId| The ID of RISC-V HART to execute main fimrware code and boot system to OS|
+|PcdBootableHartNumber|The bootable HART number, which is incorporate with RISC-V OpenSBI platform hart_index2id value|
 
 ### RISC-V OpenSBI Settings
 
 | **PCD name** |**Usage**|
 |--------------|---------|
-|PcdScratchRamBase| The base address of OpenSBI scratch buffer for all RISC-V HARTs|
-|PcdScratchRamSize| The total size of OpenSBI scratch buffer for all RISC-V HARTs|
-|PcdOpenSbiStackSize| The size of initial stack of each RISC-V HART for booting system use OpenSBI|
+|PcdScratchRamBase| The base address of RISC-V OpenSBI scratch buffer for all RISC-V HARTs|
+|PcdScratchRamSize| The total size of RISC-V OpenSBI scratch buffer for all RISC-V HARTs|
+|PcdOpenSbiStackSize| The size of initial stack of each RISC-V HART for booting system use RISC-V OpenSBI|
 |PcdTemporaryRamBase| The base address of temporary memory for PEI phase|
 |PcdTemporaryRamSize| The temporary memory size for PEI phase|
+|PcdPeiCorePrivilegeMode|The target RISC-V privilege mode for edk2 PEI phase|
 
 ## Supported Operating Systems
-Only support to boot to EFI Shell so far.
-
-Porting GRUB2 and Linux EFISTUB is in progress.
+Currently support boot to EFI Shell and Linux kernel.
+Refer to below link for more information,
+https://github.com/riscv/riscv-uefi-edk2-docs
 
 ## Known Issues and Limitations
-Only RISC-V RV64 is verified.
+Only RISC-V RV64 is verified on edk2.
+
-- 
2.25.0

[edk2-platforms][PATCH v3 3/3] Platform/U5SeriesPkg: Revise Readme.md

[Abner Chang]

Update RISC-V U5SeriesPkg Readme.md to align with the latest implementation.

Signed-off-by: Abner Chang <abner.chang@hpe.com>
Co-authored-by: Daniel Schaefer <daniel.schaefer@hpe.com>
Reviewed-by: Daniel Schaefer <daniel.schaefer@hpe.com>

Cc: Leif Lindholm <leif@nuviainc.com>
Cc: Michael D Kinney <michael.d.kinney@intel.com>
Cc: Daniel Schaefer <daniel.schaefer@hpe.com>
---
 Platform/SiFive/U5SeriesPkg/Readme.md | 124 +++++++++++++++-----------
 1 file changed, 72 insertions(+), 52 deletions(-)

diff --git a/Platform/SiFive/U5SeriesPkg/Readme.md b/Platform/SiFive/U5SeriesPkg/Readme.md
index 4d293e54f6..4b0f9ea966 100644
--- a/Platform/SiFive/U5SeriesPkg/Readme.md
+++ b/Platform/SiFive/U5SeriesPkg/Readme.md
@@ -1,92 +1,105 @@
-# Introduction
-U5SeriesPkg provides the common EFI library and driver modules for SiFive
-U5 series core platforms. Currently the supported platforms are Freedom
-U500 VC707 platform and Freedom U540 HiFive Unleashed platform.
-
-Both platforms are built with below common packages,
-- **U5SeriesPkg**, edk2 platform branch
-  (Currently is in edk2-platforms/devel-riscvplatforms branch)
-- **RiscVPlatformPkg**, edk2 master branch
-  (Currently is in edk2-staging/RISC-V-V2 branch)
-- **RiscVPkg**, edk2 master branch
-  (Currently is in edk2-staging/RISC-V-V2 branch)
+# Introduction of SiFive U5 Series Platforms
+U5SeriesPkg provides the common EDK2 libraries and drivers for SiFive U5 series
+platforms. Currently the supported platforms are Freedom U500 VC707 platform and
+Freedom U540 HiFive Unleashed platform.
+
+Both platforms are built with below common edk2 packages under edk2-platforms
+repository,
+- [**U5SeriesPkg**](https://github.com/tianocore/edk2-platforms/tree/master/Platform/SiFive/U5SeriesPkg)
+- [**RiscVPlatformPkg**](https://github.com/tianocore/edk2-platforms/tree/master/Platform/RISC-V/PlatformPkg)
+- [**RiscVProcessorPkg**](https://github.com/tianocore/edk2-platforms/tree/master/Silicon/RISC-V/ProcessorPkg)
 
 ## U500 Platform
-This is a sample RISC-V EDK2 platform package used agaist SiFive Freedom U500
+This is a sample platform package used against to SiFive Freedom U500
 VC707 FPGA Dev Kit, please refer to "SiFive Freedom U500 VC707 FPGA Getting
 Started Guide" on https://www.sifive.com/documentation.
+The binary built from Platform/SiFive/U5SeriesPkg/FreedomU500VC707Board can run
+on U500 VC707 FPGA board.
+```
+build -a RISCV64 -t GCC5 -p Platform/SiFive/U5SeriesPkg/FreedomU500VC707Board/U500.dsc
+```
 
 ## U540 Platform
-This is a sample RISC-V EDK2 platform package used against SiFive Freedom U540
-HiFive Unleashed development board, please refer to "SiFive Freedom U540-C000
-Manual" on https://www.sifive.com.
-The binary built from Platform/SiFive/U5SeriesPkg/FreedomU540HiFiveUnleashedBoard/
-can run on main stream [QEMU](https://git.qemu.org/?p=qemu.git;a=summary)
-using qemu-system-riscv64 under riscv64-softmmu. Launch the binary with
+This is a sample platform package used for the SiFive Freedom U540 HiFive Unleashed
+development board, please refer to "SiFive Freedom U540-C000 Manual" on
+https://www.sifive.com. The binary built from
+Platform/SiFive/U5SeriesPkg/FreedomU540HiFiveUnleashedBoard/ can run on both
+hardware and [QEMU](https://git.qemu.org/?p=qemu.git;a=summary).
+It is confirmed that version 5.0 of QEMU can boot with this  firmware to EFI shell
+and Linux user space.
+```
+build -a RISCV64 -t GCC5 -p Platform/SiFive/U5SeriesPkg/FreedomU540HiFiveUnleashedBoard/U540.dsc
+```
+For running U540 edk2 binary on QEMU, use qemu-system-riscv64 under riscv64-softmmu
+to launch the binary with below parameters,
 
 ```
--cpu sifive-u54 -machine sifive_u
+qemu-system-riscv64 -cpu sifive-u54 -machine sifive_u -bios U540.fd -m 2048 -nographic -smp cpus=5,maxcpus=5
 ```
 
-## Download the sources
+## Download the Source Code
 ```
-git clone https://github.com/tianocore/edk2-staging.git
-# Checkout RISC-V-V2 branch
+git clone https://github.com/tianocore/edk2.git
 git clone https://github.com/tianocore/edk2-platforms.git
-# Checkout devel-riscvplatforms branch
-git clone https://github.com/tianocore/edk2-non-osi.git
+# Below to clone opensbi submodule.
+git submodule update --init
 ```
-
-## Platform Owners
-Chang, Abner <abner.chang@hpe.com>
-Chen, Gilbert <gilbert.chen@hpe.com>
+Refer to [Readme.md](https://github.com/tianocore/edk2-platforms/blob/master/Platform/RISC-V/PlatformPkg/Readme.md) for building RISC-V platforms.
 
 ## Platform Status
-Currently the binary built from U500Pkg can boot SiFive Freedom U500 VC707
+**FreedomU500VC707Board**
+Currently the binary built from U500 edk2 package can boot SiFive Freedom U500 VC707
 FPGA to EFI shell with console in/out enabled.
 
-## Linux Build Instructions
-You can build the RISC-V platform using below script,
-`build -a RISCV64  -t GCC5 -p Platform/SiFive/U5SeriesPkg/FreedomU500VC707Board/U500.dsc`
+**FreedomU540HiFiveUnleashedBoard**
+Currently the binary built from U540 edk2 package can boot SiFive Freedom U540 HiFive
+Unleashed to EFI shell with console in/out enabled and Linux kernel. Please refer to
+https://github.com/riscv/riscv-uefi-edk2-docs for booting to Linux kernel.
 
 ## Supported Operating Systems
-Only support to boot to EFI Shell so far.
+Please refer to https://github.com/riscv/riscv-uefi-edk2-docs.
 
 ## Known Issues and Limitations
 Only RISC-V RV64 is verified on this platform.
 
 ## Related Materials
+- [RISC-V UEFI Documents](https://github.com/riscv/riscv-uefi-edk2-docs)
 - [RISC-V OpenSbi](https://github.com/riscv/opensbi)
-- [SiFive U500 VC707 FPGA Getting Started Guide](https://sifive.cdn.prismic.io/sifive%2Fc248fabc-5e44-4412-b1c3-6bb6aac73a2c_sifive-u500-vc707-gettingstarted-v0.2.pdf)
+- [SiFive U500 VC707 FPGA Getting Started Guide](https://sifive.cdn.prismic.io/
+sifive%2Fc248fabc-5e44-4412-b1c3-6bb6aac73a2c_sifive-u500-vc707-gettingstarted-v0.2.pdf)
 - [SiFive Freedom U540-C000 Manual](https://sifive.cdn.prismic.io/sifive%2F834354f0-08e6-423c-bf1f-0cb58ef14061_fu540-c000-v1.0.pdf)
 - [SiFive RISC-V Core Document](https://www.sifive.com/documentation)
 
 ## U5SeriesPkg Libraries and Drivers
 ### PeiCoreInfoHobLib
-This is the library to create RISC-V core characteristics for building up
-RISC-V related SMBIOS records to support the unified boot loader and OS image.
-This library leverage the silicon libraries provided in Silicon/SiFive.
+This is the library to create RISC-V core characteristics for building up RISC-V
+related SMBIOS records to support a single boot loader  or OS image on all RISC-V
+platforms by discovering RISC-V hart configurations dynamically. This library leverage
+the silicon libraries provided in Silicon/SiFive.
 
 ### RiscVPlatformTimerLib
-This is common U5 series platform timer library which has the
-platform-specific timer implementation.
+This is common U5 series platform timer library which has the platform-specific
+timer implementation.
+
+### SerialLib
+This is common U5 series platform serial port library.
 
 ### TimerDxe
-This is U5 series platform timer DXE driver whcih has the platform-specific
+This is common U5 series platform timer DXE driver which has the platform-specific
 timer implementation.
 
 ## U500 Platform Libraries and Drivers
 ### RiscVOpensbiPlatformLib
 In order to reduce the dependencies with RISC-V OpenSBI project
-(https://github.com/riscv/opensbi) and fewer burdens to EDK2 build process, the
-implementation of RISC-V EDK2 platform is leveraging platform source code from
-OpenSBI code tree. The "platform.c" under OpenSbiPlatformLib is cloned from
-RISC-V OpenSBI code tree (in EDK2 RiscVPkg) and built based on EDK2 build
-environment.
+(https://github.com/riscv/opensbi) and avoid duplicating code we use it, the
+implementation of RISC-V EDK2 platform is leveraging platform source code from OpenSBI
+code tree. The "platform.c" under OpenSbiPlatformLib is cloned from
+[RISC-V OpenSBI code tree](Silicon/RISC-V/ProcessorPkg/Library/RiscVOpensbiLib/opensbi)
+and built based on edk2 build environment.
 
 ### PlatformPei
-This is the platform-implementation specific library which is executed in early
-PEI phase for U500 platform initialization.
+This is the platform-implementation specific library which is executed in early PEI
+phase for U500 platform initialization.
 
 ## U540 Platform Libraries and Drivers
 ### RiscVOpensbiPlatformLib
@@ -94,17 +107,24 @@ In order to reduce the dependencies with RISC-V OpenSBI project
 (https://github.com/riscv/opensbi) and fewer burdens to EDK2 build process, the
 implementation of RISC-V EDK2 platform is leveraging platform source code from
 OpenSBI code tree. The "platform.c" under OpenSbiPlatformLib is cloned from
-RISC-V OpenSBI code tree (in EDK2 RiscVPkg) and built based on EDK2 build
-environment.
+[RISC-V OpenSBI code tree](Silicon/RISC-V/ProcessorPkg/Library/RiscVOpensbiLib/opensbi)
+and built based on edk2build environment.
 
 ### PlatformPei
-This is the platform-implementation specific library which is executed in early
-PEI phase for U540 platform initialization.
+This is the platform-implementation specific library which is executed in early PEI
+phase for U540 platform initialization.
 
 ## U5SeriesPkg Platform PCD settings
 
 | **PCD name** |**Usage**|
 |----------------|----------|
+|PcdU5PlatformSystemClock| U5 series platform system clock|
 |PcdNumberofU5Cores| Number of U5 core enabled on U5 series platform|
 |PcdE5MCSupported| Indicates whether the Monitor Core (E5) is supported on U5 series platform|
 |PcdU5UartBase|Platform serial port base address|
+
+
+## Platform Owners
+Chang, Abner <abner.chang@hpe.com>
+Chen, Gilbert <gilbert.chen@hpe.com>
+Schaefer, Daniel <daniel.schaefer@hpe.com>
-- 
2.25.0