1 Copyright (c) 2019 Western Digital Corporation or its affiliates
2 and other contributors.
4 RISC-V Open Source Supervisor Binary Interface (OpenSBI)
5 ========================================================
7 The **RISC-V Supervisor Binary Interface (SBI)** is the recommended interface
10 1. A platform-specific firmware running in M-mode and a bootloader, a
11 hypervisor or a general-purpose OS executing in S-mode or HS-mode.
12 2. A hypervisor running in HS-mode and a bootloader or a general-purpose OS
15 The *RISC-V SBI specification* is maintained as an independent project by the
16 RISC-V Foundation on [Github] (https://github.com/riscv/riscv-sbi-doc).
18 The goal of the OpenSBI project is to provide an open-source reference
19 implementation of the RISC-V SBI specifications for platform-specific firmwares
20 executing in M-mode (case 1 mentioned above). An OpenSBI implementation can be
21 easily extended by RISC-V platform and system-on-chip vendors to fit a
22 particular hardware configuration.
24 The main component of OpenSBI is provided in the form of a platform-independent
25 static library **libsbi.a** implementing the SBI interface. A firmware or
26 bootloader implementation can link against this library to ensure conformance
27 with the SBI interface specifications. *libsbi.a* also defines an interface for
28 integrating with platform-specific operations provided by the platform firmware
29 implementation (e.g. console access functions, inter-processor interrupt
32 To illustrate the use of the *libsbi.a* library, OpenSBI also provides a set of
33 platform-specific support examples. For each example, a platform-specific
34 static library *libplatsbi.a* can be compiled. This library implements
35 SBI call processing by integrating *libsbi.a* with the necessary
36 platform-dependent hardware manipulation functions. For all supported platforms,
37 OpenSBI also provides several runtime firmware examples built using the platform
38 *libplatsbi.a*. These example firmwares can be used to replace the legacy
39 *riscv-pk* bootloader (aka BBL) and enable the use of well-known bootloaders
40 such as [U-Boot] (https://git.denx.de/u-boot.git).
45 OpenSBI can be compiled natively or cross-compiled on a x86 host. For
46 cross-compilation, you can build your own toolchain or just download
47 a prebuilt one from the
48 [Bootlin toolchain repository] (https://toolchains.bootlin.com/).
50 Please note that only a 64bit version of the toolchain is available in
51 the Bootlin toolchain repository for now.
53 Building and Installing the OpenSBI Platform-Independent Library
54 ----------------------------------------------------------------
56 The OpenSBI platform-independent static library *libsbi.a* can be compiled
57 natively or it can be cross-compiled on a host with a different base
58 architecture than RISC-V.
60 For cross-compiling, the environment variable *CROSS_COMPILE* must be defined
61 to specify the name prefix of the RISC-V compiler toolchain executables, e.g.
62 *riscv64-unknown-elf-* if the gcc executable used is *riscv64-unknown-elf-gcc*.
64 To build *libsbi.a* simply execute:
69 All compiled binaries as well as the resulting *libsbi.a* static library file
70 will be placed in the *build/lib* directory. To specify an alternate build root
73 make O=<build_directory>
76 To generate files to be installed for using *libsbi.a* in other projects, run:
81 This will create the *install* directory with all necessary include files
82 copied under the *install/include* directory and the library file copied into
83 the *install/lib* directory. To specify an alternate installation root
86 make I=<install_directory> install
89 Building and Installing a Reference Platform Static Library and Firmware
90 ------------------------------------------------------------------------
92 When the *PLATFORM=<platform_subdir>* argument is specified on the make command
93 line, the platform-specific static library *libplatsbi.a* and firmware examples
94 are built for the platform *<platform_subdir>* present in the directory
95 *platform* in the OpenSBI top directory. For example, to compile the platform
96 library and the firmware examples for the QEMU RISC-V *virt* machine,
97 *<platform_subdir>* should be *qemu/virt*.
99 To build *libsbi.a*, *libplatsbi.a* and the firmware for one of the supported
102 make PLATFORM=<platform_subdir>
105 An alternate build directory path can also be specified:
107 make PLATFORM=<platform_subdir> O=<build_directory>
110 The platform-specific library *libplatsbi.a* will be generated in the
111 *build/platform/<platform_subdir>/lib* directory. The platform firmware files
112 will be under the *build/platform/<platform_subdir>/firmware* directory.
113 The compiled firmwares will be available in two different formats: an ELF file
114 and an expanded image file.
116 To install *libsbi.a*, *libplatsbi.a*, and the compiled firmwares, run:
118 make PLATFORM=<platform_subdir> install
121 This will copy the compiled platform-specific libraries and firmware files
122 under the *install/platform/<platform_subdir>/* directory. An alternate
123 install root directory path can be specified as follows:
125 make PLATFORM=<platform_subdir> I=<install_directory> install
128 In addition, platform-specific configuration options can be specified with the
129 top-level make command line. These options, such as *PLATFORM_<xyz>* or
130 *FW_<abc>*, are platform-specific and described in more details in the
131 *docs/platform/<platform_name>.md* files and
132 *docs/firmware/<firmware_name>.md* files.
137 OpenSBI is distributed under the terms of the BSD 2-clause license
138 ("Simplified BSD License" or "FreeBSD License", SPDX: *BSD-2-Clause*).
139 A copy of this license with OpenSBI copyright can be found in the file
142 All source files in OpenSBI contain the 2-Clause BSD license SPDX short
143 identifier in place of the full license text.
146 SPDX-License-Identifier: BSD-2-Clause
149 This enables machine processing of license information based on the SPDX
150 License Identifiers that are available on the [SPDX] web site.
152 OpenSBI source code also contains code reused from other projects as listed
153 below. The original license text of these projects is included in the source
154 files where the reused code is present.
156 1. The libfdt source code is disjunctively dual licensed
157 (GPL-2.0+ OR BSD-2-Clause). Some of this project code is used in OpenSBI
158 under the terms of the BSD 2-Clause license. Any contributions to this
159 code must be made under the terms of both licenses.
160 2. Some source file for the Kendryte/k210 platform code are based on code from
161 the [Kendryte standalone SDK] available on github. These files retain the
162 original copyright and license of the Kendryte standalone SDK project and
163 are licensed under the terms of the Apache License, Version 2.0.
165 See also the [third party notices] file for more information.
167 Contributing to OpenSBI
168 -----------------------
170 The OpenSBI project encourages and welcomes contributions. Contributions should
171 follow the rules described in the OpenSBI [Contribution Guideline] document.
172 In particular, all patches sent should contain a Signed-off-by tag.
174 The [Contributors List] document provides a list of individuals and
175 organizations actively contributing to the OpenSBI project.
180 Detailed documentation of various aspects of OpenSBI can be found under the
181 *docs* directory. The documentation covers the following topics.
183 * [Contribution Guideline]: Guideline for contributing code to OpenSBI project
184 * [Library Usage]: API documentation of OpenSBI static library *libsbi.a*
185 * [Platform Support Guide]: Guideline for implementing support for new platforms
186 * [Platform Documentation]: Documentation of the platforms currently supported.
187 * [Firmware Documentation]: Documentation for the different types of firmware
188 examples build supported by OpenSBI.
190 OpenSBI source code is also well documented. For source level documentation,
191 doxygen style is used. Please refer to the [Doxygen manual] for details on this
194 Doxygen can be installed on Linux distributions using *.deb* packages using
195 the following command.
197 sudo apt-get install doxygen doxygen-latex doxygen-doc doxygen-gui graphviz
200 For *.rpm* based Linux distributions, the following commands can be used.
202 sudo yum install doxygen doxygen-latex doxywizard graphviz
206 sudo yum install doxygen doxygen-latex doxywizard graphviz
209 To build a consolidated *refman.pdf* of all documentation, run:
215 make O=<build_directory> docs
218 the resulting *refman.pdf* will be available under the directory
219 *<build_directory>/docs/latex*. To install this file, run:
225 make I=<install_directory> install_docs
228 *refman.pdf* will be installed under *<install_directory>/docs*.
230 [Github]: https://github.com/riscv/riscv-sbi-doc
231 [U-Boot]: https://www.denx.de/wiki/U-Boot/SourceCode
232 [COPYING.BSD]: COPYING.BSD
233 [SPDX]: http://spdx.org/licenses/
234 [Contribution Guideline]: docs/contributing.md
235 [Contributors List]: CONTRIBUTORS.md
236 [Library Usage]: docs/library_usage.md
237 [Platform Support Guide]: docs/platform_guide.md
238 [Platform Documentation]: docs/platform/platform.md
239 [Firmware Documentation]: docs/firmware/fw.md
240 [Doxygen manual]: http://www.doxygen.nl/manual/index.html
241 [Kendryte standalone SDK]: https://github.com/kendryte/kendryte-standalone-sdk
242 [third party notices]: ThirdPartyNotices.md