| commit | 8af20068d13986c7f66a595b89d4ef251b9d9e34 | [log] [tgz] |
|---|---|---|
| author | Anup Patel <anup.patel@wdc.com> | Tue Jan 29 17:59:02 2019 +0530 |
| committer | Anup Patel <anup@brainfault.org> | Wed Jan 30 12:14:30 2019 +0530 |
| tree | 8313509d907e69082ca5e08dcef275f61e831ede | |
| parent | 27b55bb4da7321137693de7e6e73609e1271dce3 [diff] |
docs: Add library usage guide This patch adds static library usage guide (i.e. docs/library_usage.md). Signed-off-by: Anup Patel <anup.patel@wdc.com>
The RISC-V Supervisor Binary Interface (SBI) is a recommended interface between:
The RISC-V SBI specification is maintained as an independent project by the RISC-V Foundation in Github.
OpenSBI aims to provides an open-source and extensible implementation of the RISC-V SBI specification for case 1 mentioned above. OpenSBI implementation can be easily extended by RISC-V platform or System-on-Chip vendors to fit a particular hardware configuration.
OpenSBI provides three different components:
libsbi.a can be natively compiled or cross-compiled on a host with a different base architecture than RISC-V.
For cross-compiling, the environment variable CROSS_COMPILE must be defined to specify the name prefix of the RISC-V compiler toolchain executables, e.g. riscv64-unknown-elf- if the gcc executable used is riscv64-unknown-elf-gcc.
To build the generic OpenSBI library libsbi.a, simply execute:
make
All compiled binaries as well as the result libsbi.a static library file will be placed in the build/lib directory. To specify an alternate build root directory path, run:
make O=<build_directory>
To generate files to be installed for using libsbi.a in other projects, run:
make install
This will create the install directory with all necessary include files copied under the install/include directory and library file copied in the install/lib directory. To specify an alternate installation root directory path, run:
make I=<install_directory> install
The platform specific libplatsbi.a static library and the platform firmwares are only built if the PLATFORM=<platform_subdir> argument is specified on the make command line. <platform_subdir> must specify the relative path from OpenSBI code directory to one of the leaf directories under the platform directory. For example, to compile the platform library and firmwares for QEMU RISC-V virt machine, <platform_subdir> should be qemu/virt.
To build libsbi.a, libplatsbi.a and the firmwares for a specific platform, run:
make PLATFORM=<platform_subdir>
An alternate build directory path can also be specified.
make PLATFORM=<platform_subdir> O=<build_directory>
The platform specific library libplatsbi.a will be generated in the build/platform/<platform_subdir>/lib directory. The platform firmware files will be under the build/platform/<platform_subdir>/firmware directory. The compiled firmwares will be available in two different format: an ELF file and an expanded image file.
To install libsbi.a, libplatsbi.a, and the compiled firmwares, run:
make PLATFORM=<platform_subdir> install
This will copy the compiled platform specific libraries and firmware files under the install/platform/<platform_subdir>/ directory. An alternate install root directory path can be specified as follows.
make PLATFORM=<platform_subdir> I=<install_directory> install
In addition, platform specific configuration options can be specified with the top-level make command line. These options, such as PLATFORM_ or FW_, are platform specific and described in more details in the docs/platform/<platform_name>.md files and docs/firmware/<firmware_name>.md files.
OpenSBI is distributed under the terms of the BSD 2-clause license (“Simplified BSD License” or “FreeBSD License”, SPDX: BSD-2-Clause). A copy of this license with OpenSBI copyright can be found in the file COPYING.BSD.
All source files in OpenSBI contain the 2-Clause BSD license SPDX short indentifier in place of the full license text.
SPDX-License-Identifier: BSD-2-Clause
This enables machine processing of license information based on the SPDX License Identifiers that are available on the SPDX web site.
OpenSBI source code also contains code reused from other projects as listed below. The original license text of these projects is included in the source files where the reused code is present.
The OpenSBI project encourages and welcomes contributions. Contributions should follow the rules described in OpenSBI Contribution Guideline document. In particular, all patches sent should contain a Signed-off-by tag.
Detailed documentation of various aspects of OpenSBI can be found under the docs directory. The documentation covers the following topics.
OpenSBI source code is also well documented. For source level documentation, doxygen style is used. Please refer to Doxygen manual for details on this format.
Doxygen can be installed on Linux distributions using .deb packages using the following command.
sudo apt-get install doxygen doxygen-latex doxygen-doc doxygen-gui graphviz
For .rpm based Linux distributions, the following commands can be used.
sudo yum install doxygen doxygen-latex doxywizard graphviz
or
sudo yum install doxygen doxygen-latex doxywizard graphviz
To build a consolidated refman.pdf of all documentation, run:
make docs
or
make O=<build_directory> docs
the resulting refman.pdf will be available under the directory <build_directory>/docs/latex. To install this file, run:
make install_docs
or
make I=<install_directory> install_docs
refman.pdf will be installed under <install_directory>/docs.