Просмотр исходного кода

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 <merker@debian.org>
Reviewed-by: Atish Patra <atish.patra@wdc.com>
Karsten Merker 5 лет назад
Родитель
Сommit
0d33a981ec

+ 53 - 50
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)
 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
 The **RISC-V Supervisor Binary Interface (SBI)** is the recommended interface
 between:
 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.
    executing in VS-mode.
 
 
 The *RISC-V SBI specification* is maintained as an independent project by the
 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
 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
 easily extended by RISC-V platform and system-on-chip vendors to fit a
 particular hardware configuration.
 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
 static library **libsbi.a** implementing the SBI interface. A firmware or
 bootloader implementation can link against this library to ensure conformance
 bootloader implementation can link against this library to ensure conformance
 with the SBI interface specifications. *libsbi.a* also defines an interface for
 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).
 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
 *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
 Required Toolchain
 ------------------
 ------------------
 
 
 OpenSBI can be compiled natively or cross-compiled on a x86 host. For
 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
 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.
 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
 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:
 directory path, run:
 ```
 ```
 make O=<build_directory>
 make O=<build_directory>
@@ -76,38 +79,38 @@ make install
 ```
 ```
 
 
 This will create the *install* directory with all necessary include files
 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_directory> install
 make I=<install_directory> install
 ```
 ```
 
 
-Building and Installing a Reference Platform Static Library and Firmwares
--------------------------------------------------------------------------
+Building and Installing a Reference Platform Static Library and Firmware
+------------------------------------------------------------------------
 
 
 When the *PLATFORM=<platform_subdir>* argument is specified on the make command
 When the *PLATFORM=<platform_subdir>* 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 *<platform_subdir>* present in the directory
 are built for the platform *<platform_subdir>* 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,
 *<platform_subdir>* should be *qemu/virt*.
 *<platform_subdir>* 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=<platform_subdir>
 make PLATFORM=<platform_subdir>
 ```
 ```
 
 
-An alternate build directory path can also be specified.
+An alternate build directory path can also be specified:
 ```
 ```
 make PLATFORM=<platform_subdir> O=<build_directory>
 make PLATFORM=<platform_subdir> O=<build_directory>
 ```
 ```
 
 
