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>

1 files changed, 53 insertions, 38 deletions

diff --git a/docs/firmware/fw_payload.md b/docs/firmware/fw_payload.md
index 2fab092..0e705a2 100644
--- a/docs/firmware/fw_payload.md
+++ b/docs/firmware/fw_payload.md
@@ -1,51 +1,66 @@
 OpenSBI Firmware with Payload (FW_PAYLOAD)
 ==========================================
 
-The **OpenSBI firmware with Payload (FW_PAYLOAD)** is a
-firmware which includes next booting stage binary (i.e.
-bootloader/kernel) as payload in the OpenSBI firmware binary.
+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
-booting stage prior to OpenSBI firmware is not capable of
-loading OpenSBI firmware and booting stage after OpenSBI
-firmware separately.
+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 booting stage prior to OpenSBI
-firmware does not pass **flattened device tree (FDT)**. In
-this case, we have provision to embed FDT in .text section
-of **FW_PAYLOAD** firmware.
+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:
+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`
+1. Passing `FW_PAYLOAD=y` command-line parameter to top-level `make`
 2. Setting `FW_PAYLOAD=y` in platform `config.mk`
 
-Config Options
---------------
+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.
 
-We need more config details for **FW_PAYLOAD** firmware to
-work correctly. These config details can be passed as paramter
-to top-level `make` or can be set in platform `config.mk`.
-
-Following are the config options for **FW_PAYLOAD** firmware:
-
-* **FW_PAYLOAD_OFFSET** - Offset from FW_TEXT_BASE where next
-booting stage binary will be linked to **FW_PAYLOAD** firmware.
-This is a mandatory config option and will result in compile
-error if not provided.
-* **FW_PAYLOAD_PATH** - Path to the next booting stage binary.
-If this option is not provided then **`while (1)`** is taken as
-payload.
-* **FW_PAYLOAD_FDT_PATH** - Path to the FDT binary to be embedded
-in .text section of **FW_PAYLOAD** firmware. If this option is
-not provided then firmware will expect FDT to be passed by prior
-booting stage.
-* **FW_PAYLOAD_FDT_ADDR** - Address where FDT passed by prior
-booting stage (or embedded FDT) will be placed before passing
-to next booting stage. If this option is not provided then
-firmware will pass zero as FDT address to next booting stage.
\ No newline at end of file