1 RISC-V Open Source Supervisor Binary Interface (OpenSBI)
2 ========================================================
4 ![RISC-V OpenSBI](docs/riscv_opensbi_logo_final_color.png)
9 The OpenSBI project is:
11 * Copyright (c) 2019 Western Digital Corporation or its affiliates
12 * Copyright (c) 2023 RISC-V International
14 It is distributed under the terms of the BSD 2-clause license
15 ("Simplified BSD License" or "FreeBSD License", SPDX: *BSD-2-Clause*).
16 A copy of this license with OpenSBI copyright can be found in the file
19 All source files in OpenSBI contain the 2-Clause BSD license SPDX short
20 identifier in place of the full license text.
23 SPDX-License-Identifier: BSD-2-Clause
26 This enables machine processing of license information based on the SPDX
27 License Identifiers that are available on the [SPDX] web site.
29 OpenSBI source code also contains code reused from other projects as listed
30 below. The original license text of these projects is included in the source
31 files where the reused code is present.
33 * The libfdt source code is disjunctively dual licensed
34 (GPL-2.0+ OR BSD-2-Clause). Some of this project code is used in OpenSBI
35 under the terms of the BSD 2-Clause license. Any contributions to this
36 code must be made under the terms of both licenses.
38 See also the [third party notices] file for more information.
43 The **RISC-V Supervisor Binary Interface (SBI)** is the recommended interface
46 1. A platform-specific firmware running in M-mode and a bootloader, a
47 hypervisor or a general-purpose OS executing in S-mode or HS-mode.
48 2. A hypervisor running in HS-mode and a bootloader or a general-purpose OS
51 The *RISC-V SBI specification* is maintained as an independent project by the
52 RISC-V Foundation on [Github].
54 The goal of the OpenSBI project is to provide an open-source reference
55 implementation of the RISC-V SBI specifications for platform-specific firmwares
56 executing in M-mode (case 1 mentioned above). An OpenSBI implementation can be
57 easily extended by RISC-V platform and system-on-chip vendors to fit a
58 particular hardware configuration.
60 The main component of OpenSBI is provided in the form of a platform-independent
61 static library **libsbi.a** implementing the SBI interface. A firmware or
62 bootloader implementation can link against this library to ensure conformance
63 with the SBI interface specifications. *libsbi.a* also defines an interface for
64 integrating with platform-specific operations provided by the platform firmware
65 implementation (e.g. console access functions, inter-processor interrupt
68 To illustrate the use of the *libsbi.a* library, OpenSBI also provides a set of
69 platform-specific support examples. For each example, a platform-specific
70 static library *libplatsbi.a* can be compiled. This library implements
71 SBI call processing by integrating *libsbi.a* with the necessary
72 platform-dependent hardware manipulation functions. For all supported platforms,
73 OpenSBI also provides several runtime firmware examples built using the platform
74 *libplatsbi.a*. These example firmwares can be used to replace the legacy
75 *riscv-pk* bootloader (aka BBL) and enable the use of well-known bootloaders
80 Currently, OpenSBI fully supports SBI specification *v0.2*. OpenSBI also
81 supports Hart State Management (HSM) SBI extension starting from OpenSBI v0.7.
82 HSM extension allows S-mode software to boot all the harts a defined order
83 rather than legacy method of random booting of harts. As a result, many
84 required features such as CPU hotplug, kexec/kdump can also be supported easily
85 in S-mode. HSM extension in OpenSBI is implemented in a non-backward compatible
86 manner to reduce the maintenance burden and avoid confusion. That's why, any
87 S-mode software using OpenSBI will not be able to boot more than 1 hart if HSM
88 extension is not supported in S-mode.
90 Linux kernel already supports SBI v0.2 and HSM SBI extension starting from
91 **v5.7-rc1**. If you are using an Linux kernel older than **5.7-rc1** or any
92 other S-mode software without HSM SBI extension, you should stick to OpenSBI
93 v0.6 to boot all the harts. For a UMP systems, it doesn't matter.
95 N.B. Any S-mode boot loader (i.e. U-Boot) doesn't need to support HSM extension,
96 as it doesn't need to boot all the harts. The operating system should be
97 capable enough to bring up all other non-booting harts using HSM extension.
99 Required Toolchain and Packages
100 -------------------------------
102 OpenSBI can be compiled natively or cross-compiled on a x86 host. For
103 cross-compilation, you can build your own toolchain, download a prebuilt one
104 from the [Bootlin toolchain repository] or install a distribution-provided
105 toolchain; if you opt to use LLVM/Clang, most distribution toolchains will
106 support cross-compiling for RISC-V using the same toolchain as your native
107 LLVM/Clang toolchain due to LLVM's ability to support multiple backends in the
108 same binary, so is often an easy way to obtain a working cross-compilation
111 Basically, we prefer toolchains with Position Independent Executable (PIE)
112 support like *riscv64-linux-gnu-gcc*, *riscv64-unknown-freebsd-gcc*, or
113 *Clang/LLVM* as they generate PIE firmware images that can run at arbitrary
114 address with appropriate alignment. If a bare-metal GNU toolchain (e.g.
115 *riscv64-unknown-elf-gcc*) is used, static linked firmware images are
116 generated instead. *Clang/LLVM* can still generate PIE images if a bare-metal
117 triple is used (e.g. *-target riscv64-unknown-elf*).
119 Please note that only a 64-bit version of the toolchain is available in
120 the Bootlin toolchain repository for now.
122 In addition to a toolchain, OpenSBI also requires the following packages on
125 1. device-tree-compiler: The device tree compiler for compiling device
126 tree sources (DTS files).
127 2. python3: The python 3.0 (or compatible) language support for various
130 Building and Installing the OpenSBI Platform-Independent Library
131 ----------------------------------------------------------------
133 The OpenSBI platform-independent static library *libsbi.a* can be compiled
134 natively or it can be cross-compiled on a host with a different base
135 architecture than RISC-V.
137 For cross-compiling, the environment variable *CROSS_COMPILE* must be defined
138 to specify the name prefix of the RISC-V compiler toolchain executables, e.g.
139 *riscv64-linux-gnu-* if the gcc executable used is *riscv64-linux-gnu-gcc*.
141 To build *libsbi.a* simply execute:
146 All compiled binaries as well as the resulting *libsbi.a* static library file
147 will be placed in the *build/lib* directory. To specify an alternate build root
150 make O=<build_directory>
153 To generate files to be installed for using *libsbi.a* in other projects, run:
158 This will create the *install* directory with all necessary include files
159 copied under the *install/include* directory and the library file copied into
160 the *install/lib* directory. To specify an alternate installation root
163 make I=<install_directory> install
166 Building and Installing a Reference Platform Static Library and Firmware
167 ------------------------------------------------------------------------
169 When the *PLATFORM=<platform_subdir>* argument is specified on the make command
170 line, the platform-specific static library *libplatsbi.a* and firmware examples
171 are built for the platform *<platform_subdir>* present in the directory
172 *platform* in the OpenSBI top directory. For example, to compile the platform
173 library and the firmware examples for the QEMU RISC-V *virt* machine,
174 *<platform_subdir>* should be *generic*.
176 To build *libsbi.a*, *libplatsbi.a* and the firmware for one of the supported
179 make PLATFORM=<platform_subdir>
182 An alternate build directory path can also be specified:
184 make PLATFORM=<platform_subdir> O=<build_directory>
187 The platform-specific library *libplatsbi.a* will be generated in the
188 *build/platform/<platform_subdir>/lib* directory. The platform firmware files
189 will be under the *build/platform/<platform_subdir>/firmware* directory.
190 The compiled firmwares will be available in two different formats: an ELF file
191 and an expanded image file.
193 To install *libsbi.a*, *libplatsbi.a*, and the compiled firmwares, run:
195 make PLATFORM=<platform_subdir> install
198 This will copy the compiled platform-specific libraries and firmware files
199 under the *install/platform/<platform_subdir>/* directory. An alternate
200 install root directory path can be specified as follows:
202 make PLATFORM=<platform_subdir> I=<install_directory> install
205 In addition, platform-specific configuration options can be specified with the
206 top-level make command line. These options, such as *PLATFORM_<xyz>* or
207 *FW_<abc>*, are platform-specific and described in more details in the
208 *docs/platform/<platform_name>.md* files and
209 *docs/firmware/<firmware_name>.md* files.
211 All OpenSBI platforms support Kconfig style build-time configuration. Users
212 can change the build-time configuration of a platform using a graphical
213 interface as follows:
215 make PLATFORM=<platform_subdir> menuconfig
218 Alternately, an OpenSBI platform can have multiple default configurations
219 and users can select a custom default configuration as follows:
221 make PLATFORM=<platform_subdir> PLATFORM_DEFCONFIG=<platform_custom_defconfig>
224 Building 32-bit / 64-bit OpenSBI Images
225 ---------------------------------------
226 By default, building OpenSBI generates 32-bit or 64-bit images based on the
227 supplied RISC-V cross-compile toolchain. For example if *CROSS_COMPILE* is set
228 to *riscv64-linux-gnu-*, 64-bit OpenSBI images will be generated. If building
229 32-bit OpenSBI images, *CROSS_COMPILE* should be set to a toolchain that is
230 pre-configured to generate 32-bit RISC-V codes, like *riscv32-linux-gnu-*.
232 However it's possible to explicitly specify the image bits we want to build with
233 a given RISC-V toolchain. This can be done by setting the environment variable
234 *PLATFORM_RISCV_XLEN* to the desired width, for example:
237 export CROSS_COMPILE=riscv64-linux-gnu-
238 export PLATFORM_RISCV_XLEN=32
241 will generate 32-bit OpenSBI images. And vice vesa.
243 Building with Clang/LLVM
244 ------------------------
246 OpenSBI can also be built with Clang/LLVM. To build with just Clang but keep
247 the default binutils (which will still use the *CROSS_COMPILE* prefix if
248 defined), override the *CC* make variable with:
253 To build with a full LLVM-based toolchain, not just Clang, enable the *LLVM*
259 When using Clang, *CROSS_COMPILE* often does not need to be defined unless
260 using GNU binutils with prefixed binary names. *PLATFORM_RISCV_XLEN* will be
261 used to infer a default triple to pass to Clang, so if *PLATFORM_RISCV_XLEN*
262 itself defaults to an undesired value then prefer setting that rather than the
263 full triple via *CROSS_COMPILE*. If *CROSS_COMPILE* is nonetheless defined,
264 rather than being used as a prefix for the executable name, it will instead be
265 passed via the `--target` option with the trailing `-` removed, so must be a
268 These can also be mixed; for example using a GCC cross-compiler but LLVM
271 make CC=riscv64-linux-gnu-gcc LLVM=1
274 These variables must be passed for all the make invocations described in this
277 NOTE: Using Clang with a `riscv*-linux-gnu` GNU binutils linker has been seen
278 to produce broken binaries with missing relocations; it is therefore currently
279 recommended that this combination be avoided or *FW_PIC=n* be used to disable
280 building OpenSBI as a position-independent binary.
282 Building with timestamp and compiler info
283 -----------------------------------------
285 When doing development, we may want to know the build time and compiler info
286 for debug purpose. OpenSBI can also be built with timestamp and compiler info.
287 To build with those info and print it out at boot time, we can just simply add
288 `BUILD_INFO=y`, like:
293 But if you have used `BUILD_INFO=y`, and want to switch back to `BUILD_INFO=n`,
298 before the next build.
300 NOTE: Using `BUILD_INFO=y` without specifying SOURCE_DATE_EPOCH will violate
301 [reproducible builds]. This definition is ONLY for development and debug
302 purpose, and should NOT be used in a product which follows "reproducible
305 Building with optimization off for debugging
306 --------------------------------------------
308 When debugging OpenSBI, we may want to turn off the compiler optimization and
309 make debugging produce the expected results for a better debugging experience.
310 To build with optimization off we can just simply add `DEBUG=1`, like:
315 This definition is ONLY for development and debug purpose, and should NOT be
316 used in a product build.
318 Contributing to OpenSBI
319 -----------------------
321 The OpenSBI project encourages and welcomes contributions. Contributions should
322 follow the rules described in the OpenSBI [Contribution Guideline] document.
323 In particular, all patches sent should contain a Signed-off-by tag.
325 The [Contributors List] document provides a list of individuals and
326 organizations actively contributing to the OpenSBI project.
331 Detailed documentation of various aspects of OpenSBI can be found under the
332 *docs* directory. The documentation covers the following topics.
334 * [Contribution Guideline]: Guideline for contributing code to OpenSBI project
335 * [Library Usage]: API documentation of OpenSBI static library *libsbi.a*
336 * [Platform Requirements]: Requirements for using OpenSBI on a platform
337 * [Platform Support Guide]: Guideline for implementing support for new platforms
338 * [Platform Documentation]: Documentation of the platforms currently supported.
339 * [Firmware Documentation]: Documentation for the different types of firmware
340 examples build supported by OpenSBI.
341 * [Domain Support]: Documentation for the OpenSBI domain support which helps
342 users achieve system-level partitioning using OpenSBI.
344 OpenSBI source code is also well documented. For source level documentation,
345 doxygen style is used. Please refer to the [Doxygen manual] for details on this
348 Doxygen can be installed on Linux distributions using *.deb* packages using
349 the following command.
351 sudo apt-get install doxygen doxygen-latex doxygen-doc doxygen-gui graphviz
354 For *.rpm* based Linux distributions, the following commands can be used.
356 sudo yum install doxygen doxygen-latex doxywizard graphviz
360 sudo yum install doxygen doxygen-latex doxywizard graphviz
363 To build a consolidated *refman.pdf* of all documentation, run:
369 make O=<build_directory> docs
372 the resulting *refman.pdf* will be available under the directory
373 *<build_directory>/docs/latex*. To install this file, run:
379 make I=<install_directory> install_docs
382 *refman.pdf* will be installed under *<install_directory>/docs*.
384 [Github]: https://github.com/riscv/riscv-sbi-doc
385 [U-Boot]: https://www.denx.de/wiki/U-Boot/SourceCode
386 [Bootlin toolchain repository]: https://toolchains.bootlin.com/
387 [COPYING.BSD]: COPYING.BSD
388 [SPDX]: http://spdx.org/licenses/
389 [Contribution Guideline]: docs/contributing.md
390 [Contributors List]: CONTRIBUTORS.md
391 [Library Usage]: docs/library_usage.md
392 [Platform Requirements]: docs/platform_requirements.md
393 [Platform Support Guide]: docs/platform_guide.md
394 [Platform Documentation]: docs/platform/platform.md
395 [Firmware Documentation]: docs/firmware/fw.md
396 [Domain Support]: docs/domain_support.md
397 [Doxygen manual]: http://www.doxygen.nl/manual/index.html
398 [Kendryte standalone SDK]: https://github.com/kendryte/kendryte-standalone-sdk
399 [third party notices]: ThirdPartyNotices.md
400 [reproducible builds]: https://reproducible-builds.org