docs: Add a payload section describing different payloads.

Signed-off-by: Atish Patra <atish.patra@wdc.com>

3 files changed, 67 insertions, 1 deletions

diff --git a/docs/firmware/fw.md b/docs/firmware/fw.md
index 2b6c26a..acff4a6 100644
--- a/docs/firmware/fw.md
+++ b/docs/firmware/fw.md
@@ -5,7 +5,7 @@ OpenSBI provides firmware builds for specific platforms. Different types of
 firmwares are supported to deal with the differences between different platforms
 early boot stage. All firmwares will execute the same initialization procedure
 of the platform hardware according to the platform specific code as well as
-OpenSBI generic library code. The supported firmwares types will differ in how
+OpenSBI generic library code. The supported firmwares type will differ in how
 the arguments passed by the platform early boot stage are handled, as well as
 how the boot stage following the firmware will be handled and executed.
 
@@ -58,3 +58,20 @@ following documents.
 
 [FW_JUMP]: fw_jump.md
 [FW_PAYLOAD]: fw_payload.md
+
+Providing different payloads to OpenSBI Firmware
+------------------------------------------------
+OpenSBI firmware can accept various payloads using a compile time option.
+Typically, these payloads refer to the next stage boot loader (e.g. U-Boot)
+or operating system kernel images (e.g. Linux). By default, OpenSBI
+automatically provides a test payload if no specific payload is specified
+at compile time.
+
+To specify a payload at compile time, the make variable _FW_PAYLOAD_PATH_ is
+used.
+```
+make PLATFORM=<platform_subdir> FW_PAYLOAD_PATH=<payload path>
+```
+The instructions to build each payload is different and the details can
+be found in the
+*docs/firmware/payload_<payload_name>.md* files.
diff --git a/docs/firmware/payload_linux.md b/docs/firmware/payload_linux.md
new file mode 100644
index 0000000..ccbad31
--- /dev/null
+++ b/docs/firmware/payload_linux.md
@@ -0,0 +1,11 @@
+Linux as a direct payload to OpenSBI
+====================================
+
+OpenSBI has the capability to load Linux kernel image directly in supervisor
+mode. The flattened image generated by the Linux kernel build process can be
+provided as 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.
+
diff --git a/docs/firmware/payload_uboot.md b/docs/firmware/payload_uboot.md
new file mode 100644
index 0000000..3fd7fa2
--- /dev/null
+++ b/docs/firmware/payload_uboot.md
@@ -0,0 +1,38 @@
+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
+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.
+
+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.
+
+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.
+
+Once U-Boot images are built, Linux kernel image need to be converted to 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 \
+		<linux_build_directory>arch/riscv/boot/Image \
+		<linux_build_directory>/arch/riscv/boot/uImage
+```
+
+Copy the uImage to your tftpboot server path if network boot is required.