Re: [PATCH v2 10/10] doc: falcon: Describe booting the OS through TF-A

Hi Alexey,

On 2026-07-31T17:10:44, Alexey Charkov <[email protected]> wrote:
> doc: falcon: Describe booting the OS through TF-A
>
> Falcon Mode documentation only covers SPL entering the kernel itself, which
> is not what happens on ARM64 SoCs needing ARM Trusted Firmware resident to
> provide firmware services: SPL loads a FIT holding BL31 as its firmware
> image and the kernel as a loadable, and BL31 enters the kernel as BL33.
>
> Describe that flow, what the kernel image may be given that neither
> booti_setup() nor bootz_setup() runs, how it differs from the classic flow,
> and how to configure and build it on Rockchip.
>
> Signed-off-by: Alexey Charkov <[email protected]>
>
> doc/board/rockchip/rockchip.rst |   9 +++
>  doc/develop/falcon.rst          | 131 +++++++++++++++++++++++++++++++++++++++-
>  2 files changed, 138 insertions(+), 2 deletions(-)

> diff --git a/doc/board/rockchip/rockchip.rst b/doc/board/rockchip/rockchip.rst
> @@ -321,6 +321,15 @@ To build rk3588 boards:
> +Falcon mode
> +"""""""""""
> +
> +ARM64 Rockchip SoCs can also boot Linux straight from SPL through TF-A,
> +without U-Boot proper running at all. Enabling CONFIG_ROCKCHIP_FALCON_IMAGE
> +makes binman build a ``u-boot-rockchip-falcon.itb`` holding TF-A, the kernel
> +and an optional initramfs, which are passed in with LINUX_KERNEL and
> +LINUX_INITRD. See :doc:`../../develop/falcon` for the details.

Please point at the rockchip-falcon.config fragment here as the easy
on-ramp - patch 9 adds it precisely so users do not have to hand-edit
their defconfig, but nothing in either doc actually tells them to use
it. A one-liner like 'make <board>_defconfig rockchip-falcon.config'
would make the story complete.

> diff --git a/doc/develop/falcon.rst b/doc/develop/falcon.rst
> @@ -95,11 +95,138 @@ Function that a board must implement
> +SPL picks BL33 in spl_invoke_atf(), which looks for an image with
> +``os = "linux"`` in the ``/fit-images`` node it appended to the device tree
> +and falls back to ``os = "u-boot"``. The kernel is entered at EL2 with the
> +device tree address in x0, as the arm64 boot protocol requires.

Just to clarify - the fallback to os = "u-boot" only happens outside
secure Falcon mode, which is stated a paragraph later but reads as
contradictory on first pass. Consider folding the exception into this
sentence.

> diff --git a/doc/develop/falcon.rst b/doc/develop/falcon.rst
> @@ -95,11 +95,138 @@ Function that a board must implement
> +CONFIG_SPL_UFS_RAW_OS_DEVNUM and CONFIG_SPL_UFS_RAW_OS_SECTOR against
> +CONFIG_SPL_UFS_RAW_U_BOOT_DEVNUM and CONFIG_SPL_UFS_RAW_U_BOOT_SECTOR, so

'against' reads oddly here - I'd suggest 'versus' or just 'and', with
a comma before 'so'.

> diff --git a/doc/develop/falcon.rst b/doc/develop/falcon.rst
> @@ -95,11 +95,138 @@ Function that a board must implement
> +DRAM which clear BL31 and OP-TEE, and can be adjusted with
> +CONFIG_ROCKCHIP_FALCON_KERNEL_LOAD and friends.

Please spell out the 'friends' - CONFIG_ROCKCHIP_FALCON_FDT_LOAD and
CONFIG_ROCKCHIP_FALCON_INITRD_LOAD

> diff --git a/doc/develop/falcon.rst b/doc/develop/falcon.rst
> @@ -95,11 +95,138 @@ Function that a board must implement
> +Enabling CONFIG_SPL_LZMA or CONFIG_SPL_GZIP additionally compresses the
> +kernel in the image, trading some decompression time for a smaller one - for
> +a 30 MiB arm64 Image, roughly 35% of the original with LZMA and 39% with
> +gzip. Note that this compresses U-Boot itself as well, since both use the
> +same setting.

Just to check - is 'compresses U-Boot itself as well' actually true
for the Falcon-only image (u-boot-rockchip-falcon.itb), which by name
does not contain U-Boot proper? I think you mean the same
SPL_LZMA/SPL_GZIP knob also compresses U-Boot in the regular
u-boot.itb built alongside. Worth rewording to make that unambiguous.

Regards,
Simon