feat(common): add support for kernel DT handoff convention
TF-A currently supports multiple DT handoff conventions:
1. Firmware Handoff (FH): DT passed in x0, with x1–x3 carrying
additional data.
2. Kernel-compatible handoff (ARM_LINUX_KERNEL_AS_BL33): DT passed in
x0, x1–x3 zeroed.
3. Legacy TF-A convention: DT passed in x1, with x0 used for MPIDR or
NT_FW_CONFIG.
After discussions with folks in EDK2 and U-Boot, it's clear that there
is no strict requirement for placing the DT in x1. Both projects support
x0 for Arm platforms. To standardize behavior and support firmware
handoff migration, this patch introduces USE_KERNEL_DT_CONVENTION as a
configurable build flag. When enabled, the DT will be passed in x0 for
BL33.
This aligns TF-A’s behavior with Linux boot expectations and simplifies
integration across bootloaders.
Change-Id: I6bd7154fe07cb2e16e25c058f7cf862f9ae007e7
Signed-off-by: Harrison Mutai <harrison.mutai@arm.com>
diff --git a/docs/getting_started/build-options.rst b/docs/getting_started/build-options.rst
index e2fba99..6d3fea1 100644
--- a/docs/getting_started/build-options.rst
+++ b/docs/getting_started/build-options.rst
@@ -1130,6 +1130,14 @@
(Coherent memory region is included) or 0 (Coherent memory region is
excluded). Default is 1.
+- ``USE_KERNEL_DT_CONVENTION``: When this option is enabled, the hardware
+ device tree is passed to BL33 using register x0, aligning with the expectations
+ of the Linux kernel on Arm platforms. If this option is disabled, a different
+ register, typically x1, may be used instead. This build option is
+ not necessary when firmware handoff is active (that is, when TRANSFER_LIST=1
+ is set), and it will be removed once all platforms have transitioned to that
+ convention.
+
- ``USE_DSU_DRIVER``: This flag enables DSU (DynamIQ Shared Unit) driver.
The DSU driver allows save/restore of DSU PMU registers through
``PRESERVE_DSU_PMU_REGS`` build option and allows platforms to