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