README.md

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