Skip to contentSkip to conversation

sunxi: add board documentation

PATCH Superseded Andre Przywara 3 participants 7 messages Dec 13, 2021 – Dec 28, 2021 Arm/Allwinner sunXi SoC support

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 sunxi: add board documentation

Add some long overdue instructions for building and installing U-Boot on Allwinner SoC based boards.
This describes the building process, including TF-A and crust, plus installation to SD card, eMMC and SPI flash, both from Linux and U-Boot itself. Also describe FEL booting.

---
Hi,

please have a look whether this makes sense. Feel free to just try something, and point out ambiguities or missing bits. For missing topics, please send a follow-up patch ;-)

Also this is quite long, shall this be split up in two (or more) files?

This is what rst.ninjs.org made of it, if you prefer to read it formatted:
https://paste.c-net.org/PleasantNeedy

Cheers,
Andre

 doc/board/allwinner/index.rst |   9 +
 doc/board/allwinner/sunxi.rst | 304 ++++++++++++++++++++++++++++++++++
 2 files changed, 313 insertions(+)
 create mode 100644 doc/board/allwinner/index.rst
 create mode 100644 doc/board/allwinner/sunxi.rst
doc/board/allwinner/index.rst new file +9 -0
new file mode 100644
index 00000000000..7352ccd5c0a
@@ -0,0 +1,9 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+Allwinner (sunxi) boards
+========================
+
+.. toctree::
+   :maxdepth: 2
+
+   sunxi
doc/board/allwinner/sunxi.rst new file +304 -0

304 lines not on this page · raw message

Signature · 1 line
2.17.6
maintainer
#1 lore raw

Hi Andre!

Dne ponedeljek, 13. december 2021 ob 02:03:22 CET je Andre Przywara napisal(a):

Quoted 11 lines

Add some long overdue instructions for building and installing U-Boot on Allwinner SoC based boards.
This describes the building process, including TF-A and crust, plus installation to SD card, eMMC and SPI flash, both from Linux and U-Boot itself. Also describe FEL booting.

---
Hi,

please have a look whether this makes sense. Feel free to just try

something,

Quoted 2 lines

and point out ambiguities or missing bits. For missing topics, please send a follow-up patch ;-)

This documentation seems to include all of board/sunxi/README.sunxi64 and README.nand. I think it would make sense to remove those files. If any file gets out of sync for any reason, it would be very confusing for end user.

I would also remove all non-essential command parameters, so all commands are as simple as possible. Power users will know about them anyway and non-skilled users might perceive that it's harder that it really is. I have in mind "-j5 - s" for make, "-v -p" for sunxi-fel and DEBUG=1 for TF-A (maybe I missed some places). Actually, DEBUG=1 could be mentioned afterwards as troubleshooting step. In my experience, stable version of TF-A was never source of boot issues nor it provided any useful information for debugging anything else.

Some comments bellow.

Quoted 36 lines

Also this is quite long, shall this be split up in two (or more) files?

This is what rst.ninjs.org made of it, if you prefer to read it formatted:
https://paste.c-net.org/PleasantNeedy

Cheers,
Andre

 doc/board/allwinner/index.rst |   9 +
 doc/board/allwinner/sunxi.rst | 304 ++++++++++++++++++++++++++++++++++
 2 files changed, 313 insertions(+)
 create mode 100644 doc/board/allwinner/index.rst
 create mode 100644 doc/board/allwinner/sunxi.rst
doc/board/allwinner/index.rst new file +9 -0
new file mode 100644
index 00000000000..7352ccd5c0a
@@ -0,0 +1,9 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+Allwinner (sunxi) boards
+========================
+
+.. toctree::
+   :maxdepth: 2
+
+   sunxi
doc/board/allwinner/sunxi.rst new file +0 -0
new file mode 100644
index 00000000000..693eb32e168

doc/board/allwinner/sunxi.rst line 7

Quoted 7 lines
doc/board/allwinner/sunxi.rst new file +7 -0
@@ -0,0 +1,304 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. Copyright (C) 2021 Arm Ltd.
+
+Allwinner SoC based boards
+==========================
+For boards using an Allwinner ARM based SoC ("sunxi"), the U-Boot build
+system generates a single integrated image file: ``u-boot-sunxi-with-

spl.bin.``

doc/board/allwinner/sunxi.rst

Quoted 4 lines
doc/board/allwinner/sunxi.rst new file +4 -0
+This file can be used on SD cards, eMMC devices, SPI flash and for the
+USB-OTG based boot method (FEL). To build this file:
+
+* For 64-bit SoCs, build Trusted Firmware (TF-A, formerly known as ATF) 

first,

doc/board/allwinner/sunxi.rst

Quoted 6 lines
doc/board/allwinner/sunxi.rst new file +6 -0
+  you will need its ``bl31.bin``. See below for more details.
+* Optionally on 64-bit SoCs, build the crust management processor firmware.
+* Build U-Boot::
+
+  $ export BL31=/path/to/bl31.bin		# required for 64-bit SoCs
+  $ export SCP=/src/crust/build/scp/scp.bin	# optional for some 64-bit

SoCs

NIT: I guess path for SCP could be in same form, at least first part?

doc/board/allwinner/sunxi.rst line 22

Quoted 5 lines
doc/board/allwinner/sunxi.rst new file +5 -0
+  $ make <yourboardname>_defconfig
+  $ make -j5 -s
+* Transfer to an uSD card (see below for more details)::
+
+  $ dd if=u-boot-sunxi-with-spl.bin of=/dev/sdX bs=8k seek=1

Most, if not all, distros require root for above command, so $ -> #? I see that you used # below. Alternative would be to prepend command with sudo, which is imo more beginners friendly.

doc/board/allwinner/sunxi.rst

Quoted 3 lines
doc/board/allwinner/sunxi.rst new file +3 -0
+* Boot and enjoy!
+
+For more details, and alternative boot locations or installations, see 

below.

doc/board/allwinner/sunxi.rst

Quoted 4 lines
doc/board/allwinner/sunxi.rst new file +4 -0
+
+Building Arm Trusted Firmware (TF-A)
+------------------------------------
+Boards using a 64-bit Soc (A64, H5, H6, H616, R329) require the BL31 stage 

of

doc/board/allwinner/sunxi.rst

Quoted 10 lines
doc/board/allwinner/sunxi.rst new file +10 -0
+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::
+
+  $ 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
+  $ export BL31=$(pwd)/build/sun50i_a64/debug/bl31.bin
+
+The target platform (``PLAT=``) for A64 and H5 SoCs is sun50i_a64, for the 

H6

Quoted 8 lines
doc/board/allwinner/sunxi.rst new file +8 -0
+sun50i_h6, for the H616 sun50i_h616, and for the R329 sun50i_r329. Use::
+
+  $ find plat/allwinner -name platform.mk
+
+to find all supported platforms. `docs/plat/allwinner.rst`_ contains more
+information and lists some build options.
+
+Building the Crust management processor firmware

doc/board/allwinner/sunxi.rst

Quoted 10 lines
doc/board/allwinner/sunxi.rst new file +10 -0
+------------------------------------------------
+For some SoCs and boards, the integrated OpenRISC management controller can
+be used to provide power management services, foremost suspend to RAM.
+There is a community supported Open Source implementation called `crust`_,
+which runs on most SoCs featuring a management controller.
+
+This firmware part is optional, setting the SCP environment variable to
+/dev/null avoids the warning message when building without one.
+
+To build crust's scp.bin, you need an OpenRISC (or1k) cross compiler, 

then::

doc/board/allwinner/sunxi.rst line 62

Quoted 5 lines
doc/board/allwinner/sunxi.rst new file +5 -0
+
+  $ git clone https://github.com/crust-firmware/crust.git
+  $ cd crust
+  $ make <yourboard>_defconfig
+  $ make CROSS_COMPILE=or1k-none-elf- scp

I guess it would be good to point out that compiler prefix may not be the same on all distros. For example, Arch packages this compiler and proper prefix there is or1k-elf- which also works just fine.

Best regards,
Jernej

Quoted 19 lines
doc/board/allwinner/sunxi.rst new file +19 -0
+  $ export SCP=$(pwd)/build/scp/scp.bin
+
+Find a list of supported board configurations in the `configs/`_ directory.
+
+Building the U-Boot image
+-------------------------
+Find the U-Boot defconfig file for your board first. Those files live in
+the ``configs/`` directory; you can grep for the stub name of the devicetree
+file, if you know that, or for the SoC name to find the right version::
+
+    $ git grep -l MACH_SUN8I_H3 configs
+    $ git grep -l sun50i-h6-orangepi-3 configs
+
+The `linux-sunxi`_ wiki also lists the name of the defconfig file in the
+respective board page. Then use this defconfig file to create the .config
+file, and build the image::
+
+    $ make <yourboard>_defconfig
+    $ make -j5

doc/board/allwinner/sunxi.rst

Quoted 10 lines
doc/board/allwinner/sunxi.rst new file +10 -0
+
+For 64-bit boards, this requires either the BL31 environment variable to be
+set (as shown above in the TF-A build example), or it to be supplied on the
+build command line::
+
+    $ make BL31=/src/tf-a.git/build/sun50i_h616/debug/bl31.bin -j5 -s
+
+The same applies to the (optional) SCP firmware.
+
+The file containing everything you need is called ``u-boot-sunxi-with-

spl.bin``,

doc/board/allwinner/sunxi.rst

Quoted 3 lines
doc/board/allwinner/sunxi.rst new file +3 -0
+you will find it in the root folder of your U-Boot (build) tree. Except for
+raw NAND flash devices this very same file can be used for any boot source.
+It will contain the SPL image, fitted with the proper signature recognised 

by

doc/board/allwinner/sunxi.rst line 96

Quoted 2 lines
doc/board/allwinner/sunxi.rst new file +2 -0
+the BROM, and the required checksum. Also it will contain at least U-Boot
+proper, either wrapped in the legacy U-Boot image format, or in a FIT 

image.

doc/board/allwinner/sunxi.rst line 97

Quoted 1 line
doc/board/allwinner/sunxi.rst new file +1 -0
+The board's devicetree is also included, either appended to the U-Boot 

proper

doc/board/allwinner/sunxi.rst line 98

Quoted 1 line
doc/board/allwinner/sunxi.rst new file +1 -0
+image, or contained in the FIT image. If required by the SoC, this FIT file 

will

doc/board/allwinner/sunxi.rst

Quoted 10 lines
doc/board/allwinner/sunxi.rst new file +10 -0
+also include the other firmware images.
+
+Installing U-Boot
+-----------------
+
+Installing on a (micro-) SD card
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+All Allwinner SoCs will try to find a boot image at sector 16 (8KB) of
+an SD card, connected to the first MMC controller. To transfer the generated
+image to an SD card, from any Linux device (including the board itself) 

with

doc/board/allwinner/sunxi.rst

