README.booting.md: Document common booting processes

This README.booting is a consolidation of the booting content provided
in the docs/ directory. The content is updated for the current state of
the layer as well and restructured to be easier to navigate.

Signed-off-by: Nathan Rossi <nathan@nathanrossi.com>

1 files changed, 233 insertions, 0 deletions

diff --git a/README.booting.md b/README.booting.md
new file mode 100644
index 00000000..5950bf96
--- /dev/null
+++ b/README.booting.md
@@ -0,0 +1,233 @@
+Booting meta-xilinx boards
+==========================
+
+Contents
+--------
+ * [Loading via JTAG](#loading-via-jtag)
+  * [XSDB](#xsdb)
+  * [Load Bitstream](#load-bitstream)
+  * [Load U-Boot (MicroBlaze)](#load-u-boot-microblaze)
+  * [Load U-Boot (Zynq)](#load-u-boot-zynq)
+  * [U-Boot Console](#u-boot-console)
+  * [Kernel, Root Filesystem and Device Tree](#kernel-root-filesystem-and-device-tree)
+  * [Booting via U-Boot](#booting-via-u-boot)
+ * [Loading via SD](#loading-via-sd)
+  * [Preparing SD/MMC](#preparing-sdmmc)
+  * [Installing U-Boot](#installing-u-boot)
+  * [Installing Kernel and Device Tree](#installing-kernel-and-device-tree)
+  * [Installing Root Filesystem](#installing-root-filesystem)
+  * [U-Boot Configuration File](#u-boot-configuration-file)
+  * [Booting](#booting)
+ * [Loading via TFTP](#loading-via-tftp)
+  * [Kernel, Root Filesystem and Device Tree](#kernel-root-filesystem-and-device-tree-1)
+  * [Booting via U-Boot](#booting-via-u-boot-1)
+
+
+Loading via JTAG
+----------------
+This boot flow requires the use of the Xilinx tools, specifically XSDB and the
+associated JTAG device drivers. This also requires access to the JTAG interface
+on the board, a number of Xilinx and third-party boards come with on-board JTAG
+modules.
+
+### XSDB
+Start `xsdb` and connect. Ensure that the target chip is visible.
+
+        $ xsdb
+        xsdb% connect
+        xsdb% targets
+
+### Load Bitstream
+**(Note: This step is only required for platforms which have a bitstream e.g.
+MicroBlaze.)**
+
+Download the bitstream for the system using XSDB with the `fpga -f` command. If
+a bitstream is available from meta-xilinx is will be located in the
+`deploy/images/<machine-name>/` directory.
+
+        xsdb% fpga -f download.bit
+
+### Load U-Boot (MicroBlaze)
+Download `u-boot.elf` to the target CPU via the use of XSDB.
+
+        xsdb% targets -set -filter {name =~ "MicroBlaze*"}
+        xsdb% rst
+        xsdb% dow u-boot.elf
+        xsdb% con
+
+### Load U-Boot (Zynq)
+Ensure the board is configured to boot from JTAG. The Zynq platform requires the
+loading of SPL first, this can be done by loading the `u-boot-spl.bin` and
+executing it at location `0x0`. `u-boot-spl.bin` is not output to the deploy
+directory by default, it can be obtained from the work directory for U-Boot
+(`git/spl/u-boot-spl.bin`).
+
+        xsdb% targets -set -filter {name =~ "ARM*#0"}
+        xsdb% dow -data u-boot-spl.bin 0x0
+        xsdb% rwr pc 0x0
+        xsdb% con
+
+On the UART console the following should appear, indicating SPL was loaded.
+
+        U-Boot SPL 2016.01
+        Trying to boot from unknown boot device
+        SPL: Unsupported Boot Device!
+        SPL: failed to boot from all boot devices
+        ### ERROR ### Please RESET the board ###
+
+Once SPL has loaded U-Boot can now be loaded into memory and executed. Download
+`u-boot.elf` to the target.
+
+        xsdb% stop
+        xsdb% dow u-boot.elf
+        xsdb% con
+
+### U-Boot Console
+U-Boot will load and the console will be available on the UART interface.
+
+        ...
+        Hit any key to stop autoboot: 0
+        U-Boot>
+
+### Kernel, Root Filesystem and Device Tree
+Whilst it is possible to load the images via JTAG this connection is slow and
+this process can take a long time to execute (more than 10 minutes). If your
+system has ethernet it is recommended that you use TFTP to load these images
+using U-Boot.
+
+Once U-Boot has been loaded, pause the execution using XSDB and use the `dow`
+command to load the images into the targets memory. Once the images are loaded
+continue the execution and return to the U-Boot console.
+
+MicroBlaze (kc705-microblazeel):
+
+        xsdb% stop
+        xsdb% dow -data linux.bin.ub 0x85000000
+        xsdb% dow -data core-image-minimal-kc705-microblazeel.cpio.gz.u-boot 0x86000000
+        xsdb% dow -data kc705-microblazeel.dtb 0x84000000
+        xsdb% con
+
+Zynq:
+
+        xsdb% stop
+        xsdb% dow -data uImage 0x2000000
+        xsdb% dow -data core-image-minimal-<machine name>.cpio.gz.u-boot 0x3000000
+        xsdb% dow -data <machine name>.dtb 0x2A00000
+        xsdb% con
+
+### Booting via U-Boot
+At the U-Boot console use the `bootm` command to execute the kernel.
+
+MicroBlaze (kc705-microblazeel):
+
+        U-Boot> bootm 0x85000000 0x86000000 0x84000000
+
+Zynq:
+
+        U-Boot> bootm 0x2000000 0x3000000 0x2A00000
+
+
+Loading via SD
+---------------------
+**(Note: This section only applies to Zynq.)**
+
+### Preparing SD/MMC
+Setup the card with the first partition formatted as FAT16. If you intend to
+boot with the root filesystem located on the SD card, also create a second
+partition formatted as EXT4.
+
+It is recommended that the first partition be at least 64MB in size, however
+this value will depend on whether using a ramdisk for the root filesystem and
+how large the ramdisk is.
+
+### Installing U-Boot
+Add the following files to the first partition:
+ * `boot.bin`
+ * `u-boot.img` (if using u-boot-xlnx)
+ * `u-boot-dtb.img` (if using u-boot)
+
+### Installing Kernel and Device Tree
+Add the following files to the first partition:
+ * `uImage`
+ * `<machine name>.dtb`
+
+### Installing Root Filesystem
+If using a ramdisk also add the `.cpio.gz.u-boot` type of root filesystem image
+to the first partition.
+ * `core-image-minimal-<machine name>.cpio.gz.u-boot`
+
+If using the SD card as the root filesystem, populate the second partition with
+the content of the root filesystem. To install the root filesystem extract the
+corresponding tarball into the root of the second partition (the following
+command assumes that the second partition is mounted at /media/root).
+
+        tar x -C /media/root -f core-image-minimal-<machine name>.tar.gz
+
+### U-Boot Configuration File
+Also create the file `uEnv.txt` on the first partition of the SD card partition,
+with the following contents. Replacing the names of files where appropriate.
+
+        kernel_image=uImage
+        devicetree_image=<machine name>.dtb
+
+If using a ramdisk root filesystem setup the `ramdisk_image` variable.
+
+        ramdisk_image=core-image-minimal-<machine name>.cpio.gz.u-boot
+
+If using the SD card as the root filesystem setup the kernel boot args, and
+`uenvcmd` variable.
+
+        bootargs=root=/dev/mmcblk0p2 rw rootwait
+        uenvcmd=fatload mmc 0 0x3000000 ${kernel_image} && fatload mmc 0 0x2A00000 ${devicetree_image} && bootm 0x3000000 - 0x2A00000
+
+### Booting
+Insert the SD card and connect UART to a terminal program and power on the
+board. (For boards that have configurable boot jumper/switches ensure the board
+is configured for SD).
+
+Initially U-Boot SPL will load, which will in turn load U-Boot. U-Boot will use
+the `uEnv.txt` to automatically load and execute the kernel.
+
+
+Loading via TFTP
+----------------
+**(Note: This boot flow requires ethernet on the baord and a TFTP server)**
+
+Boot your system into U-Boot, using one of boot methods (e.g. JTAG, SD, QSPI).
+
+### Kernel, Root Filesystem and Device Tree
+Place the following images into the root of the TFTP server directory:
+ * `core-image-minimal-<machine name>.cpio.gz.u-boot`
+ * `uImage` (Zynq) or `linux.bin.ub` (MicroBlaze)
+ * `<machine name>.dtb`
+
+### Booting via U-Boot
+The serial console of the target board will display the U-Boot console.
+Configure the `ipaddr` and `serverip` of the U-Boot environment.
+
+        U-Boot> set serverip <server ip>
+        U-Boot> set ipaddr <board ip>
+
+Using the U-Boot console; load the Kernel, root filesystem and the DTB into
+memory. And then boot Linux using the `bootm` command. (Note the load addresses
+will be dependant on machine used)
+
+MicroBlaze (kc705-microblazeel):
+
+        U-Boot> tftpboot 0x85000000 linux.bin.ub
+        U-Boot> tftpboot 0x86000000 core-image-minimal-kc705-microblazeel.cpio.gz.u-boot
+        U-Boot> tftpboot 0x84000000 kc705-microblazeel.dtb
+        U-Boot> bootm 0x85000000 0x86000000 0x84000000
+
+Zynq:
+
+        U-Boot> tftpboot 0x2000000 uImage
+        U-Boot> tftpboot 0x3000000 core-image-minimal-<machine name>.cpio.gz.u-boot
+        U-Boot> tftpboot 0x2A00000 <machine name>.dtb
+        U-Boot> bootm 0x2000000 0x3000000 0x2A00000
+
+U-Boot will prepare the Kernel for boot and then it will being to execute.
+
+        ...
+        Starting kernel...
+