1 RISC-V Open Source Supervisor Binary Interface (OpenSBI)
2 ========================================================
7 The OpenSBI project is copyright (c) 2019 Western Digital Corporation
8 or its affiliates and other contributors.
10 It is distributed under the terms of the BSD 2-clause license
11 ("Simplified BSD License" or "FreeBSD License", SPDX: *BSD-2-Clause*).
12 A copy of this license with OpenSBI copyright can be found in the file
15 All source files in OpenSBI contain the 2-Clause BSD license SPDX short
16 identifier in place of the full license text.
19 SPDX-License-Identifier: BSD-2-Clause
22 This enables machine processing of license information based on the SPDX
23 License Identifiers that are available on the [SPDX] web site.
25 OpenSBI source code also contains code reused from other projects as listed
26 below. The original license text of these projects is included in the source
27 files where the reused code is present.
29 * The libfdt source code is disjunctively dual licensed
30 (GPL-2.0+ OR BSD-2-Clause). Some of this project code is used in OpenSBI
31 under the terms of the BSD 2-Clause license. Any contributions to this
32 code must be made under the terms of both licenses.
34 See also the [third party notices] file for more information.
39 The **RISC-V Supervisor Binary Interface (SBI)** is the recommended interface
42 1. A platform-specific firmware running in M-mode and a bootloader, a
43 hypervisor or a general-purpose OS executing in S-mode or HS-mode.
44 2. A hypervisor running in HS-mode and a bootloader or a general-purpose OS
47 The *RISC-V SBI specification* is maintained as an independent project by the
48 RISC-V Foundation on [Github].
50 The goal of the OpenSBI project is to provide an open-source reference
51 implementation of the RISC-V SBI specifications for platform-specific firmwares
52 executing in M-mode (case 1 mentioned above). An OpenSBI implementation can be
53 easily extended by RISC-V platform and system-on-chip vendors to fit a
54 particular hardware configuration.
56 The main component of OpenSBI is provided in the form of a platform-independent
57 static library **libsbi.a** implementing the SBI interface. A firmware or
58 bootloader implementation can link against this library to ensure conformance
59 with the SBI interface specifications. *libsbi.a* also defines an interface for
60 integrating with platform-specific operations provided by the platform firmware
61 implementation (e.g. console access functions, inter-processor interrupt
64 To illustrate the use of the *libsbi.a* library, OpenSBI also provides a set of
65 platform-specific support examples. For each example, a platform-specific
66 static library *libplatsbi.a* can be compiled. This library implements
67 SBI call processing by integrating *libsbi.a* with the necessary
68 platform-dependent hardware manipulation functions. For all supported platforms,
69 OpenSBI also provides several runtime firmware examples built using the platform
70 *libplatsbi.a*. These example firmwares can be used to replace the legacy
71 *riscv-pk* bootloader (aka BBL) and enable the use of well-known bootloaders
76 Currently, OpenSBI fully supports SBI specification *v0.2*. OpenSBI also
77 supports Hart State Management (HSM) SBI extension starting from OpenSBI v0.7.
78 HSM extension allows S-mode software to boot all the harts a defined order
79 rather than legacy method of random booting of harts. As a result, many
80 required features such as CPU hotplug, kexec/kdump can also be supported easily
81 in S-mode. HSM extension in OpenSBI is implemented in a non-backward compatible
82 manner to reduce the maintenance burden and avoid confusion. That's why, any
83 S-mode software using OpenSBI will not be able to boot more than 1 hart if HSM
84 extension is not supported in S-mode.
86 Linux kernel already supports SBI v0.2 and HSM SBI extension starting from
87 **v5.7-rc1**. If you are using an Linux kernel older than **5.7-rc1** or any
88 other S-mode software without HSM SBI extension, you should stick to OpenSBI
89 v0.6 to boot all the harts. For a UMP systems, it doesn't matter.
91 N.B. Any S-mode boot loader (i.e. U-Boot) doesn't need to support HSM extension,
92 as it doesn't need to boot all the harts. The operating system should be
93 capable enough to bring up all other non-booting harts using HSM extension.
98 OpenSBI can be compiled natively or cross-compiled on a x86 host. For
99 cross-compilation, you can build your own toolchain, download a prebuilt one
100 from the [Bootlin toolchain repository] or install a distribution-provided
101 toolchain; if you opt to use LLVM/Clang, most distribution toolchains will
102 support cross-compiling for RISC-V using the same toolchain as your native
103 LLVM/Clang toolchain due to LLVM's ability to support multiple backends in the
104 same binary, so is often an easy way to obtain a working cross-compilation
107 Basically, we prefer toolchains with Position Independent Executable (PIE)
108 support like *riscv64-linux-gnu-gcc*, *riscv64-unknown-freebsd-gcc*, or
109 *Clang/LLVM* as they generate PIE firmware images that can run at arbitrary
110 address with appropriate alignment. If a bare-metal GNU toolchain (e.g.
111 *riscv64-unknown-elf-gcc*) is used, static linked firmware images are
112 generated instead. *Clang/LLVM* can still generate PIE images if a bare-metal
113 triple is used (e.g. *-target riscv64-unknown-elf*).
115 Please note that only a 64-bit version of the toolchain is available in
116 the Bootlin toolchain repository for now.
118 Building and Installing the OpenSBI Platform-Independent Library
119 ----------------------------------------------------------------
121 The OpenSBI platform-independent static library *libsbi.a* can be compiled
122 natively or it can be cross-compiled on a host with a different base
123 architecture than RISC-V.
125 For cross-compiling, the environment variable *CROSS_COMPILE* must be defined
126 to specify the name prefix of the RISC-V compiler toolchain executables, e.g.
127 *riscv64-linux-gnu-* if the gcc executable used is *riscv64-linux-gnu-gcc*.
129 To build *libsbi.a* simply execute:
134 All compiled binaries as well as the resulting *libsbi.a* static library file
135 will be placed in the *build/lib* directory. To specify an alternate build root
138 make O=<build_directory>
141 To generate files to be installed for using *libsbi.a* in other projects, run:
146 This will create the *install* directory with all necessary include files
147 copied under the *install/include* directory and the library file copied into
148 the *install/lib* directory. To specify an alternate installation root
151 make I=<install_directory> install
154 Building and Installing a Reference Platform Static Library and Firmware
155 ------------------------------------------------------------------------
157 When the *PLATFORM=<platform_subdir>* argument is specified on the make command
158 line, the platform-specific static library *libplatsbi.a* and firmware examples
159 are built for the platform *<platform_subdir>* present in the directory
160 *platform* in the OpenSBI top directory. For example, to compile the platform
161 library and the firmware examples for the QEMU RISC-V *virt* machine,
162 *<platform_subdir>* should be *generic*.
164 To build *libsbi.a*, *libplatsbi.a* and the firmware for one of the supported
167 make PLATFORM=<platform_subdir>
170 An alternate build directory path can also be specified:
172 make PLATFORM=<platform_subdir> O=<build_directory>
175 The platform-specific library *libplatsbi.a* will be generated in the
176 *build/platform/<platform_subdir>/lib* directory. The platform firmware files
177 will be under the *build/platform/<platform_subdir>/firmware* directory.
178 The compiled firmwares will be available in two different formats: an ELF file
179 and an expanded image file.
181 To install *libsbi.a*, *libplatsbi.a*, and the compiled firmwares, run:
183 make PLATFORM=<platform_subdir> install
186 This will copy the compiled platform-specific libraries and firmware files
187 under the *install/platform/<platform_subdir>/* directory. An alternate
188 install root directory path can be specified as follows:
190 make PLATFORM=<platform_subdir> I=<install_directory> install
193 In addition, platform-specific configuration options can be specified with the
194 top-level make command line. These options, such as *PLATFORM_<xyz>* or
195 *FW_<abc>*, are platform-specific and described in more details in the
196 *docs/platform/<platform_name>.md* files and
197 *docs/firmware/<firmware_name>.md* files.
199 Building 32-bit / 64-bit OpenSBI Images
200 ---------------------------------------
201 By default, building OpenSBI generates 32-bit or 64-bit images based on the
202 supplied RISC-V cross-compile toolchain. For example if *CROSS_COMPILE* is set
203 to *riscv64-linux-gnu-*, 64-bit OpenSBI images will be generated. If building
204 32-bit OpenSBI images, *CROSS_COMPILE* should be set to a toolchain that is
205 pre-configured to generate 32-bit RISC-V codes, like *riscv32-linux-gnu-*.
207 However it's possible to explicitly specify the image bits we want to build with
208 a given RISC-V toolchain. This can be done by setting the environment variable
209 *PLATFORM_RISCV_XLEN* to the desired width, for example:
212 export CROSS_COMPILE=riscv64-linux-gnu-
213 export PLATFORM_RISCV_XLEN=32
216 will generate 32-bit OpenSBI images. And vice vesa.
218 Building with Clang/LLVM
219 ------------------------
221 OpenSBI can also be built with Clang/LLVM. To build with just Clang but keep
222 the default binutils (which will still use the *CROSS_COMPILE* prefix if
223 defined), override the *CC* make variable with:
228 To build with a full LLVM-based toolchain, not just Clang, enable the *LLVM*
234 When using Clang, *CROSS_COMPILE* often does not need to be defined unless
235 using GNU binutils with prefixed binary names. *PLATFORM_RISCV_XLEN* will be
236 used to infer a default triple to pass to Clang, so if *PLATFORM_RISCV_XLEN*
237 itself defaults to an undesired value then prefer setting that rather than the
238 full triple via *CROSS_COMPILE*. If *CROSS_COMPILE* is nonetheless defined,
239 rather than being used as a prefix for the executable name, it will instead be
240 passed via the `--target` option with the trailing `-` removed, so must be a
243 These can also be mixed; for example using a GCC cross-compiler but LLVM
246 make CC=riscv64-linux-gnu-gcc LLVM=1
249 These variables must be passed for all the make invocations described in this
252 NOTE: Using Clang with a `riscv*-linux-gnu` GNU binutils linker has been seen
253 to produce broken binaries with missing relocations; it is therefore currently
254 recommended that this combination be avoided or *FW_PIC=n* be used to disable
255 building OpenSBI as a position-independent binary.
257 Contributing to OpenSBI
258 -----------------------
260 The OpenSBI project encourages and welcomes contributions. Contributions should
261 follow the rules described in the OpenSBI [Contribution Guideline] document.
262 In particular, all patches sent should contain a Signed-off-by tag.
264 The [Contributors List] document provides a list of individuals and
265 organizations actively contributing to the OpenSBI project.
270 Detailed documentation of various aspects of OpenSBI can be found under the
271 *docs* directory. The documentation covers the following topics.
273 * [Contribution Guideline]: Guideline for contributing code to OpenSBI project
274 * [Library Usage]: API documentation of OpenSBI static library *libsbi.a*
275 * [Platform Requirements]: Requirements for using OpenSBI on a platform
276 * [Platform Support Guide]: Guideline for implementing support for new platforms
277 * [Platform Documentation]: Documentation of the platforms currently supported.
278 * [Firmware Documentation]: Documentation for the different types of firmware
279 examples build supported by OpenSBI.
280 * [Domain Support]: Documentation for the OpenSBI domain support which helps
281 users achieve system-level partitioning using OpenSBI.
283 OpenSBI source code is also well documented. For source level documentation,
284 doxygen style is used. Please refer to the [Doxygen manual] for details on this
287 Doxygen can be installed on Linux distributions using *.deb* packages using
288 the following command.
290 sudo apt-get install doxygen doxygen-latex doxygen-doc doxygen-gui graphviz
293 For *.rpm* based Linux distributions, the following commands can be used.
295 sudo yum install doxygen doxygen-latex doxywizard graphviz
299 sudo yum install doxygen doxygen-latex doxywizard graphviz
302 To build a consolidated *refman.pdf* of all documentation, run:
308 make O=<build_directory> docs
311 the resulting *refman.pdf* will be available under the directory
312 *<build_directory>/docs/latex*. To install this file, run:
318 make I=<install_directory> install_docs
321 *refman.pdf* will be installed under *<install_directory>/docs*.
323 [Github]: https://github.com/riscv/riscv-sbi-doc
324 [U-Boot]: https://www.denx.de/wiki/U-Boot/SourceCode
325 [Bootlin toolchain repository]: https://toolchains.bootlin.com/
326 [COPYING.BSD]: COPYING.BSD
327 [SPDX]: http://spdx.org/licenses/
328 [Contribution Guideline]: docs/contributing.md
329 [Contributors List]: CONTRIBUTORS.md
330 [Library Usage]: docs/library_usage.md
331 [Platform Requirements]: docs/platform_requirements.md
332 [Platform Support Guide]: docs/platform_guide.md
333 [Platform Documentation]: docs/platform/platform.md
334 [Firmware Documentation]: docs/firmware/fw.md
335 [Domain Support]: docs/domain_support.md
336 [Doxygen manual]: http://www.doxygen.nl/manual/index.html
337 [Kendryte standalone SDK]: https://github.com/kendryte/kendryte-standalone-sdk
338 [third party notices]: ThirdPartyNotices.md