Mirrors/opensbi
1
0
Fork 1
mirror of https://github.com/riscv-software-src/opensbi.git synced 2025-08-24 15:31:22 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs: README.md update

Browse Source 
Reformat to fit lines within 80 chars, fix hyperlinks, etc.

Signed-off-by: Damien Le Moal <damien.lemoal@wdc.com>
This commit is contained in:
Damien Le Moal
2019-01-23 15:14:13 +09:00
committed by Anup Patel
parent 84cd4b7cd0
commit fba7e7c3ea
1 changed files with 131 additions and 67 deletions
Download Patch File Download Diff File Expand all files Collapse all files

198
README.md
View File

@@ -1,138 +1,202 @@
RISC-V Open Source Supervisor Binary Interface (OpenSBI) RISC-V Open Source Supervisor Binary Interface (OpenSBI)
======================================================== ========================================================
The **RISC-V Supervisor Binary Interface (SBI)** is a recommended The **RISC-V Supervisor Binary Interface (SBI)** is a recommended interface
interface between: between:
1. A platform specific firmware (M-mode) and a general purpose 1. A platform specific firmware running in M-mode and a general purpose OS,
OS or hypervisor or bootloader (S-mode or HS-mode). hypervisor or bootloader running in S-mode or HS-mode.
2. A hypervisor (HS-mode) and a general purpose OS or bootloader (VS-mode) 2. A hypervisor running in HS-mode and a general purpose OS or bootloader
executed in VS-mode.
The *RISC-V SBI specification* is maintained as an independent project The *RISC-V SBI specification* is maintained as an independent project by the
by the RISC-V Foundation in [Github](https://github.com/riscv/riscv-sbi-doc) RISC-V Foundation in [Github].
OpenSBI aims to provides an open-source and extensible implementation of OpenSBI aims to provides an open-source and extensible implementation of the
the RISC-V SBI specification for case 1 mentioned above. OpenSBI RISC-V SBI specification for case 1 mentioned above. OpenSBI implementation
implementation can be easily extended by RISC-V platform or System-on-Chip can be easily extended by RISC-V platform or System-on-Chip vendors to fit a
vendors to fit a particular hardware configuration. particular hardware configuration.
OpenSBI provides three components:
OpenSBI provides three different components:
1. *libsbi.a* - A generic OpenSBI static library 1. *libsbi.a* - A generic OpenSBI static library
2. *libplatsbi.a* - Platform specific OpenSBI static library, that is, 2. *libplatsbi.a* - A platform specific OpenSBI static library, that is,
libsbi.a plus platform specific hooks libsbi.a plus platform specific hooks
3. *firmwares* - Platform specific bootable firmware binaries 3. *firmwares* - Platform specific bootable firmware binaries
Building and Installing generic *libsbi.a* Building and Installing the generic OpenSBI static library
------------------------------------------ ----------------------------------------------------------
For cross-compiling, the environment variable *CROSS_COMPILE* must *libsbi.a* can be natively compiled or cross-compiled on a host with a
be defined to specify the toolchain executable name prefix, e.g. different base architecture than RISC-V.
*riscv64-unknown-elf-* if the gcc executable used is
*riscv64-unknown-elf-gcc*. 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: To build the generic OpenSBI library *libsbi.a*, simply execute:
``` ```
make make
``` ```
All compiled binaries will be placed in the *build* directory. All compiled binaries as well as the result *libsbi.a* static library file will
To specify an alternate build directory target, run: be placed in the *build/lib* directory. To specify an alternate build root
directory path, run:
``` ```
make O=<build_directory> make O=<build_directory>
``` ```
To generate files to be installed for using *libsbi.a* in other projects, To generate files to be installed for using *libsbi.a* in other projects, run:
run:
``` ```
make install make install
``` ```
This will create the *install* directory with all necessary include files This will create the *install* directory with all necessary include files
and binary files under it. To specify an alternate installation directory, copied under the *install/include* directory and library file copied in the
run: *install/lib* directory. To specify an alternate installation root directory
path, run:
``` ```
make I=<install_directory> install make I=<install_directory> install
``` ```
Building and Installing platform specific *libsbi.a* and firmwares Building and Installing the platform specific static library and firmwares
------------------------------------------------------------------ --------------------------------------------------------------------------
The libplatsbi.a and firmware files are only built if the The platform specific *libplatsbi.a* static library and the platform firmwares
*`PLATFORM=<platform_subdir>`* argument is specified on make command lines. are only built if the *PLATFORM=<platform_subdir>* argument is specified on
*`<platform_subdir>`* must specify the path to one of the leaf directories the make command line. *<platform_subdir>* must specify the relative path from
under the *`platform`* directory. For example, to compile the library and OpenSBI code directory to one of the leaf directories under the *platform*
firmware for QEMU RISC-V *virt* machine, *`<platform_subdir>`* directory. For example, to compile the platform library and firmwares for QEMU
should be *`qemu/virt`*. RISC-V *virt* machine, *<platform_subdir>* should be *qemu/virt*.
To build *libsbi, libplatsbi, and firmwares* for a specific platform, run: To build *libsbi.a*, *libplatsbi.a* and the firmwares for a specific platform,
run:
``` ```
make PLATFORM=<platform_subdir> make PLATFORM=<platform_subdir>
or ```
An alternate build directory path can also be specified.
```
make PLATFORM=<platform_subdir> O=<build_directory> make PLATFORM=<platform_subdir> O=<build_directory>
``` ```
To install *libsbi, headers, libplatsbi, and firmwares*, run: The platform specific library *libplatsbi.a* will be generated in the
*build/platform/<platform_sub_dir>/lib* directory. The platform firmware files
will be under the *build/platform/<platform_sub_dir>/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 make PLATFORM=<platform_subdir> install
or ```
This will copy the compiled platform specific libraries and firmware files
under the *install/platform/<platform_sub_dir>/* directory. An alternate
install root directory path can be specified as follows.
```
make PLATFORM=<platform_subdir> I=<install_directory> install make PLATFORM=<platform_subdir> I=<install_directory> install
``` ```
In addition, platform specific make command-line options to top-level make In addition, platform specific configuration options can be specified with the
, such as *PLATFORM_<xyz>* or *FW_<abc>* can also be specified. These top-level make command line. These options, such as *PLATFORM_<xyz>* or
options are described under *`docs/platform/<platform_name>.md`* and *FW_<abc>*, are platform specific and described in more details in the
*`docs/firmware/<firmware_name>.md`*. *docs/platform/<platform_name>.md* files and
*docs/firmware/<firmware_name>.md* files.
License License
------------- -------
The software is provided under a BSD-2-Clause license. Contributions to this
project are accepted under the same license with developer sign-off as
described in the [Contributing Guidelines](docs/contributing.md).
This project also contains code from other projects as listed below. The original OpenSBI is distributed under the terms of the BSD 2-clause license
license text is included in those source files. ("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].
1. The libfdt source code is disjunctively dual licensed (GPL-2.0+ OR BSD-2-Clause). It is All source files in OpenSBI contain the 2-Clause BSD license SPDX short
used by this project under the terms of the BSD-2-Clause license. Any contributions to indentifier in place of the full license text.
this code must be made under the terms of both licenses.
```
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.
1. The libfdt source code is disjunctively dual licensed
(GPL-2.0+ OR BSD-2-Clause). Some of this project code is used in OpenSBI
under the terms of the BSD 2-Clause license. Any contributions to this
code must be made under the terms of both licenses.
Contributing to OpenSBI
-----------------------
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.
Documentation Documentation
------------- -------------
A more detailed documentation is under the *docs* directory and organized Detailed documentation of various aspects of OpenSBI can be found under the
as follows. *docs* directory. The documentation covers the following topics.
* *`docs/contributing.md`* - Guidelines for contributing to OpenSBI project * [Contribution Guideline]: Guideline for contributing code to OpenSBI project
* *`docs/platform_guide.md`* - Guidelines for adding new platform support * [Platform Support Guide]: Guideline for implementing support for new platforms
* *`docs/library_usage.md`* - Guidelines for using the static library * [Library Usage]: API documentation of OpenSBI static library *libsbi.a*
* *`docs/platform/<platform_name>.md`* - Documentation for the platform *<platform_name>* * [Platform Documentation]: Documentation of the platforms currently supported.
* *`docs/firmware/<firmware_name>.md`* - Documentation for the firmware *<firmware_name>* * [Firmware Documentation]: Documentation for the different types of firmware
build supported by OpenSBI.
The source code is also well documented. For source level documentation, OpenSBI source code is also well documented. For source level documentation,
doxygen style is used. Please refer to [Doxygen manual] for details on this doxygen style is used. Please refer to [Doxygen manual] for details on this
format. format.
[Doxygen manual]: http://www.stack.nl/~dimitri/doxygen/manual.html Doxygen can be installed on Linux distributions using *.deb* packages using
the following command.
The Doxygen can be installed on your debian build system using following:
``` ```
sudo apt-get install doxygen doxygen-latex doxygen-doc doxygen-gui graphviz sudo apt-get install doxygen doxygen-latex doxygen-doc doxygen-gui graphviz
``` ```
To build a consolidated `refman.pdf` of all documentation, run: 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 make docs
```
or or
```
make O=<build_directory> docs make O=<build_directory> docs
``` ```
**NOTE:** `refman.pdf` will be available under `<build_directory>/docs/latex`. the resulting *refman.pdf* will be available under the directory
*<build_directory>/docs/latex*. To install this file, run:
To install a consolidated `refman.pdf` of all documentation, run:
``` ```
make install_docs make install_docs
```
or or
```
make I=<install_directory> install_docs make I=<install_directory> install_docs
``` ```
**NOTE:** `refman.pdf` will be installed under `<install_directory>/docs`. *refman.pdf* will be installed under *<install_directory>/docs*.
[Github]: https://github.com/riscv/riscv-sbi-doc
[COPYING.BSD]: COPYING.BSD
[SPDX]: http://spdx.org/licenses/
[Contribution Guideline]: docs/contributing.md
[Platform Support Guide]: docs/platform_guide.md
[Library Usage]: docs/library_usage.md
[Platform Documentation]: docs/platform/platform.md
[Firmware Documentation]: docs/firmware/fw.md
[Doxygen manual]: http://www.stack.nl/~dimitri/doxygen/manual.html