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>

docs/firmware/fw_payload.md

@@ -1,51 +1,66 @@
 OpenSBI Firmware with Payload (FW_PAYLOAD)
 ==========================================
 
-The **OpenSBI firmware with Payload (FW_PAYLOAD)** is a
+The **OpenSBI firmware with Payload (FW_PAYLOAD)** is a firmware which
-firmware which includes next booting stage binary (i.e.
+includes the next booting stage binary (i.e. bootloader/kernel) as a
-bootloader/kernel) as payload in the OpenSBI firmware binary.
+payload embedded in the OpenSBI firmware binary image.
 
-This **FW_PAYLOAD** firmware is particularly useful when
+This *FW_PAYLOAD* firmware is particularly useful when the booting stage
-booting stage prior to OpenSBI firmware is not capable of
+prior to OpenSBI firmware is not capable of loading the OpenSBI firmware
-loading OpenSBI firmware and booting stage after OpenSBI
+and the booting stage after OpenSBI firmware separately.
-firmware separately.
 
-It is also possible that booting stage prior to OpenSBI
+It is also possible that the booting stage prior to OpenSBI firmware
-firmware does not pass **flattened device tree (FDT)**. In
+does not pass a *flattened device tree (FDT)*. In this case, a
-this case, we have provision to embed FDT in .text section
+*FW_PAYLOAD* firmware allows embedding a flattened device tree in
-of **FW_PAYLOAD** firmware.
+the .text section of the final firmware.
 
 How to Enable?
 --------------
 
-The **FW_PAYLOAD** firmware can be enabled by any of the
+The *FW_PAYLOAD* firmware can be enabled by any of the following methods:
-following methods:
 
-1. Passing `FW_PAYLOAD=y` command-line parameter to
+1. Passing `FW_PAYLOAD=y` command-line parameter to top-level `make`
-top-level `make`
 2. Setting `FW_PAYLOAD=y` in platform `config.mk`
 
-Config Options
+Configuration Options
---------------
+---------------------
 
-We need more config details for **FW_PAYLOAD** firmware to
+A *FW_PAYLOAD* firmware needs to be built according to some predefined
-work correctly. These config details can be passed as paramter
+configuation options to work correctly. These configuration details can
-to top-level `make` or can be set in platform `config.mk`.
+be passed as paramters to the top-level `make` command or can be defined
+ in a platform *config.mk* build configuration file.
 
-Following are the config options for **FW_PAYLOAD** firmware:
+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.
 
-* **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.

firmware/fw_payload.elf.ldS

@@ -14,7 +14,11 @@ SECTIONS
 {
 	#include "fw_base.ldS"
 
+#ifdef FW_PAYLOAD_OFFSET
 	. = FW_TEXT_START + FW_PAYLOAD_OFFSET;
+#else
+	. = ALIGN(FW_PAYLOAD_ALIGN);
+#endif
 
 	.payload :
 	{

firmware/objects.mk

@@ -35,6 +35,10 @@ firmware-genflags-$(FW_PAYLOAD) += -DFW_PAYLOAD_PATH=$(FW_PAYLOAD_PATH_FINAL)
 ifdef FW_PAYLOAD_OFFSET
 firmware-genflags-$(FW_PAYLOAD) += -DFW_PAYLOAD_OFFSET=$(FW_PAYLOAD_OFFSET)
 endif
+ifdef FW_PAYLOAD_ALIGN
+firmware-genflags-$(FW_PAYLOAD) += -DFW_PAYLOAD_ALIGN=$(FW_PAYLOAD_ALIGN)
+endif
+
 ifdef FW_PAYLOAD_FDT_PATH
 firmware-genflags-$(FW_PAYLOAD) += -DFW_PAYLOAD_FDT_PATH=$(FW_PAYLOAD_FDT_PATH)
 endif

firmware/payloads/dummy.elf.ldS

@@ -12,7 +12,11 @@ ENTRY(_start)
 
 SECTIONS
 {
+#ifdef FW_PAYLOAD_OFFSET
 	. = FW_TEXT_START + FW_PAYLOAD_OFFSET;
+#else
+	. = ALIGN(FW_PAYLOAD_ALIGN);
+#endif
 
 	PROVIDE(_payload_start = .);
 

platform/kendryte/k210/config.mk

@@ -19,10 +19,8 @@ PLATFORM_SYS_CLINT=y
 
 # Blobs to build
 FW_TEXT_START=0x80000000
-FW_JUMP=n
 FW_PAYLOAD=y
-FW_PAYLOAD_OFFSET=0x10000
+FW_PAYLOAD_ALIGN=0x1000
-#FW_PAYLOAD_FDT_ADDR=0x80040000
 
 # External Libraries to include
 PLATFORM_INCLUDE_LIBC=y