docs/firmware/fw_payload.md

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.

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.

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.

Enabling *FW_PAYLOAD* compilation
---------------------------------

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
   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
---------------------

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.

* **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 of *FW_PAYLOAD_ALIGN*, or if neither of these
  parameters are defined.

* **FW_PAYLOAD_ALIGN** - Address alignment constraint where the payload binary
  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_PATH** - Path to the image file of the next booting stage
  binary.  If this option is not provided then a simple test payload is
  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 binary
  file to be embedded in the *.text* section of the final 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** - Path to an internal flattened device tree binary file
  defined by the platform code. The file name must match the DTB file name
  specified in the platform *objects.mk* file with the *platform-dtb-y* entry.
  This option results in *FW_PAYLOAD_FDT_PATH* to be automatically set.
  Specifying *FW_PAYLOAD_FDT_PATH* on the `make` command line disables
  *FW_PAYLOAD_FDT* and the command line specified device tree binary file is
  used for building the final firmware.

* **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.

*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