README.md

   1 RISC-V Open Source Supervisor Binary Interface (OpenSBI)
   2 ========================================================
   3
   4 The **RISC-V Supervisor Binary Interface (SBI)** is the recommended interface
   5 between:
   6
   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
  10    executing in VS-mode.
  11
  12 The *RISC-V SBI specification* is maintained as an independent project by the
  13 RISC-V Foundation in [Github].
  14
  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.
  20
  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
  27 control, etc).
  28
  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
  37 such as [U-Boot].
  38
  39 Required Toolchain
  40 ------------------
  41
  42 OpenSBI can be compiled natively or cross-compiled on a x86 host. For
  43 cross-compilation, you can build your tool chain or just download from
  44 the [bootlin] (https://toolchains.bootlin.com/).
  45
  46 Please note that only 64bit version of toolchain is available in bootlin
  47 for now.
  48
  49 Building and Installing OpenSBI Platform Independent Library
  50 ------------------------------------------------------------
  51
  52 OpenSBI platform independent static library *libsbi.a* can be natively compiled
  53 or cross-compiled on a host with a different base architecture than RISC-V.
  54
  55 For cross-compiling, the environment variable *CROSS_COMPILE* must be defined
  56 to specify the name prefix of the RISC-V compiler toolchain executables, e.g.
  57 *riscv64-unknown-elf-* if the gcc executable used is *riscv64-unknown-elf-gcc*.
  58
  59 To build *libsbi.a* simply execute:
  60 ```
  61 make
  62 ```
  63
  64 All compiled binaries as well as the result *libsbi.a* static library file will
  65 be placed in the *build/lib* directory. To specify an alternate build root
  66 directory path, run:
  67 ```
  68 make O=<build_directory>
  69 ```
  70
  71 To generate files to be installed for using *libsbi.a* in other projects, run:
  72 ```
  73 make install
  74 ```
  75
  76 This will create the *install* directory with all necessary include files
  77 copied under the *install/include* directory and library file copied in the
  78 *install/lib* directory. To specify an alternate installation root directory
  79 path, run:
  80 ```
  81 make I=<install_directory> install
  82 ```
  83
  84 Building and Installing a Reference Platform Static Library and Firmwares
  85 -------------------------------------------------------------------------
  86
  87 When the *PLATFORM=<platform_subdir>* argument is specified on the make command
  88 line, the platform specific static library *libplatsbi.a* and firmware examples
  89 are built for the platform *<platform_subdir>* present in the directory
  90 *platform* in OpenSBI top directory. For example, to compile the platform
  91 library and firmware examples for QEMU RISC-V *virt* machine,
  92 *<platform_subdir>* should be *qemu/virt*.
  93
  94 To build *libsbi.a*, *libplatsbi.a* and the firmwares for one of the supported
  95 platform, run:
  96 ```
  97 make PLATFORM=<platform_subdir>
  98 ```
  99
 100 An alternate build directory path can also be specified.
 101 ```
 102 make PLATFORM=<platform_subdir> O=<build_directory>
 103 ```
 104
 105 The platform specific library *libplatsbi.a* will be generated in the
 106 *build/platform/<platform_subdir>/lib* directory. The platform firmware files
 107 will be under the *build/platform/<platform_subdir>/firmware* directory.
 108 The compiled firmwares will be available in two different format: an ELF file
 109 and an expanded image file.
 110
 111 To install *libsbi.a*, *libplatsbi.a*, and the compiled firmwares, run:
 112 ```
 113 make PLATFORM=<platform_subdir> install
 114 ```
 115
 116 This will copy the compiled platform specific libraries and firmware files
 117 under the *install/platform/<platform_subdir>/* directory. An alternate
 118 install root directory path can be specified as follows.
 119 ```
 120 make PLATFORM=<platform_subdir> I=<install_directory> install
 121 ```
 122
 123 In addition, platform specific configuration options can be specified with the
 124 top-level make command line. These options, such as *PLATFORM_<xyz>* or
 125 *FW_<abc>*, are platform specific and described in more details in the
 126 *docs/platform/<platform_name>.md* files and
 127 *docs/firmware/<firmware_name>.md* files.
 128
 129 License
 130 -------
 131
 132 OpenSBI is distributed under the terms of the BSD 2-clause license
 133 ("Simplified BSD License" or "FreeBSD License", SPDX: *BSD-2-Clause*).
 134 A copy of this license with OpenSBI copyright can be found in the file
 135 [COPYING.BSD].
 136
 137 All source files in OpenSBI contain the 2-Clause BSD license SPDX short
 138 identifier in place of the full license text.
 139
 140 ```
 141 SPDX-License-Identifier:    BSD-2-Clause
 142 ```
 143
 144 This enables machine processing of license information based on the SPDX
 145 License Identifiers that are available on the [SPDX] web site.
 146
 147 OpenSBI source code also contains code reused from other projects as listed
 148 below. The original license text of these projects is included in the source
 149 files where the reused code is present.
 150
 151 1. The libfdt source code is disjunctively dual licensed
 152    (GPL-2.0+ OR BSD-2-Clause). Some of this project code is used in OpenSBI
 153    under the terms of the BSD 2-Clause license. Any contributions to this
 154    code must be made under the terms of both licenses.
 155
 156 Contributing to OpenSBI
 157 -----------------------
 158
 159 The OpenSBI project encourages and welcomes contributions. Contributions should
 160 follow the rules described in OpenSBI [Contribution Guideline] document.
 161 In particular, all patches sent should contain a Signed-off-by tag.
 162
 163 Documentation
 164 -------------
 165
 166 Detailed documentation of various aspects of OpenSBI can be found under the
 167 *docs* directory. The documentation covers the following topics.
 168
 169 * [Contribution Guideline]: Guideline for contributing code to OpenSBI project
 170 * [Library Usage]: API documentation of OpenSBI static library *libsbi.a*
 171 * [Platform Support Guide]: Guideline for implementing support for new platforms
 172 * [Platform Documentation]: Documentation of the platforms currently supported.
 173 * [Firmware Documentation]: Documentation for the different types of firmware
 174   examples build supported by OpenSBI.
 175
 176 OpenSBI source code is also well documented. For source level documentation,
 177 doxygen style is used. Please refer to [Doxygen manual] for details on this
 178 format.
 179
 180 Doxygen can be installed on Linux distributions using *.deb* packages using
 181 the following command.
 182 ```
 183 sudo apt-get install doxygen doxygen-latex doxygen-doc doxygen-gui graphviz
 184 ```
 185
 186 For *.rpm* based Linux distributions, the following commands can be used.
 187 ```
 188 sudo yum install doxygen doxygen-latex doxywizard graphviz
 189 ```
 190 or
 191 ```
 192 sudo yum install doxygen doxygen-latex doxywizard graphviz
 193 ```
 194
 195 To build a consolidated *refman.pdf* of all documentation, run:
 196 ```
 197 make docs
 198 ```
 199 or
 200 ```
 201 make O=<build_directory> docs
 202 ```
 203
 204 the resulting *refman.pdf* will be available under the directory
 205 *<build_directory>/docs/latex*. To install this file, run:
 206 ```
 207 make install_docs
 208 ```
 209 or
 210 ```
 211 make I=<install_directory> install_docs
 212 ```
 213
 214 *refman.pdf* will be installed under *<install_directory>/docs*.
 215
 216 [Github]: https://github.com/riscv/riscv-sbi-doc
 217 [U-Boot]: https://www.denx.de/wiki/U-Boot/SourceCode
 218 [COPYING.BSD]: COPYING.BSD
 219 [SPDX]: http://spdx.org/licenses/
 220 [Contribution Guideline]: docs/contributing.md
 221 [Library Usage]: docs/library_usage.md
 222 [Platform Support Guide]: docs/platform_guide.md
 223 [Platform Documentation]: docs/platform/platform.md
 224 [Firmware Documentation]: docs/firmware/fw.md
 225 [Doxygen manual]: http://www.stack.nl/~dimitri/doxygen/manual.html
 226