Re: [PATCH v2 6/6] Documentation: sunxi: Add some documentation

[Ahmad Fatoum <a.fatoum@pengutronix.de>]

Hi Jules,

On 07.01.25 15:37, Jules Maselbas wrote:
> Add some informations about Allwinner sunxi boardsupport: the general
> boot process, how to use sunxi-fel tool, and how to create a bootable
> image disk.
> 
> Signed-off-by: Jules Maselbas <jmaselbas@zdiv.net>

Reviewed-by: Ahmad Fatoum <a.fatoum@pengutronix.de>

with changes suggested below:

> ---
>  Documentation/boards/sunxi.rst | 132 +++++++++++++++++++++++++++++++++
>  1 file changed, 132 insertions(+)
>  create mode 100644 Documentation/boards/sunxi.rst
> 
> diff --git a/Documentation/boards/sunxi.rst b/Documentation/boards/sunxi.rst
> new file mode 100644
> index 0000000000..46832559c9
> --- /dev/null
> +++ b/Documentation/boards/sunxi.rst
> @@ -0,0 +1,132 @@
> +..
> +  SPDX-License-Identifier: GPL-2.0+
> +
> +  Copyright (C) 2022, Jules Maselbas
> +
> +Allwinner sunxi
> +===============
> +
> +Because of size constraints Barebox proper cannot boot directly, the uses
> +of :doc:`PBL` allows to compress the Barebox image and it's device-tree.

s/it's/its/

> +However this is not enough, and two images are acctually needed. The first

s/acctually/actually/

> +image is suffixed *_xload* and it only consist of the PBL with a special
> +entry point that looks for ``barebox.bin`` the root of a FAT partition.
> +Only the SD card is currently searched, but this could also be in eMMC.
> +The second image is your standard Barebox plus PBL image (suffixed ``.pblb``).

The pblb image is just an intermediate artifact. There's usually an .img
that's either 1:1 the pblb or the pblb with a SoC-specific header in front
(or size patched in), so users need not mess with the pblb at all.

Also, to avoid confusion, please add a note here that xload support isn't
available yet or remove that part for now?

> +eGON header
> +-----------
> +
> +The eGON header structure is described in the file ``include/mach/sunxi/egon.h``.

This file doesn't exist yet.

> +This is also documented on https://linux-sunxi.org/EGON .
> +
> +The eGON header, followed by the actual image, must be located at the fixed
> +offset of 8192 bytes (8KB) from the start of the disk (sector 16), either
> +from SD card; or from eMMC.
> +
> +.. code-block:: sh
> +
> +  # copy the "pine64_xload" eGON image into disk sdX
> +  dd if=images/start_pine64_pine64_xload.pblb.egonimg of=/dev/sdX bs=512 seek=16
> +
> +The above will write the entire "pine64_xload" Barebox PBL plus the eGON
> +header into the disk "/dev/sdX".
> +
> +The boot ROM will load, at most, the first 32KB of the image into SRAM,
> +including the header itself! The eGON header starts with a jump instruction
> +to jump over the header, this jump instruction needs to be patched accordingly
> +with the header size.
> +
> +.. note::
> +
> +  On sunxi platforms the boot ROM loads the entire image **including**
> +  the eGON header. The actual base address will be offset by the eGON header
> +  (currently 96 bytes), this bad because arm instructions used for relocation

s/this bad/this is bad/

> +  expect the base address to be aligned on 4K boundary.
> +  As a workaround, a eGON header is included and linked into the Barebox
> +  PBL image, this dummy header will be filled later by egon_mkimage.

Nice.

> +Board images are defined in ``images/Makefile.sunxi``, here is an example::
> +
> +.. code-block:: none
> +
> +  pblb-$(CONFIG_MACH_PINE64_PINE64) += start_pine64_pine64_xload
> +  MAX_PBL_IMAGE_SIZE_start_pine64_pine64_xload = 0x8000
> +  FILE_barebox-pine64-pine64_xload.img = start_pine64_pine64_xload.pblb.egonimg
> +  image-$(CONFIG_MACH_PINE64_PINE64) += barebox-pine64-pine64_xload.img

While useful to have, I think the docs should start with user documentation
first, i.e. a Building section that points out what defconfig to use, what
images result and that only second stage is currently supported.
See for example:

https://www.barebox.org/doc/latest/boards/rockchip.html#id1

> +RMR aarch64 switch
> +------------------
> +
> +Aarch64 capable SoC (A64/sun50i) boot by default in 32-bit mode. A special header
> +is added to the start of the PBL image in order to switch to aarch64 mode as soon
> +as possible. This must be done very early in the boot process since both ISA are
> +not compatible. The code to switch mode is already assembled (mostly arm 32bit)
> +and is documented in the header file ``include/mach/sunxi/rmr_switch.h``.

Likewise file doesn't exist yes.

> +More documentation about FEL_ and how to use the sunxi-fel tool can be
> +found on https://linux-sunxi.org/FEL/USBBoot .

Is this already a clickable link?

> +Arm Trusted Firmware (TF-A)
> +---------------------------
> +
> +Boards using a 64-bit Soc (A64, H5, H6, H616, R329) require the BL31 stage of
> +the `Arm Trusted Firmware-A`_ firmware. This provides the reference
> +implementation of secure software for Armv8-A, offering PSCI and SMCCC
> +services. Allwinner support is fully mainlined. To build bl31.bin::
> +
> +.. code-block:: sh
> +
> +  git clone https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git
> +  cd trusted-firmware-a
> +  make CROSS_COMPILE=aarch64-linux-gnu- PLAT=sun50i_a64 DEBUG=1
> +  cp build/sun50i_a64/debug/bl31.bin ${barebox_dir}/firmware/sun50i-a64-bl31.bin
> +
> +The target platform (``PLAT=``) for A64 and H5 SoCs is sun50i_a64, for the H6
> +sun50i_h6, for the H616 sun50i_h616, and for the R329 sun50i_r329.


Thanks for taking the time to write such useful docs. :-)

Cheers,
Ahmad


-- 
Pengutronix e.K.                           |                             |
Steuerwalder Str. 21                       | http://www.pengutronix.de/  |
31137 Hildesheim, Germany                  | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686           | Fax:   +49-5121-206917-5555 |