Firmware/opensbi
8
0
Fork 0
forked from Mirrors/opensbi
Code Pull Requests Activity
Files
ac3041f4e906ee75d423ac788803218db51ef343
opensbi/docs/firmware/fw_payload.md
Damien Le Moal ac3041f4e9 build: Introduce FW_PAYLOAD_ALIGN 
The firmware payload offset defined by FW_PAYLOAD_OFFSET must
specify a value large enough so the the payload does not overlap
with the base firmware data, bss and text. For platforms without
any strong requirement on the payload address, introduce the
FW_PAYLOAD_ALIGN build parameter to automatically place the payload
right after the base firmware at an address aligned with the defined
value.

Either FW_PAYLOAD_OFFSET or FW_PAYLOAD_ALIGN should be defined by a
platform configuration. If both FW_PAYLOAD_OFFSET and FW_PAYLOAD_ALIGN
are defined by a platform, FW_PAYLOAD_OFFSET has precedence and is
used for building the final firmawre image.

Using FW_PAYLOAD_ALIGN=4096 with the Kendryte platform rather than
the abitrary FW_PAYLOAD_OFFSET=0x10000 value reduces the final
firmware image size by about 20KB.

Add a description of the FW_PAYLOAD_ALIGN configuration parameter in the
fw_payload documentation file as well. And while at it, also fix
various grammar and style issues in that file..

Signed-off-by: Damien Le Moal <damien.lemoal@wdc.com>
2019-01-21 09:58:33 +05:30

2.9 KiB
Raw Blame History

OpenSBI Firmware with Payload (FW_PAYLOAD)

The OpenSBI firmware with Payload (FW_PAYLOAD) is a firmware which includes the next booting stage binary (i.e. bootloader/kernel) as a payload embedded in the OpenSBI firmware binary image.

This FW_PAYLOAD firmware is particularly useful when the booting stage prior to OpenSBI firmware is not capable of loading the OpenSBI firmware and the booting stage after OpenSBI firmware separately.

It is also possible that the booting stage prior to OpenSBI firmware does not pass a flattened device tree (FDT). In this case, a FW_PAYLOAD firmware allows embedding a flattened device tree in the .text section of the final firmware.

How to Enable?

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
  2. Setting FW_PAYLOAD=y in platform config.mk

Configuration Options

A FW_PAYLOAD firmware needs to be built according to some predefined configuation options to work correctly. These configuration details can be passed as paramters to the top-level make command or can be defined in a platform config.mk build configuration file.

The following are the build configuration parameters for a FW_PAYLOAD firmware:

  • FW_PAYLOAD_OFFSET - Offset from FW_TEXT_BASE where the payload binary will be linked in the final FW_PAYLOAD firmware binary image. 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 paramreters are defined.

  • FW_PAYLOAD_ALIGN - Address alignment constraint where the payload binary will be linked after the end of the base firmaware binary in the final FW_PAYLOAD firmware binary image. This configuration parameter is mandatory if FW_PAYLOAD_OFFSET is not defined and should not be defined otherwise.

  • FW_PAYLOAD_PATH - Path to the next booting stage binary image file. If this option is not provided then a simple test payload is automatically generated, executing a while (1) loop.

  • FW_PAYLOAD_FDT_PATH - Path to an external flattened device tree binary file to be embedded in the .text section of the final FW_PAYLOAD firmware. If this option is not provided and no internal device tree file is specified by the platform (c.f. FW_PAYLOAD_FDT), then the firmware will expect the FDT to be passed as an argument by the prior booting stage.

  • FW_PAYLOAD_FDT_ADDR - Address where the FDT passed by the prior booting stage or specified by the FW_PAYLOAD_FDT_PATH parameter and embedded in the .text section will be placed before executing the next booting stage, that is, the payload firmware. If this option is not provided then the firmware will pass zero as the FDT address to the next booting stage.