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@xxxxxxxx> --- 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. +However this is not enough, and two images are acctually needed. The first +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``). + +Boot process +------------ + +On power-up Allwinner SoC starts in boot ROM, aka BROM, which will search +for an eGON image: first from the SD card, then from eMMC. If no image is +found then the BROM will enter into FEL mode that can be used for initial +programming and recovery of devices using USB. + +Some board may have a button to enter FEL mode at startup. If not, another +way to enter FEL mode is to not have a valid image eGON image, this can be +achived by erasing existing eGON image headers. + +eGON header +----------- + +The eGON header structure is described in the file ``include/mach/sunxi/egon.h``. +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 + 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. + + +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 + + +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``. + +FEL +--- + +The ``sunxi-fel`` tool is used to interact, through USB, with sunxi devices +in FEL mode. ``sunxi-fel`` is part of the sunxi-tools_. + +.. _sunxi-tools: https://github.com/linux-sunxi/sunxi-tools + +More documentation about FEL_ and how to use the sunxi-fel tool can be +found on https://linux-sunxi.org/FEL/USBBoot . + +.. note:: + + ``sunxi-fel`` has a commands dedicated to boot u-boot images but theses + commands require a valid eGON header, if not more. This can be easily bypassed. + +The ``sunxi-fel`` tool can be used to load any arbitrary image at a given address +and can also request the processor to jump and start executing at any address. +This can be achieved by the following two commands:: + +.. code-block:: sh + + sunxi-fel write-with-progress 0x00018000 images/start_pine64_pinephone.pblb + sunxi-fel exe 0x00018000 + +These two commands allows the use of a different and bigger SRAM than the +default 32KB used by the boot ROM. + +The ``sunxi-fel`` tool might require additional permissions to acces the USB device, +this can be fixed by using a udev rule to add the most appropriated group to the device, +as an exemple adding the device to the dialout group can be done with the following rule:: + + SUBSYSTEMS=="usb", ATTRS{idVendor}=="1f3a", ATTRS{idProduct}=="efe8", GROUP+="dialout" + + +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. -- 2.47.1
