mkimage: add UBL header support for booting davinci cpus

creating an u-boot.ubl file, which contains the UBL Header
needed for booting from NAND with the RBL from TI. For more
information read doc/README.ublimage.

Signed-off-by: Heiko Schocher <hs@denx.de>

1 files changed, 141 insertions, 0 deletions

diff --git a/doc/README.ublimage b/doc/README.ublimage
new file mode 100644
index 0000000000..add24d649b
--- /dev/null
+++ b/doc/README.ublimage
@@ -0,0 +1,141 @@
+---------------------------------------------
+UBL image Boot Image generation using mkimage
+---------------------------------------------
+
+This document describes how to set up an U-Boot image that can be directly
+booted by a DaVinci processor via NAND boot mode, using an UBL header,
+but without need for UBL.
+
+For more details see section 11.2 "ARM ROM Boot Modes" of
+http://focus.ti.com/lit/ug/sprufg5a/sprufg5a.pdf
+
+Command syntax:
+--------------
+./tools/mkimage -l <u-boot_file>
+		to list the UBL image file details
+
+./tools/mkimage -T ublimage \
+		-n <board specific configuration file> \
+		-d <u-boot binary>  <output image file>
+
+For example, for the davinci dm365evm board:
+./tools/mkimage -n ./board/davinci/dm365evm/ublimage.cfg \
+		-T ublimage \
+		-d u-boot-nand.bin u-boot.ubl
+
+You can generate the image directly when you compile u-boot with:
+
+$ make u-boot.ubl
+
+The output image can be flashed into the NAND.
+
+Please check the DaVinci documentation for further details.
+
+Board specific configuration file specifications:
+-------------------------------------------------
+1. This file must present in the $(BOARDDIR) and the name should be
+	ublimage.cfg (since this is used in Makefile).
+2. This file can have empty lines and lines starting with "#" as first
+	character to put comments.
+3. This file can have configuration command lines as mentioned below,
+	any other information in this file is treated as invalid.
+
+Configuration command line syntax:
+---------------------------------
+1. Each command line must have two strings, first one command or address
+	and second one data string
+2. Following are the valid command strings and associated data strings:-
+	Command string		data string
+	--------------		-----------
+	MODE			UBL special mode, on of:
+				safe
+				Example:
+				MODE	safe
+
+	ENTRY			Entry point address for the user
+				bootloader (absolute address) = TEXT_BASE
+				nand_spl loader.
+				Example:
+				ENTRY	0x00000020
+
+	PAGES			Number of pages (size of user bootloader
+				in number of pages)
+				Example:
+				PAGES	27
+
+	START_BLOCK		Block number where user bootloader is present
+				Example:
+				START_BLOCK	5
+
+	START_PAGE		Page number where user bootloader is present
+				(for RBL always 0)
+				Example:
+				START_PAGE	0
+
+------------------------------------------------
+
+Structure of the u-boot.ubl binary:
+
+compile steps:
+
+1) nand_spl code compile, with pad_to = (TEXT_BASE +
+   (CONFIG_SYS_NROF_PAGES_NAND_SPL * pagesize))
+   Example: cam_enc_4xx pad_to = 0x20 + (6 * 0x800) = 0x3020 = 12320
+   -> u-boot-spl-16k.bin
+
+   !! TEXT_BASE = 0x20, as the RBL starts at 0x20
+
+2) compile u-boot.bin ("normal" u-boot)
+   -> u-boot.bin
+
+3) create u-boot-nand.bin = u-boot-spl-16k.bin + u-boot.bin
+
+4) create u-boot.ubl, size = 1 page size NAND
+   create UBL header and paste it before u-boot.bin
+
+This steps are done automagically if you do a "make all"
+
+-> You get an u-boot.ubl binary, which you can flash
+   into your NAND.
+
+Structure of this binary (Example for the cam_enc_4xx board with a NAND
+page size = 0x800):
+
+offset :    0x00000 | 0x800       | 0x3800
+content:    UBL     | nand_spl    | u-boot code
+            Header  | code        |
+
+The NAND layout looks for example like this:
+
+(Example for the cam_enc_4xx board with a NAND page size = 0x800, block
+size = 0x20000 and CONFIG_SYS_NROF_UBL_HEADER 5):
+
+offset :    0x80000 | 0xa0000     | 0xa3000
+content:    UBL     | nand_spl    | u-boot code
+            Header  | code        |
+            ^         ^
+	    ^         0xa0000 = CONFIG_SYS_NROF_UBL_HEADER * 0x20000
+            ^
+            0x80000 = Block 4 * 0x20000
+
+If the cpu starts in NAND boot mode, it checks the UBL descriptor
+starting with block 1 (page 0).  When a valid UBL signature is found,
+the corresponding block number (from 1 to 24) is written to the last 32
+bits of ARM internal memory (0x7ffc-0x8000).  This feature is provided
+as a basic debug mechanism.  If not found, it continues with block 2
+... last possible block is 24
+
+If a valid UBL descriptor is found, the UBL descriptor is read and
+processed.  The descriptor gives the information required for loading
+and control transfer to the nand_spl code.  The nand_spl code is then
+read and processed.
+
+Once the user-specified start-up conditions are set, the RBL copies the
+nand_spl into ARM internal RAM, starting at address 0x0000: 0020.
+                                                            ^^^^
+
+The nand_spl code itself now does necessary intializations, and at least,
+copies the u-boot code from NAND into RAM, and jumps to it ...
+
+------------------------------------------------
+Author: Heiko Schocher <hs@denx.de>