Browse Source

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 years ago
parent
commit
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)
 ========================================================
@@ -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=<build_directory>
@@ -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_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
-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
-*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*.
 
-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>
 ```
 
-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>
 ```
 
-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
 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.
 
 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
 ```
 
-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
-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
 ```
 
-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
-*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/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
    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_directory> 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

+ 12 - 11
docs/contributing.md

@@ -1,19 +1,20 @@
 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:
-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
 contributions. This means that you must agree to the following prior to
 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
 requests to avoid creating unnecessary merge commits.
 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.
-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.
 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

+ 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
 # 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
 # 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.
 
 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
 ---------------------
 
-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.
 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
-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.
 
 *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
 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
-follows.
+follows:
 
 * **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
   mandatory parameter. Compilation errors will result from not defining this
   address.
 
 * **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
-  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
 -----------------
 
-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
-can be found in the platforms documentation files.
+can be found in the platform documentation files.
 
 [qemu/virt]: ../platform/qemu_virt.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
-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
-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
-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
 ---------------------------------
 
-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.
 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
 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.
 
 Configuration Options
@@ -34,7 +34,7 @@ Configuration Options
 A *FW_PAYLOAD* firmware is built according to configuration parameters and
 options. These configuration parameters can be defined using either the top
 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
   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
   *FW_PAYLOAD* firmware binary image. This configuration parameter is mandatory
   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
   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
 --------------------
 
-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
-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*).
 
 [qemu/virt]: ../platform/qemu_virt.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
 ====================================
 
-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
-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.
 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
-OpenSBI firmware, becoming the boot stage following OpenSBI firmware
+the OpenSBI firmware, becoming the boot stage following the OpenSBI firmware
 execution.
 
 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
 following out-of-tree patch series must be applied to the upstream U-Boot source
-code.
+code:
 
 HiFive Unleashed support for U-Boot
 
 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
-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
 
 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 \

+ 16 - 17
docs/library_usage.md

@@ -3,46 +3,46 @@ OpenSBI Library Usage
 
 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
    bootloader linking with this library. This library is installed as
    *<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
    *<install_directory>/platform/<platform_subdir>/lib/libplatsbi.a*
 
 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
 ---------------------------------------------------
 
 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*.
 
 There are only two constraints on calling any OpenSBI library function from an
 external M-mode firmware or bootloader:
 
 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
 perspective are *sbi_init()* and *sbi_trap_handler()*.
 
 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 *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
 forwarding all traps and interrupts to *sbi_trap_handler()*.
-

+ 9 - 7
docs/platform/platform.md

@@ -1,11 +1,12 @@
 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
   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]*.
 
 * **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
 support for other platforms. The *platform/template* directory also provides
 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_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 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
-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,
-*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*
 
 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
 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:
 
-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
-   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
 *<xyz>* under the *platform/* directory will create all the files mentioned
 above.