README.md

   1 RISC-V Open Source Supervisor Binary Interface (OpenSBI)
   2 ========================================================
   3
   4 Copyright and License
   5 ---------------------
   6
   7 The OpenSBI project is copyright (c) 2019 Western Digital Corporation
   8 or its affiliates and other contributors.
   9
  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
  13 [COPYING.BSD].
  14
  15 All source files in OpenSBI contain the 2-Clause BSD license SPDX short
  16 identifier in place of the full license text.
  17
  18 ```
  19 SPDX-License-Identifier:    BSD-2-Clause
  20 ```
  21
  22 This enables machine processing of license information based on the SPDX
  23 License Identifiers that are available on the [SPDX] web site.
  24
  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.
  28
  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.
  33
  34 See also the [third party notices] file for more information.
  35
  36 Introduction
  37 ------------
  38
  39 The **RISC-V Supervisor Binary Interface (SBI)** is the recommended interface
  40 between:
  41
  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
  45    executing in VS-mode.
  46
  47 The *RISC-V SBI specification* is maintained as an independent project by the
  48 RISC-V Foundation on [Github].
  49
  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.
  55
  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
  62 control, etc).
  63
  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
  72 such as [U-Boot].
  73
  74 Supported SBI version
  75 ---------------------
  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.
  85
  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.
  90
  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.
  94
  95 Required Toolchain
  96 ------------------
  97
  98 OpenSBI can be compiled natively or cross-compiled on a x86 host. For
  99 cross-compilation, you can build your own toolchain or just download
 100 a prebuilt one from the [Bootlin toolchain repository].
 101
 102 Please note that only a 64-bit version of the toolchain is available in
 103 the Bootlin toolchain repository for now.
 104
 105 Building and Installing the OpenSBI Platform-Independent Library
 106 ----------------------------------------------------------------
 107
 108 The OpenSBI platform-independent static library *libsbi.a* can be compiled
 109 natively or it can be cross-compiled on a host with a different base
 110 architecture than RISC-V.
 111
 112 For cross-compiling, the environment variable *CROSS_COMPILE* must be defined
 113 to specify the name prefix of the RISC-V compiler toolchain executables, e.g.
 114 *riscv64-unknown-elf-* if the gcc executable used is *riscv64-unknown-elf-gcc*.
 115
 116 To build *libsbi.a* simply execute:
 117 ```
 118 make
 119 ```
 120
 121 All compiled binaries as well as the resulting *libsbi.a* static library file
 122 will be placed in the *build/lib* directory. To specify an alternate build root
 123 directory path, run:
 124 ```
 125 make O=<build_directory>
 126 ```
 127
 128 To generate files to be installed for using *libsbi.a* in other projects, run:
 129 ```
 130 make install
 131 ```
 132
 133 This will create the *install* directory with all necessary include files
 134 copied under the *install/include* directory and the library file copied into
 135 the *install/lib* directory. To specify an alternate installation root
 136 directory path, run:
 137 ```
 138 make I=<install_directory> install
 139 ```
 140
 141 Building and Installing a Reference Platform Static Library and Firmware
 142 ------------------------------------------------------------------------
 143
 144 When the *PLATFORM=<platform_subdir>* argument is specified on the make command
 145 line, the platform-specific static library *libplatsbi.a* and firmware examples
 146 are built for the platform *<platform_subdir>* present in the directory
 147 *platform* in the OpenSBI top directory. For example, to compile the platform
 148 library and the firmware examples for the QEMU RISC-V *virt* machine,
 149 *<platform_subdir>* should be *generic*.
 150
 151 To build *libsbi.a*, *libplatsbi.a* and the firmware for one of the supported
 152 platforms, run:
 153 ```
 154 make PLATFORM=<platform_subdir>
 155 ```
 156
 157 An alternate build directory path can also be specified:
 158 ```
 159 make PLATFORM=<platform_subdir> O=<build_directory>
 160 ```
 161
 162 The platform-specific library *libplatsbi.a* will be generated in the
 163 *build/platform/<platform_subdir>/lib* directory. The platform firmware files
 164 will be under the *build/platform/<platform_subdir>/firmware* directory.
 165 The compiled firmwares will be available in two different formats: an ELF file
 166 and an expanded image file.
 167
 168 To install *libsbi.a*, *libplatsbi.a*, and the compiled firmwares, run:
 169 ```
 170 make PLATFORM=<platform_subdir> install
 171 ```
 172
 173 This will copy the compiled platform-specific libraries and firmware files
 174 under the *install/platform/<platform_subdir>/* directory. An alternate
 175 install root directory path can be specified as follows:
 176 ```
 177 make PLATFORM=<platform_subdir> I=<install_directory> install
 178 ```
 179
 180 In addition, platform-specific configuration options can be specified with the
 181 top-level make command line. These options, such as *PLATFORM_<xyz>* or
 182 *FW_<abc>*, are platform-specific and described in more details in the
 183 *docs/platform/<platform_name>.md* files and
 184 *docs/firmware/<firmware_name>.md* files.
 185
 186 Building 32-bit / 64-bit OpenSBI Images
 187 ---------------------------------------
 188 By default, building OpenSBI generates 32-bit or 64-bit images based on the
 189 supplied RISC-V cross-compile toolchain. For example if *CROSS_COMPILE* is set
 190 to *riscv64-unknown-elf-*, 64-bit OpenSBI images will be generated. If building
 191 32-bit OpenSBI images, *CROSS_COMPILE* should be set to a toolchain that is
 192 pre-configured to generate 32-bit RISC-V codes, like *riscv32-unknown-elf-*.
 193
 194 However it's possible to explicitly specify the image bits we want to build with
 195 a given RISC-V toolchain. This can be done by setting the environment variable
 196 *PLATFORM_RISCV_XLEN* to the desired width, for example:
 197
 198 ```
 199 export CROSS_COMPILE=riscv64-unknown-elf-
 200 export PLATFORM_RISCV_XLEN=32
 201 ```
 202
 203 will generate 32-bit OpenSBI images. And vice vesa.
 204
 205 Contributing to OpenSBI
 206 -----------------------
 207
 208 The OpenSBI project encourages and welcomes contributions. Contributions should
 209 follow the rules described in the OpenSBI [Contribution Guideline] document.
 210 In particular, all patches sent should contain a Signed-off-by tag.
 211
 212 The [Contributors List] document provides a list of individuals and
 213 organizations actively contributing to the OpenSBI project.
 214
 215 Documentation
 216 -------------
 217
 218 Detailed documentation of various aspects of OpenSBI can be found under the
 219 *docs* directory. The documentation covers the following topics.
 220
 221 * [Contribution Guideline]: Guideline for contributing code to OpenSBI project
 222 * [Library Usage]: API documentation of OpenSBI static library *libsbi.a*
 223 * [Platform Requirements]: Requirements for using OpenSBI on a platform
 224 * [Platform Support Guide]: Guideline for implementing support for new platforms
 225 * [Platform Documentation]: Documentation of the platforms currently supported.
 226 * [Firmware Documentation]: Documentation for the different types of firmware
 227   examples build supported by OpenSBI.
 228 * [Domain Support]: Documentation for the OpenSBI domain support which helps
 229   users achieve system-level partitioning using OpenSBI.
 230
 231 OpenSBI source code is also well documented. For source level documentation,
 232 doxygen style is used. Please refer to the [Doxygen manual] for details on this
 233 format.
 234
 235 Doxygen can be installed on Linux distributions using *.deb* packages using
 236 the following command.
 237 ```
 238 sudo apt-get install doxygen doxygen-latex doxygen-doc doxygen-gui graphviz
 239 ```
 240
 241 For *.rpm* based Linux distributions, the following commands can be used.
 242 ```
 243 sudo yum install doxygen doxygen-latex doxywizard graphviz
 244 ```
 245 or
 246 ```
 247 sudo yum install doxygen doxygen-latex doxywizard graphviz
 248 ```
 249
 250 To build a consolidated *refman.pdf* of all documentation, run:
 251 ```
 252 make docs
 253 ```
 254 or
 255 ```
 256 make O=<build_directory> docs
 257 ```
 258
 259 the resulting *refman.pdf* will be available under the directory
 260 *<build_directory>/docs/latex*. To install this file, run:
 261 ```
 262 make install_docs
 263 ```
 264 or
 265 ```
 266 make I=<install_directory> install_docs
 267 ```
 268
 269 *refman.pdf* will be installed under *<install_directory>/docs*.
 270
 271 [Github]: https://github.com/riscv/riscv-sbi-doc
 272 [U-Boot]: https://www.denx.de/wiki/U-Boot/SourceCode
 273 [Bootlin toolchain repository]: https://toolchains.bootlin.com/
 274 [COPYING.BSD]: COPYING.BSD
 275 [SPDX]: http://spdx.org/licenses/
 276 [Contribution Guideline]: docs/contributing.md
 277 [Contributors List]: CONTRIBUTORS.md
 278 [Library Usage]: docs/library_usage.md
 279 [Platform Requirements]: docs/platform_requirements.md
 280 [Platform Support Guide]: docs/platform_guide.md
 281 [Platform Documentation]: docs/platform/platform.md
 282 [Firmware Documentation]: docs/firmware/fw.md
 283 [Domain Support]: docs/domain_support.md
 284 [Doxygen manual]: http://www.doxygen.nl/manual/index.html
 285 [Kendryte standalone SDK]: https://github.com/kendryte/kendryte-standalone-sdk
 286 [third party notices]: ThirdPartyNotices.md