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>
diff --git a/doc/README.ublimage b/doc/README.ublimage
new file mode 100644
index 0000000..add24d6
--- /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>