[J-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 and MX51
processors via internal boot mode.

These processors can boot directly from NAND, SPI flash and SD card flash
using its internal boot ROM support. They 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.

This implementation does not use at the moment the secure boot feature
of the processor. The image is generated disabling all security fields.

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 compatible,
				others is invalid and error is generated.
				This command need appear the fist before
				other valid commands in configuration file.

	BOOT_FROM		nand/spi/sd/onenand
				Example:
				BOOT_FROM spi
	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 121 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 <[email protected]>
Commit	Line	Data
8edcde5e SB	1	---------------------------------------------
	2	Imximage Boot Image generation using mkimage
	3	---------------------------------------------
	4
	5	This document describes how to set up a U-Boot image
	6	that can be booted by Freescale MX25, MX35 and MX51
	7	processors via internal boot mode.
	8
	9	These processors can boot directly from NAND, SPI flash and SD card flash
	10	using its internal boot ROM support. They can boot from an internal
	11	UART, if booting from device media fails.
	12	Booting from NOR flash does not require to use this image type.
	13
	14	For more details refer Chapter 2 - System Boot and section 2.14
	15	(flash header description) of the processor's manual.
	16
	17	This implementation does not use at the moment the secure boot feature
	18	of the processor. The image is generated disabling all security fields.
	19
	20	Command syntax:
	21	--------------
	22	./tools/mkimage -l <mx u-boot_file>
	23	to list the imx image file details
	24
	25	./tools/mkimage -T imximage \
	26	-n <board specific configuration file> \
	27	-e <execution address> -d <u-boot binary> <output image file>
	28
	29	For example, for the mx51evk board:
	30	./tools/mkimage -n ./board/freescale/mx51evk/imximage.cfg \
	31	-T imximage -e 0x97800000 \
	32	-d u-boot.bin u-boot.imx
	33
	34	You can generate directly the image when you compile u-boot with:
	35
	36	$ make u-boot.imx
	37
	38	The output image can be flashed on the board SPI flash or on a SD card.
	39	In both cases, you have to copy the image at the offset required for the
	40	chosen media devices (0x400 for both SPI flash or SD card).
	41
	42	Please check Freescale documentation for further details.
	43
	44	Board specific configuration file specifications:
	45	-------------------------------------------------
	46	1. This file must present in the $(BOARDDIR) and the name should be
	47	imximage.cfg (since this is used in Makefile).
	48	2. This file can have empty lines and lines starting with "#" as first
	49	character to put comments.
	50	3. This file can have configuration command lines as mentioned below,
	51	any other information in this file is treated as invalid.
	52
	53	Configuration command line syntax:
	54	---------------------------------
	55	1. Each command line is must have two strings, first one command or address
	56	and second one data string
	57	2. Following are the valid command strings and associated data strings:-
	58	Command string data string
	59	-------------- -----------
8a1edd7d LHR	60	IMXIMAGE_VERSION 1/2
	61	1 is for mx25/mx35/mx51 compatible,
	62	2 is for mx53 compatible,
	63	others is invalid and error is generated.
	64	This command need appear the fist before
	65	other valid commands in configuration file.
	66
8edcde5e SB	67	BOOT_FROM nand/spi/sd/onenand
	68	Example:
	69	BOOT_FROM spi
	70	DATA type address value
	71
	72	type: word=4, halfword=2, byte=1
	73	address: physycal register address
	74	value: value to be set in register
	75	All values are in in hexadecimal.
	76	Example (write to IOMUXC):
	77	DATA 4 0x73FA88a0 0x200
	78
8a1edd7d LHR	79	The processor support up to 60 register programming commands for IMXIMAGE_VERSION 1
	80	and 121 register programming commands for IMXIMAGE_VERSION 2.
	81	An error is generated if more commands are found in the configuration file.
8edcde5e SB	82
	83	3. All commands are optional to program.
	84
	85	Setup a SD Card for booting
	86	--------------------------------
	87
	88	The following example prepare a SD card with u-boot and a FAT partition
	89	to be used to stored the kernel to be booted.
	90	I will set the SD in the most compatible mode, setting it with
	91	255 heads and 63 sectors, as suggested from several documentation and
	92	howto on line (I took as reference the preparation of a SD Card for the
	93	Beagleboard, running u-boot as bootloader).
	94
	95	You should start clearing the partitions table on the SD card. Because
	96	the u-boot image must be stored at the offset 0x400, it must be assured
	97	that there is no partition at that address. A new SD card is already
	98	formatted with FAT filesystem and the partition starts from the first
	99	cylinder, so we need to change it.
	100
	101	You can do all steps with fdisk. If the device for the SD card is
	102	/dev/mmcblk0, the following commands make the job:
	103
	104	1. Start the fdisk utility (as superuser)
	105	fdisk /dev/mmcblk0
	106
	107	2. Clear the actual partition
	108
	109	Command (m for help): o
	110
	111	3. Print card info:
	112
	113	Command (m for help): p
	114	Disk /dev/mmcblk0: 1981 MB, 1981284352 bytes
	115
	116	In my case, I have a 2 GB card. I need the size to set later the correct value
	117	for the cylinders.
	118
	119	4. Go to expert mode:
	120
	121	Command (m for help): x
	122
	123	5. Set card geometry
	124
	125	Expert command (m for help): h
	126	Number of heads (1-256, default 4): 255
	127
	128	Expert command (m for help): s
	129	Number of sectors (1-63, default 16): 63
	130	Warning: setting sector offset for DOS compatiblity
	131
	132	We have set 255 heads, 63 sector. We have to set the cylinder.
	133	The value to be set can be calculated with:
	134
	135	cilynder = <total size> / <heads> / <sectors> / <blocksize>
	136
	137	in this example,
	138	1981284352 / 255 / 63 / 512 = 239.x = 239
	139
	140
	141	Expert command (m for help): c
	142	Number of cylinders (1-1048576, default 60032): 239
	143
	144	6. Leave the expert mode
	145	Expert command (m for help): r
146
147	7. Set up a partition
148
149	Now set a partition table to store the kernel or whatever you want. Of course,
150	you can set additional partitions to store rootfs, data, etc.
151	In my example I want to set a single partition. I must take care
152	to not overwrite the space where I will put u-boot.
153
154	Command (m for help): n
155	Command action
156	e extended
157	p primary partition (1-4)
158	p
159	Partition number (1-4): 1
160	First cylinder (1-239, default 1): 3
161	Last cylinder, +cylinders or +size{K,M,G} (3-239, default 239): +100M
162
163	Command (m for help): p
164
165	Disk /dev/mmcblk0: 1967 MB, 1967128576 bytes
166	255 heads, 63 sectors/track, 239 cylinders
167	Units = cylinders of 16065 * 512 = 8225280 bytes
168	Disk identifier: 0xb712a870
169
93910edb WD	170	Device Boot Start End Blocks Id System
93910edb WD	171	/dev/mmcblk0p1 3 16 112455 83 Linux
8edcde5e SB	172
	173	I have set 100MB, leaving the first 2 sectors free. I will copy u-boot
	174	there.
	175
	176	8. Write the partition table and exit.
	177
	178	Command (m for help): w
	179	The partition table has been altered!
	180
	181	Calling ioctl() to re-read partition table.
	182
	183	9. Copy u-boot.imx on the SD card
	184
	185	I use dd:
	186
	187	dd if=u-boot.imx of=/dev/mmcblk0 bs=512 seek=2
	188
	189	This command copies the u-boot image at the address 0x400, as required
	190	by the processor.
	191
	192	Now remove your card from the PC and go to the target. If evrything went right,
	193	the u-boot prompt should come after power on.
	194
	195	------------------------------------------------
	196	Author: Stefano babic <[email protected]>