diff options
| -rw-r--r-- | README.md | 103 | ||||
| -rw-r--r-- | docs/contributing.md | 23 | ||||
| -rw-r--r-- | docs/doxygen.cfg | 2 | ||||
| -rw-r--r-- | docs/firmware/fw_jump.md | 22 | ||||
| -rw-r--r-- | docs/firmware/fw_payload.md | 31 | ||||
| -rw-r--r-- | docs/firmware/payload_linux.md | 9 | ||||
| -rw-r--r-- | docs/firmware/payload_uboot.md | 16 | ||||
| -rw-r--r-- | docs/library_usage.md | 33 | ||||
| -rw-r--r-- | docs/platform/platform.md | 16 | ||||
| -rw-r--r-- | docs/platform_guide.md | 32 |
10 files changed, 146 insertions, 141 deletions
@@ -1,4 +1,5 @@ -Copyright (c) 2019 Western Digital Corporation or its affiliates. +Copyright (c) 2019 Western Digital Corporation or its affiliates +and other contributors. RISC-V Open Source Supervisor Binary Interface (OpenSBI) ======================================================== @@ -6,53 +7,55 @@ RISC-V Open Source Supervisor Binary Interface (OpenSBI) The **RISC-V Supervisor Binary Interface (SBI)** is the recommended interface between: -1. A platform specific firmware running in M-mode and bootloader, hypervisor or - a general purpose OS executing in S-mode or HS-mode. -2. A hypervisor running in HS-mode and a bootloader or a general purpose OS +1. A platform-specific firmware running in M-mode and a bootloader, a + hypervisor or a general-purpose OS executing in S-mode or HS-mode. +2. A hypervisor running in HS-mode and a bootloader or a general-purpose OS executing in VS-mode. The *RISC-V SBI specification* is maintained as an independent project by the -RISC-V Foundation in [Github]. +RISC-V Foundation on [Github] (https://github.com/riscv/riscv-sbi-doc). The goal of the OpenSBI project is to provide an open-source reference -implementation of the RISC-V SBI specifications for platform specific firmwares -executing in M-mode (case 1 mentioned above). OpenSBI implementation can be +implementation of the RISC-V SBI specifications for platform-specific firmwares +executing in M-mode (case 1 mentioned above). An OpenSBI implementation can be easily extended by RISC-V platform and system-on-chip vendors to fit a particular hardware configuration. -The main component of OpenSBI is provided in the form of a platform independent +The main component of OpenSBI is provided in the form of a platform-independent static library **libsbi.a** implementing the SBI interface. A firmware or bootloader implementation can link against this library to ensure conformance with the SBI interface specifications. *libsbi.a* also defines an interface for -integrating with platform specific operations provided by the platform firmware -implementation (e.g. console access functions, inter-processor interrupts +integrating with platform-specific operations provided by the platform firmware +implementation (e.g. console access functions, inter-processor interrupt control, etc). -To illustrate the use of *libsbi.a* library, OpenSBI also provides a set of -platform specific support examples. For each example, a platform -specific static library *libplatsbi.a* can be compiled. This library implements -SBI calls processing by integrating *libsbi.a* with necessary platform dependent -hardware manipulation functions. For all supported platforms, OpenSBI also -provides several runtime firmware examples built using the platform +To illustrate the use of the *libsbi.a* library, OpenSBI also provides a set of +platform-specific support examples. For each example, a platform-specific +static library *libplatsbi.a* can be compiled. This library implements +SBI call processing by integrating *libsbi.a* with the necessary +platform-dependent hardware manipulation functions. For all supported platforms, +OpenSBI also provides several runtime firmware examples built using the platform *libplatsbi.a*. These example firmwares can be used to replace the legacy -*riskv-pk* bootloader (aka BBL) and enable the use of well known bootloaders -such as [U-Boot]. +*riscv-pk* bootloader (aka BBL) and enable the use of well-known bootloaders +such as [U-Boot] (https://git.denx.de/u-boot.git). Required Toolchain ------------------ OpenSBI can be compiled natively or cross-compiled on a x86 host. For -cross-compilation, you can build your tool chain or just download from -the [bootlin] (https://toolchains.bootlin.com/). +cross-compilation, you can build your own toolchain or just download +a prebuilt one from the +[Bootlin toolchain repository] (https://toolchains.bootlin.com/). -Please note that only 64bit version of toolchain is available in bootlin -for now. +Please note that only a 64bit version of the toolchain is available in +the Bootlin toolchain repository for now. -Building and Installing OpenSBI Platform Independent Library ------------------------------------------------------------- +Building and Installing the OpenSBI Platform-Independent Library +---------------------------------------------------------------- -OpenSBI platform independent static library *libsbi.a* can be natively compiled -or cross-compiled on a host with a different base architecture than RISC-V. +The OpenSBI platform-independent static library *libsbi.a* can be compiled +natively or it can be cross-compiled on a host with a different base +architecture than RISC-V. For cross-compiling, the environment variable *CROSS_COMPILE* must be defined to specify the name prefix of the RISC-V compiler toolchain executables, e.g. @@ -63,8 +66,8 @@ To build *libsbi.a* simply execute: make ``` -All compiled binaries as well as the result *libsbi.a* static library file will -be placed in the *build/lib* directory. To specify an alternate build root +All compiled binaries as well as the resulting *libsbi.a* static library file +will be placed in the *build/lib* directory. To specify an alternate build root directory path, run: ``` make O=<build_directory> @@ -76,38 +79,38 @@ make install ``` This will create the *install* directory with all necessary include files -copied under the *install/include* directory and library file copied in the -*install/lib* directory. To specify an alternate installation root directory -path, run: +copied under the *install/include* directory and the library file copied into +the *install/lib* directory. To specify an alternate installation root +directory path, run: ``` make I=<install_directory> install ``` -Building and Installing a Reference Platform Static Library and Firmwares -------------------------------------------------------------------------- +Building and Installing a Reference Platform Static Library and Firmware +------------------------------------------------------------------------ When the *PLATFORM=<platform_subdir>* argument is specified on the make command -line, the platform specific static library *libplatsbi.a* and firmware examples +line, the platform-specific static library *libplatsbi.a* and firmware examples are built for the platform *<platform_subdir>* present in the directory -*platform* in OpenSBI top directory. For example, to compile the platform -library and firmware examples for QEMU RISC-V *virt* machine, +*platform* in the OpenSBI top directory. For example, to compile the platform +library and the firmware examples for the QEMU RISC-V *virt* machine, *<platform_subdir>* should be *qemu/virt*. -To build *libsbi.a*, *libplatsbi.a* and the firmwares for one of the supported -platform, run: +To build *libsbi.a*, *libplatsbi.a* and the firmware for one of the supported +platforms, run: ``` make PLATFORM=<platform_subdir> ``` -An alternate build directory path can also be specified. +An alternate build directory path can also be specified: ``` make PLATFORM=<platform_subdir> O=<build_directory> ``` -The platform specific library *libplatsbi.a* will be generated in the +The platform-specific library *libplatsbi.a* will be generated in the *build/platform/<platform_subdir>/lib* directory. The platform firmware files will be under the *build/platform/<platform_subdir>/firmware* directory. -The compiled firmwares will be available in two different format: an ELF file +The compiled firmwares will be available in two different formats: an ELF file and an expanded image file. To install *libsbi.a*, *libplatsbi.a*, and the compiled firmwares, run: @@ -115,16 +118,16 @@ To install *libsbi.a*, *libplatsbi.a*, and the compiled firmwares, run: make PLATFORM=<platform_subdir> install ``` -This will copy the compiled platform specific libraries and firmware files +This will copy the compiled platform-specific libraries and firmware files under the *install/platform/<platform_subdir>/* directory. An alternate -install root directory path can be specified as follows. +install root directory path can be specified as follows: ``` make PLATFORM=<platform_subdir> I=<install_directory> install ``` -In addition, platform specific configuration options can be specified with the +In addition, platform-specific configuration options can be specified with the top-level make command line. These options, such as *PLATFORM_<xyz>* or -*FW_<abc>*, are platform specific and described in more details in the +*FW_<abc>*, are platform-specific and described in more details in the *docs/platform/<platform_name>.md* files and *docs/firmware/<firmware_name>.md* files. @@ -155,7 +158,7 @@ files where the reused code is present. under the terms of the BSD 2-Clause license. Any contributions to this code must be made under the terms of both licenses. 2. Some source file for the Kendryte/k210 platform code are based on code from - the Kendryte [standalone SDK] available on github. These files retain the + the [Kendryte standalone SDK] available on github. These files retain the original copyright and license of the Kendryte standalone SDK project and are licensed under the terms of the Apache License, Version 2.0. @@ -165,7 +168,7 @@ Contributing to OpenSBI ----------------------- The OpenSBI project encourages and welcomes contributions. Contributions should -follow the rules described in OpenSBI [Contribution Guideline] document. +follow the rules described in the OpenSBI [Contribution Guideline] document. In particular, all patches sent should contain a Signed-off-by tag. The [Contributors List] document provides a list of individuals and @@ -185,7 +188,7 @@ Detailed documentation of various aspects of OpenSBI can be found under the examples build supported by OpenSBI. OpenSBI source code is also well documented. For source level documentation, -doxygen style is used. Please refer to [Doxygen manual] for details on this +doxygen style is used. Please refer to the [Doxygen manual] for details on this format. Doxygen can be installed on Linux distributions using *.deb* packages using @@ -234,6 +237,6 @@ make I=<install_directory> install_docs [Platform Support Guide]: docs/platform_guide.md [Platform Documentation]: docs/platform/platform.md [Firmware Documentation]: docs/firmware/fw.md -[Doxygen manual]: http://www.stack.nl/~dimitri/doxygen/manual.html -[standalone SDK]: https://github.com/kendryte/kendryte-standalone-sdk +[Doxygen manual]: http://www.doxygen.nl/manual/index.html +[Kendryte standalone SDK]: https://github.com/kendryte/kendryte-standalone-sdk [third party notices]: ThirdPartyNotices.md diff --git a/docs/contributing.md b/docs/contributing.md index 2291089..7b9898f 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -1,19 +1,20 @@ OpenSBI Contribution Guideline ============================== -All contributions to OpenSBI can be sent in following ways: -1. Email patches to OpenSBI mailing list `opensbi@lists.infradead.org` -2. GitHub Pull Requests (PRs) to [OpenSBI main repository] +All contributions to OpenSBI can be sent in the following ways: +1. Email patches to the OpenSBI mailing list at `opensbi@lists.infradead.org` +2. GitHub Pull Requests (PRs) to the [OpenSBI main repository] -To join OpenSBI mailing list, please visit [OpenSBI infradead page]. +To join the OpenSBI mailing list, please visit the [OpenSBI infradead page]. -OpenSBI maintainers prefer patches via OpenSBI mailing list (option1 above) -so that they are visible to wider audience. All accepted patches on the -OpenSBI mailing list will be taken by any of the OpenSBI maintainers and -merged into [OpenSBI main repository] using GitHub PRs. +The OpenSBI maintainers prefer patches via the OpenSBI mailing list +(option 1 above) so that they are visible to a wider audience. All +accepted patches on the OpenSBI mailing list will be taken by any of +the OpenSBI maintainers and merged into the [OpenSBI main repository] +using GitHub PRs. All contributed work must follow the following rules: -1. OpenSBI code should be written in accordance to [Linux coding style]. +1. OpenSBI code should be written in accordance to the [Linux coding style]. 2. This project embraces the [Developer Certificate of Origin (DCO)] for contributions. This means that you must agree to the following prior to submitting patches: if you agree with this developer certificate you @@ -27,9 +28,9 @@ prefixes are for example "lib:", "platform:", "firmware:", "docs:" and "top:". 5. Maintainers should use "Rebase and Merge" when using GitHub to merge pull requests to avoid creating unnecessary merge commits. 6. Maintainers should avoid creating branches directly in the main -riscv/opensbi repository. Instead prefer using a fork of riscv/opensbi main +riscv/opensbi repository. Instead prefer using a fork of the riscv/opensbi main repository and branches within that fork to create pull requests. -7. A maintainer cannot merge his own pull requests in riscv/opensbi main +7. A maintainer cannot merge his own pull requests in the riscv/opensbi main repository. 8. A pull request must get at least one review from a maintainer. 9. A pull request must spend at least 24 hours in review to allow for other diff --git a/docs/doxygen.cfg b/docs/doxygen.cfg index feb461b..8ab53ed 100644 --- a/docs/doxygen.cfg +++ b/docs/doxygen.cfg @@ -44,7 +44,7 @@ PROJECT_NUMBER = "v@@OPENSBI_MAJOR@@.@@OPENSBI_MINOR@@" # for a project that appears at the top of each page and should give viewer a # quick idea about the purpose of the project. Keep the description short. -PROJECT_BRIEF = "Open source implemenation of supervisor binary interface" +PROJECT_BRIEF = "Open source implemenation of the supervisor binary interface" # With the PROJECT_LOGO tag one can specify a logo or an icon that is included # in the documentation. The maximum height of the logo should not exceed 55 diff --git a/docs/firmware/fw_jump.md b/docs/firmware/fw_jump.md index da21cda..7fdeeb4 100644 --- a/docs/firmware/fw_jump.md +++ b/docs/firmware/fw_jump.md @@ -6,19 +6,19 @@ handles the address of the next booting stage entry, e.g. a bootloader or an OS kernel, without directly including the binary code for this next stage. A *FW_JUMP* firmware is particularly useful when the booting stage executed -prior to OpenSBI firmware is capable of loading both the OpenSBI firmware and -the booting stage binary to follow OpenSBI firmware. +prior to the OpenSBI firmware is capable of loading both the OpenSBI firmware +and the booting stage binary to follow the OpenSBI firmware. *FW_JUMP* Compilation --------------------- -A platform *FW_JUMP* firmware can be enabled by any of the following methods. +A platform *FW_JUMP* firmware can be enabled by any of the following methods: 1. Specifying `FW_JUMP=y` on the top level `make` command line. 2. Specifying `FW_JUMP=y` in the target platform *config.mk* configuration file. The compiled *FW_JUMP* firmware ELF file is named *fw_jump.elf*. Its expanded -image file is *fw_jump.bin*. Both files are created in the platform specific +image file is *fw_jump.bin*. Both files are created in the platform-specific build directory under the *build/platform/<platform_subdir>/firmware* directory. *FW_JUMP* Firmware Configuration Options @@ -27,26 +27,26 @@ build directory under the *build/platform/<platform_subdir>/firmware* directory. To operate correctly, a *FW_JUMP* firmware requires some configuration parameters to be defined using either the top level `make` command line or the target platform *config.mk* configuration file. The possible parameters are as -follows. +follows: * **FW_JUMP_ADDR** - Address of the entry point of the booting stage to be - executed following OpenSBI firmware. This address generally correspond + executed following OpenSBI firmware. This address generally corresponds exactly to the address where this next booting stage was loaded. This is a mandatory parameter. Compilation errors will result from not defining this address. * **FW_JUMP_FDT_ADDR** - Address where the *flattened device tree (FDT file)* passed by the prior booting stage will be placed in memory before executing - the booting stage following OpenSBI firmware. If this option is not provided, - then OpenSBI firmware will pass zero as the FDT address to the following - booting stage. + the booting stage following the OpenSBI firmware. If this option is not + provided, then the OpenSBI firmware will pass zero as the FDT address to the + following booting stage. *FW_JUMP* Example ----------------- -The *[qemu/virt]* and *[qemu/sifive_u]* platforms illustrates how to configure +The *[qemu/virt]* and *[qemu/sifive_u]* platforms illustrate how to configure and use a *FW_JUMP* firmware. Detailed information regarding these platforms -can be found in the platforms documentation files. +can be found in the platform documentation files. [qemu/virt]: ../platform/qemu_virt.md [qemu/sifive_u]: ../platform/qemu_sifive_u.md diff --git a/docs/firmware/fw_payload.md b/docs/firmware/fw_payload.md index 72ea9bb..c9a9ad8 100644 --- a/docs/firmware/fw_payload.md +++ b/docs/firmware/fw_payload.md @@ -2,22 +2,22 @@ OpenSBI Firmware with Payload *FW_PAYLOAD* ========================================== OpenSBI **firmware with Payload (FW_PAYLOAD)** is a firmware which directly -includes the binary for the booting stage to follow OpenSBI firmware execution. -Typically, this payload will be a bootloader or an OS kernel. +includes the binary for the booting stage to follow the OpenSBI firmware +execution. Typically, this payload will be a bootloader or an OS kernel. A *FW_PAYLOAD* firmware is particularly useful when the booting stage executed -prior to OpenSBI firmware is not capable of loading both OpenSBI firmware and -the booting stage to follow OpenSBI firmware. +prior to the OpenSBI firmware is not capable of loading both the OpenSBI +firmware and the booting stage to follow OpenSBI firmware. A *FW_PAYLOAD* firmware is also useful for cases where the booting stage prior -to OpenSBI firmware does not pass a *flattened device tree (FDT file)*. In such -case, a *FW_PAYLOAD* firmware allows embedding a flattened device tree in the -.text section of the final firmware. +to the OpenSBI firmware does not pass a *flattened device tree (FDT file)*. In +such a case, a *FW_PAYLOAD* firmware allows embedding a flattened device tree +in the .text section of the final firmware. Enabling *FW_PAYLOAD* compilation --------------------------------- -The *FW_PAYLOAD* firmware can be enabled by any of the following methods. +The *FW_PAYLOAD* firmware can be enabled by any of the following methods: 1. Specifying `FW_PAYLOAD=y` on the top level `make` command line. 2. Specifying `FW_PAYLOAD=y` in the target platform *config.mk* configuration @@ -25,7 +25,7 @@ The *FW_PAYLOAD* firmware can be enabled by any of the following methods. The compiled *FW_PAYLOAD* firmware ELF file is named *fw_jump.elf*. Its expanded image file is *fw_payload.bin*. Both files are created in the -platform specific build directory under the +platform-specific build directory under the *build/platform/<platform_subdir>/firmware* directory. Configuration Options @@ -34,7 +34,7 @@ Configuration Options A *FW_PAYLOAD* firmware is built according to configuration parameters and options. These configuration parameters can be defined using either the top level `make` command line or the target platform *config.mk* configuration -file. The parameters currently defined are as follows. +file. The parameters currently defined are as follows: * **FW_PAYLOAD_OFFSET** - Offset from *FW_TEXT_BASE* where the payload binary will be linked in the final *FW_PAYLOAD* firmware binary image. This @@ -47,8 +47,8 @@ file. The parameters currently defined are as follows. will be linked after the end of the base firmware binary in the final *FW_PAYLOAD* firmware binary image. This configuration parameter is mandatory if *FW_PAYLOAD_OFFSET* is not defined. If both *FW_PAYLOAD_OFFSET* and - *FW_PAYLOAD_ALIGN* are defined, *FW_PAYLOAD_OFFSET* is used and - *FW_PAYLOAD_ALIGN* ignored. + *FW_PAYLOAD_ALIGN* are defined, *FW_PAYLOAD_OFFSET* is used and + *FW_PAYLOAD_ALIGN* is ignored. * **FW_PAYLOAD_PATH** - Path to the image file of the next booting stage binary. If this option is not provided then a simple test payload is @@ -78,13 +78,12 @@ file. The parameters currently defined are as follows. *FW_PAYLOAD* Example -------------------- -The *[qemu/virt]* and *[qemu/sifive_u]* platforms illustrates how to configure +The *[qemu/virt]* and *[qemu/sifive_u]* platforms illustrate how to configure and use a *FW_PAYLOAD* firmware. Detailed information regarding these platforms -can be found in the platforms documentation files. +can be found in the platform documentation files. -The *kendryte/k210* platform also enables build of a *FW_PAYLOAD* using an +The *kendryte/k210* platform also enables a build of a *FW_PAYLOAD* using an internally defined device tree file (*FW_PAYLOAD_FDT*). [qemu/virt]: ../platform/qemu_virt.md [qemu/sifive_u]: ../platform/qemu_sifive_u.md - diff --git a/docs/firmware/payload_linux.md b/docs/firmware/payload_linux.md index ccbad31..048eb50 100644 --- a/docs/firmware/payload_linux.md +++ b/docs/firmware/payload_linux.md @@ -1,11 +1,10 @@ Linux as a direct payload to OpenSBI ==================================== -OpenSBI has the capability to load Linux kernel image directly in supervisor +OpenSBI has the capability to load a Linux kernel image directly in supervisor mode. The flattened image generated by the Linux kernel build process can be -provided as payload to OpenSBI. +provided as a payload to OpenSBI. -Detailed examples and platform guides can be found in both [QEMU]( -../platform/qemu_virt.md) and [HiFive Unleashed](../platform/sifive_fu540.md) -platform guide respectively. +Detailed examples can be found in both the [QEMU](../platform/qemu_virt.md) +and the [HiFive Unleashed](../platform/sifive_fu540.md) platform guides. diff --git a/docs/firmware/payload_uboot.md b/docs/firmware/payload_uboot.md index 42bf55f..d30f6f8 100644 --- a/docs/firmware/payload_uboot.md +++ b/docs/firmware/payload_uboot.md @@ -4,30 +4,32 @@ U-Boot as a payload to OpenSBI [U-Boot](https://www.denx.de/wiki/U-Boot) is an open-source primary boot loader. It can be used as first and/or second stage boot loader in an embedded environment. In the context of OpenSBI, U-Boot can be specified as a payload to -OpenSBI firmware, becoming the boot stage following OpenSBI firmware +the OpenSBI firmware, becoming the boot stage following the OpenSBI firmware execution. The current stable upstream code of U-Boot does not yet include all patches necessary to fully support OpenSBI. To use U-Boot as an OpenSBI payload, the following out-of-tree patch series must be applied to the upstream U-Boot source -code. +code: HiFive Unleashed support for U-Boot https://lists.denx.de/pipermail/u-boot/2019-February/358058.html This patch series enables a single CPU to execute U-Boot. As a result, the next -stage boot code such as Linux kernel can also only execute a single CPU. U-Boot -SMP support for RISC-V can be enabled with the following additional patches. +stage boot code such as a Linux kernel can also only execute on a single CPU. +U-Boot SMP support for RISC-V can be enabled with the following additional +patches: https://lists.denx.de/pipermail/u-boot/2019-February/358393.html Building and Generating U-Boot images ===================================== -Please refer to U-Boot build documentation for detailed instructions on how to build U-Boot images. +Please refer to the U-Boot build documentation for detailed instructions on +how to build U-Boot images. -Once U-Boot images are built, Linux kernel image need to be converted to a format -that U-Boot understands. +Once U-Boot images are built, the Linux kernel image needs to be converted +into a format that U-Boot understands: ``` <uboot-dir>/tools/mkimage -A riscv -O linux -T kernel -C none -a 0x80200000 -e 0x80200000 -n Linux -d \ diff --git a/docs/library_usage.md b/docs/library_usage.md index 579411f..92d51f5 100644 --- a/docs/library_usage.md +++ b/docs/library_usage.md @@ -3,46 +3,46 @@ OpenSBI Library Usage OpenSBI provides two types of static libraries: -1. *libsbi.a* - A platform independent generic static library implementing the - interface defined by the SBI specifications. Platform specific processing +1. *libsbi.a* - A platform-independent generic static library implementing the + interface defined by the SBI specifications. Platform-specific processing hooks for the execution of this interface must be provided by the firmware or bootloader linking with this library. This library is installed as *<install_directory>/lib/libsbi.a* -2. *libplatsbi.a* - An example platform specific static library integrating - *libsbi.a* with platform specific hooks. This library is available only for +2. *libplatsbi.a* - An example platform-specific static library integrating + *libsbi.a* with platform-specific hooks. This library is available only for the platforms supported by OpenSBI. This library is installed as *<install_directory>/platform/<platform_subdir>/lib/libplatsbi.a* Implementations may choose either *libsbi.a* or *libplatsbi.a* to link with -their firmware or bootloader. In the case of *libsbi.a*, platform specific -hooks in the form of a *struct sbi_platform* instance needs to be provided. +their firmware or bootloader. In the case of *libsbi.a*, platform-specific +hooks in the form of a *struct sbi_platform* instance need to be provided. -The platform specific example firmwares provided by OpenSBI are not mandatory. -An implementation may choose to link OpenSBI generic static library together -with an M-mode firmware or bootloader providing hardware specific hooks. Since -OpenSBI is a statically linked library, users must ensure that the license of -these external components is compatible with OpenSBI license. +The platform-specific example firmwares provided by OpenSBI are not mandatory. +An implementation may choose to link the OpenSBI generic static library together +with an M-mode firmware or bootloader providing the hardware-specific hooks. +Since OpenSBI is a statically linked library, users must ensure that the +license of these external components is compatible with the OpenSBI license. Constraints on OpenSBI usage from external firmware --------------------------------------------------- Users have to ensure that an external firmware or bootloader linking against -OpenSBI static libraries (*libsbi.a* or *libplatsbi.a*) are compiled with the +OpenSBI static libraries (*libsbi.a* or *libplatsbi.a*) is compiled with the same GCC target options *-mabi*, *-march*, and *-mcmodel*. There are only two constraints on calling any OpenSBI library function from an external M-mode firmware or bootloader: 1. The RISC-V *MSCRATCH* CSR must point to a valid OpenSBI scratch space - (i.e. *struct sbi_scratch* instance) -2. The RISC-V *SP* register (i.e. stack pointer) must be set per-HART - pointing to distinct non-overlapping stacks + (i.e. a *struct sbi_scratch* instance). +2. The RISC-V *SP* register (i.e. the stack pointer) must be set per-HART + pointing to distinct non-overlapping stacks. The most important functions from an external firmware or bootloader perspective are *sbi_init()* and *sbi_trap_handler()*. In addition to the above constraints, the external firmware or bootloader must -ensure that interrupts are disabled in *MSTATUS* and *MIE* CSRs when calling +ensure that interrupts are disabled in the *MSTATUS* and *MIE* CSRs when calling the functions *sbi_init()* and *sbi_trap_handler()*. The *sbi_init()* function should be called by the external firmware or @@ -62,4 +62,3 @@ bootloader to service the following interrupts and traps: **Note:** external firmwares or bootloaders can be more conservative by forwarding all traps and interrupts to *sbi_trap_handler()*. - diff --git a/docs/platform/platform.md b/docs/platform/platform.md index 12efa81..2235b6a 100644 --- a/docs/platform/platform.md +++ b/docs/platform/platform.md @@ -1,11 +1,12 @@ OpenSBI Supported Platforms =========================== -OpenSBI currently supports the following virtual and hardware platforms. +OpenSBI currently supports the following virtual and hardware platforms: -* **QEMU RISC-V Virt Machine**: Platform support for QEMU *virt* virtual RISC-V - machine. This virtual machine is intended for RISC-V software development and - test. More details on this platform can be found in the file *[qemu_virt.md]*. +* **QEMU RISC-V Virt Machine**: Platform support for the QEMU *virt* virtual + RISC-V machine. This virtual machine is intended for RISC-V software + development and tests. More details on this platform can be found in the + file *[qemu_virt.md]*. * **QEMU SiFive Unleashed Machine**: Platform support for the *sifive_u* QEMU virtual RISC-V machine. This is an emulation machine of the HiFive Unleashed @@ -18,13 +19,14 @@ OpenSBI currently supports the following virtual and hardware platforms. *[sifive_fu540.md]*. * **Kendryte K210 SoC**: Platform support for the Kendryte K210 SoC used on - boards such as the Kendryte KD233 and Sipeed MAIX Dock boards. + boards such as the Kendryte KD233 or the Sipeed MAIX Dock. The code for these supported platforms can be used as example to implement support for other platforms. The *platform/template* directory also provides template files for implementing support for a new platform. The *object.mk*, -*config.mk* and *platform.c* template files provides enough comments to facilitate -the implementation. +*config.mk* and *platform.c* template files provides enough comments to +facilitate the implementation. [qemu_virt.md]: qemu_virt.md [qemu_sifive_u.md]: qemu_sifive_u.md +[sifive_fu540.md]: sifive_fu540.md diff --git a/docs/platform_guide.md b/docs/platform_guide.md index 5eecf9b..53e9394 100644 --- a/docs/platform_guide.md +++ b/docs/platform_guide.md @@ -1,15 +1,15 @@ OpenSBI Platform Support Guideline ================================== -OpenSBI platform support allows an implementation to define a set of platform -specific hooks (hardware manipulation functions) in the form of a +The OpenSBI platform support allows an implementation to define a set of +platform-specific hooks (hardware manipulation functions) in the form of a *struct sbi_platform* data structure instance. This instance is required by -platform independent *libsbi.a* to execute platform specific operations. +the platform-independent *libsbi.a* to execute platform-specific operations. -Each of the reference platform support provided by OpenSBI define an instance +Each of the reference platform supports provided by OpenSBI defines an instance of the *struct sbi_platform* data structure. For each supported platform, -*libplatsbi.a* integrates this instance with *libsbi.a* to create a platform -specific OpenSBI static library. This library is installed +*libplatsbi.a* integrates this instance with *libsbi.a* to create a +platform-specific OpenSBI static library. This library is installed in *<install_directory>/platform/<platform_subdir>/lib/libplatsbi.a* OpenSBI also provides implementation examples of bootable runtime firmwares for @@ -22,21 +22,21 @@ for the legacy *riskv-pk* boot loader (BBL). A complete doxygen-style documentation of *struct sbi_platform* and related APIs is available in the file *include/sbi/sbi_platform.h*. -Adding a new platform support ------------------------------ +Adding support for a new platform +--------------------------------- Support for a new platform named *<xyz>* can be added as follows: -1. Create a directory named *<xyz>* under *platform/* directory -2. Create a platform configuration file named *config.mk* under +1. Create a directory named *<xyz>* under the *platform/* directory. +2. Create a platform configuration file named *config.mk* under the *platform/<xyz>/* directory. This configuration file will provide - compiler flags, select common drivers, and select firmware options -3. Create *platform/<xyz>/objects.mk* file for listing the platform - specific object files to be compiled -4. Create *platform/<xyz>/platform.c* file providing a *struct sbi_platform* - instance + compiler flags, select common drivers, and select firmware options. +3. Create a *platform/<xyz>/objects.mk* file for listing the + platform-specific object files to be compiled. +4. Create a *platform/<xyz>/platform.c* file providing a *struct sbi_platform* + instance. -A template platform support code is available under the *platform/template* +A platform support code template is available under the *platform/template* directory. Copying this directory and its content as a new directory named *<xyz>* under the *platform/* directory will create all the files mentioned above. |