Quoted 9 lines
doc/board/allwinner/sunxi.rst new file +9 -0
+an (micro-)SD card reader, type::
+
+    # dd if=u-boot-sunxi-with-spl.bin of=/dev/sdX bs=1k seek=8
+
+``/dev/sdx`` needs to be replaced with the block device name of the SD card
+reader. On some machines this could be ``/dev/mmcblkX``.
+Newer SoCs (starting from H3), also look at sector 256 (128KB) for the
+signature (after having checked the 8KB location). Installing the firmware
+there has the advantage of not overlapping with a GPT partition table. 

Simply

doc/board/allwinner/sunxi.rst

Quoted 3 lines
doc/board/allwinner/sunxi.rst new file +3 -0
+replace the "``seek=8``" above with "``seek=128``".
+
+You can also use an existing (mainline) U-Boot to write to the SD card. 

Load

doc/board/allwinner/sunxi.rst line 121

Quoted 1 line
doc/board/allwinner/sunxi.rst new file +1 -0
+the generated U-Boot image somewhere into DRAM (via ``ext4load``, 

``fatload``,

doc/board/allwinner/sunxi.rst

Quoted 13 lines
doc/board/allwinner/sunxi.rst new file +13 -0
+or ``tftpboot``), then write to MMC device 0::
+
+    => fatload mmc 0:1 $kernel_addr_r u-boot-sunxi-with-spl.bin
+    => mmc dev 0
+    => mmc write $kernel_addr_r 0x10 0x7f0
+
+To use the alternative boot location on newer SoCs::
+
+    => mmc write $kernel_addr_r 0x100 0x700
+
+Installing on eMMC (on-board flash memory)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Some boards have a soldered eMMC chip, some other boards have an eMMC 

socket

doc/board/allwinner/sunxi.rst

Quoted 3 lines
doc/board/allwinner/sunxi.rst new file +3 -0
+to receive an optional eMMC module. U-Boot can be installed to those chips,
+to boot without an SD card inserted. The Boot-ROM can boot either from the
+regular user data partition, or from one of the separate eMMC boot 

partitions.

doc/board/allwinner/sunxi.rst

Quoted 8 lines
doc/board/allwinner/sunxi.rst new file +8 -0
+U-Boot can be installed either from a running Linux instance on the device,
+from a running (mainline) U-Boot, or via an adapter for the (removable)
+eMMC module.
+
+Installing on an eMMC user data partition from Linux
+````````````````````````````````````````````````````
+If you have a running Linux instance on the device, and have somehow copied
+over the image file to that device, you can write the image directly into 

the

doc/board/allwinner/sunxi.rst

Quoted 4 lines
doc/board/allwinner/sunxi.rst new file +4 -0
+eMMC device from there.
+Find the name of the block device file first, it is one of the
+``/dev/mmcblk<X>`` devices. eMMC devices typically also list a
+``/dev/mmcblk<X>boot0`` partition (see below), this helps you to tell it 

apart

doc/board/allwinner/sunxi.rst

Quoted 11 lines
doc/board/allwinner/sunxi.rst new file +11 -0
+from the SD card device.
+To install onto the user data partition::
+
+    # dd if=u-boot-sunxi-with-spl.bin of=/dev/dev/mmcblkX bs=1k seek=8
+
+Similar to SD cards, the BROM in newer SoCs (H3 and above) also checks
+sector 256 of an eMMC, so you can use "``seek=128``" as well.
+
+Installing on an eMMC boot partition from Linux
+```````````````````````````````````````````````
+In the following examples, ``/dev/mmcblkX`` needs to be replaced with the 

block

doc/board/allwinner/sunxi.rst line 162

Quoted 2 lines
doc/board/allwinner/sunxi.rst new file +2 -0
+device name of the eMMC device. The eMMC device can be recognised by also
+listing the boot partitions (``/dev/mmcblkXboot0``) in ``/proc/

partitions``.

Quoted 24 lines
doc/board/allwinner/sunxi.rst new file +24 -0
+
+To allow booting from one of the eMMC boot partitions, this one needs to be
+enabled first. This only needs to be done once, as this setting is
+persistent, even though the boot partition can be disabled or changed again
+any time later::
+
+    # apt-get install mmc-utils
+    # mmc bootbus set single_hs x1 x4 /dev/mmcblkX
+    # mmc bootpart enable 1 1 /dev/mmcblkX
+
+The first "1" in the last command points to the boot partition number to be
+used, typically devices offer two boot partitions.
+
+By default Linux disables write access to the boot partitions, to prevent
+accidental overwrites. You need to disable the write protection (until the
+next reboot), then can write the U-Boot image to the *first* sector of the
+selected boot partition::
+
+    # echo 0 > /sys/block/mmcblkXboot0/force_ro
+    # dd if=u-boot-sunxi-with-spl.bin of=/dev/mmcblkXboot0 bs=1k
+
+Installing on an eMMC user data partition from U-Boot
+`````````````````````````````````````````````````````
+You can also write the generated image file to an SD card, boot the device

doc/board/allwinner/sunxi.rst

Quoted 10 lines
doc/board/allwinner/sunxi.rst new file +10 -0
+from there, and burn the very same image to the eMMC device from U-Boot.
+The following commands copy the image from the SD card to the eMMC device::
+
+    => mmc dev 0
+    => mmc read $kernel_addr_r 0x10 0x7f0
+    => mmc dev 1
+    => mmc write $kernel_addr_r 0x10 0x7f0
+
+You can also copy an image from the 8K offset of an SD card to the 128K
+offset of the eMMC (or any combination), just change the "``0x10 0x7f0``" 

above

doc/board/allwinner/sunxi.rst line 197

Quoted 1 line
doc/board/allwinner/sunxi.rst new file +1 -0
+to "``0x100 0x700``", respectively. Of course the image file can be loaded 

via

doc/board/allwinner/sunxi.rst line 198

Quoted 1 line
doc/board/allwinner/sunxi.rst new file +1 -0
+any other loading method, including ``fatload``, ``ext4load``, 

``tftpboot``.

doc/board/allwinner/sunxi.rst

Quoted 12 lines
doc/board/allwinner/sunxi.rst new file +12 -0
+
+Installing on an eMMC boot partition from U-Boot
+````````````````````````````````````````````````
+The selected eMMC boot partition needs to be initially enabled first (same
+as in Linux above), you can do this from U-Boot with::
+
+    => mmc dev 1
+    => mmc bootbus 1 1 0 0
+    => mmc partconf 1 1 1 1
+
+The first "1" in both commands denotes the MMC device number. The second "1"
+in the partconf command sets the required ``BOOT_ACK`` option, the last two 

"1"s

doc/board/allwinner/sunxi.rst line 212

Quoted 2 lines
doc/board/allwinner/sunxi.rst new file +2 -0
+selects the active boot partition and the target for the next data access,
+respectively. So for the next "``mmc write``" command to address one of the 

boot

doc/board/allwinner/sunxi.rst line 213

Quoted 1 line
doc/board/allwinner/sunxi.rst new file +1 -0
+partitions, the last number must either be "1" or "2", "0" would switch 

(back)

doc/board/allwinner/sunxi.rst

Quoted 10 lines
doc/board/allwinner/sunxi.rst new file +10 -0
+to the normal user data partition.
+
+Then load the ``u-boot-sunxi-with-spl.bin`` image file into DRAM, either by
+reading directly from an SD card or eMMC user data partition, or from a
+file system or TFTP (see above), and transfer it to the boot partition::
+
+    => tftpboot $kernel_addr_r u-boot-sunxi-with-spl.bin
+    => mmc write $kernel_addr_r 0 0x7f0
+
+After that the device should boot from the selected boot partition, which 

takes

Quoted 10 lines
doc/board/allwinner/sunxi.rst new file +10 -0
+precedence over booting from the user data partition.
+
+Installing on SPI flash
+^^^^^^^^^^^^^^^^^^^^^^^
+Some devices have a SPI NOR flash chip soldered on the board. If it is
+connected to the SPI0 pins on PortC, the BROM can also boot from there.
+Typically the SPI flash has the lowest boot priority, so SD card and eMMC
+devices will be considered first.
+
+Installing on SPI flash from Linux

doc/board/allwinner/sunxi.rst

Quoted 10 lines
doc/board/allwinner/sunxi.rst new file +10 -0
+``````````````````````````````````
+If the devicetree enables and describes the SPI flash device, you can access
+the SPI flash content from Linux, using the `MTD utils`_::
+
+    # apt-get install mtd-utils
+    # mtdinfo
+    # mtd_debug erase /dev/mtdX 0 0xf0000
+    # mtd_debug write /dev/mtdX 0 0xf0000 u-boot-sunxi-with-spl.bin
+
+``/dev/mtdX`` needs to be replaced with the respective device name, as 

listed

doc/board/allwinner/sunxi.rst

Quoted 5 lines
doc/board/allwinner/sunxi.rst new file +5 -0
+in the output of ``mtdinfo``.
+
+Installing on SPI flash from U-Boot
+```````````````````````````````````
+If SPI flash driver and command support (``CONFIG_CMD_SF``) is enabled in 

the

doc/board/allwinner/sunxi.rst

Quoted 11 lines
doc/board/allwinner/sunxi.rst new file +11 -0
+U-Boot configuration, the image file can be installed via U-Boot as well::
+
+    => tftpboot $kernel_addr_r u-boot-sunxi-with-spl.bin
+    => sf probe
+    => sf erase 0 +0xf0000
+    => sf write $kernel_addr_r 0 $filesize
+
+Installing on SPI flash via USB in FEL mode
+```````````````````````````````````````````
+If the device is in FEL mode (see below), the SPI flash can also be filled
+with the sunxi-fel utility, via an USB(-OTG) cable from any USB host 

machine::

doc/board/allwinner/sunxi.rst

Quoted 8 lines
doc/board/allwinner/sunxi.rst new file +8 -0
+
+    $ sunxi-fel -v -p spiflash-write 0 u-boot-sunxi-with-spl.bin
+
+Booting via the USB(-OTG) FEL mode
+----------------------------------
+If none of the boot locations checked by the BROM contain a medium or valid
+signature, the BROM will enter the so-called FEL mode, in which it will
+listen to commands from a host on the SoC's USB-OTG interface. Those 

commands

doc/board/allwinner/sunxi.rst

Quoted 4 lines
doc/board/allwinner/sunxi.rst new file +4 -0
+allow to read from and write to arbitrary memory locations, also to start
+execution at any address, which allows to bootstrap a board solely via an
+USB cable. Some boards feature a "FEL" or "U-Boot" button, which forces
+FEL mode despite a valid boot location being present. The same can be 

achieved

doc/board/allwinner/sunxi.rst

Quoted 6 lines
doc/board/allwinner/sunxi.rst new file +6 -0
+via a `magic binary`_ on an SD card, which allows to enter FEL mode on any
+board.
+
+To use FEL booting, let the board enter FEL mode, via any of the mentioned
+methods (no boot media, FEL button, SD card with FEL binary), then connect
+a USB cable to the board's USB OTG port. Some boards (Pine64, TV boxes) 

don't

doc/board/allwinner/sunxi.rst

