From fba7e7c3eaef7f256063fea3cfda829ccf75eab4 Mon Sep 17 00:00:00 2001 From: Damien Le Moal Date: Wed, 23 Jan 2019 15:14:13 +0900 Subject: [PATCH] docs: README.md update Reformat to fit lines within 80 chars, fix hyperlinks, etc. Signed-off-by: Damien Le Moal --- README.md | 198 +++++++++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 131 insertions(+), 67 deletions(-) diff --git a/README.md b/README.md index f63f202..36f4039 100644 --- a/README.md +++ b/README.md @@ -1,138 +1,202 @@ RISC-V Open Source Supervisor Binary Interface (OpenSBI) ======================================================== -The **RISC-V Supervisor Binary Interface (SBI)** is a recommended -interface between: +The **RISC-V Supervisor Binary Interface (SBI)** is a recommended interface +between: -1. A platform specific firmware (M-mode) and a general purpose - OS or hypervisor or bootloader (S-mode or HS-mode). -2. A hypervisor (HS-mode) and a general purpose OS or bootloader (VS-mode) +1. A platform specific firmware running in M-mode and a general purpose OS, + hypervisor or bootloader running in S-mode or HS-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 -by the RISC-V Foundation in [Github](https://github.com/riscv/riscv-sbi-doc) +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 components: +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: 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 3. *firmwares* - Platform specific bootable firmware binaries -Building and Installing generic *libsbi.a* ------------------------------------------- +Building and Installing the generic OpenSBI static library +---------------------------------------------------------- + +*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 toolchain executable name prefix, e.g. -*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: ``` make ``` -All compiled binaries will be placed in the *build* directory. -To specify an alternate build directory target, run: +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= ``` -To generate files to be installed for using *libsbi.a* in other projects, -run: +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 -and binary files under it. To specify an alternate installation directory, -run: +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 ``` -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 -*`PLATFORM=`* argument is specified on make command lines. -*``* must specify the path to one of the leaf directories -under the *`platform`* directory. For example, to compile the library and -firmware for QEMU RISC-V *virt* machine, *``* -should be *`qemu/virt`*. +The platform specific *libplatsbi.a* static library and the platform firmwares +are only built if the *PLATFORM=* argument is specified on +the make command line. ** 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, ** 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= -or +``` + +An alternate build directory path can also be specified. +``` make PLATFORM= O= ``` -To install *libsbi, headers, libplatsbi, and firmwares*, run: +The platform specific library *libplatsbi.a* will be generated in the +*build/platform//lib* directory. The platform firmware files +will be under the *build/platform//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= install -or +``` + +This will copy the compiled platform specific libraries and firmware files +under the *install/platform//* directory. An alternate +install root directory path can be specified as follows. +``` make PLATFORM= I= install ``` -In addition, platform specific make command-line options to top-level make -, such as *PLATFORM_* or *FW_* can also be specified. These -options are described under *`docs/platform/.md`* and -*`docs/firmware/.md`*. +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/.md* files and +*docs/firmware/.md* files. 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). +------- + +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. -This project also contains code from other projects as listed below. The original -license text is included in those source files. +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. -1. The libfdt source code is disjunctively dual licensed (GPL-2.0+ OR BSD-2-Clause). It is - used by this project 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 ------------- -A more detailed documentation is under the *docs* directory and organized -as follows. +Detailed documentation of various aspects of OpenSBI can be found under the +*docs* directory. The documentation covers the following topics. -* *`docs/contributing.md`* - Guidelines for contributing to OpenSBI project -* *`docs/platform_guide.md`* - Guidelines for adding new platform support -* *`docs/library_usage.md`* - Guidelines for using the static library -* *`docs/platform/.md`* - Documentation for the platform ** -* *`docs/firmware/.md`* - Documentation for the firmware ** +* [Contribution Guideline]: Guideline for contributing code to OpenSBI project +* [Platform Support Guide]: Guideline for implementing support for new platforms +* [Library Usage]: API documentation of OpenSBI static library *libsbi.a* +* [Platform Documentation]: Documentation of the platforms currently supported. +* [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 format. -[Doxygen manual]: http://www.stack.nl/~dimitri/doxygen/manual.html - -The Doxygen can be installed on your debian build system using following: +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 ``` -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 +``` or +``` make O= docs ``` -**NOTE:** `refman.pdf` will be available under `/docs/latex`. - -To install a consolidated `refman.pdf` of all documentation, run: +the resulting *refman.pdf* will be available under the directory +*/docs/latex*. To install this file, run: ``` make install_docs +``` or +``` make I= install_docs ``` -**NOTE:** `refman.pdf` will be installed under `/docs`. +*refman.pdf* will be installed under */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 + -- 2.7.4