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

---------------------------------------------
Imximage Boot Image generation using mkimage
---------------------------------------------

This document describes how to set up a U-Boot image that can be booted
by Freescale MX25, MX35, MX51, MX53 and MX6 processors via internal boot
mode.

These processors can boot directly from NAND, SPI flash and SD card flash
using its internal boot ROM support. MX6 processors additionally support
boot from NOR flash and SATA disks. All processors can boot from an internal
UART, if booting from device media fails.
Booting from NOR flash does not require to use this image type.

For more details refer Chapter 2 - System Boot and section 2.14
(flash header description) of the processor's manual.

Command syntax:
--------------
./tools/mkimage -l <mx u-boot_file>
		to list the imx image file details

./tools/mkimage -T imximage \
		-n <board specific configuration file> \
		-e <execution address> -d <u-boot binary>  <output image file>

For example, for the mx51evk board:
./tools/mkimage -n ./board/freescale/mx51evk/imximage.cfg \
		-T imximage -e 0x97800000  \
		-d u-boot.bin u-boot.imx

You can generate directly the image when you compile u-boot with:

$ make u-boot.imx

The output image can be flashed on the board SPI flash or on a SD card.
In both cases, you have to copy the image at the offset required for the
chosen media devices (0x400 for both SPI flash or SD card).

Please check Freescale documentation for further details.

Board specific configuration file specifications:
-------------------------------------------------
1. This file must present in the $(BOARDDIR) and the name should be
	imximage.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 is 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
	--------------		-----------
	IMXIMAGE_VERSION        1/2
				1 is for mx25/mx35/mx51 compatible,
				2 is for mx53/mx6 compatible,
				others is invalid and error is generated.
				This command need appear the fist before
				other valid commands in configuration file.

	BOOT_OFFSET		value

				This command is parallel to BOOT_FROM and
				is preferred over BOOT_FROM.

				value:  Offset of the image header, this
					value shall be set to one of the
					values found in the file:
						arch/arm/include/asm/\
						mach-imx/imximage.cfg
				Example:
				BOOT_OFFSET FLASH_OFFSET_STANDARD

	BOOT_FROM		nand/spi/sd/onenand/nor/sata

				This command is parallel to BOOT_OFFSET and
				is to be deprecated in favor of BOOT_OFFSET.

				Example:
				BOOT_FROM spi

	CSF			value

				Total size of CSF (Command Sequence File)
				used for Secure Boot/ High Assurance Boot
				(HAB).

				Using this command will populate the IVT
				(Initial Vector Table) CSF pointer and adjust
				the length fields only. The CSF itself needs
				to be generated with Freescale tools and
				'manually' appended to the u-boot.imx file.

				The CSF is then simply concatenated
				to the u-boot image, making a signed bootloader,
				that the processor can verify
				if the fuses for the keys are burned.

				Further infos how to configure the SOC to verify
				the bootloader can be found in the "High
				Assurance Boot Version Application Programming
				Interface Reference Manual" as part of the
				Freescale Code Signing Tool, available on the
				manufacturer's website.

				Example:
				CSF 0x2000

	DATA			type address value

				type: word=4, halfword=2, byte=1
				address: physycal register address
				value: value to be set in register
				All values are in in hexadecimal.
				Example (write to IOMUXC):
				DATA 4 0x73FA88a0 0x200

The processor support up to 60 register programming commands for IMXIMAGE_VERSION 1
and 220 register programming commands for IMXIMAGE_VERSION 2.
An error is generated if more commands are found in the configuration file.

3. All commands are optional to program.

Setup a SD Card for booting
--------------------------------

The following example prepare a SD card with u-boot and a FAT partition
to be used to stored the kernel to be booted.
I will set the SD in the most compatible mode, setting it with
255 heads and 63 sectors, as suggested from several documentation and
howto on line (I took as reference the preparation of a SD Card for the
Beagleboard, running u-boot as bootloader).

You should start clearing the partitions table on the SD card. Because
the u-boot image must be stored at the offset 0x400, it must be assured
that there is no partition at that address. A new SD card is already
formatted with FAT filesystem and the partition starts from the first
cylinder, so we need to change it.

You can do all steps with fdisk. If the device for the SD card is
/dev/mmcblk0, the following commands make the job:

1. Start the fdisk utility (as superuser)
	fdisk /dev/mmcblk0

2. Clear the actual partition

Command (m for help): o

3. Print card info:

Command (m for help): p
Disk /dev/mmcblk0: 1981 MB, 1981284352 bytes

In my case, I have a 2 GB card. I need the size to set later the correct value
for the cylinders.

4. Go to expert mode:

Command (m for help): x