Quoted 10 lines
doc/board/allwinner/sunxi.rst new file +10 -0
+have a separate OTG port. In this case mostly one of the USB-A ports is
+connected to USB0, and can be used via a non-standard USB-A to USB-A cable.
+
+Typically there is no on-board indication of FEL mode, other than a new USB
+device appearing on the connected host computer. The USB vendor/device ID
+is 1f3a:efe8. Mostly this will identify as "sunxi SoC OTG connector in
+FEL/flashing mode", but older distributions might still report "Onda
+(unverified) V972 tablet in flashing mode".
+
+The `sunxi_fel`_ tool implements the proprietary BROM protocol, and allows 

to

doc/board/allwinner/sunxi.rst line 288

Quoted 1 line
doc/board/allwinner/sunxi.rst new file +1 -0
+bootstrap U-Boot by just providing our venerable u-boot-sunxi-with-

spl.bin::

doc/board/allwinner/sunxi.rst

Quoted 9 lines
doc/board/allwinner/sunxi.rst new file +9 -0
+
+    $ sudo apt-get install sunxi-tools
+    $ sunxi-fel -v -p uboot u-boot-sunxi-with-spl.bin
+
+Additional binaries like a kernel, an initial ramdisk or a boot script, can
+also be uploaded via FEL, check the Wiki's `FEL page`_ for more details.
+
+.. _`Arm Trusted Firmware-A`:  https://www.trustedfirmware.org/projects/tf-a/
+.. _`docs/plat/allwinner.rst`: https://trustedfirmware-a.readthedocs.io/en/

latest/plat/allwinner.html

doc/board/allwinner/sunxi.rst

Quoted 5 lines
doc/board/allwinner/sunxi.rst new file +5 -0
+.. _`crust`: https://github.com/crust-firmware/crust
+.. _`configs/`: https://github.com/crust-firmware/crust/tree/master/configs
+.. _`linux-sunxi`: https://linux-sunxi.org
+.. _`MTD utils`: http://www.linux-mtd.infradead.org/
+.. _`magic binary`: https://github.com/linux-sunxi/sunxi-tools/raw/master/

bin/fel-sdboot.sunxi

Quoted 6 lines
doc/board/allwinner/sunxi.rst new file +2 -0
+.. _`sunxi_fel`: https://github.com/linux-sunxi/sunxi-tools
+.. _`FEL page`: https://linux-sunxi.org/FEL/USBBoot
Signature · 1 line
2.17.6
#2 lore raw

On Mon, 13 Dec 2021 18:20:37 +0100
Jernej Škrabec <[email protected]> wrote:

Hi Jernej,

thanks for having a look!

Quoted 12 lines

Dne ponedeljek, 13. december 2021 ob 02:03:22 CET je Andre Przywara napisal(a):

Quoted 10 lines

Add some long overdue instructions for building and installing U-Boot on Allwinner SoC based boards.
This describes the building process, including TF-A and crust, plus installation to SD card, eMMC and SPI flash, both from Linux and U-Boot itself. Also describe FEL booting.

---
Hi,

Quoted 8 lines
Quoted 1 line

please have a look whether this makes sense. Feel free to just try

something,

Quoted 2 lines

and point out ambiguities or missing bits. For missing topics, please send a follow-up patch ;-)

This documentation seems to include all of board/sunxi/README.sunxi64 and README.nand. I think it would make sense to remove those files. If any file gets out of sync for any reason, it would be very confusing for end user.

Indeed, I think README.sunxi64 is redundant now.
I didn't look at README.nand too closely, but since I don't even mention NAND, I don't think it can be removed just yet. I guess I just convert it to RST and move it into this directory.

Quoted 4 lines

I would also remove all non-essential command parameters, so all commands are as simple as possible. Power users will know about them anyway and non-skilled users might perceive that it's harder that it really is. I have in mind "-j5 - s" for make, "-v -p" for sunxi-fel

I see, makes sense.

Quoted 4 lines

and DEBUG=1 for TF-A (maybe I missed some
places). Actually, DEBUG=1 could be mentioned afterwards as troubleshooting step. In my experience, stable version of TF-A was never source of boot issues nor it provided any useful information for debugging anything else.

Well, I'd tend to keep DEBUG=1 enabled, this lists the regulators enabled, which helps debugging. Also in the past DEBUG=0 was very silent, which wasn't helpful to verify that TF-A actually started.

Do you typically build or recommend DEBUG=0?

Quoted 59 lines

Some comments bellow.

Quoted 36 lines

Also this is quite long, shall this be split up in two (or more) files?

This is what rst.ninjs.org made of it, if you prefer to read it formatted:
https://paste.c-net.org/PleasantNeedy

Cheers,
Andre

 doc/board/allwinner/index.rst |   9 +
 doc/board/allwinner/sunxi.rst | 304 ++++++++++++++++++++++++++++++++++
 2 files changed, 313 insertions(+)
 create mode 100644 doc/board/allwinner/index.rst
 create mode 100644 doc/board/allwinner/sunxi.rst
doc/board/allwinner/index.rst new file +9 -0
new file mode 100644
index 00000000000..7352ccd5c0a
@@ -0,0 +1,9 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+Allwinner (sunxi) boards
+========================
+
+.. toctree::
+   :maxdepth: 2
+
+   sunxi
doc/board/allwinner/sunxi.rst new file +0 -0
new file mode 100644
index 00000000000..693eb32e168

doc/board/allwinner/sunxi.rst line 7

Quoted 7 lines
doc/board/allwinner/sunxi.rst new file +7 -0
@@ -0,0 +1,304 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. Copyright (C) 2021 Arm Ltd.
+
+Allwinner SoC based boards
+==========================
+For boards using an Allwinner ARM based SoC ("sunxi"), the U-Boot build
+system generates a single integrated image file: ``u-boot-sunxi-with-  

spl.bin.``

doc/board/allwinner/sunxi.rst

Quoted 4 lines
doc/board/allwinner/sunxi.rst new file +4 -0
+This file can be used on SD cards, eMMC devices, SPI flash and for the
+USB-OTG based boot method (FEL). To build this file:
+
+* For 64-bit SoCs, build Trusted Firmware (TF-A, formerly known as ATF)   

first,

doc/board/allwinner/sunxi.rst

Quoted 6 lines
doc/board/allwinner/sunxi.rst new file +6 -0
+  you will need its ``bl31.bin``. See below for more details.
+* Optionally on 64-bit SoCs, build the crust management processor firmware.
+* Build U-Boot::
+
+  $ export BL31=/path/to/bl31.bin		# required for 64-bit SoCs
+  $ export SCP=/src/crust/build/scp/scp.bin	# optional for some 64-bit  

SoCs

Quoted 1 line

NIT: I guess path for SCP could be in same form, at least first part?

Yeah, makes sense.

Quoted 9 lines

doc/board/allwinner/sunxi.rst line 22

Quoted 5 lines
doc/board/allwinner/sunxi.rst new file +5 -0
+  $ make <yourboardname>_defconfig
+  $ make -j5 -s
+* Transfer to an uSD card (see below for more details)::
+
+  $ dd if=u-boot-sunxi-with-spl.bin of=/dev/sdX bs=8k seek=1  

Most, if not all, distros require root for above command, so $ -> #? I see that you used # below. Alternative would be to prepend command with sudo, which is imo more beginners friendly.

Ah, good catch!

Quoted 45 lines

doc/board/allwinner/sunxi.rst

Quoted 3 lines
doc/board/allwinner/sunxi.rst new file +3 -0
+* Boot and enjoy!
+
+For more details, and alternative boot locations or installations, see   

below.

doc/board/allwinner/sunxi.rst

Quoted 4 lines
doc/board/allwinner/sunxi.rst new file +4 -0
+
+Building Arm Trusted Firmware (TF-A)
+------------------------------------
+Boards using a 64-bit Soc (A64, H5, H6, H616, R329) require the BL31 stage   

of

doc/board/allwinner/sunxi.rst

Quoted 10 lines
doc/board/allwinner/sunxi.rst new file +10 -0
+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::
+
+  $ 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
+  $ export BL31=$(pwd)/build/sun50i_a64/debug/bl31.bin
+
+The target platform (``PLAT=``) for A64 and H5 SoCs is sun50i_a64, for the   

H6

Quoted 8 lines
doc/board/allwinner/sunxi.rst new file +8 -0
+sun50i_h6, for the H616 sun50i_h616, and for the R329 sun50i_r329. Use::
+
+  $ find plat/allwinner -name platform.mk
+
+to find all supported platforms. `docs/plat/allwinner.rst`_ contains more
+information and lists some build options.
+
+Building the Crust management processor firmware

doc/board/allwinner/sunxi.rst

Quoted 10 lines
doc/board/allwinner/sunxi.rst new file +10 -0
+------------------------------------------------
+For some SoCs and boards, the integrated OpenRISC management controller can
+be used to provide power management services, foremost suspend to RAM.
+There is a community supported Open Source implementation called `crust`_,
+which runs on most SoCs featuring a management controller.
+
+This firmware part is optional, setting the SCP environment variable to
+/dev/null avoids the warning message when building without one.
+
+To build crust's scp.bin, you need an OpenRISC (or1k) cross compiler,   

then::

doc/board/allwinner/sunxi.rst line 62

Quoted 5 lines
doc/board/allwinner/sunxi.rst new file +5 -0
+
+  $ git clone https://github.com/crust-firmware/crust.git
+  $ cd crust
+  $ make <yourboard>_defconfig
+  $ make CROSS_COMPILE=or1k-none-elf- scp  
Quoted 3 lines

I guess it would be good to point out that compiler prefix may not be the same on all distros. For example, Arch packages this compiler and proper prefix there is or1k-elf- which also works just fine.

I feel I shouldn't spend too much time on this, instead just point to crust's README.

Thanks,
Andre

Quoted 285 lines

Best regards,
Jernej

Quoted 19 lines
doc/board/allwinner/sunxi.rst new file +19 -0
+  $ export SCP=$(pwd)/build/scp/scp.bin
+
+Find a list of supported board configurations in the `configs/`_ directory.
+
+Building the U-Boot image
+-------------------------
+Find the U-Boot defconfig file for your board first. Those files live in
+the ``configs/`` directory; you can grep for the stub name of the devicetree
+file, if you know that, or for the SoC name to find the right version::
+
+    $ git grep -l MACH_SUN8I_H3 configs
+    $ git grep -l sun50i-h6-orangepi-3 configs
+
+The `linux-sunxi`_ wiki also lists the name of the defconfig file in the
+respective board page. Then use this defconfig file to create the .config
+file, and build the image::
+
+    $ make <yourboard>_defconfig
+    $ make -j5

doc/board/allwinner/sunxi.rst

Quoted 10 lines
doc/board/allwinner/sunxi.rst new file +10 -0
+
+For 64-bit boards, this requires either the BL31 environment variable to be
+set (as shown above in the TF-A build example), or it to be supplied on the
+build command line::
+
+    $ make BL31=/src/tf-a.git/build/sun50i_h616/debug/bl31.bin -j5 -s
+
+The same applies to the (optional) SCP firmware.
+
+The file containing everything you need is called ``u-boot-sunxi-with-  

spl.bin``,

