1 RISC-V Open Source Supervisor Binary Interface (OpenSBI)
2 ========================================================
4 The **RISC-V Supervisor Binary Interface (SBI)** is the recommended interface
7 1. A platform specific firmware running in M-mode and bootloader, hypervisor or
8 a general purpose OS executing in S-mode or HS-mode.
9 2. A hypervisor running in HS-mode and a bootloader or a general purpose OS
12 The *RISC-V SBI specification* is maintained as an independent project by the
13 RISC-V Foundation in [Github].
15 The goal of the OpenSBI project is to provide an open-source reference
16 implementation of the RISC-V SBI specifications for platform specific firmwares
17 executing in M-mode (case 1 mentioned above). OpenSBI implementation can be
18 easily extended by RISC-V platform and system-on-chip vendors to fit a
19 particular hardware configuration.
21 The main component of OpenSBI is provided in the form of a platform independent
22 static library **libsbi.a** implementing the SBI interface. A firmware or
23 bootloader implementation can link against this library to ensure conformance
24 with the SBI interface specifications. *libsbi.a* also defines an interface for
25 integrating with platform specific operations provided by the platform firmware
26 implementation (e.g. console access functions, inter-processor interrupts
29 To illustrate the use of *libsbi.a* library, OpenSBI also provides a set of
30 platform specific support examples. For each example, a platform
31 specific static library *libplatsbi.a* can be compiled. This library implements
32 SBI calls processing by integrating *libsbi.a* with necessary platform dependent
33 hardware manipulation functions. For all supported platforms, OpenSBI also
34 provides several runtime firmware examples built using the platform
35 *libplatsbi.a*. These example firmwares can be used to replace the legacy
36 *riskv-pk* bootloader (aka BBL) and enable the use of well known bootloaders
39 Building and Installing OpenSBI Platform Independent Library
40 ------------------------------------------------------------
42 OpenSBI platform independent static library *libsbi.a* can be natively compiled
43 or cross-compiled on a host with a different base architecture than RISC-V.
45 For cross-compiling, the environment variable *CROSS_COMPILE* must be defined
46 to specify the name prefix of the RISC-V compiler toolchain executables, e.g.
47 *riscv64-unknown-elf-* if the gcc executable used is *riscv64-unknown-elf-gcc*.
49 To build *libsbi.a* simply execute:
54 All compiled binaries as well as the result *libsbi.a* static library file will
55 be placed in the *build/lib* directory. To specify an alternate build root
58 make O=<build_directory>
61 To generate files to be installed for using *libsbi.a* in other projects, run:
66 This will create the *install* directory with all necessary include files
67 copied under the *install/include* directory and library file copied in the
68 *install/lib* directory. To specify an alternate installation root directory
71 make I=<install_directory> install
74 Building and Installing a Reference Platform Static Library and Firmwares
75 -------------------------------------------------------------------------
77 When the *PLATFORM=<platform_subdir>* argument is specified on the make command
78 line, the platform specific static library *libplatsbi.a* and firmware examples
79 are built for the platform *<platform_subdir>* present in the directory
80 *platform* in OpenSBI top directory. For example, to compile the platform
81 library and firmware examples for QEMU RISC-V *virt* machine,
82 *<platform_subdir>* should be *qemu/virt*.
84 To build *libsbi.a*, *libplatsbi.a* and the firmwares for one of the supported
87 make PLATFORM=<platform_subdir>
90 An alternate build directory path can also be specified.
92 make PLATFORM=<platform_subdir> O=<build_directory>
95 The platform specific library *libplatsbi.a* will be generated in the
96 *build/platform/<platform_subdir>/lib* directory. The platform firmware files
97 will be under the *build/platform/<platform_subdir>/firmware* directory.
98 The compiled firmwares will be available in two different format: an ELF file
99 and an expanded image file.
101 To install *libsbi.a*, *libplatsbi.a*, and the compiled firmwares, run:
103 make PLATFORM=<platform_subdir> install
106 This will copy the compiled platform specific libraries and firmware files
107 under the *install/platform/<platform_subdir>/* directory. An alternate
108 install root directory path can be specified as follows.
110 make PLATFORM=<platform_subdir> I=<install_directory> install
113 In addition, platform specific configuration options can be specified with the
114 top-level make command line. These options, such as *PLATFORM_<xyz>* or
115 *FW_<abc>*, are platform specific and described in more details in the
116 *docs/platform/<platform_name>.md* files and
117 *docs/firmware/<firmware_name>.md* files.
122 OpenSBI is distributed under the terms of the BSD 2-clause license
123 ("Simplified BSD License" or "FreeBSD License", SPDX: *BSD-2-Clause*).
124 A copy of this license with OpenSBI copyright can be found in the file
127 All source files in OpenSBI contain the 2-Clause BSD license SPDX short
128 indentifier in place of the full license text.
131 SPDX-License-Identifier: BSD-2-Clause
134 This enables machine processing of license information based on the SPDX
135 License Identifiers that are available on the [SPDX] web site.
137 OpenSBI source code also contains code reused from other projects as listed
138 below. The original license text of these projects is included in the source
139 files where the reused code is present.
141 1. The libfdt source code is disjunctively dual licensed
142 (GPL-2.0+ OR BSD-2-Clause). Some of this project code is used in OpenSBI
143 under the terms of the BSD 2-Clause license. Any contributions to this
144 code must be made under the terms of both licenses.
146 Contributing to OpenSBI
147 -----------------------
149 The OpenSBI project encourages and welcomes contributions. Contributions should
150 follow the rules described in OpenSBI [Contribution Guideline] document.
151 In particular, all patches sent should contain a Signed-off-by tag.
156 Detailed documentation of various aspects of OpenSBI can be found under the
157 *docs* directory. The documentation covers the following topics.
159 * [Contribution Guideline]: Guideline for contributing code to OpenSBI project
160 * [Library Usage]: API documentation of OpenSBI static library *libsbi.a*
161 * [Platform Support Guide]: Guideline for implementing support for new platforms
162 * [Platform Documentation]: Documentation of the platforms currently supported.
163 * [Firmware Documentation]: Documentation for the different types of firmware
164 examples build supported by OpenSBI.
166 OpenSBI source code is also well documented. For source level documentation,
167 doxygen style is used. Please refer to [Doxygen manual] for details on this
170 Doxygen can be installed on Linux distributions using *.deb* packages using
171 the following command.
173 sudo apt-get install doxygen doxygen-latex doxygen-doc doxygen-gui graphviz
176 For *.rpm* based Linux distributions, the following commands can be used.
178 sudo yum install doxygen doxygen-latex doxywizard graphviz
182 sudo yum install doxygen doxygen-latex doxywizard graphviz
185 To build a consolidated *refman.pdf* of all documentation, run:
191 make O=<build_directory> docs
194 the resulting *refman.pdf* will be available under the directory
195 *<build_directory>/docs/latex*. To install this file, run:
201 make I=<install_directory> install_docs
204 *refman.pdf* will be installed under *<install_directory>/docs*.
206 [Github]: https://github.com/riscv/riscv-sbi-doc
207 [U-Boot]: https://www.denx.de/wiki/U-Boot/SourceCode
208 [COPYING.BSD]: COPYING.BSD
209 [SPDX]: http://spdx.org/licenses/
210 [Contribution Guideline]: docs/contributing.md
211 [Library Usage]: docs/library_usage.md
212 [Platform Support Guide]: docs/platform_guide.md
213 [Platform Documentation]: docs/platform/platform.md
214 [Firmware Documentation]: docs/firmware/fw.md
215 [Doxygen manual]: http://www.stack.nl/~dimitri/doxygen/manual.html