1. About

This project builds up a RISC-V server reference platform to address common challenges faced by SOC vendors in developing platform firmware products, thereby minimizing redundant tasks across the board.

2. Server SOC Reference Model

This chapter introduces the hardware-level topology of ‘rvsp-ref’, allowing users to gain insights into the device list and resource allocation under this model.

2.1 Requirements

This qemu virtual machine (server soc reference board) is required to be compliant with RISC-V Server SOC Spec (the commit id at writing this doc is aec20046c35b108f76a11a751f754505aaad7800) as much as possible.

Table 1 Server SOC Requirement

2.2 High Level Design

The Implementation Choices

• Make the configuration as fixed as possible so that this new machine is easy-to-go and less confusing.
• Remove the unnecessary devices as many as possible, e.g. CLINT/PLIC are removed.
• Keep the MemMap entries as similar as RiscVVirt vm for easy adoption at the early stage.
• Keep dtb entries as small as possible.

Table 2 Devices and Memory Mappings

2.3 Qemu/Guest FW Interface

Hardcode Addresses

It's possible qemu and guest have no explicit interface about some information, e.g. address of specific devices, but both of them hardcodes the same address to access the device.

3 Boot Flow

The following diagram illustrates various platform initialization scenarios. This document will not cover the detailed work of initializing on real hardware platforms, as it is beyond its scope. Our focus will be on the more general firmware initialization tasks performed on the qemu emulator. See the part of the diagram indicated by the blue color, which corresponds to QemuServerPlatform Boot Flow.

Note: For specifics on the qemu Server SOC reference model in this document, it is essential to consult both the latest developments in the qemu source code and the definition in the server platform specifications. Relevant information for both can be obtained from Server SOC TG and Server Platform TG of RVI.c

Figuire 1 RISC-V Platform EDK2 Firmware Enabling Philosophy

3.1 The Traditional Boot Flow

PI Architecture Firmware Phases shows the phases that a platform with PI Architecture firmware will execute.

Figuire 2 PI Architecture Firmware Phases

In a PI Architecture firmware implementation, the phase executed prior to DXE is PEI. This specification covers the transition from the PEI to the DXE phase, the DXE phase, and the DXE phase’s interaction with the BDS phase. The DXE phase does not require a PEI phase to be executed. The only requirement for the DXE phase to execute is the presence of a valid HOB list. There are many different implementations that can produce a valid HOB list for the DXE phase to execute. The PEI phase in a PI Architecture firmware implementation is just one of many possible implementations.

Based on the content quoted from the PI specification above, it is evident that the PEI phase is merely a traditional and integral part of the UEFI boot flow. In actual PI Architecture firmware implementations, it is not mandatory. Currently, the primary purpose of the PEI Phase is to perform memory initialization and pass necessary HOBs to DXE.

For the former, the alternative solution for the former involves the implementation of OOB firmware, which is currently beyond the scope of this document. Regarding the latter, we can move more works for building Hand-Off Blocks (HOBs) to the SEC phase. All of these considerations collectively contribute to providing additional insights and flexibility for the practical initiation of hardware.

3.2 Alternative Boot Flow

The boot flow without the PEI phase, also known as the Pei-Less flow, is the initialization approach that will be further discussed in this document. Detailed standards for Pei-Less can be obtained from RISE's Firmware TG.(See Boot Flow in Project No. EDK2_00_18)

3.2.1 SEC Phase

See HOB Translations for more information on HOB types.

Figuire 3 HOB List

The HOBs list, as mandated by the PI specification, is illustrated in Figure 2.3. It is recommended to refer to the SecMain structure in RiscVVirt for guidance.

Figure 2.3 displays the HOBs list, a prerequisite set by the PI specification for readiness before entering the DXE phase. For additional insights, it is recommended to refer to the SecMain module in RiscVVirt.

Regarding memory initialization, specific details are intentionally omitted in this document. The recommended strategy involves the use of OOB firmware, like SPL. This provides input to the System Memory HOB generated by the UEFI firmware during the SEC phase, and the input for HOB is extracted from static data in the device tree, including entries like 'memory' by AddMemoryBaseSizeHob() and 'reserved-memory BuildMemoryAllocationHob().'

