xref: /openbmc/u-boot/doc/README.ublimage (revision 04e5ae793153e74d682f2d0e297e58fd75366c8f)
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 
104 offset :    0x00000 | 0x800	  | 0x3800
105 content:    UBL     | nand_spl	  | u-boot code
106 	    Header  | code	  |
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 
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
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.
135 							    ^^^^
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>
142