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 hardware 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 documentation 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] for details on this
 113 format.
 114
 115 [Doxygen manual]: http://www.stack.nl/~dimitri/doxygen/manual.html
 116
 117 The Doxygen can be installed on your debian build system using following:
 118 ```
 119 sudo apt-get install doxygen doxygen-latex doxygen-doc doxygen-gui graphviz
 120 ```
 121
 122 To build a consolidated `refman.pdf` of all documentation, run:
 123 ```
 124 make docs
 125 or
 126 make O=<build_directory> docs
 127 ```
 128
 129 **NOTE:** `refman.pdf` will be available under `<build_directory>/docs/latex`.
 130
 131 To install a consolidated `refman.pdf` of all documentation, run:
 132 ```
 133 make install_docs
 134 or
 135 make I=<install_directory> install_docs
 136 ```
 137
 138 **NOTE:** `refman.pdf` will be installed under `<install_directory>/docs`.