doc/board/allwinner/sunxi.rst

Quoted 3 lines
doc/board/allwinner/sunxi.rst new file +3 -0
+you will find it in the root folder of your U-Boot (build) tree. Except for
+raw NAND flash devices this very same file can be used for any boot source.
+It will contain the SPL image, fitted with the proper signature recognised   

by

doc/board/allwinner/sunxi.rst line 96

Quoted 2 lines
doc/board/allwinner/sunxi.rst new file +2 -0
+the BROM, and the required checksum. Also it will contain at least U-Boot
+proper, either wrapped in the legacy U-Boot image format, or in a FIT   

image.

doc/board/allwinner/sunxi.rst line 97

Quoted 1 line
doc/board/allwinner/sunxi.rst new file +1 -0
+The board's devicetree is also included, either appended to the U-Boot   

proper

doc/board/allwinner/sunxi.rst line 98

Quoted 1 line
doc/board/allwinner/sunxi.rst new file +1 -0
+image, or contained in the FIT image. If required by the SoC, this FIT file   

will

doc/board/allwinner/sunxi.rst

Quoted 10 lines
doc/board/allwinner/sunxi.rst new file +10 -0
+also include the other firmware images.
+
+Installing U-Boot
+-----------------
+
+Installing on a (micro-) SD card
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+All Allwinner SoCs will try to find a boot image at sector 16 (8KB) of
+an SD card, connected to the first MMC controller. To transfer the generated
+image to an SD card, from any Linux device (including the board itself)   

with

doc/board/allwinner/sunxi.rst

Quoted 9 lines
doc/board/allwinner/sunxi.rst new file +9 -0
+an (micro-)SD card reader, type::
+
+    # dd if=u-boot-sunxi-with-spl.bin of=/dev/sdX bs=1k seek=8
+
+``/dev/sdx`` needs to be replaced with the block device name of the SD card
+reader. On some machines this could be ``/dev/mmcblkX``.
+Newer SoCs (starting from H3), also look at sector 256 (128KB) for the
+signature (after having checked the 8KB location). Installing the firmware
+there has the advantage of not overlapping with a GPT partition table.   

Simply

doc/board/allwinner/sunxi.rst

Quoted 3 lines
doc/board/allwinner/sunxi.rst new file +3 -0
+replace the "``seek=8``" above with "``seek=128``".
+
+You can also use an existing (mainline) U-Boot to write to the SD card.   

Load

doc/board/allwinner/sunxi.rst line 121

Quoted 1 line
doc/board/allwinner/sunxi.rst new file +1 -0
+the generated U-Boot image somewhere into DRAM (via ``ext4load``,   

``fatload``,

doc/board/allwinner/sunxi.rst

Quoted 13 lines
doc/board/allwinner/sunxi.rst new file +13 -0
+or ``tftpboot``), then write to MMC device 0::
+
+    => fatload mmc 0:1 $kernel_addr_r u-boot-sunxi-with-spl.bin
+    => mmc dev 0
+    => mmc write $kernel_addr_r 0x10 0x7f0
+
+To use the alternative boot location on newer SoCs::
+
+    => mmc write $kernel_addr_r 0x100 0x700
+
+Installing on eMMC (on-board flash memory)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Some boards have a soldered eMMC chip, some other boards have an eMMC   

socket

doc/board/allwinner/sunxi.rst

Quoted 3 lines
doc/board/allwinner/sunxi.rst new file +3 -0
+to receive an optional eMMC module. U-Boot can be installed to those chips,
+to boot without an SD card inserted. The Boot-ROM can boot either from the
+regular user data partition, or from one of the separate eMMC boot   

partitions.

doc/board/allwinner/sunxi.rst

Quoted 8 lines
doc/board/allwinner/sunxi.rst new file +8 -0
+U-Boot can be installed either from a running Linux instance on the device,
+from a running (mainline) U-Boot, or via an adapter for the (removable)
+eMMC module.
+
+Installing on an eMMC user data partition from Linux
+````````````````````````````````````````````````````
+If you have a running Linux instance on the device, and have somehow copied
+over the image file to that device, you can write the image directly into   

the

doc/board/allwinner/sunxi.rst

Quoted 4 lines
doc/board/allwinner/sunxi.rst new file +4 -0
+eMMC device from there.
+Find the name of the block device file first, it is one of the
+``/dev/mmcblk<X>`` devices. eMMC devices typically also list a
+``/dev/mmcblk<X>boot0`` partition (see below), this helps you to tell it   

apart

doc/board/allwinner/sunxi.rst

Quoted 11 lines
doc/board/allwinner/sunxi.rst new file +11 -0
+from the SD card device.
+To install onto the user data partition::
+
+    # dd if=u-boot-sunxi-with-spl.bin of=/dev/dev/mmcblkX bs=1k seek=8
+
+Similar to SD cards, the BROM in newer SoCs (H3 and above) also checks
+sector 256 of an eMMC, so you can use "``seek=128``" as well.
+
+Installing on an eMMC boot partition from Linux
+```````````````````````````````````````````````
+In the following examples, ``/dev/mmcblkX`` needs to be replaced with the   

block

doc/board/allwinner/sunxi.rst line 162

Quoted 2 lines
doc/board/allwinner/sunxi.rst new file +2 -0
+device name of the eMMC device. The eMMC device can be recognised by also
+listing the boot partitions (``/dev/mmcblkXboot0``) in ``/proc/  

partitions``.

Quoted 24 lines
doc/board/allwinner/sunxi.rst new file +24 -0
+
+To allow booting from one of the eMMC boot partitions, this one needs to be
+enabled first. This only needs to be done once, as this setting is
+persistent, even though the boot partition can be disabled or changed again
+any time later::
+
+    # apt-get install mmc-utils
+    # mmc bootbus set single_hs x1 x4 /dev/mmcblkX
+    # mmc bootpart enable 1 1 /dev/mmcblkX
+
+The first "1" in the last command points to the boot partition number to be
+used, typically devices offer two boot partitions.
+
+By default Linux disables write access to the boot partitions, to prevent
+accidental overwrites. You need to disable the write protection (until the
+next reboot), then can write the U-Boot image to the *first* sector of the
+selected boot partition::
+
+    # echo 0 > /sys/block/mmcblkXboot0/force_ro
+    # dd if=u-boot-sunxi-with-spl.bin of=/dev/mmcblkXboot0 bs=1k
+
+Installing on an eMMC user data partition from U-Boot
+`````````````````````````````````````````````````````
+You can also write the generated image file to an SD card, boot the device

doc/board/allwinner/sunxi.rst

Quoted 10 lines
doc/board/allwinner/sunxi.rst new file +10 -0
+from there, and burn the very same image to the eMMC device from U-Boot.
+The following commands copy the image from the SD card to the eMMC device::
+
+    => mmc dev 0
+    => mmc read $kernel_addr_r 0x10 0x7f0
+    => mmc dev 1
+    => mmc write $kernel_addr_r 0x10 0x7f0
+
+You can also copy an image from the 8K offset of an SD card to the 128K
+offset of the eMMC (or any combination), just change the "``0x10 0x7f0``"   

above

doc/board/allwinner/sunxi.rst line 197

Quoted 1 line
doc/board/allwinner/sunxi.rst new file +1 -0
+to "``0x100 0x700``", respectively. Of course the image file can be loaded   

via

doc/board/allwinner/sunxi.rst line 198

Quoted 1 line
doc/board/allwinner/sunxi.rst new file +1 -0
+any other loading method, including ``fatload``, ``ext4load``,   

``tftpboot``.

doc/board/allwinner/sunxi.rst

Quoted 12 lines
doc/board/allwinner/sunxi.rst new file +12 -0
+
+Installing on an eMMC boot partition from U-Boot
+````````````````````````````````````````````````
+The selected eMMC boot partition needs to be initially enabled first (same
+as in Linux above), you can do this from U-Boot with::
+
+    => mmc dev 1
+    => mmc bootbus 1 1 0 0
+    => mmc partconf 1 1 1 1
+
+The first "1" in both commands denotes the MMC device number. The second "1"
+in the partconf command sets the required ``BOOT_ACK`` option, the last two   

"1"s

doc/board/allwinner/sunxi.rst line 212

Quoted 2 lines
doc/board/allwinner/sunxi.rst new file +2 -0
+selects the active boot partition and the target for the next data access,
+respectively. So for the next "``mmc write``" command to address one of the   

boot

doc/board/allwinner/sunxi.rst line 213

Quoted 1 line
doc/board/allwinner/sunxi.rst new file +1 -0
+partitions, the last number must either be "1" or "2", "0" would switch   

(back)

doc/board/allwinner/sunxi.rst

Quoted 10 lines
doc/board/allwinner/sunxi.rst new file +10 -0
+to the normal user data partition.
+
+Then load the ``u-boot-sunxi-with-spl.bin`` image file into DRAM, either by
+reading directly from an SD card or eMMC user data partition, or from a
+file system or TFTP (see above), and transfer it to the boot partition::
+
+    => tftpboot $kernel_addr_r u-boot-sunxi-with-spl.bin
+    => mmc write $kernel_addr_r 0 0x7f0
+
+After that the device should boot from the selected boot partition, which   

takes

Quoted 10 lines
doc/board/allwinner/sunxi.rst new file +10 -0
+precedence over booting from the user data partition.
+
+Installing on SPI flash
+^^^^^^^^^^^^^^^^^^^^^^^
+Some devices have a SPI NOR flash chip soldered on the board. If it is
+connected to the SPI0 pins on PortC, the BROM can also boot from there.
+Typically the SPI flash has the lowest boot priority, so SD card and eMMC
+devices will be considered first.
+
+Installing on SPI flash from Linux

doc/board/allwinner/sunxi.rst

Quoted 10 lines
doc/board/allwinner/sunxi.rst new file +10 -0
+``````````````````````````````````
+If the devicetree enables and describes the SPI flash device, you can access
+the SPI flash content from Linux, using the `MTD utils`_::
+
+    # apt-get install mtd-utils
+    # mtdinfo
+    # mtd_debug erase /dev/mtdX 0 0xf0000
+    # mtd_debug write /dev/mtdX 0 0xf0000 u-boot-sunxi-with-spl.bin
+
+``/dev/mtdX`` needs to be replaced with the respective device name, as   

listed

doc/board/allwinner/sunxi.rst

Quoted 5 lines
doc/board/allwinner/sunxi.rst new file +5 -0
+in the output of ``mtdinfo``.
+
+Installing on SPI flash from U-Boot
+```````````````````````````````````
+If SPI flash driver and command support (``CONFIG_CMD_SF``) is enabled in   

the

doc/board/allwinner/sunxi.rst

Quoted 11 lines
doc/board/allwinner/sunxi.rst new file +11 -0
+U-Boot configuration, the image file can be installed via U-Boot as well::
+
+    => tftpboot $kernel_addr_r u-boot-sunxi-with-spl.bin
+    => sf probe
+    => sf erase 0 +0xf0000
+    => sf write $kernel_addr_r 0 $filesize
+
+Installing on SPI flash via USB in FEL mode
+```````````````````````````````````````````
+If the device is in FEL mode (see below), the SPI flash can also be filled
+with the sunxi-fel utility, via an USB(-OTG) cable from any USB host   

