From 0d33a981ec19181c7f6448f90599f31dfd082994 Mon Sep 17 00:00:00 2001 From: Karsten Merker <merker@debian.org> Date: Sun, 5 May 2019 12:33:25 +0200 Subject: docs: miscellaneous documentation fixes and updates - fix some broken hyperlinks - add additional hyperlinks to references to external documents - reformat some paragraphs to keep lines under 80 characters - unify the enumeration style between different parts of the documentation - fix spelling/grammar mistakes - extend the copyright notice in README.md to be the same as the one in COPYING.BSD Signed-off-by: Karsten Merker <merker@debian.org> Reviewed-by: Atish Patra <atish.patra@wdc.com> --- docs/firmware/fw_jump.md | 22 +++++++++++----------- docs/firmware/fw_payload.md | 31 +++++++++++++++---------------- docs/firmware/payload_linux.md | 9 ++++----- docs/firmware/payload_uboot.md | 16 +++++++++------- 4 files changed, 39 insertions(+), 39 deletions(-) (limited to 'docs/firmware') 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 \ -- cgit v1.2.3