README.md

   1 RISC-V Open Source Supervisor Binary Interface (OpenSBI)
   2 ========================================================
   3
   4 The **RISC-V Supervisor Binary Interface (SBI)** is a recommended
   5 interface between:
   6
   7 1. A platform specific firmware (M-mode) and a general purpose
   8    OS or hypervisor or bootloader (S-mode or HS-mode).
   9 2. A hypervisor (HS-mode) and a general purpose OS or bootloader (VS-mode)
  10
  11 The *RISC-V SBI specification* is maintained as an independent project
  12 by the RISC-V Foundation in [Github](https://github.com/riscv/riscv-sbi-doc)
  13
  14 OpenSBI aims to provides an open-source and extensible implementation of
  15 the RISC-V SBI specification for case 1 mentioned above. OpenSBI
  16 implementation can be easily extended by RISC-V platform or System-on-Chip
  17 vendors to fit a particular hadware configuration.
  18
  19 OpenSBI provides three components:
  20
  21 1. *libsbi.a* - A generic OpenSBI static library
  22 2. *libplatsbi.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 generic *libsbi.a*
  27 ------------------------------------------
  28
  29 For cross-compiling, the environment variable *CROSS_COMPILE* must
  30 be defined to specify the toolchain executable name prefix, e.g.
  31 *riscv64-unknown-elf-* if the gcc executable used is
  32 *riscv64-unknown-elf-gcc*.
  33
  34 To build the generic OpenSBI library *libsbi.a*, simply execute:
  35 ```
  36 make
  37 ```
  38
  39 All compiled binaries will be placed in the *build* directory.
  40 To specify an alternate build directory target, run:
  41 ```
  42 make O=<build_directory>
  43 ```
  44
  45 To generate files to be installed for using *libsbi.a* in other projects,
  46 run:
  47 ```
  48 make install
  49 ```
  50 This will create the *install* directory with all necessary include files
  51 and binary files under it. To specify an alternate installation directory,
  52 run:
  53 ```
  54 make I=<install_directory> install
  55 ```
  56
  57 Building and Installing platform specific *libsbi.a* and firmwares
  58 ------------------------------------------------------------------
  59
  60 The libplatsbi.a and firmware files are only built if the
  61 *`PLATFORM=<platform_subdir>`* argument is specified on make command lines.
  62 *`<platform_subdir>`* must specify the path to one of the leaf directories
  63 under the *`platform`* directory. For example, to compile the library and
  64 firmware for QEMU RISC-V *virt* machine, *`<platform_subdir>`*
  65 should be *`qemu/virt`*.
  66
  67 To build *libsbi, libplatsbi, and firmwares* for a specific platform, run:
  68 ```
  69 make PLATFORM=<platform_subdir>
  70 or
  71 make PLATFORM=<platform_subdir> O=<build_directory>
  72 ```
  73
  74 To install *libsbi, headers, libplatsbi, and firmwares*, run:
  75 ```
  76 make PLATFORM=<platform_subdir> install
  77 or
  78 make PLATFORM=<platform_subdir> I=<install_directory> install
  79 ```
  80
  81 In addition, platform specific make command-line options to top-level make
  82 , such as *PLATFORM_<xyz>* or *FW_<abc>* can also be specified. These
  83 options are described under *`docs/platform/<platform_name>.md`* and
  84 *`docs/firmware/<firmware_name>.md`*.
  85
  86 License
  87 -------------
  88 The software is provided under a BSD-2-Clause license. Contributions to this
  89 project are accepted under the same license with developer sign-off as
  90 described in the [Contributing Guidelines] [docs/contributing.md].
  91
  92 This project also contains code from other projects as listed below. The original
  93 license text is included in those source files.
  94
  95 1. The libfdt source code is disjunctively dual licensed (GPL-2.0+ OR BSD-2-Clause). It is
  96    used by this project under the terms of the BSD-2-Clause license. Any contributions to
  97    this code must be made under the terms of both licenses.
  98
  99 Documentation
 100 -------------
 101
 102 A more detailed documenation is under the *docs* directory and organized
 103 as follows.
 104
 105 * *`docs/contributing.md`* - Guidelines for contributing to OpenSBI project
 106 * *`docs/platform_guide.md`* - Guidelines for adding new platform support
 107 * *`docs/library_usage.md`* - Guidelines for using the static library
 108 * *`docs/platform/<platform_name>.md`* - Documentation for the platform *<platform_name>*
 109 * *`docs/firmware/<firmware_name>.md`* - Documentation for the firmware *<firmware_name>*
 110
 111 The source code is also well documented. For source level documentation,
 112 doxygen style is used. Please refer to [Doxygen manual]
 113 (http://www.stack.nl/~dimitri/doxygen/manual.html) for details on this
 114 format.
 115
 116 The Doxygen can be installed on your debian build system using following:
 117 ```
 118 sudo apt-get install doxygen doxygen-latex doxygen-doc doxygen-gui graphviz
 119 ```
 120
 121 To build a consolidated `refman.pdf` of all documenation, run:
 122 ```
 123 make docs
 124 or
 125 make O=<build_directory> docs
 126 ```
 127
 128 **NOTE:** `refman.pdf` will be available under `<build_directory>/docs/latex`.
 129
 130 To install a consolidated `refman.pdf` of all documenation, run:
 131 ```
 132 make install_docs
 133 or
 134 make I=<install_directory> install_docs
 135 ```
 136
 137 **NOTE:** `refman.pdf` will be installed under `<install_directory>/docs`.