machine::

doc/board/allwinner/sunxi.rst

Quoted 8 lines
doc/board/allwinner/sunxi.rst new file +8 -0
+
+    $ sunxi-fel -v -p spiflash-write 0 u-boot-sunxi-with-spl.bin
+
+Booting via the USB(-OTG) FEL mode
+----------------------------------
+If none of the boot locations checked by the BROM contain a medium or valid
+signature, the BROM will enter the so-called FEL mode, in which it will
+listen to commands from a host on the SoC's USB-OTG interface. Those   

commands

doc/board/allwinner/sunxi.rst

Quoted 4 lines
doc/board/allwinner/sunxi.rst new file +4 -0
+allow to read from and write to arbitrary memory locations, also to start
+execution at any address, which allows to bootstrap a board solely via an
+USB cable. Some boards feature a "FEL" or "U-Boot" button, which forces
+FEL mode despite a valid boot location being present. The same can be   

achieved

doc/board/allwinner/sunxi.rst

Quoted 6 lines
doc/board/allwinner/sunxi.rst new file +6 -0
+via a `magic binary`_ on an SD card, which allows to enter FEL mode on any
+board.
+
+To use FEL booting, let the board enter FEL mode, via any of the mentioned
+methods (no boot media, FEL button, SD card with FEL binary), then connect
+a USB cable to the board's USB OTG port. Some boards (Pine64, TV boxes)   

don't

doc/board/allwinner/sunxi.rst

Quoted 10 lines
doc/board/allwinner/sunxi.rst new file +10 -0
+have a separate OTG port. In this case mostly one of the USB-A ports is
+connected to USB0, and can be used via a non-standard USB-A to USB-A cable.
+
+Typically there is no on-board indication of FEL mode, other than a new USB
+device appearing on the connected host computer. The USB vendor/device ID
+is 1f3a:efe8. Mostly this will identify as "sunxi SoC OTG connector in
+FEL/flashing mode", but older distributions might still report "Onda
+(unverified) V972 tablet in flashing mode".
+
+The `sunxi_fel`_ tool implements the proprietary BROM protocol, and allows   

to

doc/board/allwinner/sunxi.rst line 288

Quoted 1 line
doc/board/allwinner/sunxi.rst new file +1 -0
+bootstrap U-Boot by just providing our venerable u-boot-sunxi-with-  

spl.bin::

doc/board/allwinner/sunxi.rst

Quoted 9 lines
doc/board/allwinner/sunxi.rst new file +9 -0
+
+    $ sudo apt-get install sunxi-tools
+    $ sunxi-fel -v -p uboot u-boot-sunxi-with-spl.bin
+
+Additional binaries like a kernel, an initial ramdisk or a boot script, can
+also be uploaded via FEL, check the Wiki's `FEL page`_ for more details.
+
+.. _`Arm Trusted Firmware-A`:  https://www.trustedfirmware.org/projects/tf-a/
+.. _`docs/plat/allwinner.rst`: https://trustedfirmware-a.readthedocs.io/en/  

latest/plat/allwinner.html

doc/board/allwinner/sunxi.rst

Quoted 5 lines
doc/board/allwinner/sunxi.rst new file +5 -0
+.. _`crust`: https://github.com/crust-firmware/crust
+.. _`configs/`: https://github.com/crust-firmware/crust/tree/master/configs
+.. _`linux-sunxi`: https://linux-sunxi.org
+.. _`MTD utils`: http://www.linux-mtd.infradead.org/
+.. _`magic binary`: https://github.com/linux-sunxi/sunxi-tools/raw/master/  

bin/fel-sdboot.sunxi

Quoted 6 lines
doc/board/allwinner/sunxi.rst new file +2 -0
+.. _`sunxi_fel`: https://github.com/linux-sunxi/sunxi-tools
+.. _`FEL page`: https://linux-sunxi.org/FEL/USBBoot
Signature · 1 line
2.17.6
maintainer
#3 lore raw

Dne torek, 14. december 2021 ob 02:07:58 CET je Andre Przywara napisal(a):

Quoted 26 lines

On Mon, 13 Dec 2021 18:20:37 +0100
Jernej Škrabec <[email protected]> wrote:

Hi Jernej,

thanks for having a look!

Quoted 19 lines

Dne ponedeljek, 13. december 2021 ob 02:03:22 CET je Andre Przywara napisal(a):

Quoted 11 lines

Add some long overdue instructions for building and installing U-Boot on Allwinner SoC based boards.
This describes the building process, including TF-A and crust, plus installation to SD card, eMMC and SPI flash, both from Linux and U-Boot itself. Also describe FEL booting.

---
Hi,

please have a look whether this makes sense. Feel free to just try

something,

Quoted 2 lines

and point out ambiguities or missing bits. For missing topics, please send a follow-up patch ;-)

This documentation seems to include all of board/sunxi/README.sunxi64 and README.nand. I think it would make sense to remove those files. If any file

gets

Quoted 8 lines
Quoted 1 line

out of sync for any reason, it would be very confusing for end user.

Indeed, I think README.sunxi64 is redundant now.
I didn't look at README.nand too closely, but since I don't even mention NAND, I don't think it can be removed just yet. I guess I just convert it to RST and move it into this directory.

Quoted 1 line

I would also remove all non-essential command parameters, so all commands

are

Quoted 1 line
Quoted 1 line

as simple as possible. Power users will know about them anyway and non-

skilled

Quoted 1 line
Quoted 1 line

users might perceive that it's harder that it really is. I have in mind "-

j5 -

Quoted 6 lines
Quoted 1 line

s" for make, "-v -p" for sunxi-fel

I see, makes sense.

Quoted 2 lines

and DEBUG=1 for TF-A (maybe I missed some
places). Actually, DEBUG=1 could be mentioned afterwards as

troubleshooting

Quoted 1 line
Quoted 1 line

step. In my experience, stable version of TF-A was never source of boot

issues

Quoted 5 lines
Quoted 1 line

nor it provided any useful information for debugging anything else.

Well, I'd tend to keep DEBUG=1 enabled, this lists the regulators enabled, which helps debugging. Also in the past DEBUG=0 was very silent, which wasn't helpful to verify that TF-A actually started.

I patched out enabling regulators in TF-A, we already discussed this in the past.

Quoted 2 lines

Do you typically build or recommend DEBUG=0?