-The platform specific library *libplatsbi.a* will be generated in the
+The platform-specific library *libplatsbi.a* will be generated in the
 *build/platform/<platform_subdir>/lib* directory. The platform firmware files
 *build/platform/<platform_subdir>/lib* directory. The platform firmware files
 will be under the *build/platform/<platform_subdir>/firmware* directory.
 will be under the *build/platform/<platform_subdir>/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.
 and an expanded image file.
 
 
 To install *libsbi.a*, *libplatsbi.a*, and the compiled firmwares, run:
 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=<platform_subdir> install
 make PLATFORM=<platform_subdir> 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/<platform_subdir>/* directory. An alternate
 under the *install/platform/<platform_subdir>/* directory. An alternate
-install root directory path can be specified as follows.
+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 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_<xyz>* or
 top-level make command line. These options, such as *PLATFORM_<xyz>* or
-*FW_<abc>*, are platform specific and described in more details in the
+*FW_<abc>*, are platform-specific and described in more details in the
 *docs/platform/<platform_name>.md* files and
 *docs/platform/<platform_name>.md* files and
 *docs/firmware/<firmware_name>.md* files.
 *docs/firmware/<firmware_name>.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
    under the terms of the BSD 2-Clause license. Any contributions to this
    code must be made under the terms of both licenses.
    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
 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
    original copyright and license of the Kendryte standalone SDK project and
    are licensed under the terms of the Apache License, Version 2.0.
    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
 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.
 In particular, all patches sent should contain a Signed-off-by tag.
 
 
 The [Contributors List] document provides a list of individuals and
 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.
   examples build supported by OpenSBI.
 
 
 OpenSBI 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 the [Doxygen manual] for details on this
 format.
 format.
 
 
 Doxygen can be installed on Linux distributions using *.deb* packages using
 Doxygen can be installed on Linux distributions using *.deb* packages using
@@ -234,6 +237,6 @@ make I=<install_directory> install_docs
 [Platform Support Guide]: docs/platform_guide.md
 [Platform Support Guide]: docs/platform_guide.md
 [Platform Documentation]: docs/platform/platform.md
 [Platform Documentation]: docs/platform/platform.md
 [Firmware Documentation]: docs/firmware/fw.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
 [third party notices]: ThirdPartyNotices.md

+ 12 - 11
docs/contributing.md

@@ -1,19 +1,20 @@
 OpenSBI Contribution Guideline
 OpenSBI Contribution Guideline
 ==============================
 ==============================
 
 
-All contributions to OpenSBI can be sent in following ways:
-1. Email patches to OpenSBI mailing list `opensbi@lists.infradead.org`
-2. GitHub Pull Requests (PRs) to [OpenSBI main repository]
+All contributions to OpenSBI can be sent in the following ways:
+1. Email patches to the OpenSBI mailing list at `opensbi@lists.infradead.org`
+2. GitHub Pull Requests (PRs) to the [OpenSBI main repository]
 
 
-To join OpenSBI mailing list, please visit [OpenSBI infradead page].
+To join the OpenSBI mailing list, please visit the [OpenSBI infradead page].
 
 
-OpenSBI maintainers prefer patches via OpenSBI mailing list (option1 above)
-so that they are visible to wider audience. All accepted patches on the
-OpenSBI mailing list will be taken by any of the OpenSBI maintainers and
-merged into [OpenSBI main repository] using GitHub PRs.
+The OpenSBI maintainers prefer patches via the OpenSBI mailing list
+(option 1 above) so that they are visible to a wider audience. All
+accepted patches on the OpenSBI mailing list will be taken by any of
+the OpenSBI maintainers and merged into the [OpenSBI main repository]
+using GitHub PRs.
 
 
 All contributed work must follow the following rules:
 All contributed work must follow the following rules:
-1. OpenSBI code should be written in accordance to [Linux coding style].
+1. OpenSBI code should be written in accordance to the [Linux coding style].
 2. This project embraces the [Developer Certificate of Origin (DCO)] for
 2. This project embraces the [Developer Certificate of Origin (DCO)] for
 contributions. This means that you must agree to the following prior to
 contributions. This means that you must agree to the following prior to
 submitting patches: if you agree with this developer certificate you
 submitting patches: if you agree with this developer certificate you
@@ -27,9 +28,9 @@ prefixes are for example "lib:", "platform:", "firmware:", "docs:" and "top:".
 5. Maintainers should use "Rebase and Merge" when using GitHub to merge pull
 5. Maintainers should use "Rebase and Merge" when using GitHub to merge pull
 requests to avoid creating unnecessary merge commits.
 requests to avoid creating unnecessary merge commits.
 6. Maintainers should avoid creating branches directly in the main
 6. Maintainers should avoid creating branches directly in the main
-riscv/opensbi repository. Instead prefer using a fork of riscv/opensbi main
+riscv/opensbi repository. Instead prefer using a fork of the riscv/opensbi main
 repository and branches within that fork to create pull requests.
 repository and branches within that fork to create pull requests.
-7. A maintainer cannot merge his own pull requests in riscv/opensbi main
+7. A maintainer cannot merge his own pull requests in the riscv/opensbi main
 repository.
 repository.
 8. A pull request must get at least one review from a maintainer.
 8. A pull request must get at least one review from a maintainer.
 9. A pull request must spend at least 24 hours in review to allow for other
 9. A pull request must spend at least 24 hours in review to allow for other

+ 1 - 1
docs/doxygen.cfg

@@ -44,7 +44,7 @@ PROJECT_NUMBER         = "v@@OPENSBI_MAJOR@@.@@OPENSBI_MINOR@@"
 # for a project that appears at the top of each page and should give viewer a
 # for a project that appears at the top of each page and should give viewer a
 # quick idea about the purpose of the project. Keep the description short.
 # quick idea about the purpose of the project. Keep the description short.
 
 
-PROJECT_BRIEF          = "Open source implemenation of supervisor binary interface"
+PROJECT_BRIEF          = "Open source implemenation of the supervisor binary interface"
 
 
 # With the PROJECT_LOGO tag one can specify a logo or an icon that is included
 # With the PROJECT_LOGO tag one can specify a logo or an icon that is included
 # in the documentation. The maximum height of the logo should not exceed 55
 # in the documentation. The maximum height of the logo should not exceed 55

+ 11 - 11
docs/firmware/fw_jump.md

@@ -6,19 +6,19 @@ handles the address of the next booting stage entry, e.g. a bootloader or an OS
 kernel, without directly including the binary code for this next stage.
 kernel, without directly including the binary code for this next stage.
 
 
 A *FW_JUMP* firmware is particularly useful when the booting stage executed
 A *FW_JUMP* firmware is particularly useful when the booting stage executed
-prior to OpenSBI firmware is capable of loading both the OpenSBI firmware and
-the booting stage binary to follow OpenSBI firmware.
+prior to the OpenSBI firmware is capable of loading both the OpenSBI firmware
+and the booting stage binary to follow the OpenSBI firmware.
 
 
 *FW_JUMP* Compilation
 *FW_JUMP* Compilation
 ---------------------
 ---------------------
 
 
-A platform *FW_JUMP* firmware can be enabled by any of the following methods.
+A platform *FW_JUMP* firmware can be enabled by any of the following methods:
 
 
 1. Specifying `FW_JUMP=y` on the top level `make` command line.
 1. Specifying `FW_JUMP=y` on the top level `make` command line.
 2. Specifying `FW_JUMP=y` in the target platform *config.mk* configuration file.
 2. Specifying `FW_JUMP=y` in the target platform *config.mk* configuration file.
 
 
 The compiled *FW_JUMP* firmware ELF file is named *fw_jump.elf*. Its expanded
 The compiled *FW_JUMP* firmware ELF file is named *fw_jump.elf*. Its expanded
-image file is *fw_jump.bin*. Both files are created in the platform specific
+image file is *fw_jump.bin*. Both files are created in the platform-specific
 build directory under the *build/platform/<platform_subdir>/firmware* directory.
 build directory under the *build/platform/<platform_subdir>/firmware* directory.
 
 
 *FW_JUMP* Firmware Configuration Options
 *FW_JUMP* Firmware Configuration Options
@@ -27,26 +27,26 @@ build directory under the *build/platform/<platform_subdir>/firmware* directory.
 To operate correctly, a *FW_JUMP* firmware requires some configuration
 To operate correctly, a *FW_JUMP* firmware requires some configuration
 parameters to be defined using either the top level `make` command line or the
 parameters to be defined using either the top level `make` command line or the
 target platform *config.mk* configuration file. The possible parameters are as
 target platform *config.mk* configuration file. The possible parameters are as
-follows.
+follows:
 
 
 * **FW_JUMP_ADDR** - Address of the entry point of the booting stage to be
 * **FW_JUMP_ADDR** - Address of the entry point of the booting stage to be
-  executed following OpenSBI firmware. This address generally correspond
+  executed following OpenSBI firmware. This address generally corresponds
   exactly to the address where this next booting stage was loaded. This is a
   exactly to the address where this next booting stage was loaded. This is a
   mandatory parameter. Compilation errors will result from not defining this
   mandatory parameter. Compilation errors will result from not defining this
   address.
   address.
 
 
 * **FW_JUMP_FDT_ADDR** - Address where the *flattened device tree (FDT file)*
 * **FW_JUMP_FDT_ADDR** - Address where the *flattened device tree (FDT file)*
   passed by the prior booting stage will be placed in memory before executing
   passed by the prior booting stage will be placed in memory before executing
-  the booting stage following OpenSBI firmware. If this option is not provided,
-  then OpenSBI firmware will pass zero as the FDT address to the following
-  booting stage.
+  the booting stage following the OpenSBI firmware. If this option is not
+  provided, then the OpenSBI firmware will pass zero as the FDT address to the
+  following booting stage.
 
 
 *FW_JUMP* Example
 *FW_JUMP* Example
 -----------------
 -----------------
 
 
-The *[qemu/virt]* and *[qemu/sifive_u]* platforms illustrates how to configure
+The *[qemu/virt]* and *[qemu/sifive_u]* platforms illustrate how to configure
 and use a *FW_JUMP* firmware. Detailed information regarding these platforms
 and use a *FW_JUMP* firmware. Detailed information regarding these platforms
-can be found in the platforms documentation files.
+can be found in the platform documentation files.
 
 
 [qemu/virt]: ../platform/qemu_virt.md
 [qemu/virt]: ../platform/qemu_virt.md
 [qemu/sifive_u]: ../platform/qemu_sifive_u.md
 [qemu/sifive_u]: ../platform/qemu_sifive_u.md

+ 15 - 16
docs/firmware/fw_payload.md

@@ -2,22 +2,22 @@ OpenSBI Firmware with Payload *FW_PAYLOAD*
 ==========================================
 ==========================================
 
 
 OpenSBI **firmware with Payload (FW_PAYLOAD)** is a firmware which directly
 OpenSBI **firmware with Payload (FW_PAYLOAD)** is a firmware which directly
-includes the binary for the booting stage to follow OpenSBI firmware execution.
-Typically, this payload will be a bootloader or an OS kernel.
+includes the binary for the booting stage to follow the OpenSBI firmware
+execution. Typically, this payload will be a bootloader or an OS kernel.
 
 
 A *FW_PAYLOAD* firmware is particularly useful when the booting stage executed
 A *FW_PAYLOAD* firmware is particularly useful when the booting stage executed
-prior to OpenSBI firmware is not capable of loading both OpenSBI firmware and
-the booting stage to follow OpenSBI firmware.
+prior to the OpenSBI firmware is not capable of loading both the OpenSBI
+firmware and the booting stage to follow OpenSBI firmware.
 
 
 A *FW_PAYLOAD* firmware is also useful for cases where the booting stage prior
 A *FW_PAYLOAD* firmware is also useful for cases where the booting stage prior
-to OpenSBI firmware does not pass a *flattened device tree (FDT file)*. In such
-case, a *FW_PAYLOAD* firmware allows embedding a flattened device tree in the
-.text section of the final firmware.
+to the OpenSBI firmware does not pass a *flattened device tree (FDT file)*. In
+such a case, a *FW_PAYLOAD* firmware allows embedding a flattened device tree
+in the .text section of the final firmware.
 
 
 Enabling *FW_PAYLOAD* compilation
 Enabling *FW_PAYLOAD* compilation
 ---------------------------------
 ---------------------------------
 
 
-The *FW_PAYLOAD* firmware can be enabled by any of the following methods.
+The *FW_PAYLOAD* firmware can be enabled by any of the following methods:
 
 
 1. Specifying `FW_PAYLOAD=y` on the top level `make` command line.
 1. Specifying `FW_PAYLOAD=y` on the top level `make` command line.
 2. Specifying `FW_PAYLOAD=y` in the target platform *config.mk* configuration
 2. Specifying `FW_PAYLOAD=y` in the target platform *config.mk* configuration
@@ -25,7 +25,7 @@ The *FW_PAYLOAD* firmware can be enabled by any of the following methods.
 
 
 The compiled *FW_PAYLOAD* firmware ELF file is named *fw_jump.elf*. Its
 The compiled *FW_PAYLOAD* firmware ELF file is named *fw_jump.elf*. Its
 expanded image file is *fw_payload.bin*. Both files are created in the
 expanded image file is *fw_payload.bin*. Both files are created in the
-platform specific build directory under the
+platform-specific build directory under the
 *build/platform/<platform_subdir>/firmware* directory.
 *build/platform/<platform_subdir>/firmware* directory.
 
 
 Configuration Options
 Configuration Options
@@ -34,7 +34,7 @@ Configuration Options
 A *FW_PAYLOAD* firmware is built according to configuration parameters and
 A *FW_PAYLOAD* firmware is built according to configuration parameters and
 options. These configuration parameters can be defined using either the top
 options. These configuration parameters can be defined using either the top
 level `make` command line or the target platform *config.mk* configuration
 level `make` command line or the target platform *config.mk* configuration
-file. The parameters currently defined are as   follows.
+file. The parameters currently defined are as follows:
 
 
 * **FW_PAYLOAD_OFFSET** - Offset from *FW_TEXT_BASE* where the payload binary
 * **FW_PAYLOAD_OFFSET** - Offset from *FW_TEXT_BASE* where the payload binary
   will be linked in the final *FW_PAYLOAD* firmware binary image. This
   will be linked in the final *FW_PAYLOAD* firmware binary image. This
@@ -47,8 +47,8 @@ file. The parameters currently defined are as   follows.
   will be linked after the end of the base firmware binary in the final
   will be linked after the end of the base firmware binary in the final
   *FW_PAYLOAD* firmware binary image. This configuration parameter is mandatory
   *FW_PAYLOAD* firmware binary image. This configuration parameter is mandatory
   if *FW_PAYLOAD_OFFSET* is not defined. If both *FW_PAYLOAD_OFFSET* and
   if *FW_PAYLOAD_OFFSET* is not defined. If both *FW_PAYLOAD_OFFSET* and
-  *FW_PAYLOAD_ALIGN* are defined, *FW_PAYLOAD_OFFSET* is used and 
-  *FW_PAYLOAD_ALIGN* ignored.
+  *FW_PAYLOAD_ALIGN* are defined, *FW_PAYLOAD_OFFSET* is used and
+  *FW_PAYLOAD_ALIGN* is ignored.
 
 
 * **FW_PAYLOAD_PATH** - Path to the image file of the next booting stage
 * **FW_PAYLOAD_PATH** - Path to the image file of the next booting stage
   binary.  If this option is not provided then a simple test payload is
   binary.  If this option is not provided then a simple test payload is
@@ -78,13 +78,12 @@ file. The parameters currently defined are as   follows.
 *FW_PAYLOAD* Example
 *FW_PAYLOAD* Example
 --------------------
 --------------------
 
 
-The *[qemu/virt]* and *[qemu/sifive_u]* platforms illustrates how to configure
+The *[qemu/virt]* and *[qemu/sifive_u]* platforms illustrate how to configure
 and use a *FW_PAYLOAD* firmware. Detailed information regarding these platforms
 and use a *FW_PAYLOAD* firmware. Detailed information regarding these platforms
-can be found in the platforms documentation files.
+can be found in the platform documentation files.
 
 
-The *kendryte/k210* platform also enables build of a *FW_PAYLOAD* using an
+The *kendryte/k210* platform also enables a build of a *FW_PAYLOAD* using an
 internally defined device tree file (*FW_PAYLOAD_FDT*).
 internally defined device tree file (*FW_PAYLOAD_FDT*).
 
 
 [qemu/virt]: ../platform/qemu_virt.md
 [qemu/virt]: ../platform/qemu_virt.md
 [qemu/sifive_u]: ../platform/qemu_sifive_u.md
 [qemu/sifive_u]: ../platform/qemu_sifive_u.md
-

+ 4 - 5
docs/firmware/payload_linux.md

@@ -1,11 +1,10 @@
 Linux as a direct payload to OpenSBI
 Linux as a direct payload to OpenSBI
 ====================================
 ====================================
 
 
-OpenSBI has the capability to load Linux kernel image directly in supervisor
+OpenSBI has the capability to load a Linux kernel image directly in supervisor
 mode. The flattened image generated by the Linux kernel build process can be
 mode. The flattened image generated by the Linux kernel build process can be
-provided as payload to OpenSBI.
+provided as a payload to OpenSBI.
 
 
-Detailed examples and platform guides can be found in both [QEMU](
-../platform/qemu_virt.md) and [HiFive Unleashed](../platform/sifive_fu540.md)
-platform guide respectively.
+Detailed examples can be found in both the [QEMU](../platform/qemu_virt.md)
+and the [HiFive Unleashed](../platform/sifive_fu540.md) platform guides.
 
 

+ 9 - 7
docs/firmware/payload_uboot.md

@@ -4,30 +4,32 @@ U-Boot as a payload to OpenSBI
 [U-Boot](https://www.denx.de/wiki/U-Boot) is an open-source primary boot loader.
 [U-Boot](https://www.denx.de/wiki/U-Boot) is an open-source primary boot loader.
 It can be used as first and/or second stage boot loader in an embedded
 It can be used as first and/or second stage boot loader in an embedded
 environment. In the context of OpenSBI, U-Boot can be specified as a payload to
 environment. In the context of OpenSBI, U-Boot can be specified as a payload to
-OpenSBI firmware, becoming the boot stage following OpenSBI firmware
+the OpenSBI firmware, becoming the boot stage following the OpenSBI firmware
 execution.
 execution.
 
 
 The current stable upstream code of U-Boot does not yet include all patches
 The current stable upstream code of U-Boot does not yet include all patches
 necessary to fully support OpenSBI. To use U-Boot as an OpenSBI payload, the
 necessary to fully support OpenSBI. To use U-Boot as an OpenSBI payload, the
 following out-of-tree patch series must be applied to the upstream U-Boot source
 following out-of-tree patch series must be applied to the upstream U-Boot source
-code.
+code:
 
 
 HiFive Unleashed support for U-Boot
 HiFive Unleashed support for U-Boot
 
 
 https://lists.denx.de/pipermail/u-boot/2019-February/358058.html
 https://lists.denx.de/pipermail/u-boot/2019-February/358058.html
 
 
 This patch series enables a single CPU to execute U-Boot. As a result, the next
 This patch series enables a single CPU to execute U-Boot. As a result, the next
-stage boot code such as Linux kernel can also only execute a single CPU. U-Boot
-SMP support for RISC-V can be enabled with the following additional patches.
+stage boot code such as a Linux kernel can also only execute on a single CPU.
+U-Boot SMP support for RISC-V can be enabled with the following additional
+patches:
 
 
 https://lists.denx.de/pipermail/u-boot/2019-February/358393.html
 https://lists.denx.de/pipermail/u-boot/2019-February/358393.html
 
 
 Building and Generating U-Boot images
 Building and Generating U-Boot images
 =====================================
 =====================================
-Please refer to U-Boot build documentation for detailed instructions on how to build U-Boot images.
+Please refer to the U-Boot build documentation for detailed instructions on
+how to build U-Boot images.
 
 
-Once U-Boot images are built, Linux kernel image need to be converted to a format
-that U-Boot understands.
+Once U-Boot images are built, the Linux kernel image needs to be converted
+into a format that U-Boot understands:
 
 
 ```
 ```
 <uboot-dir>/tools/mkimage -A riscv -O linux -T kernel -C none -a 0x80200000 -e 0x80200000 -n Linux -d \
 <uboot-dir>/tools/mkimage -A riscv -O linux -T kernel -C none -a 0x80200000 -e 0x80200000 -n Linux -d \

+ 16 - 17
docs/library_usage.md

@@ -3,46 +3,46 @@ OpenSBI Library Usage
 
 
 OpenSBI provides two types of static libraries:
 OpenSBI provides two types of static libraries:
 
 
-1. *libsbi.a* - A platform independent generic static library implementing the
-   interface defined by the SBI specifications. Platform specific processing
+1. *libsbi.a* - A platform-independent generic static library implementing the
+   interface defined by the SBI specifications. Platform-specific processing
    hooks for the execution of this interface must be provided by the firmware or
    hooks for the execution of this interface must be provided by the firmware or
    bootloader linking with this library. This library is installed as
    bootloader linking with this library. This library is installed as
    *<install_directory>/lib/libsbi.a*
    *<install_directory>/lib/libsbi.a*
-2. *libplatsbi.a* - An example platform specific static library integrating 
-   *libsbi.a* with platform specific hooks. This library is available only for
+2. *libplatsbi.a* - An example platform-specific static library integrating
+   *libsbi.a* with platform-specific hooks. This library is available only for
    the platforms supported by OpenSBI. This library is installed as
    the platforms supported by OpenSBI. This library is installed as
    *<install_directory>/platform/<platform_subdir>/lib/libplatsbi.a*
    *<install_directory>/platform/<platform_subdir>/lib/libplatsbi.a*
 
 
 Implementations may choose either *libsbi.a* or *libplatsbi.a* to link with
 Implementations may choose either *libsbi.a* or *libplatsbi.a* to link with
-their firmware or bootloader. In the case of *libsbi.a*, platform specific
-hooks in the form of a *struct sbi_platform* instance needs to be provided.
+their firmware or bootloader. In the case of *libsbi.a*, platform-specific
+hooks in the form of a *struct sbi_platform* instance need to be provided.
 
 
-The platform specific example firmwares provided by OpenSBI are not mandatory.
-An implementation may choose to link OpenSBI generic static library together
-with an M-mode firmware or bootloader providing hardware specific hooks. Since
-OpenSBI is a statically linked library, users must ensure that the license of
-these external components is compatible with OpenSBI license.
+The platform-specific example firmwares provided by OpenSBI are not mandatory.
+An implementation may choose to link the OpenSBI generic static library together
+with an M-mode firmware or bootloader providing the hardware-specific hooks.
+Since OpenSBI is a statically linked library, users must ensure that the
+license of these external components is compatible with the OpenSBI license.
 
 
 Constraints on OpenSBI usage from external firmware
 Constraints on OpenSBI usage from external firmware
 ---------------------------------------------------
 ---------------------------------------------------
 
 
 Users have to ensure that an external firmware or bootloader linking against
 Users have to ensure that an external firmware or bootloader linking against
-OpenSBI static libraries (*libsbi.a* or *libplatsbi.a*) are compiled with the
+OpenSBI static libraries (*libsbi.a* or *libplatsbi.a*) is compiled with the
 same GCC target options *-mabi*, *-march*, and *-mcmodel*.
 same GCC target options *-mabi*, *-march*, and *-mcmodel*.
 
 
 There are only two constraints on calling any OpenSBI library function from an
 There are only two constraints on calling any OpenSBI library function from an
 external M-mode firmware or bootloader:
 external M-mode firmware or bootloader:
 
 
 1. The RISC-V *MSCRATCH* CSR must point to a valid OpenSBI scratch space
 1. The RISC-V *MSCRATCH* CSR must point to a valid OpenSBI scratch space
-   (i.e. *struct sbi_scratch* instance)
-2. The RISC-V *SP* register (i.e. stack pointer) must be set per-HART
-   pointing to distinct non-overlapping stacks
+   (i.e. a *struct sbi_scratch* instance).
+2. The RISC-V *SP* register (i.e. the stack pointer) must be set per-HART
+   pointing to distinct non-overlapping stacks.
 
 
 The most important functions from an external firmware or bootloader
 The most important functions from an external firmware or bootloader
 perspective are *sbi_init()* and *sbi_trap_handler()*.
 perspective are *sbi_init()* and *sbi_trap_handler()*.
 
 
 In addition to the above constraints, the external firmware or bootloader must
 In addition to the above constraints, the external firmware or bootloader must
-ensure that interrupts are disabled in *MSTATUS* and *MIE* CSRs when calling
+ensure that interrupts are disabled in the *MSTATUS* and *MIE* CSRs when calling
 the functions *sbi_init()* and *sbi_trap_handler()*.
 the functions *sbi_init()* and *sbi_trap_handler()*.
 
 
 The *sbi_init()* function should be called by the external firmware or
 The *sbi_init()* function should be called by the external firmware or
@@ -62,4 +62,3 @@ bootloader to service the following interrupts and traps:
 
 
 **Note:** external firmwares or bootloaders can be more conservative by
 **Note:** external firmwares or bootloaders can be more conservative by
 forwarding all traps and interrupts to *sbi_trap_handler()*.
 forwarding all traps and interrupts to *sbi_trap_handler()*.
-

+ 9 - 7
docs/platform/platform.md

@@ -1,11 +1,12 @@
 OpenSBI Supported Platforms
 OpenSBI Supported Platforms
 ===========================
 ===========================
 
 
-OpenSBI currently supports the following virtual and hardware platforms.
+OpenSBI currently supports the following virtual and hardware platforms:
 
 
-* **QEMU RISC-V Virt Machine**: Platform support for QEMU *virt* virtual RISC-V
-  machine. This virtual machine is intended for RISC-V software development and
-  test. More details on this platform can be found in the file *[qemu_virt.md]*.
+* **QEMU RISC-V Virt Machine**: Platform support for the QEMU *virt* virtual
+  RISC-V machine. This virtual machine is intended for RISC-V software
+  development and tests. More details on this platform can be found in the
+  file *[qemu_virt.md]*.
 
 
 * **QEMU SiFive Unleashed Machine**: Platform support for the *sifive_u* QEMU
 * **QEMU SiFive Unleashed Machine**: Platform support for the *sifive_u* QEMU
   virtual RISC-V machine. This is an emulation machine of the HiFive Unleashed
   virtual RISC-V machine. This is an emulation machine of the HiFive Unleashed
@@ -18,13 +19,14 @@ OpenSBI currently supports the following virtual and hardware platforms.
   *[sifive_fu540.md]*.
   *[sifive_fu540.md]*.
 
 
 * **Kendryte K210 SoC**: Platform support for the Kendryte K210 SoC used on
 * **Kendryte K210 SoC**: Platform support for the Kendryte K210 SoC used on
-  boards such as the Kendryte KD233 and Sipeed MAIX Dock boards.
+  boards such as the Kendryte KD233 or the Sipeed MAIX Dock.
 
 
 The code for these supported platforms can be used as example to implement
 The code for these supported platforms can be used as example to implement
 support for other platforms. The *platform/template* directory also provides
 support for other platforms. The *platform/template* directory also provides
 template files for implementing support for a new platform. The *object.mk*,
 template files for implementing support for a new platform. The *object.mk*,
-*config.mk* and *platform.c* template files provides enough comments to facilitate
-the implementation.
+*config.mk* and *platform.c* template files provides enough comments to
+facilitate the implementation.
 
 
 [qemu_virt.md]: qemu_virt.md
 [qemu_virt.md]: qemu_virt.md
 [qemu_sifive_u.md]: qemu_sifive_u.md
 [qemu_sifive_u.md]: qemu_sifive_u.md
+[sifive_fu540.md]: sifive_fu540.md

+ 16 - 16
docs/platform_guide.md

@@ -1,15 +1,15 @@
 OpenSBI Platform Support Guideline
 OpenSBI Platform Support Guideline
 ==================================
 ==================================
 
 
-OpenSBI platform support allows an implementation to define a set of platform
-specific hooks (hardware manipulation functions) in the form of a
+The OpenSBI platform support allows an implementation to define a set of
+platform-specific hooks (hardware manipulation functions) in the form of a
 *struct sbi_platform* data structure instance. This instance is required by
 *struct sbi_platform* data structure instance. This instance is required by
-platform independent *libsbi.a* to execute platform specific operations.
+the platform-independent *libsbi.a* to execute platform-specific operations.
 
 
-Each of the reference platform support provided by OpenSBI define an instance
+Each of the reference platform supports provided by OpenSBI defines an instance
 of the *struct sbi_platform* data structure. For each supported platform,
 of the *struct sbi_platform* data structure. For each supported platform,
-*libplatsbi.a* integrates this instance with *libsbi.a* to create a platform
-specific OpenSBI static library. This library is installed
+*libplatsbi.a* integrates this instance with *libsbi.a* to create a
+platform-specific OpenSBI static library. This library is installed
 in *<install_directory>/platform/<platform_subdir>/lib/libplatsbi.a*
 in *<install_directory>/platform/<platform_subdir>/lib/libplatsbi.a*
 
 
 OpenSBI also provides implementation examples of bootable runtime firmwares for
 OpenSBI also provides implementation examples of bootable runtime firmwares for
@@ -22,21 +22,21 @@ for the legacy *riskv-pk* boot loader (BBL).
 A complete doxygen-style documentation of *struct sbi_platform* and related
 A complete doxygen-style documentation of *struct sbi_platform* and related
 APIs is available in the file *include/sbi/sbi_platform.h*.
 APIs is available in the file *include/sbi/sbi_platform.h*.
 
 
-Adding a new platform support
------------------------------
+Adding support for a new platform
+---------------------------------
 
 
 Support for a new platform named *<xyz>* can be added as follows:
 Support for a new platform named *<xyz>* can be added as follows:
 
 
-1. Create a directory named *<xyz>* under *platform/* directory
-2. Create a platform configuration file named *config.mk* under
+1. Create a directory named *<xyz>* under the *platform/* directory.
+2. Create a platform configuration file named *config.mk* under the
    *platform/<xyz>/* directory. This configuration file will provide
    *platform/<xyz>/* directory. This configuration file will provide
-   compiler flags, select common drivers, and select firmware options
-3. Create *platform/<xyz>/objects.mk* file for listing the platform
-   specific object files to be compiled
-4. Create *platform/<xyz>/platform.c* file providing a *struct sbi_platform*
-   instance
+   compiler flags, select common drivers, and select firmware options.
+3. Create a *platform/<xyz>/objects.mk* file for listing the
+   platform-specific object files to be compiled.
+4. Create a *platform/<xyz>/platform.c* file providing a *struct sbi_platform*
+   instance.
 
 
-A template platform support code is available under the *platform/template*
+A platform support code template is available under the *platform/template*
 directory. Copying this directory and its content as a new directory named
 directory. Copying this directory and its content as a new directory named
 *<xyz>* under the *platform/* directory will create all the files mentioned
 *<xyz>* under the *platform/* directory will create all the files mentioned
 above.
 above.