The creation of HOBs for IO, MMIO, and other resources provides SOC vendors with the flexibility to customize according to their chip specifications. The PopulateIoResources() function provides a straightforward approach to achieve this customization.

It is essential to emphasize that RiscVVirt adopts a separate Flash Descriptor (FD) approach for firmware code and Variables. The advantage is clear as it allows for the protection of the firmware code by setting it as read-only, while conferring write permissions exclusively to the Variable FD, effectively ensuring the security of the firmware. Particularly, this approach provides convenient and flexible control, especially when dealing with firmware upgrade actions in the future. Of course, in qemu-based firmware development, virtualizing two or even more flashes is extremely straightforward. However, it's worth mentioning that in many real hardware platforms, the single-flash configuration is more common, and further elaboration on this point is not necessary here.

In the upcoming server platform solution, we will continue to adopt a similar approach as RiscVVirt. However, there is a slight difference in the treatment of the Variable FD.

3.2.2 DXE Phase

The following table supplements the missing implementation details in Table 2.5: DXE Architectural Protocols of the PI 1.8A specification. The DXE Foundation is abstracted from the platform through the DXE Architectural Protocols. The DXE Architectural Protocols manifest the platform-specific components of the DXE Foundation. DXE drivers that are loaded and executed by the DXE Dispatcher component of the DXE Foundation must produce these protocols.

For implementations outside of the EmbeddedPkg solutions, please follow the guidance outlined in the table.

Table 3 DXE Architectural Protocols

Note: 1.The 'Driver Compatibility, task required' column addresses platform dependencies exclusively at the DXE driver level. The platform-specificity of the consumed libraries does not influence the conclusion.

3.2.3 Network Stack

The Server SOC model currently in use, 'rvsp-ref,' comes with e1000 as the default NIC device. However, as this device lacks an integrated UEFI UNDI driver, it cannot provide the foundational services to enable the network. From a testing perspective, here are two recommended steps：

• Build UndiRuntimeDxe to your firmware FD, with the following patch: edk2-platforms/Drivers/OptionRomPkg/UndiRuntimeDxe/UndiRuntimeDxe.inf
• Append NIC ‘i82557b’ to the qemu command line. See the reference command in Chapter 4.

From a product implementation perspective, it is not recommended to directly use UndiRuntimeDxe as the provider for the UNDI services. It is more appropriate to provide the UNDI services based on the NIC device integrated into the platform.

3.3 Extra work for Fdt-to-OS

The DXE Foundation produces the UEFI System Table, and the UEFI System Table is consumed by every DXE driver and executable image invoked by the DXE Dispatcher and BDS. It contains all the information required for these components to utilize the services provided by the DXE Foundation and the services provided by any previously loaded DXE driver. UEFI System Table and Related Components shows the various components that are available through the UEFI System Table.

Figuire 4 UEFI System Table and Related Components

As shown in figure 9.2, the UEFI Configuration Tables are an extensible list of tables that describe the configuration of the platform. Today, this includes pointers to tables such as DXE Services, the HOB list, ACPI table, SMBIOS table, and the SAL System Table. This list may be expanded in the future as new table types are defined.

Due to the broad usage of device trees in embedded firmware products, several chip manufacturers in the upstream and downstream supply chains use static data from the device tree to initialize specific peripherals. For compatibility reasons, it is essential to install the device tree pointer into the system configuration table. Two DXE drivers are available as references:

Table 4 The Proposal for FdtTabGuid

3.4 DT File Decoding

The DXE driver FdtClientDxe, mentioned in the previous section, supplies a limited set of APIs for parsing DT binary, handling fundamental DT data extraction tasks.

Users with more advanced demands can turn to another DXE service produced by FdtBusPkg, which offers an extensive array of APIs to meet the requirements of more complex scenarios. Detailed information is accessible in the firmware TG of RISE community (Project No. EDK2_00_03), and the source code is available from FdtBusPkg repository. It will be upstreamed to the edk2 repository in the future, and any suggestions or requirements for improvement are encouraged before this transition.

3.5 OpenSbi