I set DEBUG=1 only when I actually want to debug this part of boot process, which is very rarely. I don't remember that I would help anyone with building TF-A, so I don't make recommendations in either direction. For LibreELEC, we build it with DEBUG=0, unless debug build of ATF package was requested. Again, basically never. Release images are build with DEBUG=0. Note that based on my experience, many LibreELEC users don't actually own serial adapter, so it doesn't really matter what U-Boot and TF-A print out. Fortunatelly, boot issues in LE are very rare these days (I don't remember last time someone reported it).

Best regards,
Jernej

Quoted 7 lines
Quoted 7 lines

Some comments bellow.

Quoted 4 lines

Also this is quite long, shall this be split up in two (or more) files?

This is what rst.ninjs.org made of it, if you prefer to read it

formatted:

Quoted 5 lines
Quoted 5 lines
Quoted 5 lines

https://paste.c-net.org/PleasantNeedy

Cheers,
Andre

Quoted 7 lines
Quoted 7 lines

doc/board/allwinner/

Quoted 7 lines
 doc/board/allwinner/index.rst |   9 +
 doc/board/allwinner/sunxi.rst | 304 ++++++++++++++++++++++++++++++++++
 2 files changed, 313 insertions(+)
 create mode 100644 doc/board/allwinner/index.rst
 create mode 100644 doc/board/allwinner/sunxi.rst
doc/board/allwinner/ renamed from doc/board/allwinner/index.rst +0 -0

index.rst

Quoted 7 lines
Quoted 7 lines
Quoted 7 lines

new file mode 100644
index 00000000000..7352ccd5c0a

doc/board/allwinner/index.rst new file +2 -0
@@ -0,0 +1,9 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
Quoted 8 lines
Quoted 8 lines

doc/board/allwinner/

Quoted 8 lines
doc/board/allwinner/index.rst new file +7 -0
+Allwinner (sunxi) boards
+========================
+
+.. toctree::
+   :maxdepth: 2
+
+   sunxi
doc/board/allwinner/ renamed from doc/board/allwinner/sunxi.rst +0 -0

sunxi.rst

Quoted 13 lines
Quoted 13 lines

doc/board/allwinner/sunxi.rst line 7

Quoted 12 lines

new file mode 100644
index 00000000000..693eb32e168

doc/board/allwinner/sunxi.rst new file +7 -0
@@ -0,0 +1,304 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. Copyright (C) 2021 Arm Ltd.
+
+Allwinner SoC based boards
+==========================
+For boards using an Allwinner ARM based SoC ("sunxi"), the U-Boot build
+system generates a single integrated image file: ``u-boot-sunxi-with-  

spl.bin.``

Quoted 7 lines
Quoted 7 lines

doc/board/allwinner/sunxi.rst

Quoted 4 lines
doc/board/allwinner/sunxi.rst new file +4 -0
+This file can be used on SD cards, eMMC devices, SPI flash and for the
+USB-OTG based boot method (FEL). To build this file:
+
+* For 64-bit SoCs, build Trusted Firmware (TF-A, formerly known as ATF)   

first,

Quoted 2 lines
doc/board/allwinner/sunxi.rst new file +2 -0
+  you will need its ``bl31.bin``. See below for more details.
+* Optionally on 64-bit SoCs, build the crust management processor 

firmware.

Quoted 3 lines
Quoted 3 lines

doc/board/allwinner/sunxi.rst

Quoted 3 lines
doc/board/allwinner/sunxi.rst new file +3 -0
+* Build U-Boot::
+
+  $ export BL31=/path/to/bl31.bin		# required for 

64-bit SoCs

Quoted 1 line
Quoted 1 line

doc/board/allwinner/sunxi.rst line 17

Quoted 1 line
doc/board/allwinner/sunxi.rst new file +1 -0
+  $ export SCP=/src/crust/build/scp/scp.bin	# optional for some 64-

bit

Quoted 18 lines
Quoted 3 lines

SoCs

NIT: I guess path for SCP could be in same form, at least first part?

Yeah, makes sense.

Quoted 9 lines

doc/board/allwinner/sunxi.rst line 22

Quoted 5 lines
doc/board/allwinner/sunxi.rst new file +5 -0
+  $ make <yourboardname>_defconfig
+  $ make -j5 -s
+* Transfer to an uSD card (see below for more details)::
+
+  $ dd if=u-boot-sunxi-with-spl.bin of=/dev/sdX bs=8k seek=1  

Most, if not all, distros require root for above command, so $ -> #? I see that you used # below. Alternative would be to prepend command with sudo, which is imo more beginners friendly.

Ah, good catch!

Quoted 8 lines
Quoted 8 lines

doc/board/allwinner/sunxi.rst

Quoted 3 lines
doc/board/allwinner/sunxi.rst new file +3 -0
+* Boot and enjoy!
+
+For more details, and alternative boot locations or installations, see   

below.

doc/board/allwinner/sunxi.rst

Quoted 4 lines
doc/board/allwinner/sunxi.rst new file +4 -0
+
+Building Arm Trusted Firmware (TF-A)
+------------------------------------
+Boards using a 64-bit Soc (A64, H5, H6, H616, R329) require the BL31 

stage

Quoted 11 lines
Quoted 11 lines

of

doc/board/allwinner/sunxi.rst

Quoted 10 lines
doc/board/allwinner/sunxi.rst new file +10 -0
+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::
+
+  $ 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
+  $ export BL31=$(pwd)/build/sun50i_a64/debug/bl31.bin
+
+The target platform (``PLAT=``) for A64 and H5 SoCs is sun50i_a64, for 

the

Quoted 2 lines
Quoted 2 lines

H6

Quoted 1 line
doc/board/allwinner/sunxi.rst new file +1 -0
+sun50i_h6, for the H616 sun50i_h616, and for the R329 sun50i_r329. 

Use::

Quoted 4 lines
Quoted 4 lines

doc/board/allwinner/sunxi.rst

Quoted 4 lines
doc/board/allwinner/sunxi.rst new file +4 -0
+
+  $ find plat/allwinner -name platform.mk
+
+to find all supported platforms. `docs/plat/allwinner.rst`_ contains 

more

Quoted 5 lines
Quoted 5 lines

doc/board/allwinner/sunxi.rst

Quoted 5 lines
doc/board/allwinner/sunxi.rst new file +5 -0
+information and lists some build options.
+
+Building the Crust management processor firmware
+------------------------------------------------
+For some SoCs and boards, the integrated OpenRISC management controller 

can

Quoted 2 lines
Quoted 2 lines

doc/board/allwinner/sunxi.rst line 51

Quoted 2 lines
doc/board/allwinner/sunxi.rst new file +2 -0
+be used to provide power management services, foremost suspend to RAM.
+There is a community supported Open Source implementation called 

crust_,

Quoted 7 lines
Quoted 7 lines

doc/board/allwinner/sunxi.rst

Quoted 6 lines
doc/board/allwinner/sunxi.rst new file +6 -0
+which runs on most SoCs featuring a management controller.
+
+This firmware part is optional, setting the SCP environment variable to
+/dev/null avoids the warning message when building without one.
+
+To build crust's scp.bin, you need an OpenRISC (or1k) cross compiler,   

then::

Quoted 7 lines
Quoted 7 lines

doc/board/allwinner/sunxi.rst line 62

Quoted 5 lines
doc/board/allwinner/sunxi.rst new file +5 -0
+
+  $ git clone https://github.com/crust-firmware/crust.git
+  $ cd crust
+  $ make <yourboard>_defconfig
+  $ make CROSS_COMPILE=or1k-none-elf- scp  

I guess it would be good to point out that compiler prefix may not be the

same

Quoted 10 lines
Quoted 2 lines

on all distros. For example, Arch packages this compiler and proper prefix there is or1k-elf- which also works just fine.

I feel I shouldn't spend too much time on this, instead just point to crust's README.

Thanks,
Andre

Quoted 1 line
Quoted 6 lines
Quoted 6 lines

Best regards,
Jernej

doc/board/allwinner/sunxi.rst

Quoted 3 lines
doc/board/allwinner/sunxi.rst new file +3 -0
+  $ export SCP=$(pwd)/build/scp/scp.bin
+
+Find a list of supported board configurations in the `configs/`_ 

directory.

Quoted 5 lines
Quoted 5 lines

doc/board/allwinner/sunxi.rst

Quoted 5 lines
doc/board/allwinner/sunxi.rst new file +5 -0
+
+Building the U-Boot image
+-------------------------
+Find the U-Boot defconfig file for your board first. Those files live in
+the ``configs/`` directory; you can grep for the stub name of the 

devicetree

Quoted 5 lines
Quoted 5 lines
Quoted 5 lines
doc/board/allwinner/sunxi.rst new file +5 -0
+file, if you know that, or for the SoC name to find the right version::
+
+    $ git grep -l MACH_SUN8I_H3 configs
+    $ git grep -l sun50i-h6-orangepi-3 configs
+
Quoted 8 lines
Quoted 8 lines

doc/board/allwinner/sunxi.rst

Quoted 8 lines
doc/board/allwinner/sunxi.rst new file +8 -0
+The `linux-sunxi`_ wiki also lists the name of the defconfig file in the
+respective board page. Then use this defconfig file to create the .config
+file, and build the image::
+
+    $ make <yourboard>_defconfig
+    $ make -j5
+
+For 64-bit boards, this requires either the BL31 environment variable 

to be

Quoted 1 line
Quoted 1 line

doc/board/allwinner/sunxi.rst line 84

Quoted 1 line
doc/board/allwinner/sunxi.rst new file +1 -0
+set (as shown above in the TF-A build example), or it to be supplied on 

the

Quoted 9 lines
Quoted 9 lines

doc/board/allwinner/sunxi.rst

Quoted 7 lines
doc/board/allwinner/sunxi.rst new file +7 -0
+build command line::
+
+    $ make BL31=/src/tf-a.git/build/sun50i_h616/debug/bl31.bin -j5 -s
+
+The same applies to the (optional) SCP firmware.
+
+The file containing everything you need is called ``u-boot-sunxi-with-  

spl.bin``,

Quoted 1 line
doc/board/allwinner/sunxi.rst new file +1 -0
+you will find it in the root folder of your U-Boot (build) tree. Except 

for

Quoted 1 line
Quoted 1 line

doc/board/allwinner/sunxi.rst line 93

Quoted 1 line
doc/board/allwinner/sunxi.rst new file +1 -0
+raw NAND flash devices this very same file can be used for any boot 

source.

Quoted 1 line
Quoted 1 line

doc/board/allwinner/sunxi.rst line 94

Quoted 1 line
doc/board/allwinner/sunxi.rst new file +1 -0
+It will contain the SPL image, fitted with the proper signature 

recognised

Quoted 2 lines
Quoted 2 lines

by

Quoted 1 line
doc/board/allwinner/sunxi.rst new file +1 -0
+the BROM, and the required checksum. Also it will contain at least U-

Boot

Quoted 5 lines
Quoted 5 lines

doc/board/allwinner/sunxi.rst line 96

Quoted 1 line
doc/board/allwinner/sunxi.rst new file +1 -0
+proper, either wrapped in the legacy U-Boot image format, or in a FIT   

image.

doc/board/allwinner/sunxi.rst line 97

Quoted 1 line
doc/board/allwinner/sunxi.rst new file +1 -0
+The board's devicetree is also included, either appended to the U-Boot   

proper

Quoted 1 line
doc/board/allwinner/sunxi.rst new file +1 -0
+image, or contained in the FIT image. If required by the SoC, this FIT 

file

Quoted 10 lines
Quoted 10 lines

will

doc/board/allwinner/sunxi.rst

Quoted 9 lines
doc/board/allwinner/sunxi.rst new file +9 -0
+also include the other firmware images.
+
+Installing U-Boot
+-----------------
+
+Installing on a (micro-) SD card
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+All Allwinner SoCs will try to find a boot image at sector 16 (8KB) of
+an SD card, connected to the first MMC controller. To transfer the 

generated

Quoted 7 lines
Quoted 7 lines

doc/board/allwinner/sunxi.rst line 108

Quoted 1 line
doc/board/allwinner/sunxi.rst new file +1 -0
+image to an SD card, from any Linux device (including the board itself)   

with

doc/board/allwinner/sunxi.rst

Quoted 5 lines
doc/board/allwinner/sunxi.rst new file +5 -0
+an (micro-)SD card reader, type::
+
+    # dd if=u-boot-sunxi-with-spl.bin of=/dev/sdX bs=1k seek=8
+
+``/dev/sdx`` needs to be replaced with the block device name of the SD 

card

Quoted 3 lines
Quoted 3 lines

doc/board/allwinner/sunxi.rst

Quoted 3 lines
doc/board/allwinner/sunxi.rst new file +3 -0
+reader. On some machines this could be ``/dev/mmcblkX``.
+Newer SoCs (starting from H3), also look at sector 256 (128KB) for the
+signature (after having checked the 8KB location). Installing the 

firmware

Quoted 22 lines
Quoted 22 lines

doc/board/allwinner/sunxi.rst line 117

Quoted 1 line
doc/board/allwinner/sunxi.rst new file +1 -0
+there has the advantage of not overlapping with a GPT partition table.   

Simply

doc/board/allwinner/sunxi.rst

Quoted 3 lines
doc/board/allwinner/sunxi.rst new file +3 -0
+replace the "``seek=8``" above with "``seek=128``".
+
+You can also use an existing (mainline) U-Boot to write to the SD card.   

Load

doc/board/allwinner/sunxi.rst line 121

Quoted 1 line
doc/board/allwinner/sunxi.rst new file +1 -0
+the generated U-Boot image somewhere into DRAM (via ``ext4load``,   

``fatload``,

doc/board/allwinner/sunxi.rst

Quoted 13 lines
doc/board/allwinner/sunxi.rst new file +13 -0
+or ``tftpboot``), then write to MMC device 0::
+
+    => fatload mmc 0:1 $kernel_addr_r u-boot-sunxi-with-spl.bin
+    => mmc dev 0
+    => mmc write $kernel_addr_r 0x10 0x7f0
+
+To use the alternative boot location on newer SoCs::
+
+    => mmc write $kernel_addr_r 0x100 0x700
+
+Installing on eMMC (on-board flash memory)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Some boards have a soldered eMMC chip, some other boards have an eMMC   

socket

Quoted 1 line
Quoted 1 line

doc/board/allwinner/sunxi.rst line 135

Quoted 1 line
doc/board/allwinner/sunxi.rst new file +1 -0
+to receive an optional eMMC module. U-Boot can be installed to those 

chips,

Quoted 1 line
Quoted 1 line

doc/board/allwinner/sunxi.rst line 136

Quoted 1 line
doc/board/allwinner/sunxi.rst new file +1 -0
+to boot without an SD card inserted. The Boot-ROM can boot either from 

the

Quoted 3 lines
Quoted 3 lines

doc/board/allwinner/sunxi.rst line 137

Quoted 1 line
doc/board/allwinner/sunxi.rst new file +1 -0
+regular user data partition, or from one of the separate eMMC boot   

partitions.

Quoted 1 line
doc/board/allwinner/sunxi.rst new file +1 -0
+U-Boot can be installed either from a running Linux instance on the 

device,

Quoted 6 lines
Quoted 6 lines

doc/board/allwinner/sunxi.rst

Quoted 6 lines
doc/board/allwinner/sunxi.rst new file +6 -0
+from a running (mainline) U-Boot, or via an adapter for the (removable)
+eMMC module.
+
+Installing on an eMMC user data partition from Linux
+````````````````````````````````````````````````````
+If you have a running Linux instance on the device, and have somehow 

copied

Quoted 1 line
Quoted 1 line

doc/board/allwinner/sunxi.rst line 145

Quoted 1 line
doc/board/allwinner/sunxi.rst new file +1 -0
+over the image file to that device, you can write the image directly 

into

Quoted 5 lines
Quoted 5 lines

the

doc/board/allwinner/sunxi.rst

Quoted 4 lines
doc/board/allwinner/sunxi.rst new file +4 -0
+eMMC device from there.
+Find the name of the block device file first, it is one of the
+``/dev/mmcblk<X>`` devices. eMMC devices typically also list a
+``/dev/mmcblk<X>boot0`` partition (see below), this helps you to tell 

it

Quoted 12 lines
Quoted 12 lines

apart

doc/board/allwinner/sunxi.rst

Quoted 11 lines
doc/board/allwinner/sunxi.rst new file +11 -0
+from the SD card device.
+To install onto the user data partition::
+
+    # dd if=u-boot-sunxi-with-spl.bin of=/dev/dev/mmcblkX bs=1k seek=8
+
+Similar to SD cards, the BROM in newer SoCs (H3 and above) also checks
+sector 256 of an eMMC, so you can use "``seek=128``" as well.
+
+Installing on an eMMC boot partition from Linux
+```````````````````````````````````````````````
+In the following examples, ``/dev/mmcblkX`` needs to be replaced with 

the

Quoted 2 lines
Quoted 2 lines

block

Quoted 1 line
doc/board/allwinner/sunxi.rst new file +1 -0
+device name of the eMMC device. The eMMC device can be recognised by 

also

Quoted 4 lines
Quoted 4 lines

doc/board/allwinner/sunxi.rst line 162

Quoted 1 line
doc/board/allwinner/sunxi.rst new file +1 -0
+listing the boot partitions (``/dev/mmcblkXboot0``) in ``/proc/  

partitions``.

doc/board/allwinner/sunxi.rst line 164

Quoted 2 lines
doc/board/allwinner/sunxi.rst new file +2 -0
+
+To allow booting from one of the eMMC boot partitions, this one needs 

to be

Quoted 2 lines
Quoted 2 lines

doc/board/allwinner/sunxi.rst line 166

Quoted 2 lines
doc/board/allwinner/sunxi.rst new file +2 -0
+enabled first. This only needs to be done once, as this setting is
+persistent, even though the boot partition can be disabled or changed 

again

Quoted 7 lines
Quoted 7 lines

doc/board/allwinner/sunxi.rst

Quoted 7 lines
doc/board/allwinner/sunxi.rst new file +7 -0
+any time later::
+
+    # apt-get install mmc-utils
+    # mmc bootbus set single_hs x1 x4 /dev/mmcblkX
+    # mmc bootpart enable 1 1 /dev/mmcblkX
+
+The first "1" in the last command points to the boot partition number to 

be

Quoted 3 lines
Quoted 3 lines

doc/board/allwinner/sunxi.rst

Quoted 3 lines
doc/board/allwinner/sunxi.rst new file +3 -0
+used, typically devices offer two boot partitions.
+
+By default Linux disables write access to the boot partitions, to 

prevent

Quoted 1 line
Quoted 1 line

doc/board/allwinner/sunxi.rst line 177

Quoted 1 line
doc/board/allwinner/sunxi.rst new file +1 -0
+accidental overwrites. You need to disable the write protection (until 

the

Quoted 1 line
Quoted 1 line

doc/board/allwinner/sunxi.rst line 178

Quoted 1 line
doc/board/allwinner/sunxi.rst new file +1 -0
+next reboot), then can write the U-Boot image to the *first* sector of 

the

Quoted 8 lines
Quoted 8 lines

doc/board/allwinner/sunxi.rst

Quoted 8 lines
doc/board/allwinner/sunxi.rst new file +8 -0
+selected boot partition::
+
+    # echo 0 > /sys/block/mmcblkXboot0/force_ro
+    # dd if=u-boot-sunxi-with-spl.bin of=/dev/mmcblkXboot0 bs=1k
+
+Installing on an eMMC user data partition from U-Boot
+`````````````````````````````````````````````````````
+You can also write the generated image file to an SD card, boot the 

device

Quoted 1 line
Quoted 1 line

doc/board/allwinner/sunxi.rst line 187

Quoted 1 line
doc/board/allwinner/sunxi.rst new file +1 -0
+from there, and burn the very same image to the eMMC device from U-

Boot.

Quoted 1 line
Quoted 1 line

doc/board/allwinner/sunxi.rst line 188

Quoted 1 line
doc/board/allwinner/sunxi.rst new file +1 -0
+The following commands copy the image from the SD card to the eMMC 

device::

Quoted 8 lines
Quoted 8 lines

doc/board/allwinner/sunxi.rst

Quoted 8 lines
doc/board/allwinner/sunxi.rst new file +8 -0
+
+    => mmc dev 0
+    => mmc read $kernel_addr_r 0x10 0x7f0
+    => mmc dev 1
+    => mmc write $kernel_addr_r 0x10 0x7f0
+
+You can also copy an image from the 8K offset of an SD card to the 128K
+offset of the eMMC (or any combination), just change the "``0x10 

0x7f0``"

Quoted 2 lines
Quoted 2 lines

above

Quoted 1 line
doc/board/allwinner/sunxi.rst new file +1 -0
+to "``0x100 0x700``", respectively. Of course the image file can be 

loaded

Quoted 7 lines
Quoted 7 lines

via

doc/board/allwinner/sunxi.rst line 198

Quoted 1 line
doc/board/allwinner/sunxi.rst new file +1 -0
+any other loading method, including ``fatload``, ``ext4load``,   

``tftpboot``.

doc/board/allwinner/sunxi.rst

Quoted 4 lines
doc/board/allwinner/sunxi.rst new file +4 -0
+
+Installing on an eMMC boot partition from U-Boot
+````````````````````````````````````````````````
+The selected eMMC boot partition needs to be initially enabled first 

(same

Quoted 7 lines
Quoted 7 lines

doc/board/allwinner/sunxi.rst

Quoted 7 lines
doc/board/allwinner/sunxi.rst new file +7 -0
+as in Linux above), you can do this from U-Boot with::
+
+    => mmc dev 1
+    => mmc bootbus 1 1 0 0
+    => mmc partconf 1 1 1 1
+
+The first "1" in both commands denotes the MMC device number. The second 

"1"

Quoted 1 line
Quoted 1 line

doc/board/allwinner/sunxi.rst line 210

Quoted 1 line
doc/board/allwinner/sunxi.rst new file +1 -0
+in the partconf command sets the required ``BOOT_ACK`` option, the last 

two

Quoted 2 lines
Quoted 2 lines

"1"s

Quoted 1 line
doc/board/allwinner/sunxi.rst new file +1 -0
+selects the active boot partition and the target for the next data 

access,

Quoted 1 line
Quoted 1 line

doc/board/allwinner/sunxi.rst line 212

Quoted 1 line
doc/board/allwinner/sunxi.rst new file +1 -0
+respectively. So for the next "``mmc write``" command to address one of 

the

Quoted 6 lines
Quoted 6 lines

boot

doc/board/allwinner/sunxi.rst line 213

Quoted 1 line
doc/board/allwinner/sunxi.rst new file +1 -0
+partitions, the last number must either be "1" or "2", "0" would switch   

(back)

doc/board/allwinner/sunxi.rst

Quoted 3 lines
doc/board/allwinner/sunxi.rst new file +3 -0
+to the normal user data partition.
+
+Then load the ``u-boot-sunxi-with-spl.bin`` image file into DRAM, either 

by

Quoted 7 lines
Quoted 7 lines

doc/board/allwinner/sunxi.rst

Quoted 7 lines
doc/board/allwinner/sunxi.rst new file +7 -0
+reading directly from an SD card or eMMC user data partition, or from a
+file system or TFTP (see above), and transfer it to the boot partition::
+
+    => tftpboot $kernel_addr_r u-boot-sunxi-with-spl.bin
+    => mmc write $kernel_addr_r 0 0x7f0
+
+After that the device should boot from the selected boot partition, 

which

Quoted 8 lines
Quoted 8 lines

takes

doc/board/allwinner/sunxi.rst

Quoted 7 lines
doc/board/allwinner/sunxi.rst new file +7 -0
+precedence over booting from the user data partition.
+
+Installing on SPI flash
+^^^^^^^^^^^^^^^^^^^^^^^
+Some devices have a SPI NOR flash chip soldered on the board. If it is
+connected to the SPI0 pins on PortC, the BROM can also boot from there.
+Typically the SPI flash has the lowest boot priority, so SD card and 

eMMC

Quoted 5 lines
Quoted 5 lines

doc/board/allwinner/sunxi.rst

Quoted 5 lines
doc/board/allwinner/sunxi.rst new file +5 -0
+devices will be considered first.
+
+Installing on SPI flash from Linux
+``````````````````````````````````
+If the devicetree enables and describes the SPI flash device, you can 

access

Quoted 9 lines
Quoted 9 lines

doc/board/allwinner/sunxi.rst

Quoted 8 lines
doc/board/allwinner/sunxi.rst new file +8 -0
+the SPI flash content from Linux, using the `MTD utils`_::
+
+    # apt-get install mtd-utils
+    # mtdinfo
+    # mtd_debug erase /dev/mtdX 0 0xf0000
+    # mtd_debug write /dev/mtdX 0 0xf0000 u-boot-sunxi-with-spl.bin
+
+``/dev/mtdX`` needs to be replaced with the respective device name, as   

listed

Quoted 5 lines
Quoted 5 lines

doc/board/allwinner/sunxi.rst

Quoted 5 lines
doc/board/allwinner/sunxi.rst new file +5 -0
+in the output of ``mtdinfo``.
+
+Installing on SPI flash from U-Boot
+```````````````````````````````````
+If SPI flash driver and command support (``CONFIG_CMD_SF``) is enabled 

in

Quoted 2 lines
Quoted 2 lines

the

Quoted 1 line
doc/board/allwinner/sunxi.rst new file +1 -0
+U-Boot configuration, the image file can be installed via U-Boot as 

well::

Quoted 9 lines
Quoted 9 lines

doc/board/allwinner/sunxi.rst

Quoted 9 lines
doc/board/allwinner/sunxi.rst new file +9 -0
+
+    => tftpboot $kernel_addr_r u-boot-sunxi-with-spl.bin
+    => sf probe
+    => sf erase 0 +0xf0000
+    => sf write $kernel_addr_r 0 $filesize
+
+Installing on SPI flash via USB in FEL mode
+```````````````````````````````````````````
+If the device is in FEL mode (see below), the SPI flash can also be 

filled

Quoted 8 lines
Quoted 8 lines

doc/board/allwinner/sunxi.rst line 259

Quoted 1 line
doc/board/allwinner/sunxi.rst new file +1 -0
+with the sunxi-fel utility, via an USB(-OTG) cable from any USB host   

machine::

doc/board/allwinner/sunxi.rst

Quoted 6 lines
doc/board/allwinner/sunxi.rst new file +6 -0
+
+    $ sunxi-fel -v -p spiflash-write 0 u-boot-sunxi-with-spl.bin
+
+Booting via the USB(-OTG) FEL mode
+----------------------------------
+If none of the boot locations checked by the BROM contain a medium or 

valid

Quoted 4 lines
Quoted 4 lines

doc/board/allwinner/sunxi.rst line 267

Quoted 2 lines
doc/board/allwinner/sunxi.rst new file +2 -0
+signature, the BROM will enter the so-called FEL mode, in which it will
+listen to commands from a host on the SoC's USB-OTG interface. Those   

commands

Quoted 1 line
doc/board/allwinner/sunxi.rst new file +1 -0
+allow to read from and write to arbitrary memory locations, also to 

start

Quoted 1 line
Quoted 1 line

doc/board/allwinner/sunxi.rst line 269

Quoted 1 line
doc/board/allwinner/sunxi.rst new file +1 -0
+execution at any address, which allows to bootstrap a board solely via 

an

Quoted 4 lines
Quoted 4 lines

doc/board/allwinner/sunxi.rst line 271

Quoted 2 lines
doc/board/allwinner/sunxi.rst new file +2 -0
+USB cable. Some boards feature a "FEL" or "U-Boot" button, which forces
+FEL mode despite a valid boot location being present. The same can be   

achieved

Quoted 1 line
doc/board/allwinner/sunxi.rst new file +1 -0
+via a `magic binary`_ on an SD card, which allows to enter FEL mode on 

any

Quoted 3 lines
Quoted 3 lines

doc/board/allwinner/sunxi.rst

Quoted 3 lines
doc/board/allwinner/sunxi.rst new file +3 -0
+board.
+
+To use FEL booting, let the board enter FEL mode, via any of the 

mentioned

Quoted 1 line
Quoted 1 line

doc/board/allwinner/sunxi.rst line 276

Quoted 1 line
doc/board/allwinner/sunxi.rst new file +1 -0
+methods (no boot media, FEL button, SD card with FEL binary), then 

connect

Quoted 4 lines
Quoted 4 lines

doc/board/allwinner/sunxi.rst line 277

Quoted 1 line
doc/board/allwinner/sunxi.rst new file +1 -0
+a USB cable to the board's USB OTG port. Some boards (Pine64, TV boxes)   

don't

doc/board/allwinner/sunxi.rst line 279

Quoted 2 lines
doc/board/allwinner/sunxi.rst new file +2 -0
+have a separate OTG port. In this case mostly one of the USB-A ports is
+connected to USB0, and can be used via a non-standard USB-A to USB-A 

cable.

Quoted 2 lines
Quoted 2 lines

doc/board/allwinner/sunxi.rst line 281

Quoted 2 lines
doc/board/allwinner/sunxi.rst new file +2 -0
+
+Typically there is no on-board indication of FEL mode, other than a new 

USB

Quoted 1 line
Quoted 1 line

doc/board/allwinner/sunxi.rst line 282

Quoted 1 line
doc/board/allwinner/sunxi.rst new file +1 -0
+device appearing on the connected host computer. The USB vendor/device 

ID

Quoted 5 lines
Quoted 5 lines

doc/board/allwinner/sunxi.rst

Quoted 5 lines
doc/board/allwinner/sunxi.rst new file +5 -0
+is 1f3a:efe8. Mostly this will identify as "sunxi SoC OTG connector in
+FEL/flashing mode", but older distributions might still report "Onda
+(unverified) V972 tablet in flashing mode".
+
+The `sunxi_fel`_ tool implements the proprietary BROM protocol, and 

allows

Quoted 8 lines
Quoted 8 lines

to

doc/board/allwinner/sunxi.rst line 288

Quoted 1 line
doc/board/allwinner/sunxi.rst new file +1 -0
+bootstrap U-Boot by just providing our venerable u-boot-sunxi-with-  

spl.bin::

doc/board/allwinner/sunxi.rst

Quoted 5 lines
doc/board/allwinner/sunxi.rst new file +5 -0
+
+    $ sudo apt-get install sunxi-tools
+    $ sunxi-fel -v -p uboot u-boot-sunxi-with-spl.bin
+
+Additional binaries like a kernel, an initial ramdisk or a boot script, 

can

Quoted 1 line
Quoted 1 line

doc/board/allwinner/sunxi.rst line 294

Quoted 1 line
doc/board/allwinner/sunxi.rst new file +1 -0
+also be uploaded via FEL, check the Wiki's `FEL page`_ for more 

details.

Quoted 2 lines
Quoted 2 lines

doc/board/allwinner/sunxi.rst line 296

Quoted 2 lines
doc/board/allwinner/sunxi.rst new file +2 -0
+
+.. _`Arm Trusted Firmware-A`:  https://www.trustedfirmware.org/projects/

tf-a/

Quoted 1 line
Quoted 1 line

doc/board/allwinner/sunxi.rst line 297

Quoted 1 line
doc/board/allwinner/sunxi.rst new file +1 -0
+.. _`docs/plat/allwinner.rst`: https://trustedfirmware-a.readthedocs.io/

en/

Quoted 3 lines
Quoted 3 lines

latest/plat/allwinner.html

Quoted 2 lines
doc/board/allwinner/sunxi.rst new file +2 -0
+.. _`crust`: https://github.com/crust-firmware/crust
+.. _`configs/`: https://github.com/crust-firmware/crust/tree/master/

configs

Quoted 3 lines
Quoted 3 lines

doc/board/allwinner/sunxi.rst

Quoted 3 lines
doc/board/allwinner/sunxi.rst new file +3 -0
+.. _`linux-sunxi`: https://linux-sunxi.org
+.. _`MTD utils`: http://www.linux-mtd.infradead.org/
+.. _`magic binary`: https://github.com/linux-sunxi/sunxi-tools/raw/

master/

Quoted 12 lines
Quoted 10 lines

bin/fel-sdboot.sunxi

Quoted 6 lines
doc/board/allwinner/sunxi.rst new file +2 -0
+.. _`sunxi_fel`: https://github.com/linux-sunxi/sunxi-tools
+.. _`FEL page`: https://linux-sunxi.org/FEL/USBBoot
Signature · 1 line
2.17.6
Reviewed-by on v1 1/1
#4 lore raw
In reply to Andre Przywara

Hi Andre,

Quoted 20 lines · Andre Przywara

Add some long overdue instructions for building and installing U-Boot on Allwinner SoC based boards.
This describes the building process, including TF-A and crust, plus installation to SD card, eMMC and SPI flash, both from Linux and U-Boot itself. Also describe FEL booting.

---
Hi,

please have a look whether this makes sense. Feel free to just try something, and point out ambiguities or missing bits. For missing topics, please send a follow-up patch ;-)

