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. Platform specific firmware running in M-mode and
   8    general-purpose-os/hypervisor/bootloader running in S-mode/HS-mode
   9 2. Hypervisor runnng in HS-mode and general-purpose-os/bootloader
  10    running in VS-mode
  11
  12 The **RISC-V SBI specification** is maintained as independent project
  13 by RISC-V Foundation on [Github](https://github.com/riscv/riscv-sbi-doc)
  14
  15 The **RISC-V OpenSBI project** aims to provides an open-source and
  16 extensible implementation of the **RISC-V SBI specification** for
  17 point 1) mentioned above. It can be easily extended by RISC-V platform
  18 or RISC-V System-on-Chip vendors.
  19
  20 We can create three things using the RISC-V OpenSBI project:
  21
  22 1. **libsbi.a** - Generic OpenSBI static library
  23 2. **libplatsbi.a** - Platform specific OpenSBI static library
  24    (It is libsbi.a plus platform specific hooks represented
  25     by "platform" symbol)
  26 3. **firmwares** - Platform specific firmware binaries
  27
  28 How to Build?
  29 -------------
  30
  31 For cross-compiling, please ensure that CROSS_COMPILE environment
  32 variable is set before starting build system.
  33
  34 The libplatsbi.a and firmwares are optional and only built when
  35 `PLATFORM=<platform_subdir>` parameter is specified to top-level make.
  36 (**NOTE**: `<platform_subdir>` is sub-directory under platform/ directory)
  37
  38 To build and install Generic OpenSBI library do the following:
  39
  40 1. Build **libsbi.a**:
  41 `make`
  42 OR
  43 `make O=<build_directory>`
  44 2. Install **libsbi.a and headers**:
  45 `make install`
  46 OR
  47 `make I=<install_directory> install`
  48
  49 To build and install platform specific OpenSBI library and firmwares
  50 do the following:
  51
  52 1. Build **libsbi, libplatsbi, and firmwares**:
  53 `make PLATFORM=<platform_subdir>`
  54 OR
  55 `make PLATFORM=<platform_subdir> O=<build_directory>`
  56 2. Install **libsbi, headers, libplatsbi, and firmwares**:
  57 `make PLATFORM=<platform_subdir> install`
  58 OR
  59 `make PLATFORM=<platform_subdir> I=<install_directory> install`
  60
  61 In addition, we can also specify platform specific command-line
  62 options to top-level make (such as `PLATFORM_<xyz>` or `FW_<abc>`)
  63 which are described under `docs/platform/<platform_name>.md` OR
  64 `docs/firmware/<firmware_name>.md`.
  65
  66 Documentation
  67 -------------
  68
  69 All our documenation is under `docs` directory organized in following
  70 manner:
  71
  72 * `docs/platform_guide.md` - Guidelines for adding new platform support
  73 * `docs/library_usage.md` - Guidelines for using static library
  74 * `docs/platform/<platform_name>.md` - Documentation for `<platform_name>` platform
  75 * `docs/firmware/<firmware_name>.md` - Documentation for firmware `<firmware_name>`
  76
  77 We also prefer source level documentation, so wherever possible we describe
  78 stuff directly in the source code. This helps us maintain source and its
  79 documentation at the same place. For source level documentation we strictly
  80 follow Doxygen style. Please refer [Doxygen manual]
  81 (http://www.stack.nl/~dimitri/doxygen/manual.html) for details.