5. Set card geometry

Expert command (m for help): h
Number of heads (1-256, default 4): 255

Expert command (m for help): s
Number of sectors (1-63, default 16): 63
Warning: setting sector offset for DOS compatiblity

We have set 255 heads, 63 sector. We have to set the cylinder.
The value to be set can be calculated with:

	cilynder = <total size> / <heads> / <sectors> / <blocksize>

in this example,
	1981284352 / 255 / 63 / 512 = 239.x = 239


Expert command (m for help): c
Number of cylinders (1-1048576, default 60032): 239

6. Leave the expert mode
Expert command (m for help): r

7. Set up a partition

Now set a partition table to store the kernel or whatever you want. Of course,
you can set additional partitions to store rootfs, data, etc.
In my example I want to set a single partition. I must take care
to not overwrite the space where I will put u-boot.

Command (m for help): n
Command action
   e   extended
   p   primary partition (1-4)
p
Partition number (1-4): 1
First cylinder (1-239, default 1): 3
Last cylinder, +cylinders or +size{K,M,G} (3-239, default 239): +100M

Command (m for help): p

Disk /dev/mmcblk0: 1967 MB, 1967128576 bytes
255 heads, 63 sectors/track, 239 cylinders
Units = cylinders of 16065 * 512 = 8225280 bytes
Disk identifier: 0xb712a870

	Device Boot	 Start	       End	Blocks	 Id  System
/dev/mmcblk0p1		     3		16	112455	 83  Linux

I have set 100MB, leaving the first 2 sectors free. I will copy u-boot
there.

8. Write the partition table and exit.

Command (m for help): w
The partition table has been altered!

Calling ioctl() to re-read partition table.

9. Copy u-boot.imx on the SD card

I use dd:

dd if=u-boot.imx of=/dev/mmcblk0 bs=512 seek=2

This command copies the u-boot image at the address 0x400, as required
by the processor.

Now remove your card from the PC and go to the target. If evrything went right,
the u-boot prompt should come after power on.

------------------------------------------------
Author: Stefano babic <sbabic@denx.de>
Commit	Line	Data
8edcde5e SB	1	---------------------------------------------
	2	Imximage Boot Image generation using mkimage
	3	---------------------------------------------
	4
19b409c0 DB	5	This document describes how to set up a U-Boot image that can be booted
	6	by Freescale MX25, MX35, MX51, MX53 and MX6 processors via internal boot
	7	mode.
8edcde5e SB	8
8edcde5e SB	9	These processors can boot directly from NAND, SPI flash and SD card flash
19b409c0 DB	10	using its internal boot ROM support. MX6 processors additionally support
19b409c0 DB	11	boot from NOR flash and SATA disks. All processors can boot from an internal
8edcde5e SB	12	UART, if booting from device media fails.
	13	Booting from NOR flash does not require to use this image type.
	14
	15	For more details refer Chapter 2 - System Boot and section 2.14
	16	(flash header description) of the processor's manual.
	17
8edcde5e SB	18	Command 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
	27	For 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
	32	You can generate directly the image when you compile u-boot with:
	33
	34	$ make u-boot.imx
	35
	36	The output image can be flashed on the board SPI flash or on a SD card.
	37	In both cases, you have to copy the image at the offset required for the
	38	chosen media devices (0x400 for both SPI flash or SD card).
	39
	40	Please check Freescale documentation for further details.
	41
	42	Board specific configuration file specifications:
	43	-------------------------------------------------
	44	1. This file must present in the $(BOARDDIR) and the name should be
	45	imximage.cfg (since this is used in Makefile).
	46	2. This file can have empty lines and lines starting with "#" as first
	47	character to put comments.
	48	3. This file can have configuration command lines as mentioned below,
	49	any other information in this file is treated as invalid.
	50
	51	Configuration command line syntax:
	52	---------------------------------
	53	1. Each command line is must have two strings, first one command or address
	54	and second one data string
	55	2. Following are the valid command strings and associated data strings:-
	56	Command string data string
	57	-------------- -----------
8a1edd7d LHR	58	IMXIMAGE_VERSION 1/2
8a1edd7d LHR	59	1 is for mx25/mx35/mx51 compatible,
19b409c0	60	2 is for mx53/mx6 compatible,
8a1edd7d LHR	61	others is invalid and error is generated.
	62	This command need appear the fist before
	63	other valid commands in configuration file.
	64
6cb83829 MV	65	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/\
552a848e	74	mach-imx/imximage.cfg
6cb83829 MV	75	Example:
	76	BOOT_OFFSET FLASH_OFFSET_STANDARD
	77
