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>

9 files changed, 93 insertions, 91 deletions

diff --git a/docs/contributing.md b/docs/contributing.md
index 2291089..7b9898f 100644
--- a/docs/contributing.md
+++ b/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
diff --git a/docs/doxygen.cfg b/docs/doxygen.cfg
index feb461b..8ab53ed 100644
--- a/docs/doxygen.cfg
+++ b/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
diff --git a/docs/firmware/fw_jump.md b/docs/firmware/fw_jump.md
index da21cda..7fdeeb4 100644
--- a/docs/firmware/fw_jump.md
+++ b/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
diff --git a/docs/firmware/fw_payload.md b/docs/firmware/fw_payload.md
index 72ea9bb..c9a9ad8 100644
--- a/docs/firmware/fw_payload.md
+++ b/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
-
diff --git a/docs/firmware/payload_linux.md b/docs/firmware/payload_linux.md
index ccbad31..048eb50 100644
--- a/docs/firmware/payload_linux.md
+++ b/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.
 
diff --git a/docs/firmware/payload_uboot.md b/docs/firmware/payload_uboot.md
index 42bf55f..d30f6f8 100644
--- a/docs/firmware/payload_uboot.md
+++ b/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 \
diff --git a/docs/library_usage.md b/docs/library_usage.md
index 579411f..92d51f5 100644
--- a/docs/library_usage.md
+++ b/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()*.
-
diff --git a/docs/platform/platform.md b/docs/platform/platform.md
index 12efa81..2235b6a 100644
--- a/docs/platform/platform.md
+++ b/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
diff --git a/docs/platform_guide.md b/docs/platform_guide.md
index 5eecf9b..53e9394 100644
--- a/docs/platform_guide.md
+++ b/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.