docs: Add documentation about dynamic firmware

This patch adds documenation about dynamic firmware.

Signed-off-by: Anup Patel <anup.patel@wdc.com>
Reviewed-by: Alistair Francis <alistair.francis@wdc.com>
Reviewed-by: Atish Patra <atish.patra@wdc.com>

2 files changed, 51 insertions, 3 deletions

diff --git a/docs/firmware/fw.md b/docs/firmware/fw.md
index 8ca54b6..4133c23 100644
--- a/docs/firmware/fw.md
+++ b/docs/firmware/fw.md
@@ -9,12 +9,22 @@ 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 two different types of firmwares.
+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 only handles the address of the next booting stage
+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.
 
@@ -48,14 +58,17 @@ configuration parameter.
   loads OpenSBI firmware.
 
 Additionally, each firmware type as a set of type specific configuration
-parameters. Detailed information for each firmware type can be found in the 
+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
 
diff --git a/docs/firmware/fw_dynamic.md b/docs/firmware/fw_dynamic.md
new file mode 100644
index 0000000..041b6cc
--- /dev/null
+++ b/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*.