README.md

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