GitHub-Mirror/opensbi
2
0
Fork 0
mirror of https://github.com/Fishwaldo/opensbi.git synced 2025-07-11 23:48:39 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs/firmware: Update FW_PAYLOAD documentation

Browse source 
Reformatting, typos, and various corrections.

Signed-off-by: Damien Le Moal <damien.lemoal@wdc.com>
This commit is contained in:
Damien Le Moal 2019-01-23 16:21:59 +09:00 • committed by Anup Patel
parent fff48ee2bf
commit 560147b264
1 changed files with 71 additions and 56 deletions
Download patch file Download diff file Expand all files Collapse all files

127
docs/firmware/fw_payload.md
View file

@ -1,75 +1,90 @@
OpenSBI Firmware with Payload (FW_PAYLOAD) OpenSBI Firmware with Payload *FW_PAYLOAD*
========================================== ==========================================
The **OpenSBI firmware with Payload (FW_PAYLOAD)** is a firmware which OpenSBI **firmware with Payload (FW_PAYLOAD)** is a firmware which directly
includes the next booting stage binary (i.e. bootloader/kernel) as a includes the binary for the booting stage to follow OpenSBI firmware execution.
payload embedded in the OpenSBI firmware binary image. Typically, this payload will be a bootloader or an OS kernel.
This *FW_PAYLOAD* firmware is particularly useful when the booting stage A *FW_PAYLOAD* firmware is particularly useful when the booting stage executed
prior to OpenSBI firmware is not capable of loading the OpenSBI firmware prior to OpenSBI firmware is not capable of loading both OpenSBI firmware and
and the booting stage after OpenSBI firmware separately. the booting stage to follow OpenSBI firmware.
It is also possible that the booting stage prior to OpenSBI firmware A *FW_PAYLOAD* firmware is also useful for cases where the booting stage prior
does not pass a *flattened device tree (FDT)*. In this case, a to OpenSBI firmware does not pass a *flattened device tree (FDT file)*. In such
*FW_PAYLOAD* firmware allows embedding a flattened device tree in case, a *FW_PAYLOAD* firmware allows embedding a flattened device tree in the
the .text section of the final firmware. .text section of the final firmware.
How to Enable? 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. Passing `FW_PAYLOAD=y` command-line parameter to top-level `make` 1. Specifying `FW_PAYLOAD=y` on the top level `make` command line.
2. Setting `FW_PAYLOAD=y` in platform `config.mk` 2. Specifying `FW_PAYLOAD=y` in the target platform *config.mk* configuration
file.
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
*build/platform/<platform_subdir>/firmware* directory.
Configuration Options Configuration Options
--------------------- ---------------------
A *FW_PAYLOAD* firmware needs to be built according to some predefined A *FW_PAYLOAD* firmware is built according to configuration parameters and
configuration options to work correctly. These configuration details can options. These configuration parameters can be defined using either the top
be passed as parameters to the top-level `make` command or can be defined level `make` command line or the target platform *config.mk* configuration
in a platform *config.mk* build configuration file. file. The parameters currently defined are as follows.
The following are the build configuration parameters for a *FW_PAYLOAD* * **FW_PAYLOAD_OFFSET** - Offset from *FW_TEXT_BASE* where the payload binary
firmware: will be linked in the final *FW_PAYLOAD* firmware binary image. This
configuration parameter is mandatory if *FW_PAYLOAD_ALIGN* is not defined.
* **FW_PAYLOAD_OFFSET** - Offset from *FW_TEXT_BASE* where the payload Compilation errors will result from an incorrect definition of
binary will be linked in the final *FW_PAYLOAD* firmware binary image. *FW_PAYLOAD_OFFSET* or of *FW_PAYLOAD_ALIGN*, or if neither of these
<<<<<<< HEAD
This configuration parameter is mandatory if *FW_PAYLOAD_ALIGN* is not
defined. Compilation errors will result from an incorrect definition
of *FW_PAYLOAD_OFFSET* or *FW_PAYLOAD_ALIGN*, or if neither of these
parameters are defined. parameters are defined.
* **FW_PAYLOAD_ALIGN** - Address alignment constraint where the payload * **FW_PAYLOAD_ALIGN** - Address alignment constraint where the payload binary
binary will be linked after the end of the base firmware binary in the will be linked after the end of the base firmware binary in the final
final *FW_PAYLOAD* firmware binary image. This configuration parameter *FW_PAYLOAD* firmware binary image. This configuration parameter is mandatory
is mandatory if *FW_PAYLOAD_OFFSET* is not defined and should not be if *FW_PAYLOAD_OFFSET* is not defined. If both *FW_PAYLOAD_OFFSET* and
defined otherwise. *FW_PAYLOAD_ALIGN* are defined, *FW_PAYLOAD_OFFSET* is used and
*FW_PAYLOAD_ALIGN* ignored.
* **FW_PAYLOAD_PATH** - Path to the next booting stage binary image * **FW_PAYLOAD_PATH** - Path to the image file of the next booting stage
file. 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
automatically generated, executing a `while (1)` loop. automatically generated and used as a payload. This test payload executes
an infinite `while (1)` loop after printing a message on the platform console.
* **FW_PAYLOAD_FDT_PATH** - Path to an external flattened device tree * **FW_PAYLOAD_FDT_PATH** - Path to an external flattened device tree binary
binary file to be embedded in the *.text* section of the final file to be embedded in the *.text* section of the final firmware. If this
*FW_PAYLOAD* firmware. If this option is not provided and no internal option is not provided and no internal device tree file is specified by the
device tree file is specified by the platform (c.f. *FW_PAYLOAD_FDT*), platform (c.f. *FW_PAYLOAD_FDT*), then the firmware will expect the FDT to
then the firmware will expect the FDT to be passed as an argument by be passed as an argument by the prior booting stage.
the prior booting stage.
* **FW_PAYLOAD_FDT** - Path to an internal flattened device tree * **FW_PAYLOAD_FDT** - Path to an internal flattened device tree binary file
binary file defined by the platform code. The file name must match the defined by the platform code. The file name must match the DTB file name
DTB file name specified in the platform *objects.mk* file with the specified in the platform *objects.mk* file with the *platform-dtb-y* entry.
*platform-dtb-y* entry. This option results in *FW_PAYLOAD_FDT_PATH* to This option results in *FW_PAYLOAD_FDT_PATH* to be automatically set.
be automatically set. Specifying *FW_PAYLOAD_FDT_PATH* on the `make` Specifying *FW_PAYLOAD_FDT_PATH* on the `make` command line disables
command line disables *FW_PAYLOAD_FDT* and the command line specified *FW_PAYLOAD_FDT* and the command line specified device tree binary file is
device tree binary file is used for building the final firmware. used for building the final firmware.
* **FW_PAYLOAD_FDT_ADDR** - Address where the FDT passed by the prior * **FW_PAYLOAD_FDT_ADDR** - Address where the FDT passed by the prior booting
booting stage or specified by the *FW_PAYLOAD_FDT_PATH* parameter and stage or specified by the *FW_PAYLOAD_FDT_PATH* parameter and embedded in
embedded in the *.text* section will be placed before executing the the *.text* section will be placed before executing the next booting stage,
next booting stage, that is, the payload firmware. If this option is that is, the payload firmware. If this option is not provided then the
not provided then the firmware will pass zero as the FDT address to the firmware will pass zero as the FDT address to the next booting stage.
next booting stage.
*FW_PAYLOAD* Example
--------------------
The *[qemu/virt]* and *[qemu/sifive_u]* platforms illustrates how to configure
and use a *FW_PAYLOAD* firmware. Detailed information regarding these platforms
can be found in the platforms documentation files.
The *kendryte/k210* platform also enables 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