It is recommended to align with the version of OpenSBI in the RISC-V BRS Development Suite Repository. The binary file can be found at the following path: ./rv-brs-test-suite/brsi/scripts/opensbi/build/platform/generic/firmware/fw_dynamic.bin

Or build it by the command example1:

cd opensbi
make ARCH=riscv CROSS_COMPILE=riscv64-linux-gnu- PLATFORM=generic

3.6 OS Image

Similarly, the BRS Repo offers an OS image based on RISC-V. To validate the boot flow, you can make use of the prebuilt images located in the test suite at /rv-brs-test-suite/brsi/prebuilt_images/. For those interested in building their own image, please refer to the repository guidance for detailed steps.

4 Development Environment Setup

4.1 Compiling edk2 firmware separately outside of BRS (Manually)

1. Building the RISC-V edk2 server platform

git clone https://github.com/tianocore/edk2.git
cd edk2
git submodule update --init
cd ..

git clone https://github.com/tianocore/edk2-platforms.git
cd edk2-platforms
git submodule update --init
cd ..

export WORKSPACE=`pwd`
export GCC5_RISCV64_PREFIX=riscv64-linux-gnu-
export PACKAGES_PATH=$WORKSPACE/edk2:$WORKSPACE/edk2-platforms

cd edk2
make -C BaseTools clean
make -C BaseTools
source edksetup.sh
./edksetup.sh

build -a RISCV64 -t GCC5 -p Platform/Qemu/RiscVQemuServerPlatform/RiscVQemuServerPlatform.dsc

2. Convert FD files

 truncate -s 32M Build/RiscVQemuServerPlatform/DEBUG_GCC5/FV/RISCV_SP_CODE.fd
 truncate -s 32M Build/RiscVQemuServerPlatform/DEBUG_GCC5/FV/RISCV_SP_VARS.fd

3. Boot Execution

Command example1:

./qemu-system-riscv64 -nographic -m 8G -smp 2 \
 -machine rvsp-ref,pflash0=pflash0,pflash1=pflash1 \
 -blockdev node-name=pflash0,driver=file,read-only=on,filename=$FW_DIR/RISCV_SP_CODE.fd \
 -blockdev node-name=pflash1,driver=file,filename=$FW_DIR/RISCV_SP_VARS.fd \
 -bios $Sbi_DIR/fw_dynamic.bin \
 -drive file=$Img_DIR/brs_live_image.img,if=ide,format=raw

Note:

• ‘rvsp-ref’ is a specified qemu-based SOC model, whose source code is still under development and will be accessible from the RVI staging repository later. (The ongoing patch can be found in the web)
• The Pre-build image ‘brs_live_image.img,if’ can be downloaded in RISC-V BRS Development Suite repository, or you can build it by yourself. See 3.6
• ‘-bios $Sbi_DIR/fw_dynamic.bin’ the parameter points to the opensbi path. See more in 3.5.

In general, a series of modules related to Network are enabled by default. However, during SCT test execution, it is noticed that most Network test items fail to pass. The most likely reason is the lack of a UNDI driver built in the current platform firmware codebase. So, if you intend to enable the edk2 network stack with QEMU in the boot flow, it is suggested to use the following command:

Command example2:

  Command example1 \
  -device i82557b,netdev=net2 \
  -netdev type=user,id=net2

4.2 Building and running based on BRS environment (Automatically)

1. Build brs test suit

git clone https://github.com/intel/rv-brs-test-suite.git

The test suite's default Qemu model(virt) is established on a virtual hardware platform that leverages Virtio services provided by the Ovmf package. Obviously, to validate the current server platfor m with the test suite, modifications are required at minimum in both Qemu and the edk2 firmware.

By the build steps from README.md, the necessary code changes can be completed in two steps.

   Step 1.1:  change common/scripts/get_source.sh 

get_edk2_src()
{
    git clone --depth 1 --single-branch \
    --branch edk2-stable202308 https://github.com/tianocore/edk2.git
    pushd $TOP_DIR/edk2

    git submodule update --init

    popd

    git clone --depth 1 --single-branch \
    --branch master https://github.com/tianocore/edk2-platforms.git
    pushd $TOP_DIR/edk2-platforms

    git submodule update --init
    popd
}

 Step 1.2:  change brsi/scripts/build-scripts/start_qemu.sh

