README.nand
1Allwinner NAND flashing
2=======================
3
4A lot of Allwinner devices, especially the older ones (pre-H3 era),
5comes with a NAND. NANDs storages are a pretty weak choice when it
6comes to the reliability, and it comes with a number of flaws like
7read and write disturbs, data retention issues, bloks becoming
8unusable, etc.
9
10In order to mitigate that, various strategies have been found to be
11able to recover from those issues like ECC, hardware randomization,
12and of course, redundancy for the critical parts.
13
14This is obviously something that we will take into account when
15creating our images. However, the BROM will use a quite weird pattern
16when accessing the NAND, and will access only at most 4kB per page,
17which means that we also have to split that binary accross several
18pages.
19
20In order to accomodate that, we create a tool that will generate an
21SPL image that is ready to be programmed directly embedding the ECCs,
22randomized, and with the necessary bits needed to reduce the number of
23bitflips. The U-Boot build system, when configured for the NAND (with
24CONFIG_MTD_RAW_NAND=y) will also generate the image sunxi-spl-with-ecc.bin
25that will have been generated by that tool.
26
27In order to flash your U-Boot image onto a board, assuming that the
28board is in FEL mode, you'll need the sunxi-tools that you can find at
29this repository: https://github.com/linux-sunxi/sunxi-tools
30
31Then, you'll need to first load an SPL to initialise the RAM:
32sunxi-fel spl spl/sunxi-spl.bin
33
34Load the binaries we'll flash into RAM:
35sunxi-fel write 0x4a000000 u-boot-dtb.bin
36sunxi-fel write 0x43000000 spl/sunxi-spl-with-ecc.bin
37
38And execute U-Boot
39sunxi-fel exe 0x4a000000
40
41On your board, you'll now have all the needed binaries into RAM, so
42you only need to erase the NAND...
43
44nand erase.chip
45
46Then write the SPL and its backup:
47
48nand write.raw.noverify 0x43000000 0 40
49nand write.raw.noverify 0x43000000 0x400000 40
50
51And finally write the U-Boot binary:
52nand write 0x4a000000 0x800000 0xc0000
53
54You can now reboot and enjoy your NAND.
README.sunxi64
1Allwinner 64-bit boards README
2==============================
3
4Newer Allwinner SoCs feature ARMv8 cores (ARM Cortex-A53) with support for
5both the 64-bit AArch64 mode and the ARMv7 compatible 32-bit AArch32 mode.
6Examples are the Allwinner A64 (used for instance on the Pine64 board) or
7the Allwinner H5 SoC (as used on the OrangePi PC 2).
8These SoCs are wired to start in AArch32 mode on reset and execute 32-bit
9code from the Boot ROM (BROM). As this has some implications on U-Boot, this
10file describes how to make full use of the 64-bit capabilities.
11
12Quick Start / Overview
13======================
14- Build the ARM Trusted Firmware binary (see "ARM Trusted Firmware (ATF)" below)
15 $ cd /src/arm-trusted-firmware
16 $ make PLAT=sun50i_a64 DEBUG=1 bl31
17- Build the SCP firmware binary (see "SCP firmware (Crust)" below)
18 $ cd /src/crust
19 $ make pine64_plus_defconfig && make -j5 scp
20- Build U-Boot (see "SPL/U-Boot" below)
21 $ export BL31=/path/to/bl31.bin
22 $ export SCP=/src/crust/build/scp/scp.bin
23 $ make pine64_plus_defconfig && make -j5
24- Transfer to an uSD card (see "microSD card" below)
25 $ dd if=u-boot-sunxi-with-spl.bin of=/dev/sdx bs=8k seek=1
26- Boot and enjoy!
27
28Building the firmware
29=====================
30
31The Allwinner A64/H5/H6 firmware consists of several parts: U-Boot's SPL,
32ARM Trusted Firmware (ATF), optional System Control Processor (SCP) firmware
33(e.g. Crust), and the U-Boot proper.
34
35The SPL will load all of the other firmware binaries into RAM, along with the
36right device tree blob (.dtb), and will pass execution to ATF (in EL3). If SCP
37firmware was loaded, ATF will power on the SCP and wait for it to boot.
38ATF will then drop into U-Boot proper (in EL2).
39
40As the ATF binary and SCP firmware will become part of the U-Boot image file,
41you will need to build them first.
42
43 ARM Trusted Firmware (ATF)
44----------------------------
45Checkout the latest master branch from the official ATF repository [1] and
46build it:
47$ export CROSS_COMPILE=aarch64-linux-gnu-
48$ make PLAT=sun50i_a64 DEBUG=1 bl31
49The resulting binary is build/sun50i_a64/debug/bl31.bin. Either put the
50location of this file into the BL31 environment variable or copy this to
51the root of your U-Boot build directory (or create a symbolic link).
52$ export BL31=/src/arm-trusted-firmware/build/sun50i_a64/debug/bl31.bin
53 (adjust the actual path accordingly)
54The platform target "sun50i_a64" covers all boards with either an Allwinner
55A64 or H5 SoC (since they are very similar). For boards with an Allwinner H6
56SoC use "sun50i_h6".
57
58If you run into size issues with the resulting U-Boot image file, it might
59help to use a release build, by using "DEBUG=0" when building bl31.bin.
60As sometimes the ATF build process is a bit picky about the toolchain used,
61or if you can't be bothered with building ATF, there are known working
62binaries in the firmware repository[3], purely for convenience reasons.
63
64 SCP firmware (Crust)
65----------------------
66SCP firmware is responsible for implementing system suspend/resume, and (on
67boards without a PMIC) soft poweroff/on. ATF contains fallback code for CPU
68power control, so SCP firmware is optional if you don't need either of these
69features. It runs on the AR100, with is an or1k CPU, not ARM, so it needs a
70different cross toolchain.
71
72There is one SCP firmware implementation currently available, Crust:
73$ git clone https://github.com/crust-firmware/crust
74$ cd crust
75$ export CROSS_COMPILE=or1k-linux-musl-
76$ make pine64_plus_defconfig
77$ make scp
78
79The same configuration generally works on any board with the same SoC (A64, H5,
80or H6), so if there is no config for your board, use one for a similar board.
81
82Like for ATF, U-Boot finds the SCP firmware binary via an environment variable:
83$ export SCP=/src/crust/build/scp/scp.bin
84
85If you do not want to use SCP firmware, you can silence the warning from binman
86by pointing it to an empty file:
87$ export SCP=/dev/null
88
89 SPL/U-Boot
90------------
91Both U-Boot proper and the SPL are using the 64-bit mode. As the boot ROM
92enters the SPL still in AArch32 secure SVC mode, there is some shim code to
93enter AArch64 very early. The rest of the SPL runs in AArch64 EL3.
94U-Boot proper runs in EL2 and can load any AArch64 code (using the "go"
95command), EFI applications (with "bootefi") or arm64 Linux kernel images
96(often named "Image"), using the "booti" command.
97
98$ make clean
99$ export CROSS_COMPILE=aarch64-linux-gnu-
100$ make pine64_plus_defconfig
101$ make
102
103This will build the SPL in spl/sunxi-spl.bin and a FIT image called u-boot.itb,
104which contains the rest of the firmware. u-boot-sunxi-with-spl.bin joins those
105two components in one convenient image file.
106
107
108Boot process
109============
110The on-die BROM code will try several methods to load and execute the firmware.
111On a typical board like the Pine64 this will result in the following boot order:
112
1131) Reading 32KB from sector 16 (@8K) of the microSD card to SRAM A1. If the
114BROM finds the magic "eGON" header in the first bytes, it will execute that
115code. If not (no SD card at all or invalid magic), it will:
1162) Try to read 32KB from sector 16 (@8K) of memory connected to the MMC2
117controller, typically an on-board eMMC chip. If there is no eMMC or it does
118not contain a valid boot header, it will:
1193) Initialize the SPI0 controller and try to access a NOR flash connected to
120it (using the CS0 pin). If a flash chip is found, the BROM will load the
121first 32KB (from offset 0) into SRAM A1. Now it checks for the magic eGON
122header and checksum and will execute the code upon finding it. If not, it will:
1234) Initialize the USB OTG controller and will wait for a host to connect to
124it, speaking the Allwinner proprietary (but deciphered) "FEL" USB protocol.
125
126
127To boot the Pine64 board, you can use U-Boot and any of the described methods.
128
129FEL boot (USB OTG)
130------------------
131FEL is the name of the Allwinner defined USB boot protocol built in the
132mask ROM of most Allwinner SoCs. It allows to bootstrap a board solely
133by using the USB-OTG interface and a host port on another computer.
134As the FEL mode is controlled by the boot ROM, it expects to be running in
135AArch32. For now the AArch64 SPL cannot properly return into FEL mode, so the
136feature is disabled in the configuration at the moment.
137The repository in [3] contains FEL capable SPL binaries, built using an
138off-tree branch to generate 32-bit ARM code (along with instructions
139how to re-create them).
140
141microSD card
142------------
143Transfer the SPL and the U-Boot FIT image directly to an uSD card:
144# dd if=spl/sunxi-spl.bin of=/dev/sdx bs=8k seek=1
145# dd if=u-boot.itb of=/dev/sdx bs=8k seek=5
146# sync
147(replace /dev/sdx with you SD card device file name, which could be
148/dev/mmcblk[x] as well).
149
150Alternatively you can use the SPL and the U-Boot FIT image combined into a
151single file and transfer that instead:
152# dd if=u-boot-sunxi-with-spl.bin of=/dev/sdx bs=8k seek=1
153
154You can partition the microSD card, but leave the first MB unallocated (most
155partitioning tools will do this anyway).
156
157NOR flash
158---------
159Some boards (like the SoPine, Pinebook or the OrangePi PC2) come with a
160soldered SPI NOR flash chip. On other boards like the Pine64 such a chip
161can be connected to the SPI0/CS0 pins on the PI-2 headers.
162Create the SPL and FIT image like described above for the SD card.
163Now connect either an "A to A" USB cable to the upper USB port on the Pine64
164or get an adaptor and use a regular A-microB cable connected to it. Other
165boards often have a proper micro-B USB socket connected to the USB OTB port.
166Remove a microSD card from the slot and power on the board.
167On your host computer download and build the sunxi-tools package[2], then
168use "sunxi-fel" to access the board:
169$ ./sunxi-fel ver -v -p
170This should give you an output starting with: AWUSBFEX soc=00001689(A64) ...
171Now use the sunxi-fel tool to write to the NOR flash:
172$ ./sunxi-fel spiflash-write 0 spl/sunxi-spl.bin
173$ ./sunxi-fel spiflash-write 32768 u-boot.itb
174Now boot the board without an SD card inserted and you should see the
175U-Boot prompt on the serial console.
176
177(Legacy) boot0 method
178---------------------
179boot0 is Allwinner's secondary program loader and it can be used as some kind
180of SPL replacement to get U-Boot up and running from an microSD card.
181For some time using boot0 was the only option to get the Pine64 booted.
182With working DRAM init code in U-Boot's SPL this is no longer necessary,
183but this method is described here for the sake of completeness.
184Please note that this method works only with the boot0 files shipped with
185A64 based boards, the H5 uses an incompatible layout which is not supported
186by this method.
187
188The boot0 binary is a 32 KByte blob and contained in the official Pine64 images
189distributed by Pine64 or Allwinner. It can be easily extracted from a micro
190SD card or an image file:
191# dd if=/dev/sd<x> of=boot0.bin bs=8k skip=1 count=4
192where /dev/sd<x> is the device name of the uSD card or the name of the image
193file. Apparently Allwinner allows re-distribution of this proprietary code
194"as-is".
195This boot0 blob takes care of DRAM initialisation and loads the remaining
196firmware parts, then switches the core into AArch64 mode.
197The original boot0 code looks for U-Boot at a certain place on an uSD card
198(at 19096 KB), also it expects a header with magic bytes and a checksum.
199There is a tool called boot0img[3] which takes a boot0.bin image and a compiled
200U-Boot binary (plus other binaries) and will populate that header accordingly.
201To make space for the magic header, the pine64_plus_defconfig will make sure
202there is sufficient space at the beginning of the U-Boot binary.
203boot0img will also take care of putting the different binaries at the right
204places on the uSD card and works around unused, but mandatory parts by using
205trampoline code. See the output of "boot0img -h" for more information.
206boot0img can also patch boot0 to avoid loading U-Boot from 19MB, instead
207fetching it from just behind the boot0 binary (-B option).
208$ ./boot0img -o firmware.img -B boot0.img -u u-boot-dtb.bin -e -s bl31.bin \
209-a 0x44008 -d trampoline64:0x44000
210Then write this image to a microSD card, replacing /dev/sdx with the right
211device file (see above):
212$ dd if=firmware.img of=/dev/sdx bs=8k seek=1
213
214[1] https://github.com/ARM-software/arm-trusted-firmware.git
215[2] git://github.com/linux-sunxi/sunxi-tools.git
216[3] https://github.com/apritzel/pine64/
217