blob: fa4e486661c262b3a2b437334cd072f8041b4014 [file] [log] [blame]
Stefano Babic7b07f092010-01-20 18:19:10 +01001---------------------------------------------
2Imximage Boot Image generation using mkimage
3---------------------------------------------
4
Dirk Behmedfbf6ce2012-01-11 23:28:31 +00005This document describes how to set up a U-Boot image that can be booted
6by Freescale MX25, MX35, MX51, MX53 and MX6 processors via internal boot
7mode.
Stefano Babic7b07f092010-01-20 18:19:10 +01008
9These processors can boot directly from NAND, SPI flash and SD card flash
Dirk Behmedfbf6ce2012-01-11 23:28:31 +000010using its internal boot ROM support. MX6 processors additionally support
11boot from NOR flash and SATA disks. All processors can boot from an internal
Stefano Babic7b07f092010-01-20 18:19:10 +010012UART, if booting from device media fails.
13Booting from NOR flash does not require to use this image type.
14
15For more details refer Chapter 2 - System Boot and section 2.14
16(flash header description) of the processor's manual.
17
Stefano Babic7b07f092010-01-20 18:19:10 +010018Command syntax:
19--------------
20./tools/mkimage -l <mx u-boot_file>
21 to list the imx image file details
22
23./tools/mkimage -T imximage \
24 -n <board specific configuration file> \
25 -e <execution address> -d <u-boot binary> <output image file>
26
27For example, for the mx51evk board:
28./tools/mkimage -n ./board/freescale/mx51evk/imximage.cfg \
29 -T imximage -e 0x97800000 \
30 -d u-boot.bin u-boot.imx
31
32You can generate directly the image when you compile u-boot with:
33
34$ make u-boot.imx
35
36The output image can be flashed on the board SPI flash or on a SD card.
37In both cases, you have to copy the image at the offset required for the
38chosen media devices (0x400 for both SPI flash or SD card).
39
40Please check Freescale documentation for further details.
41
42Board specific configuration file specifications:
43-------------------------------------------------
441. This file must present in the $(BOARDDIR) and the name should be
45 imximage.cfg (since this is used in Makefile).
462. This file can have empty lines and lines starting with "#" as first
47 character to put comments.
483. This file can have configuration command lines as mentioned below,
49 any other information in this file is treated as invalid.
50
51Configuration command line syntax:
52---------------------------------
531. Each command line is must have two strings, first one command or address
54 and second one data string
552. Following are the valid command strings and associated data strings:-
56 Command string data string
57 -------------- -----------
Liu Hui-R643434aa360a2011-01-19 09:40:26 +000058 IMXIMAGE_VERSION 1/2
59 1 is for mx25/mx35/mx51 compatible,
Dirk Behmedfbf6ce2012-01-11 23:28:31 +000060 2 is for mx53/mx6 compatible,
Liu Hui-R643434aa360a2011-01-19 09:40:26 +000061 others is invalid and error is generated.
62 This command need appear the fist before
63 other valid commands in configuration file.
64
Marek Vasutd45fd732013-04-25 10:16:02 +000065 BOOT_OFFSET value
66
67 This command is parallel to BOOT_FROM and
68 is preferred over BOOT_FROM.
69
70 value: Offset of the image header, this
71 value shall be set to one of the
72 values found in the file:
73 arch/arm/include/asm/\
Stefano Babic33731bc2017-06-29 10:16:06 +020074 mach-imx/imximage.cfg
Marek Vasutd45fd732013-04-25 10:16:02 +000075 Example:
76 BOOT_OFFSET FLASH_OFFSET_STANDARD
77
Dirk Behmedfbf6ce2012-01-11 23:28:31 +000078 BOOT_FROM nand/spi/sd/onenand/nor/sata
Marek Vasutd45fd732013-04-25 10:16:02 +000079
80 This command is parallel to BOOT_OFFSET and
81 is to be deprecated in favor of BOOT_OFFSET.
82
Stefano Babic7b07f092010-01-20 18:19:10 +010083 Example:
84 BOOT_FROM spi
Marek Vasutd45fd732013-04-25 10:16:02 +000085
Stefano Babic4aa97492013-06-27 11:42:38 +020086 CSF value
87
88 Total size of CSF (Command Sequence File)
89 used for Secure Boot/ High Assurance Boot
90 (HAB).
91
92 Using this command will populate the IVT
93 (Initial Vector Table) CSF pointer and adjust
94 the length fields only. The CSF itself needs
95 to be generated with Freescale tools and
96 'manually' appended to the u-boot.imx file.
97
98 The CSF is then simply concatenated
99 to the u-boot image, making a signed bootloader,
100 that the processor can verify
101 if the fuses for the keys are burned.
102
103 Further infos how to configure the SOC to verify
104 the bootloader can be found in the "High
105 Assurance Boot Version Application Programming
106 Interface Reference Manual" as part of the
107 Freescale Code Signing Tool, available on the
108 manufacturer's website.
109
110 Example:
111 CSF 0x2000
112
Stefano Babic7b07f092010-01-20 18:19:10 +0100113 DATA type address value
114
115 type: word=4, halfword=2, byte=1
116 address: physycal register address
117 value: value to be set in register
118 All values are in in hexadecimal.
119 Example (write to IOMUXC):
120 DATA 4 0x73FA88a0 0x200
121
Liu Hui-R643434aa360a2011-01-19 09:40:26 +0000122The processor support up to 60 register programming commands for IMXIMAGE_VERSION 1
Fabio Estevamf892d522014-09-09 12:28:18 -0300123and 220 register programming commands for IMXIMAGE_VERSION 2.
Liu Hui-R643434aa360a2011-01-19 09:40:26 +0000124An error is generated if more commands are found in the configuration file.
Stefano Babic7b07f092010-01-20 18:19:10 +0100125
1263. All commands are optional to program.
127
128Setup a SD Card for booting
129--------------------------------
130
131The following example prepare a SD card with u-boot and a FAT partition
132to be used to stored the kernel to be booted.
133I will set the SD in the most compatible mode, setting it with
134255 heads and 63 sectors, as suggested from several documentation and
135howto on line (I took as reference the preparation of a SD Card for the
136Beagleboard, running u-boot as bootloader).
137
138You should start clearing the partitions table on the SD card. Because
139the u-boot image must be stored at the offset 0x400, it must be assured
140that there is no partition at that address. A new SD card is already
141formatted with FAT filesystem and the partition starts from the first
142cylinder, so we need to change it.
143
144You can do all steps with fdisk. If the device for the SD card is
145/dev/mmcblk0, the following commands make the job:
146
1471. Start the fdisk utility (as superuser)
148 fdisk /dev/mmcblk0
149
1502. Clear the actual partition
151
152Command (m for help): o
153
1543. Print card info:
155
156Command (m for help): p
157Disk /dev/mmcblk0: 1981 MB, 1981284352 bytes
158
159In my case, I have a 2 GB card. I need the size to set later the correct value
160for the cylinders.
161
1624. Go to expert mode:
163
164Command (m for help): x
165
1665. Set card geometry
167
168Expert command (m for help): h
169Number of heads (1-256, default 4): 255
170
171Expert command (m for help): s
172Number of sectors (1-63, default 16): 63
173Warning: setting sector offset for DOS compatiblity
174
175We have set 255 heads, 63 sector. We have to set the cylinder.
176The value to be set can be calculated with:
177
Michael Heimpoldd0c329b2018-11-02 23:11:49 +0100178 cylinder = <total size> / <heads> / <sectors> / <blocksize>
Stefano Babic7b07f092010-01-20 18:19:10 +0100179
180in this example,
181 1981284352 / 255 / 63 / 512 = 239.x = 239
182
183
184Expert command (m for help): c
185Number of cylinders (1-1048576, default 60032): 239
186
1876. Leave the expert mode
188Expert command (m for help): r
189
1907. Set up a partition
191
192Now set a partition table to store the kernel or whatever you want. Of course,
193you can set additional partitions to store rootfs, data, etc.
194In my example I want to set a single partition. I must take care
195to not overwrite the space where I will put u-boot.
196
197Command (m for help): n
198Command action
199 e extended
200 p primary partition (1-4)
201p
202Partition number (1-4): 1
203First cylinder (1-239, default 1): 3
204Last cylinder, +cylinders or +size{K,M,G} (3-239, default 239): +100M
205
206Command (m for help): p
207
208Disk /dev/mmcblk0: 1967 MB, 1967128576 bytes
209255 heads, 63 sectors/track, 239 cylinders
210Units = cylinders of 16065 * 512 = 8225280 bytes
211Disk identifier: 0xb712a870
212
Wolfgang Denka2cfb242010-03-12 23:06:04 +0100213 Device Boot Start End Blocks Id System
214/dev/mmcblk0p1 3 16 112455 83 Linux
Stefano Babic7b07f092010-01-20 18:19:10 +0100215
Michal Simek4d0837b2023-09-08 09:11:31 +0200216I have set 100MB, leaving the first 2 sectors free. I will copy U-Boot
Stefano Babic7b07f092010-01-20 18:19:10 +0100217there.
218
2198. Write the partition table and exit.
220
221Command (m for help): w
222The partition table has been altered!
223
224Calling ioctl() to re-read partition table.
225
2269. Copy u-boot.imx on the SD card
227
228I use dd:
229
230dd if=u-boot.imx of=/dev/mmcblk0 bs=512 seek=2
231
232This command copies the u-boot image at the address 0x400, as required
233by the processor.
234
235Now remove your card from the PC and go to the target. If evrything went right,
236the u-boot prompt should come after power on.
237
238------------------------------------------------
239Author: Stefano babic <sbabic@denx.de>