From 0d33a981ec19181c7f6448f90599f31dfd082994 Mon Sep 17 00:00:00 2001 From: Karsten Merker Date: Sun, 5 May 2019 12:33:25 +0200 Subject: docs: miscellaneous documentation fixes and updates - fix some broken hyperlinks - add additional hyperlinks to references to external documents - reformat some paragraphs to keep lines under 80 characters - unify the enumeration style between different parts of the documentation - fix spelling/grammar mistakes - extend the copyright notice in README.md to be the same as the one in COPYING.BSD Signed-off-by: Karsten Merker Reviewed-by: Atish Patra --- README.md | 103 ++++++++++++++++++++++++++++++++------------------------------ 1 file changed, 53 insertions(+), 50 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 7b5b225..1f62048 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,5 @@ -Copyright (c) 2019 Western Digital Corporation or its affiliates. +Copyright (c) 2019 Western Digital Corporation or its affiliates +and other contributors. RISC-V Open Source Supervisor Binary Interface (OpenSBI) ======================================================== @@ -6,53 +7,55 @@ RISC-V Open Source Supervisor Binary Interface (OpenSBI) The **RISC-V Supervisor Binary Interface (SBI)** is the recommended interface between: -1. A platform specific firmware running in M-mode and bootloader, hypervisor or - a general purpose OS executing in S-mode or HS-mode. -2. A hypervisor running in HS-mode and a bootloader or a general purpose OS +1. A platform-specific firmware running in M-mode and a bootloader, a + hypervisor or a general-purpose OS executing in S-mode or HS-mode. +2. A hypervisor running in HS-mode and a bootloader or a general-purpose OS executing in VS-mode. The *RISC-V SBI specification* is maintained as an independent project by the -RISC-V Foundation in [Github]. +RISC-V Foundation on [Github] (https://github.com/riscv/riscv-sbi-doc). The goal of the OpenSBI project is to provide an open-source reference -implementation of the RISC-V SBI specifications for platform specific firmwares -executing in M-mode (case 1 mentioned above). OpenSBI implementation can be +implementation of the RISC-V SBI specifications for platform-specific firmwares +executing in M-mode (case 1 mentioned above). An OpenSBI implementation can be easily extended by RISC-V platform and system-on-chip vendors to fit a particular hardware configuration. -The main component of OpenSBI is provided in the form of a platform independent +The main component of OpenSBI is provided in the form of a platform-independent static library **libsbi.a** implementing the SBI interface. A firmware or bootloader implementation can link against this library to ensure conformance with the SBI interface specifications. *libsbi.a* also defines an interface for -integrating with platform specific operations provided by the platform firmware -implementation (e.g. console access functions, inter-processor interrupts +integrating with platform-specific operations provided by the platform firmware +implementation (e.g. console access functions, inter-processor interrupt control, etc). -To illustrate the use of *libsbi.a* library, OpenSBI also provides a set of -platform specific support examples. For each example, a platform -specific static library *libplatsbi.a* can be compiled. This library implements -SBI calls processing by integrating *libsbi.a* with necessary platform dependent -hardware manipulation functions. For all supported platforms, OpenSBI also -provides several runtime firmware examples built using the platform +To illustrate the use of the *libsbi.a* library, OpenSBI also provides a set of +platform-specific support examples. For each example, a platform-specific +static library *libplatsbi.a* can be compiled. This library implements +SBI call processing by integrating *libsbi.a* with the necessary +platform-dependent hardware manipulation functions. For all supported platforms, +OpenSBI also provides several runtime firmware examples built using the platform *libplatsbi.a*. These example firmwares can be used to replace the legacy -*riskv-pk* bootloader (aka BBL) and enable the use of well known bootloaders -such as [U-Boot]. +*riscv-pk* bootloader (aka BBL) and enable the use of well-known bootloaders +such as [U-Boot] (https://git.denx.de/u-boot.git). Required Toolchain ------------------ OpenSBI can be compiled natively or cross-compiled on a x86 host. For -cross-compilation, you can build your tool chain or just download from -the [bootlin] (https://toolchains.bootlin.com/). +cross-compilation, you can build your own toolchain or just download +a prebuilt one from the +[Bootlin toolchain repository] (https://toolchains.bootlin.com/). -Please note that only 64bit version of toolchain is available in bootlin -for now. +Please note that only a 64bit version of the toolchain is available in +the Bootlin toolchain repository for now. -Building and Installing OpenSBI Platform Independent Library ------------------------------------------------------------- +Building and Installing the OpenSBI Platform-Independent Library +---------------------------------------------------------------- -OpenSBI platform independent static library *libsbi.a* can be natively compiled -or cross-compiled on a host with a different base architecture than RISC-V. +The OpenSBI platform-independent static library *libsbi.a* can be compiled +natively or it can be 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. @@ -63,8 +66,8 @@ To build *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 +All compiled binaries as well as the resulting *libsbi.a* static library file +will be placed in the *build/lib* directory. To specify an alternate build root directory path, run: ``` make O= @@ -76,38 +79,38 @@ 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: +copied under the *install/include* directory and the library file copied into +the *install/lib* directory. To specify an alternate installation root +directory path, run: ``` make I= install ``` -Building and Installing a Reference Platform Static Library and Firmwares -------------------------------------------------------------------------- +Building and Installing a Reference Platform Static Library and Firmware +------------------------------------------------------------------------ When the *PLATFORM=* argument is specified on the make command -line, the platform specific static library *libplatsbi.a* and firmware examples +line, the platform-specific static library *libplatsbi.a* and firmware examples are built for the platform ** present in the directory -*platform* in OpenSBI top directory. For example, to compile the platform -library and firmware examples for QEMU RISC-V *virt* machine, +*platform* in the OpenSBI top directory. For example, to compile the platform +library and the firmware examples for the QEMU RISC-V *virt* machine, ** should be *qemu/virt*. -To build *libsbi.a*, *libplatsbi.a* and the firmwares for one of the supported -platform, run: +To build *libsbi.a*, *libplatsbi.a* and the firmware for one of the supported +platforms, run: ``` make PLATFORM= ``` -An alternate build directory path can also be specified. +An alternate build directory path can also be specified: ``` make PLATFORM= O= ``` -The platform specific library *libplatsbi.a* will be generated in the +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 +The compiled firmwares will be available in two different formats: an ELF file and an expanded image file. To install *libsbi.a*, *libplatsbi.a*, and the compiled firmwares, run: @@ -115,16 +118,16 @@ To install *libsbi.a*, *libplatsbi.a*, and the compiled firmwares, run: make PLATFORM= install ``` -This will copy the compiled platform specific libraries and firmware files +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. +install root directory path can be specified as follows: ``` make PLATFORM= I= install ``` -In addition, platform specific configuration options can be specified with the +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 +*FW_*, are platform-specific and described in more details in the *docs/platform/.md* files and *docs/firmware/.md* files. @@ -155,7 +158,7 @@ files where the reused code is present. under the terms of the BSD 2-Clause license. Any contributions to this code must be made under the terms of both licenses. 2. Some source file for the Kendryte/k210 platform code are based on code from - the Kendryte [standalone SDK] available on github. These files retain the + the [Kendryte standalone SDK] available on github. These files retain the original copyright and license of the Kendryte standalone SDK project and are licensed under the terms of the Apache License, Version 2.0. @@ -165,7 +168,7 @@ Contributing to OpenSBI ----------------------- The OpenSBI project encourages and welcomes contributions. Contributions should -follow the rules described in OpenSBI [Contribution Guideline] document. +follow the rules described in the OpenSBI [Contribution Guideline] document. In particular, all patches sent should contain a Signed-off-by tag. The [Contributors List] document provides a list of individuals and @@ -185,7 +188,7 @@ Detailed documentation of various aspects of OpenSBI can be found under the examples build supported by OpenSBI. 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 the [Doxygen manual] for details on this format. Doxygen can be installed on Linux distributions using *.deb* packages using @@ -234,6 +237,6 @@ make I= install_docs [Platform Support Guide]: docs/platform_guide.md [Platform Documentation]: docs/platform/platform.md [Firmware Documentation]: docs/firmware/fw.md -[Doxygen manual]: http://www.stack.nl/~dimitri/doxygen/manual.html -[standalone SDK]: https://github.com/kendryte/kendryte-standalone-sdk +[Doxygen manual]: http://www.doxygen.nl/manual/index.html +[Kendryte standalone SDK]: https://github.com/kendryte/kendryte-standalone-sdk [third party notices]: ThirdPartyNotices.md -- cgit v1.2.3