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 pplatform specific firmware executed in M-mode and a general purpose
   8    OS hypervisor or bootloader executed in S-mode or HS-mode.
   9 2. A hypervisor executed 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
  13 by the RISC-V Foundation in [Github](https://github.com/riscv/riscv-sbi-doc)
  14
  15 OpenSBI aims to provides an open-source and extensible implementation of
  16 the RISC-V SBI specification for case 1 mentioned above. OpenSBI
  17 implementation can be easily extended by RISC-V platform or System-on-Chip
  18 vendors to fit a particular hadware configuration.
  19
  20 OpenSBI provides three components:
  21
  22 1. *libsbi.a* - A generic OpenSBI static library
  23 2. *libplatsbi.a* - Platform specific OpenSBI static library, that is,
  24                     libsbi.a plus platform specific hooks
  25 3. *firmwares* - Platform specific bootable firmware binaries
  26
  27 Building and Installing generic *libsbi.a*
  28 ------------------------------------------
  29
  30 For cross-compiling, the environment variable *CROSS_COMPILE* must
  31 be defined to specify the toolchain executable name prefix, e.g.
  32 *riscv64-unknown-elf-* if the gcc executable used is
  33 *riscv64-unknown-elf-gcc*.
  34
  35 To build the generic OpenSBI library *libsbi.a*, simply execute:
  36 ```
  37 make
  38 ```
  39
  40 All compiled binaries will be placed in the *build* directory.
  41 To specify an alternate build directory target, run:
  42 ```
  43 make O=<build_directory>
  44 ```
  45
  46 To generate files to be installed for using *libsbi.a* in other projects,
  47 run:
  48 ```
  49 make install
  50 ```
  51 This will create the *install* directory with all necessary include files
  52 and binary files under it. To specify an alternate installation directory,
  53 run:
  54 ```
  55 make I=<install_directory> install
  56 ```
  57
  58 Building and Installing platform specific *libsbi.a* and firmwares
  59 ------------------------------------------------------------------
  60
  61 The libplatsbi.a and firmware files are only built if the
  62 *PLATFORM=<platform path>* argument is specified on make command lines.
  63 *<platform path>* must specify the path to one of the leaf directories
  64 under the *platform* directory. For example, to compile the library and
  65 firmware for QEMU generic RISC-V *virt* machine, *<platform path>*
  66 should be *qemu/virt*.
  67
  68 To build *libsbi, libplatsbi, and firmwares* for a specific platform, run:
  69 ```
  70 make PLATFORM=<platform_subdir>
  71 ```
  72
  73 or
  74
  75 ```
  76 make PLATFORM=<platform_subdir> O=<build_directory>
  77 ```
  78
  79 To install *libsbi, headers, libplatsbi, and firmwares*, run:
  80 ```
  81 make PLATFORM=<platform_subdir> install
  82 ```
  83
  84 or
  85
  86 ```
  87 make PLATFORM=<platform_subdir> I=<install_directory> install`
  88 ```
  89
  90 In addition, platform specific make command-line options to top-level make
  91 ,such as *PLATFORM_<xyz>* or *FW_<abc>* can also be specified. These
  92 options are described under *docs/platform/<platform_name>.md* and
  93 *docs/firmware/<firmware_name>.md*.
  94
  95 Documentation
  96 -------------
  97
  98 A more detailed documenation is under the *docs* directory and organized
  99 as follows.
 100
 101 * *docs/platform_guide.md* - Guidelines for adding new platform support
 102 * *docs/library_usage.md* - Guidelines for using the static library
 103 * *docs/platform/<platform_name>.md* - Platform specific documentation for
 104                                        the platform *<platform_name>*
 105 * *docs/firmware/<firmware_name>.md* - Platform specific documentation for
 106                                        the firmware *<firmware_name>*
 107
 108 The source code is also well documented. For source level documentation,
 109 doxygen style is used. Please refer to [Doxygen manual]
 110 (http://www.stack.nl/~dimitri/doxygen/manual.html) for details on this
 111 format.
 112