build_edk2()
{
    if [ ! -d "$TOP_DIR/edk2" ];then
        source ./build-scripts/get_brsi_source.sh
        source ./build-scripts/build_brsi.sh
        source ./build-scripts/build_image.sh
    fi
    if [ -f "$TOP_DIR/Build/RiscVQemuServerPlatform/${UEFI_BUILD_MODE}_${UEFI_TOOLCHAIN}/FV/RISCV_SP_CODE.fd" ];then
        echo "skip build edk2."
    else
        echo "build edk2..."
        pushd $TOP_DIR
        export GCC5_RISCV64_PREFIX=riscv64-linux-gnu-
        export PACKAGES_PATH=$TOP_DIR/edk2
        export EDK_TOOLS_PATH=$TOP_DIR/edk2/BaseTools
        source edk2/edksetup.sh
        make -C edk2/BaseTools clean
        make -C edk2/BaseTools
        make -C edk2/BaseTools/Source/C
        source edk2/edksetup.sh BaseTools
        build -a RISCV64 --buildtarget ${UEFI_BUILD_MODE} -p Platform/Qemu/RiscVQemuServerPlatform/RiscVQemuServerPlatform.dsc -t ${UEFI_TOOLCHAIN}
        truncate -s 32M Build/RiscVQemuServerPlatform/${UEFI_BUILD_MODE}_${UEFI_TOOLCHAIN}/FV/RISCV_SP_CODE.fd
        truncate -s 32M Build/RiscVQemuServerPlatform/${UEFI_BUILD_MODE}_${UEFI_TOOLCHAIN}/FV/RISCV_SP_VARS.fd
        popd
    fi
}

continue to follow the remaining steps in the README.md,   start from executing './build-scripts/build_brsi.sh' and './build-scripts/build_image.sh'.

2.  Run a combined script for Boot and test functions

 ./build-scripts/start_qemu.sh

4.3 Verification

The tests covered in this document are based on the BRS spec, focusing on two primary modules: SCT and FWTS. The relevant test scripts, pre-build image and guidance can be obtained from the RISC-V BRS Development Suite Repository.


5 WIP and Pending Tasks

The listed items in the table represent ongoing firmware development tasks that are still unfinished. Some specifications are in the process of refinement, and a few are yet to be drafted. Please refer to subsequent updates from the RISE community for more information.

5.1 Bios Requirements and TODOs

Table 5 Bios Requirements

5.2 UEFI Implementation and TODOs

Table 6 Upcoming UEFI Features List

6 Known Issues

The following table outlines the current known issues, which will be resolved gradually during the subsequent phases of development.

Table 7 Known Issues

7 Appendix

1. The patch of Qemu model ‘rvsp-ref’ :  Add RISC-V Server Platform Reference Board

========================================================================================================================================================================

References

Server Soc Specification: https://github.com/riscv-non-isa/server-soc

Server Platform Specification: https://github.com/riscv-non-isa/riscv-server-platform

BRS Specification: https://github.com/riscv-non-isa/riscv-brs 

Boot Flow: EDK2 implementation choices for RISC-V platforms.pdf

RISC-V BRS Development Suite Repository: https://github.com/intel/rv-brs-test-suite

Project Scope and Timelines

Slides in the monthly meeting: 2024-01-RISCV Edk2 Qemu Server Platform Package Proposal - V3.1.pdf

Porting Guide: RISC-V Edk2 Server Reference Platform_v0.1.pdf

Components and Repos

Repos:
 edk2-platform: https://github.com/ChaiEvan/edk2-platforms/tree/RV_ServerPlatformRef_v1

Dependencies

Server SOC spec and Server Platform Spec

Measure of Success

Code upstream to edk2-platform

Stakeholders and Partners

• RISE
  • Intel: Evan Chai <evan.chai@intel.com>

Status

Updates

14 Jun 2024 

Plan in Q3 could be create the initial qemu server platform codebase with some of the ACPI/SMBIOS table implementation, and upstream to edk2-platforms

UEFI Implementation for RiscVQemuServerPlatform.pdf