mirror of
https://github.com/riscv-software-src/opensbi.git
synced 2025-08-24 15:31:22 +01:00
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>
This commit is contained in:
Karsten Merker
committed by
Anup Patel
Anup Patel
parent
3bb2d25f44
commit
0d33a981ec
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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 \
|
||||
|
||||
Reference in New Issue
Block a user