19b409c0	78	BOOT_FROM nand/spi/sd/onenand/nor/sata
6cb83829 MV	79
	80	This command is parallel to BOOT_OFFSET and
	81	is to be deprecated in favor of BOOT_OFFSET.
	82
8edcde5e SB	83	Example:
8edcde5e SB	84	BOOT_FROM spi
6cb83829	85
0187c985 SB	86	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
8edcde5e SB	113	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
8a1edd7d	122	The processor support up to 60 register programming commands for IMXIMAGE_VERSION 1
6ce79d2f	123	and 220 register programming commands for IMXIMAGE_VERSION 2.
8a1edd7d	124	An error is generated if more commands are found in the configuration file.
8edcde5e SB	125
	126	3. All commands are optional to program.
	127
	128	Setup a SD Card for booting
	129	--------------------------------
	130
	131	The following example prepare a SD card with u-boot and a FAT partition
	132	to be used to stored the kernel to be booted.
	133	I will set the SD in the most compatible mode, setting it with
	134	255 heads and 63 sectors, as suggested from several documentation and
	135	howto on line (I took as reference the preparation of a SD Card for the
	136	Beagleboard, running u-boot as bootloader).
	137
	138	You should start clearing the partitions table on the SD card. Because
	139	the u-boot image must be stored at the offset 0x400, it must be assured
	140	that there is no partition at that address. A new SD card is already
	141	formatted with FAT filesystem and the partition starts from the first
	142	cylinder, so we need to change it.
	143
	144	You can do all steps with fdisk. If the device for the SD card is
	145	/dev/mmcblk0, the following commands make the job:
	146
	147	1. Start the fdisk utility (as superuser)
	148	fdisk /dev/mmcblk0
	149
	150	2. Clear the actual partition
	151
	152	Command (m for help): o
	153
	154	3. Print card info:
	155
	156	Command (m for help): p
	157	Disk /dev/mmcblk0: 1981 MB, 1981284352 bytes
	158
	159	In my case, I have a 2 GB card. I need the size to set later the correct value
	160	for the cylinders.
	161
	162	4. Go to expert mode:
	163
	164	Command (m for help): x
	165
	166	5. Set card geometry
	167
	168	Expert command (m for help): h
	169	Number of heads (1-256, default 4): 255
	170
	171	Expert command (m for help): s
	172	Number of sectors (1-63, default 16): 63
	173	Warning: setting sector offset for DOS compatiblity
	174
	175	We have set 255 heads, 63 sector. We have to set the cylinder.
	176	The value to be set can be calculated with:
	177
	178	cilynder = <total size> / <heads> / <sectors> / <blocksize>
	179
	180	in this example,
	181	1981284352 / 255 / 63 / 512 = 239.x = 239
	182
	183
	184	Expert command (m for help): c
	185	Number of cylinders (1-1048576, default 60032): 239
	186
	187	6. Leave the expert mode
	188	Expert command (m for help): r
189
190	7. Set up a partition
191
192	Now set a partition table to store the kernel or whatever you want. Of course,
193	you can set additional partitions to store rootfs, data, etc.
194	In my example I want to set a single partition. I must take care
195	to not overwrite the space where I will put u-boot.
196
197	Command (m for help): n
198	Command action
199	e extended
200	p primary partition (1-4)
201	p
202	Partition number (1-4): 1
203	First cylinder (1-239, default 1): 3
204	Last cylinder, +cylinders or +size{K,M,G} (3-239, default 239): +100M
205
206	Command (m for help): p
207
208	Disk /dev/mmcblk0: 1967 MB, 1967128576 bytes
209	255 heads, 63 sectors/track, 239 cylinders
210	Units = cylinders of 16065 * 512 = 8225280 bytes
211	Disk identifier: 0xb712a870
212
93910edb WD	213	Device Boot Start End Blocks Id System
93910edb WD	214	/dev/mmcblk0p1 3 16 112455 83 Linux
8edcde5e SB	215
	216	I have set 100MB, leaving the first 2 sectors free. I will copy u-boot
	217	there.
	218
	219	8. Write the partition table and exit.
	220
	221	Command (m for help): w
	222	The partition table has been altered!
	223
	224	Calling ioctl() to re-read partition table.
	225
	226	9. Copy u-boot.imx on the SD card
	227
	228	I use dd:
	229
	230	dd if=u-boot.imx of=/dev/mmcblk0 bs=512 seek=2
	231
	232	This command copies the u-boot image at the address 0x400, as required
	233	by the processor.
	234
	235	Now remove your card from the PC and go to the target. If evrything went right,
	236	the u-boot prompt should come after power on.
	237
	238	------------------------------------------------
	239	Author: Stefano babic <sbabic@denx.de>