Also this is quite long, shall this be split up in two (or more) files?

This is what rst.ninjs.org made of it, if you prefer to read it formatted:
https://paste.c-net.org/PleasantNeedy

Quoted 8 lines

Cheers,
Andre

 doc/board/allwinner/index.rst |   9 +
 doc/board/allwinner/sunxi.rst | 304 ++++++++++++++++++++++++++++++++++
 2 files changed, 313 insertions(+)
 create mode 100644 doc/board/allwinner/index.rst
 create mode 100644 doc/board/allwinner/sunxi.rst

I agree that a follow-on patch to remove the duplicated files would be helpful, but this patch is a big step forward on its own.

It would be interesting to convert sunxi to use binman.

Regards,
Simon

#5 lore raw

On Fri, 17 Dec 2021 09:37:08 -0700
Simon Glass <[email protected]> wrote:

Hi Simon,

Quoted 30 lines · Andre Przywara
Quoted 20 lines

Add some long overdue instructions for building and installing U-Boot on Allwinner SoC based boards.
This describes the building process, including TF-A and crust, plus installation to SD card, eMMC and SPI flash, both from Linux and U-Boot itself. Also describe FEL booting.

---
Hi,

please have a look whether this makes sense. Feel free to just try something, and point out ambiguities or missing bits. For missing topics, please send a follow-up patch ;-)

