doc: ARMv8: add README.pine64

Since we lack information about the DRAM initialization for the
Allwinner A64 SoC, booting any A64 based board like the Pine64 is a bit
involved at the moment.
Add a README file to explain the process.

Signed-off-by: Andre Przywara <andre.przywara@arm.com>
Reviewed-by: Tom Rini <trini@konsulko.com>
[trini: Move to board/sunxi/ from doc/]
Signed-off-by: Tom Rini <trini@konsulko.com>

1 files changed, 98 insertions, 0 deletions

diff --git a/board/sunxi/README.pine64 b/board/sunxi/README.pine64
new file mode 100644
index 0000000..5553415
--- /dev/null
+++ b/board/sunxi/README.pine64
@@ -0,0 +1,98 @@
+Pine64 board README
+====================
+
+The Pine64(+) is a single board computer equipped with an AArch64 capable ARMv8
+compliant Allwinner A64 SoC.
+This chip has ARM Cortex A-53 cores and thus can run both in AArch32
+(compatible to 32-bit ARMv7) and AArch64 modes. Upon reset the SoC starts
+in AArch32 mode and executes 32-bit code from the Boot ROM (BROM).
+This has some implications on U-Boot.
+
+Quick start
+============
+- Get hold of a boot0.img file (see below for more details).
+- Get the boot0img tool source from the tools directory in [1] and compile
+  that on your host.
+- Build U-Boot:
+$ export CROSS_COMPILE=aarch64-linux-gnu-
+$ make pine64_plus_defconfig
+$ make
+- You also need a compiled ARM Trusted Firmware (ATF) binary. Checkout the
+  "allwinner" branch from the github repository [2] and build it:
+$ export CROSS_COMPILE=aarch64-linux-gnu-
+$ make PLAT=sun50iw1p1 DEBUG=1 bl31
+  The resulting binary is build/sun50iw1p1/debug/bl31.bin.
+
+Now put an empty (or disposable) micro SD card in your card reader and learn
+its device file name, replacing /dev/sd<x> below with the result (that could
+be /dev/mmcblk<x> as well):
+
+$ ./boot0img --device /dev/sd<x> -e -u u-boot.bin -B boot0.img \
+	-d trampoline64:0x44000 -s bl31.bin -a 0x44008 -p 100
+(either copying the respective files to the working directory or specifying
+the paths directly)
+
+This will create a new partition table (with a 100 MB FAT boot partition),
+copies boot0.img, ATF and U-Boot to the proper locations on the SD card and
+will fill in the magic Allwinner header to be recognized by boot0.
+Prefix the above call with "sudo" if you don't have write access to the
+uSD card. You can also use "-o output.img" instead of "--device /dev/sd<x>"
+to create an image file and "dd" that to the uSD card.
+Omitting the "-p" option will skip the partition table.
+
+Now put this uSD card in the board and power it on. You should be greeted by
+the U-Boot prompt.
+
+
+Main U-Boot
+============
+The main U-Boot proper is a real 64-bit ARMv8 port and runs entirely in the
+64-bit AArch64 mode. It can load any AArch64 code, EFI applications or arm64
+Linux kernel images (often named "Image") using the booti command.
+Launching 32-bit code and kernels is technically possible, though not without
+drawbacks (or hacks to avoid them) and currently not implemented.
+
+SPL support
+============
+The main task of the SPL support is to bring up the DRAM controller and make
+DRAM actually accessible. At the moment there is no documentation or source
+code available which would do this.
+There are currently two ways to overcome this situation: using a tainted 32-bit
+SPL (involving some hacks and resulting in a non-redistributable binary, thus
+not described here) or using the Allwinner boot0 blob.
+
+boot0 method
+-------------
+boot0 is Allwiner's secondary program loader and it can be used as some kind
+of SPL replacement to get U-Boot up and running.
+The binary is a 32 KByte blob and contained on every Pine64 image distributed
+so far. It can be easily extracted from a micro SD card or an image file:
+# dd if=/dev/sd<x> of=boot0.bin bs=8k skip=1 count=4
+where /dev/sd<x> is the device name of the uSD card or the name of the image
+file. Apparently Allwinner allows re-distribution of this proprietary code
+as-is.
+For the time being this boot0 blob is the only redistributable way of making
+U-Boot work on the Pine64. Beside loading the various parts of the (original)
+firmware it also switches the core into AArch64 mode.
+The original boot0 code looks for U-Boot at a certain place on an uSD card
+(at 19096 KB), also it expects a header with magic bytes and a checksum.
+There is a tool called boot0img[1] which takes a boot0.bin image and a compiled
+U-Boot binary (plus other binaries) and will populate that header accordingly.
+To make space for the magic header, the pine64_plus_defconfig will make sure
+there is sufficient space at the beginning of the U-Boot binary.
+boot0img will also take care of putting the different binaries at the right
+places on the uSD card and works around unused, but mandatory parts by using
+trampoline code. See the output of "boot0img -h" for more information.
+boot0img can also patch boot0 to avoid loading U-Boot from 19MB, instead
+fetching it from just behind the boot0 binary (-B option).
+
+FEL boot
+=========
+FEL is the name of the Allwinner defined USB boot protocol built-in the
+mask ROM of most Allwinner SoCs. It allows to bootstrap a board solely
+by using the USB-OTG interface and a host port on another computer.
+Since FEL boot does not work with boot0, it requires the libdram hack, which
+is not described here.
+
+[1] https://github.com/apritzel/pine64/
+[2] https://github.com/apritzel/arm-trusted-firmware.git