6 files changed, 293 insertions, 0 deletions
diff --git a/roms/opensbi/docs/firmware/fw.md b/roms/opensbi/docs/firmware/fw.md
new file mode 100644
index 000000000..cc0cc9e56
--- /dev/null
+++ b/roms/opensbi/docs/firmware/fw.md
@@ -0,0 +1,111 @@
+OpenSBI Platform Firmwares
+==========================
+
+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 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.
+
+OpenSBI currently supports three different types of firmwares.
+
+Firmware with Dynamic Information (*FW_DYNAMIC*)
+------------------------------------------------
+
+The *FW_DYNAMIC* firmware gets information about the next booting stage entry,
+e.g. a bootloader or an OS kernel, from previous booting stage at runtime.
+
+A *FW_DYNAMIC* 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.
+
+Firmware with Jump Address (*FW_JUMP*)
+--------------------------------------
+
+The *FW_JUMP* firmware assumes a fixed 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.
+
+Firmware with Payload (*FW_PAYLOAD*)
+------------------------------------
+
+The *FW_PAYLOAD* firmware directly includes the binary code 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.
+
+Firmware Configuration and Compilation
+--------------------------------------
+
+All firmware types support the following common compile time configuration
+parameters:
+
+* **FW_TEXT_ADDR** - Defines the execution address of the OpenSBI firmware.
+  This configuration parameter is mandatory.
+* **FW_FDT_PATH** - Path to an external flattened device tree binary file to
+  be embedded in the *.rodata* section of the final firmware. If this option
+  is not provided then the firmware will expect the FDT to be passed as an
+  argument by the prior booting stage.
+* **FW_FDT_PADDING** - Optional zero bytes padding to the embedded flattened
+  device tree binary file specified by **FW_FDT_PATH** option.
+
+Additionally, each firmware type as a set of type specific configuration
+parameters. Detailed information for each firmware type can be found in the
+following documents.
+
+* *[FW_DYNAMIC]*: The *Firmware with Dynamic Information (FW_DYNAMIC)* is
+  described in more details in the file *fw_dynamic.md*.
+* *[FW_JUMP]*: The *Firmware with Jump Address (FW_JUMP)* is described in more
+  details in the file *fw_jump.md*.
+* *[FW_PAYLOAD]*: The *Firmware with Payload (FW_PAYLOAD)* is described in more
+  details in the file *fw_payload.md*.
+
+[FW_DYNAMIC]: fw_dynamic.md
+[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.
+
+Options for OpenSBI Firmware behaviors
+--------------------------------------
+An optional compile time flag FW_OPTIONS can be used to control the OpenSBI
+firmware run-time behaviors.
+
+```
+make PLATFORM=<platform_subdir> FW_OPTIONS=<options>
+```
+
+FW_OPTIONS is a bitwise or'ed value of various options, eg: *FW_OPTIONS=0x1*
+stands for disabling boot prints from the OpenSBI library.
+
+For all supported options, please check "enum sbi_scratch_options" in the
+*include/sbi/sbi_scratch.h* header file.
diff --git a/roms/opensbi/docs/firmware/fw_dynamic.md b/roms/opensbi/docs/firmware/fw_dynamic.md
new file mode 100644
index 000000000..01f43f9f4
--- /dev/null
+++ b/roms/opensbi/docs/firmware/fw_dynamic.md
@@ -0,0 +1,35 @@
+OpenSBI Firmware with Dynamic Information (FW_DYNAMIC)
+======================================================
+
+OpenSBI **firmware with dynamic info (FW_DYNAMIC)** is a firmware which gets
+information about next booting stage (e.g. a bootloader or an OS) and runtime
+OpenSBI library options from previous booting stage.
+
+The previous booting stage will pass information to *FW_DYNAMIC* by creating
+*struct fw_dynamic_info* in memory and passing it's address to *FW_DYNAMIC*
+via *a2* register of RISC-V CPU.
+
+A *FW_DYNAMIC* 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.
+
+*FW_DYNAMIC* Compilation
+------------------------
+
+A platform can enable *FW_DYNAMIC* firmware using any of the following methods.
+
+1. Specifying `FW_DYNAMIC=y` on the top level `make` command line.
+2. Specifying `FW_DYNAMIC=y` in the target platform *config.mk* configuration
+file.
+
+The compiled *FW_DYNAMIC* firmware ELF file is named *fw_dynamic.elf*. It's
+expanded image file is *fw_dynamic.bin*. Both files are created in the platform
+specific build directory under the *build/platform/<platform_subdir>/firmware*
+directory.
+
+*FW_DYNAMIC* Firmware Configuration Options
+-------------------------------------------
+
+The *FW_DYNAMIC* firmware does not requires any platform specific configuration
+parameters because all required information is passed by previous booting stage
+at runtime via *struct fw_dynamic_info*.
diff --git a/roms/opensbi/docs/firmware/fw_jump.md b/roms/opensbi/docs/firmware/fw_jump.md
new file mode 100644
index 000000000..eea301387
--- /dev/null
+++ b/roms/opensbi/docs/firmware/fw_jump.md
@@ -0,0 +1,51 @@
+OpenSBI Firmware with Jump Address (FW_JUMP)
+============================================
+
+OpenSBI **firmware with Jump Address (FW_JUMP)** is a firmware which only
+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 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:
+
+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
+build directory under the *build/platform/<platform_subdir>/firmware* directory.
+
+*FW_JUMP* Firmware Configuration Options
+----------------------------------------
+
+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:
+
+* **FW_JUMP_ADDR** - Address of the entry point of the booting stage to be
+  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 the OpenSBI firmware. If this option is not
+  provided, then the OpenSBI firmware will pass the FDT address passed by the
+  previous booting stage to the next booting stage.
+
+*FW_JUMP* Example
+-----------------
+
+The *[qemu/virt]* platform illustrates how to configure and use a *FW_JUMP*
+firmware. Detailed information regarding these platforms can be found in the
+platform documentation files.
+
+[qemu/virt]: ../platform/qemu_virt.md
diff --git a/roms/opensbi/docs/firmware/fw_payload.md b/roms/opensbi/docs/firmware/fw_payload.md
new file mode 100644
index 000000000..094744806
--- /dev/null
+++ b/roms/opensbi/docs/firmware/fw_payload.md
@@ -0,0 +1,72 @@
+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 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 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 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:
+
+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* 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
+  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_ADDR** - Address where the FDT passed by the prior booting
+  stage or specified by the *FW_FDT_PATH* parameter and embedded in the
+  *.rodata* 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 the FDT address passed by the previous booting stage
+  to the next booting stage.
+
+*FW_PAYLOAD* Example
+--------------------
+
+The *[qemu/virt]* platforms illustrate how to configure and use a *FW_PAYLOAD*
+firmware. Detailed information regarding these platforms can be found in the
+platform documentation files.
+
+[qemu/virt]: ../platform/qemu_virt.md
diff --git a/roms/opensbi/docs/firmware/payload_linux.md b/roms/opensbi/docs/firmware/payload_linux.md
new file mode 100644
index 000000000..e896567ab
--- /dev/null
+++ b/roms/opensbi/docs/firmware/payload_linux.md
@@ -0,0 +1,9 @@
+Linux as a direct payload to OpenSBI
+====================================
+
+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 a payload to OpenSBI.
+
+Detailed examples can be found in both the [QEMU](../platform/qemu_virt.md)
+and the [HiFive Unleashed](../platform/sifive_fu540.md) platform guides.
diff --git a/roms/opensbi/docs/firmware/payload_uboot.md b/roms/opensbi/docs/firmware/payload_uboot.md
new file mode 100644
index 000000000..b8f0803e2
--- /dev/null
+++ b/roms/opensbi/docs/firmware/payload_uboot.md
@@ -0,0 +1,15 @@
+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
+the OpenSBI firmware, becoming the boot stage following the OpenSBI firmware
+execution.
+
+Building and Generating U-Boot images
+=====================================
+Please refer to the U-Boot build documentation for detailed instructions on
+how to build U-Boot image and boot high level operating systems from U-Boot
+prompt.
+