Also this is quite long, shall this be split up in two (or more) files?

This is what rst.ninjs.org made of it, if you prefer to read it formatted:
https://paste.c-net.org/PleasantNeedy

Quoted 8 lines

Cheers,
Andre

 doc/board/allwinner/index.rst |   9 +
 doc/board/allwinner/sunxi.rst | 304 ++++++++++++++++++++++++++++++++++
 2 files changed, 313 insertions(+)
 create mode 100644 doc/board/allwinner/index.rst
 create mode 100644 doc/board/allwinner/sunxi.rst  
Quoted 4 lines

I agree that a follow-on patch to remove the duplicated files would be helpful, but this patch is a big step forward on its own.

Thanks! I will address the other comments ASAP.

Quoted 1 line

It would be interesting to convert sunxi to use binman.

But Samuel fixed that already, didn't he? Or is there anything left that binman should do? We even now use mkimage to generate the magic BROM SPL signature, and then let binman combine this with the FIT image into the final binary. Or am I missing something here?

Or are you asking for patches that remove sunxi as the bad example from the existing documentation? ;-)

Cheers,
Andre

#6 lore raw

Hi Andre,

Quoted 41 lines · Andre Przywara

On Fri, 17 Dec 2021 09:37:08 -0700
Simon Glass <[email protected]> wrote:

Hi Simon,

Quoted 30 lines · Andre Przywara
Quoted 20 lines

Add some long overdue instructions for building and installing U-Boot on Allwinner SoC based boards.
This describes the building process, including TF-A and crust, plus installation to SD card, eMMC and SPI flash, both from Linux and U-Boot itself. Also describe FEL booting.

---
Hi,

please have a look whether this makes sense. Feel free to just try something, and point out ambiguities or missing bits. For missing topics, please send a follow-up patch ;-)

Also this is quite long, shall this be split up in two (or more) files?

This is what rst.ninjs.org made of it, if you prefer to read it formatted:
https://paste.c-net.org/PleasantNeedy

Quoted 8 lines

Cheers,
Andre

 doc/board/allwinner/index.rst |   9 +
 doc/board/allwinner/sunxi.rst | 304 ++++++++++++++++++++++++++++++++++
 2 files changed, 313 insertions(+)
 create mode 100644 doc/board/allwinner/index.rst
 create mode 100644 doc/board/allwinner/sunxi.rst
Quoted 4 lines

I agree that a follow-on patch to remove the duplicated files would be helpful, but this patch is a big step forward on its own.

Quoted 8 lines

Thanks! I will address the other comments ASAP.

Quoted 1 line

It would be interesting to convert sunxi to use binman.

But Samuel fixed that already, didn't he? Or is there anything left that binman should do? We even now use mkimage to generate the magic BROM SPL signature, and then let binman combine this with the FIT image into the final binary. Or am I missing something here?

Yes I think you are right. I was thinking of creating the image so that you could just dd it straight to the device without skipping stuff. But now I remember that we need to skip the partition table...

Quoted 3 lines

Or are you asking for patches that remove sunxi as the bad example from the existing documentation? ;-)

Regards,
Simon