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

["Jules Maselbas" <jmaselbas@zdiv.net>]

On Tue Jan 14, 2025 at 9:39 AM CET, Ahmad Fatoum wrote:
> 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?
Yeah i think it's better to remove irrelevant 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.
only relevant for the PBL

>> +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
Thanks, i'll take a look

>> +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.
yep, only relevant for PBL.

>> +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. :-)
Thanks for reading it :)

> Cheers,
> Ahmad