[people/ms/u-boot.git] / doc / README.ublimage

---------------------------------------------
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>
Commit	Line	Data
7816f2cf HS	1	---------------------------------------------
	2	UBL image Boot Image generation using mkimage
	3	---------------------------------------------
	4
	5	This document describes how to set up an U-Boot image that can be directly
	6	booted by a DaVinci processor via NAND boot mode, using an UBL header,
	7	but without need for UBL.
	8
	9	For more details see section 11.2 "ARM ROM Boot Modes" of
	10	http://focus.ti.com/lit/ug/sprufg5a/sprufg5a.pdf
	11
	12	Command syntax:
	13	--------------
	14	./tools/mkimage -l <u-boot_file>
	15	to list the UBL image file details
	16
	17	./tools/mkimage -T ublimage \
	18	-n <board specific configuration file> \
	19	-d <u-boot binary> <output image file>
	20
	21	For example, for the davinci dm365evm board:
	22	./tools/mkimage -n ./board/davinci/dm365evm/ublimage.cfg \
	23	-T ublimage \
	24	-d u-boot-nand.bin u-boot.ubl
	25
	26	You can generate the image directly when you compile u-boot with:
	27
	28	$ make u-boot.ubl
	29
	30	The output image can be flashed into the NAND.
	31
	32	Please check the DaVinci documentation for further details.
	33
	34	Board specific configuration file specifications:
	35	-------------------------------------------------
	36	1. This file must present in the $(BOARDDIR) and the name should be
	37	ublimage.cfg (since this is used in Makefile).
	38	2. This file can have empty lines and lines starting with "#" as first
	39	character to put comments.
	40	3. This file can have configuration command lines as mentioned below,
	41	any other information in this file is treated as invalid.
	42
	43	Configuration command line syntax:
	44	---------------------------------
	45	1. Each command line must have two strings, first one command or address
	46	and second one data string
	47	2. Following are the valid command strings and associated data strings:-
	48	Command string data string
	49	-------------- -----------
	50	MODE UBL special mode, on of:
	51	safe
	52	Example:
	53	MODE safe
	54
	55	ENTRY Entry point address for the user
	56	bootloader (absolute address) = TEXT_BASE
	57	nand_spl loader.
	58	Example:
	59	ENTRY 0x00000020
	60
	61	PAGES Number of pages (size of user bootloader
	62	in number of pages)
	63	Example:
	64	PAGES 27
65
66	START_BLOCK Block number where user bootloader is present
67	Example:
68	START_BLOCK 5
69
70	START_PAGE Page number where user bootloader is present
71	(for RBL always 0)
72	Example:
73	START_PAGE 0
74
75	------------------------------------------------
76
77	Structure of the u-boot.ubl binary:
78
79	compile steps:
80
81	1) nand_spl code compile, with pad_to = (TEXT_BASE +
82	(CONFIG_SYS_NROF_PAGES_NAND_SPL * pagesize))
83	Example: cam_enc_4xx pad_to = 0x20 + (6 * 0x800) = 0x3020 = 12320
84	-> u-boot-spl-16k.bin
85
86	!! TEXT_BASE = 0x20, as the RBL starts at 0x20
87
88	2) compile u-boot.bin ("normal" u-boot)
89	-> u-boot.bin
90
91	3) create u-boot-nand.bin = u-boot-spl-16k.bin + u-boot.bin
92
93	4) create u-boot.ubl, size = 1 page size NAND
94	create UBL header and paste it before u-boot.bin
95
96	This steps are done automagically if you do a "make all"
97
98	-> You get an u-boot.ubl binary, which you can flash
99	into your NAND.
100
101	Structure of this binary (Example for the cam_enc_4xx board with a NAND
102	page size = 0x800):
103
04e5ae79 WD	104	offset : 0x00000 \| 0x800 \| 0x3800
	105	content: UBL \| nand_spl \| u-boot code
	106	Header \| code \|
7816f2cf HS	107
	108	The NAND layout looks for example like this:
	109
	110	(Example for the cam_enc_4xx board with a NAND page size = 0x800, block
	111	size = 0x20000 and CONFIG_SYS_NROF_UBL_HEADER 5):
	112
04e5ae79 WD	113	offset : 0x80000 \| 0xa0000 \| 0xa3000
	114	content: UBL \| nand_spl \| u-boot code
	115	Header \| code \|
	116	^ ^
	117	^ 0xa0000 = CONFIG_SYS_NROF_UBL_HEADER * 0x20000
	118	^
	119	0x80000 = Block 4 * 0x20000
7816f2cf HS	120
	121	If the cpu starts in NAND boot mode, it checks the UBL descriptor
	122	starting with block 1 (page 0). When a valid UBL signature is found,
	123	the corresponding block number (from 1 to 24) is written to the last 32
	124	bits of ARM internal memory (0x7ffc-0x8000). This feature is provided
	125	as a basic debug mechanism. If not found, it continues with block 2
	126	... last possible block is 24
	127
	128	If a valid UBL descriptor is found, the UBL descriptor is read and
	129	processed. The descriptor gives the information required for loading
	130	and control transfer to the nand_spl code. The nand_spl code is then
	131	read and processed.
	132
	133	Once the user-specified start-up conditions are set, the RBL copies the
	134	nand_spl into ARM internal RAM, starting at address 0x0000: 0020.
04e5ae79	135	^^^^
7816f2cf HS	136
	137	The nand_spl code itself now does necessary intializations, and at least,
	138	copies the u-boot code from NAND into RAM, and jumps to it ...
	139
	140	------------------------------------------------
	141	Author: Heiko Schocher <hs@denx.de>