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 Documentation
  87 -------------
  88
  89 A more detailed documenation is under the *docs* directory and organized
  90 as follows.
  91
  92 * *`docs/contributing.md`* - Guidelines for contributing to OpenSBI project
  93 * *`docs/platform_guide.md`* - Guidelines for adding new platform support
  94 * *`docs/library_usage.md`* - Guidelines for using the static library
  95 * *`docs/platform/<platform_name>.md`* - Documentation for the platform *<platform_name>*
  96 * *`docs/firmware/<firmware_name>.md`* - Documentation for the firmware *<firmware_name>*
  97
  98 The source code is also well documented. For source level documentation,
  99 doxygen style is used. Please refer to [Doxygen manual]
 100 (http://www.stack.nl/~dimitri/doxygen/manual.html) for details on this
 101 format.
 102
 103 The Doxygen can be installed on your debian build system using following:
 104 ```
 105 sudo apt-get install doxygen doxygen-latex doxygen-doc doxygen-gui graphviz
 106 ```
 107
 108 To build a consolidated `refman.pdf` of all documenation, run:
 109 ```
 110 make docs
 111 or
 112 make O=<build_directory> docs
 113 ```
 114
 115 **NOTE:** `refman.pdf` will be available under `<build_directory>/docs/latex`.
 116
 117 To install a consolidated `refman.pdf` of all documenation, run:
 118 ```
 119 make install_docs
 120 or
 121 make I=<install_directory> install_docs
 122 ```
 123
 124 **NOTE:** `refman.pdf` will be installed under `<install_directory>/docs`.