README.md

   1 Copyright (c) 2019 Western Digital Corporation or its affiliates
   2 and other contributors.
   3
   4 RISC-V Open Source Supervisor Binary Interface (OpenSBI)
   5 ========================================================
   6
   7 The **RISC-V Supervisor Binary Interface (SBI)** is the recommended interface
   8 between:
   9
  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
  13    executing in VS-mode.
  14
  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).
  17
  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.
  23
  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
  30 control, etc).
  31
  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).
  41
  42 Supported SBI version
  43 ---------------------
  44 Currently, OpenSBI fully supports SBI specification *v0.2*. OpenSBI also
  45 supports Hart State Management (HSM) SBI extension starting from OpenSBI v0.7.
  46 HSM extension allows S-mode software to boot all the harts a defined order
  47 rather than legacy method of random booting of harts. As a result, many
  48 required features such as CPU hotplug, kexec/kdump can also be supported easily
  49 in S-mode. HSM extension in OpenSBI is implemented in a non-backward compatible
  50 manner to reduce the maintenance burden and avoid confusion. That's why, any
  51 S-mode software using OpenSBI will not be able to boot more than 1 hart if HSM
  52 extension is not supported in S-mode.
  53
  54 Linux kernel already supports SBI v0.2 and HSM SBI extension starting from
  55 **v5.7-rc1**. If you are using an Linux kernel older than **5.7-rc1** or any
  56 other S-mode software without HSM SBI extension, you should stick to OpenSBI
  57 v0.6 to boot all the harts. For a UMP systems, it doesn't matter.
  58
  59 N.B. Any S-mode boot loader (i.e. U-Boot) doesn't need to support HSM extension,
  60 as it doesn't need to boot all the harts. The operating system should be
  61 capable enough to bring up all other non-booting harts using HSM extension.
  62
  63 Required Toolchain
  64 ------------------
  65
  66 OpenSBI can be compiled natively or cross-compiled on a x86 host. For
  67 cross-compilation, you can build your own toolchain or just download
  68 a prebuilt one from the
  69 [Bootlin toolchain repository] (https://toolchains.bootlin.com/).
  70
  71 Please note that only a 64-bit version of the toolchain is available in
  72 the Bootlin toolchain repository for now.
  73
  74 Building and Installing the OpenSBI Platform-Independent Library
  75 ----------------------------------------------------------------
  76
  77 The OpenSBI platform-independent static library *libsbi.a* can be compiled
  78 natively or it can be cross-compiled on a host with a different base
  79 architecture than RISC-V.
  80
  81 For cross-compiling, the environment variable *CROSS_COMPILE* must be defined
  82 to specify the name prefix of the RISC-V compiler toolchain executables, e.g.
  83 *riscv64-unknown-elf-* if the gcc executable used is *riscv64-unknown-elf-gcc*.
  84
  85 To build *libsbi.a* simply execute:
  86 ```
  87 make
  88 ```
  89
  90 All compiled binaries as well as the resulting *libsbi.a* static library file
  91 will be placed in the *build/lib* directory. To specify an alternate build root
  92 directory path, run:
  93 ```
  94 make O=<build_directory>
  95 ```
  96
  97 To generate files to be installed for using *libsbi.a* in other projects, run:
  98 ```
  99 make install
 100 ```
 101
 102 This will create the *install* directory with all necessary include files
 103 copied under the *install/include* directory and the library file copied into
 104 the *install/lib* directory. To specify an alternate installation root
 105 directory path, run:
 106 ```
 107 make I=<install_directory> install
 108 ```
 109
 110 Building and Installing a Reference Platform Static Library and Firmware
 111 ------------------------------------------------------------------------
 112
 113 When the *PLATFORM=<platform_subdir>* argument is specified on the make command
 114 line, the platform-specific static library *libplatsbi.a* and firmware examples
 115 are built for the platform *<platform_subdir>* present in the directory
 116 *platform* in the OpenSBI top directory. For example, to compile the platform
 117 library and the firmware examples for the QEMU RISC-V *virt* machine,
 118 *<platform_subdir>* should be *qemu/virt*.
 119
 120 To build *libsbi.a*, *libplatsbi.a* and the firmware for one of the supported
 121 platforms, run:
 122 ```
 123 make PLATFORM=<platform_subdir>
 124 ```
 125
 126 An alternate build directory path can also be specified:
 127 ```
 128 make PLATFORM=<platform_subdir> O=<build_directory>
 129 ```
 130
 131 The platform-specific library *libplatsbi.a* will be generated in the
 132 *build/platform/<platform_subdir>/lib* directory. The platform firmware files
 133 will be under the *build/platform/<platform_subdir>/firmware* directory.
 134 The compiled firmwares will be available in two different formats: an ELF file
 135 and an expanded image file.
 136
 137 To install *libsbi.a*, *libplatsbi.a*, and the compiled firmwares, run:
 138 ```
 139 make PLATFORM=<platform_subdir> install
 140 ```
 141
 142 This will copy the compiled platform-specific libraries and firmware files
 143 under the *install/platform/<platform_subdir>/* directory. An alternate
 144 install root directory path can be specified as follows:
 145 ```
 146 make PLATFORM=<platform_subdir> I=<install_directory> install
 147 ```
 148
 149 In addition, platform-specific configuration options can be specified with the
 150 top-level make command line. These options, such as *PLATFORM_<xyz>* or
 151 *FW_<abc>*, are platform-specific and described in more details in the
 152 *docs/platform/<platform_name>.md* files and
 153 *docs/firmware/<firmware_name>.md* files.
 154
 155 Building 32-bit / 64-bit OpenSBI Images
 156 ---------------------------------------
 157 By default, building OpenSBI generates 32-bit or 64-bit images based on the
 158 supplied RISC-V cross-compile toolchain. For example if *CROSS_COMPILE* is set
 159 to *riscv64-unknown-elf-*, 64-bit OpenSBI images will be generated. If building
 160 32-bit OpenSBI images, *CROSS_COMPILE* should be set to a toolchain that is
 161 pre-configured to generate 32-bit RISC-V codes, like *riscv32-unknown-elf-*.
 162
 163 However it's possible to explicitly specify the image bits we want to build with
 164 a given RISC-V toolchain. This can be done by setting the environment variable
 165 *PLATFORM_RISCV_XLEN* to the desired width, for example:
 166
 167 ```
 168 export CROSS_COMPILE=riscv64-unknown-elf-
 169 export PLATFORM_RISCV_XLEN=32
 170 ```
 171
 172 will generate 32-bit OpenSBI images. And vice vesa.
 173
 174 License
 175 -------
 176
 177 OpenSBI is distributed under the terms of the BSD 2-clause license
 178 ("Simplified BSD License" or "FreeBSD License", SPDX: *BSD-2-Clause*).
 179 A copy of this license with OpenSBI copyright can be found in the file
 180 [COPYING.BSD].
 181
 182 All source files in OpenSBI contain the 2-Clause BSD license SPDX short
 183 identifier in place of the full license text.
 184
 185 ```
 186 SPDX-License-Identifier:    BSD-2-Clause
 187 ```
 188
 189 This enables machine processing of license information based on the SPDX
 190 License Identifiers that are available on the [SPDX] web site.
 191
 192 OpenSBI source code also contains code reused from other projects as listed
 193 below. The original license text of these projects is included in the source
 194 files where the reused code is present.
 195
 196 * The libfdt source code is disjunctively dual licensed
 197   (GPL-2.0+ OR BSD-2-Clause). Some of this project code is used in OpenSBI
 198   under the terms of the BSD 2-Clause license. Any contributions to this
 199   code must be made under the terms of both licenses.
 200
 201 See also the [third party notices] file for more information.
 202
 203 Contributing to OpenSBI
 204 -----------------------
 205
 206 The OpenSBI project encourages and welcomes contributions. Contributions should
 207 follow the rules described in the OpenSBI [Contribution Guideline] document.
 208 In particular, all patches sent should contain a Signed-off-by tag.
 209
 210 The [Contributors List] document provides a list of individuals and
 211 organizations actively contributing to the OpenSBI project.
 212
 213 Documentation
 214 -------------
 215
 216 Detailed documentation of various aspects of OpenSBI can be found under the
 217 *docs* directory. The documentation covers the following topics.
 218
 219 * [Contribution Guideline]: Guideline for contributing code to OpenSBI project
 220 * [Library Usage]: API documentation of OpenSBI static library *libsbi.a*
 221 * [Platform Support Guide]: Guideline for implementing support for new platforms
 222 * [Platform Documentation]: Documentation of the platforms currently supported.
 223 * [Firmware Documentation]: Documentation for the different types of firmware
 224   examples build supported by OpenSBI.
 225
 226 OpenSBI source code is also well documented. For source level documentation,
 227 doxygen style is used. Please refer to the [Doxygen manual] for details on this
 228 format.
 229
 230 Doxygen can be installed on Linux distributions using *.deb* packages using
 231 the following command.
 232 ```
 233 sudo apt-get install doxygen doxygen-latex doxygen-doc doxygen-gui graphviz
 234 ```
 235
 236 For *.rpm* based Linux distributions, the following commands can be used.
 237 ```
 238 sudo yum install doxygen doxygen-latex doxywizard graphviz
 239 ```
 240 or
 241 ```
 242 sudo yum install doxygen doxygen-latex doxywizard graphviz
 243 ```
 244
 245 To build a consolidated *refman.pdf* of all documentation, run:
 246 ```
 247 make docs
 248 ```
 249 or
 250 ```
 251 make O=<build_directory> docs
 252 ```
 253
 254 the resulting *refman.pdf* will be available under the directory
 255 *<build_directory>/docs/latex*. To install this file, run:
 256 ```
 257 make install_docs
 258 ```
 259 or
 260 ```
 261 make I=<install_directory> install_docs
 262 ```
 263
 264 *refman.pdf* will be installed under *<install_directory>/docs*.
 265
 266 [Github]: https://github.com/riscv/riscv-sbi-doc
 267 [U-Boot]: https://www.denx.de/wiki/U-Boot/SourceCode
 268 [COPYING.BSD]: COPYING.BSD
 269 [SPDX]: http://spdx.org/licenses/
 270 [Contribution Guideline]: docs/contributing.md
 271 [Contributors List]: CONTRIBUTORS.md
 272 [Library Usage]: docs/library_usage.md
 273 [Platform Support Guide]: docs/platform_guide.md
 274 [Platform Documentation]: docs/platform/platform.md
 275 [Firmware Documentation]: docs/firmware/fw.md
 276 [Doxygen manual]: http://www.doxygen.nl/manual/index.html
 277 [Kendryte standalone SDK]: https://github.com/kendryte/kendryte-standalone-sdk
 278 [third party notices]: ThirdPartyNotices.md