[J-u-boot.git] / doc / README.mx28_common

Booting U-boot on a MX28 processor
==================================

This document describes the MX28 U-Boot port. This document mostly
covers topics related to making the module/board bootable.

Terminology
-----------

The dollar symbol ($) introduces a snipped of shell code. This shall be typed
into the unix command prompt in U-Boot source code root directory.

The (=>) introduces a snipped of code that should by typed into U-Boot command
prompt

Contents
--------

1) Prerequisites
2) Compiling U-Boot for a MX28 based board
3) Installation of U-Boot for a MX28 based board to SD card
4) Installation of U-Boot into NAND flash

1) Prerequisites
----------------

To make a MX28 based board bootable, some tools are necessary. The first one
is the "elftosb" tool distributed by Freescale Semiconductor. The other one
is the "mxsboot" tool found in U-Boot source tree.

Firstly, obtain the elftosb archive from the following location:

	ftp://ftp.denx.de/pub/tools/elftosb-10.12.01.tar.gz

We use a $VER variable here to denote the current version. At the time of
writing of this document, that is "10.12.01". To obtain the file from command
line, use:

	$ VER="10.12.01"
	$ wget ftp://ftp.denx.de/pub/tools/elftosb-${VER}.tar.gz

Extract the file:

	$ tar xzf elftosb-${VER}.tar.gz

Compile the file. We need to manually tell the linker to use also libm:

	$ cd elftosb-${VER}/
	$ make LIBS="-lstdc++ -lm" elftosb

Optionally, remove debugging symbols from elftosb:

	$ strip bld/linux/elftosb

Finally, install the "elftosb" binary. The "install" target is missing, so just
copy the binary by hand:

	$ sudo cp bld/linux/elftosb /usr/local/bin/

Make sure the "elftosb" binary can be found in your $PATH, in this case this
means "/usr/local/bin/" has to be in your $PATH.

2) Compiling U-Boot for a MX28 based board
-------------------------------------------

Compiling the U-Boot for a MX28 board is straightforward and done as compiling
U-Boot for any other ARM device. For cross-compiler setup, please refer to
ELDK5.0 documentation. First, clean up the source code:

	$ make mrproper

Next, configure U-Boot for a MX28 based board

	$ make <mx28_based_board_name>_config

Examples:

1. For building U-boot for Denx M28EVK board:

	$ make m28evk_config

2. For building U-boot for Freescale MX28EVK board:

	$ make mx28evk_config

Lastly, compile U-Boot and prepare a "BootStream". The "BootStream" is a special
type of file, which the i.MX28 CPU can boot. This is handled by the following
command:

	$ make u-boot.sb

HINT: To speed-up the build process, you can add -j<N>, where N is number of
      compiler instances that'll run in parallel.

The code produces "u-boot.sb" file. This file needs to be augmented with a
proper header to allow successful boot from SD or NAND. Adding the header is
discussed in the following chapters.

3) Installation of U-Boot for a MX28 based board to SD card
-----------------------------------------------------------

To boot a MX28 based board from SD, set the boot mode DIP switches according
to i.MX28 manual chapter 12.2.1 (Table 12-2).

An SD card the i.MX28 CPU can use to boot U-Boot must contain a DOS partition
table, which in turn carries a partition of special type and which contains a
special header. The rest of partitions in the DOS partition table can be used
by the user.

To prepare such partition, use your favourite partitioning tool. The partition
must have the following parameters:

	* Start sector .......... sector 2048
	* Partition size ........ at least 1024 kb
	* Partition type ........ 0x53 (sometimes "OnTrack DM6 Aux3")

For example in Linux fdisk, the sequence for a clear card follows. Be sure to
run fdisk with the option "-u=sectors" to set units to sectors:

	* o ..................... create a clear partition table
	* n ..................... create new partition
		* p ............. primary partition
		* 1 ............. first partition
		* 2048 .......... first sector is 2048
		* +1M ........... make the partition 1Mb big
	* t 1 ................... change first partition ID
		* 53 ............ change the ID to 0x53 (OnTrack DM6 Aux3)
	* <create other partitions>
	* w ..................... write partition table to disk

The partition layout is ready, next the special partition must be filled with
proper contents. The contents is generated by running the following command
(see chapter 2)):

	$ ./tools/mxsboot sd u-boot.sb u-boot.sd

The resulting file, "u-boot.sd", shall then be written to the partition. In this
case, we assume the first partition of the SD card is /dev/mmcblk0p1:

	$ dd if=u-boot.sd of=/dev/mmcblk0p1

Last step is to insert the card into MX28 based board and boot.

NOTE: If the user needs to adjust the start sector, the "mxsboot" tool contains
      a "-p" switch for that purpose. The "-p" switch takes the sector number as
      an argument.

4) Installation of U-Boot into NAND flash
-----------------------------------------

To boot a MX28 based board from NAND, set the boot mode DIP switches according
to i.MX28 manual chapter 12.2.1 (Table 12-2), PORT=GPMI, NAND 1.8 V.

There are two possibilities when preparing an image writable to NAND flash.

	I) The NAND wasn't written at all yet or the BCB is broken
	----------------------------------------------------------
	   In this case, both BCB (FCB and DBBT) and firmware needs to be
	   written to NAND. To generate NAND image containing all these,
	   there is a tool called "mxsboot" in the "tools/" directory. The tool
	   is invoked on "u-boot.sb" file from chapter 2):

		 $ ./tools/mxsboot nand u-boot.sb u-boot.nand

	   NOTE: The above invokation works for NAND flash with geometry of
		 2048b per page, 64b OOB data, 128kb erase size. If your chip
		 has a different geometry, please use:

		 -w <size>	change page size (default 2048 b)
		 -o <size>	change oob size (default 64 b)
		 -e <size>	change erase size (default 131072 b)

		 The geometry information can be obtained from running U-Boot
		 on the MX28 board by issuing the "nand info" command.

	   The resulting file, "u-boot.nand" can be written directly to NAND
	   from the U-Boot prompt. To simplify the process, the U-Boot default
	   environment contains script "update_nand_full" to update the system.

	   This script expects a working TFTP server containing the file
	   "u-boot.nand" in it's root directory. This can be changed by
	   adjusting the "update_nand_full_filename" varible.

	   To update the system, run the following in U-Boot prompt:

		 => run update_nand_full

	   In case you would only need to update the bootloader in future,
	   see II) below.

	II) The NAND was already written with a good BCB
	------------------------------------------------
	   This part applies after the part I) above was done at least once.

	   If part I) above was done correctly already, there is no need to
	   write the FCB and DBBT parts of NAND again. It's possible to upgrade
	   only the bootloader image.

	   To simplify the process of firmware update, the U-Boot default
	   environment contains script "update_nand_firmware" to update only
	   the firmware, without rewriting FCB and DBBT.

	   This script expects a working TFTP server containing the file
	   "u-boot.sb" in it's root directory. This can be changed by
	   adjusting the "update_nand_firmware_filename" varible.

	   To update the system, run the following in U-Boot prompt:

		 => run update_nand_firmware

	III) Special settings for the update scripts
	--------------------------------------------
	   There is a slight possibility of the user wanting to adjust the
	   STRIDE and COUNT options of the NAND boot. For description of these,
	   see i.MX28 manual section 12.12.1.2 and 12.12.1.3.

	   The update scripts take this possibility into account. In case the
	   user changes STRIDE by blowing fuses, the user also has to change
	   "update_nand_stride" variable. In case the user changes COUNT by
	   blowing fuses, the user also has to change "update_nand_count"
	   variable for the update scripts to work correctly.

	   In case the user needs to boot a firmware image bigger than 1Mb, the
	   user has to adjust the "update_nand_firmware_maxsz" variable for the
	   update scripts to work properly.
Commit	Line	Data
419ea2d8 FE	1	Booting U-boot on a MX28 processor
	2	==================================
	3
	4	This document describes the MX28 U-Boot port. This document mostly
	5	covers topics related to making the module/board bootable.
	6
	7	Terminology
	8	-----------
	9
	10	The dollar symbol ($) introduces a snipped of shell code. This shall be typed
	11	into the unix command prompt in U-Boot source code root directory.
	12
	13	The (=>) introduces a snipped of code that should by typed into U-Boot command
	14	prompt
	15
	16	Contents
	17	--------
	18
	19	1) Prerequisites
	20	2) Compiling U-Boot for a MX28 based board
	21	3) Installation of U-Boot for a MX28 based board to SD card
e9fd0a00	22	4) Installation of U-Boot into NAND flash
419ea2d8 FE	23
	24	1) Prerequisites
	25	----------------
	26
	27	To make a MX28 based board bootable, some tools are necessary. The first one
	28	is the "elftosb" tool distributed by Freescale Semiconductor. The other one
	29	is the "mxsboot" tool found in U-Boot source tree.
	30
	31	Firstly, obtain the elftosb archive from the following location:
	32
9de1c22f	33	ftp://ftp.denx.de/pub/tools/elftosb-10.12.01.tar.gz
419ea2d8 FE	34
	35	We use a $VER variable here to denote the current version. At the time of
	36	writing of this document, that is "10.12.01". To obtain the file from command
	37	line, use:
	38
	39	$ VER="10.12.01"
9de1c22f	40	$ wget ftp://ftp.denx.de/pub/tools/elftosb-${VER}.tar.gz
419ea2d8 FE	41
	42	Extract the file:
	43
	44	$ tar xzf elftosb-${VER}.tar.gz
	45
	46	Compile the file. We need to manually tell the linker to use also libm:
	47
	48	$ cd elftosb-${VER}/
	49	$ make LIBS="-lstdc++ -lm" elftosb
	50
	51	Optionally, remove debugging symbols from elftosb:
	52
	53	$ strip bld/linux/elftosb
	54
	55	Finally, install the "elftosb" binary. The "install" target is missing, so just
	56	copy the binary by hand:
	57
	58	$ sudo cp bld/linux/elftosb /usr/local/bin/
	59
	60	Make sure the "elftosb" binary can be found in your $PATH, in this case this
	61	means "/usr/local/bin/" has to be in your $PATH.
	62
	63	2) Compiling U-Boot for a MX28 based board
	64	-------------------------------------------
	65
84286c22 FE	66	Compiling the U-Boot for a MX28 board is straightforward and done as compiling
	67	U-Boot for any other ARM device. For cross-compiler setup, please refer to
	68	ELDK5.0 documentation. First, clean up the source code:
419ea2d8 FE	69
	70	$ make mrproper
	71
	72	Next, configure U-Boot for a MX28 based board
	73
	74	$ make <mx28_based_board_name>_config
	75
	76	Examples:
	77
	78	1. For building U-boot for Denx M28EVK board:
	79
	80	$ make m28evk_config
	81
	82	2. For building U-boot for Freescale MX28EVK board:
	83
	84	$ make mx28evk_config
	85
	86	Lastly, compile U-Boot and prepare a "BootStream". The "BootStream" is a special
	87	type of file, which the i.MX28 CPU can boot. This is handled by the following
	88	command:
	89
	90	$ make u-boot.sb
	91
	92	HINT: To speed-up the build process, you can add -j<N>, where N is number of
	93	compiler instances that'll run in parallel.
	94
	95	The code produces "u-boot.sb" file. This file needs to be augmented with a
	96	proper header to allow successful boot from SD or NAND. Adding the header is
	97	discussed in the following chapters.
	98
	99	3) Installation of U-Boot for a MX28 based board to SD card
	100	-----------------------------------------------------------
	101
	102	To boot a MX28 based board from SD, set the boot mode DIP switches according
3f5e2e2a	103	to i.MX28 manual chapter 12.2.1 (Table 12-2).
419ea2d8 FE	104
	105	An SD card the i.MX28 CPU can use to boot U-Boot must contain a DOS partition
	106	table, which in turn carries a partition of special type and which contains a
	107	special header. The rest of partitions in the DOS partition table can be used
	108	by the user.
	109
	110	To prepare such partition, use your favourite partitioning tool. The partition
	111	must have the following parameters:
	112
	113	* Start sector .......... sector 2048
	114	* Partition size ........ at least 1024 kb
	115	* Partition type ........ 0x53 (sometimes "OnTrack DM6 Aux3")
	116
	117	For example in Linux fdisk, the sequence for a clear card follows. Be sure to
	118	run fdisk with the option "-u=sectors" to set units to sectors:
	119
	120	* o ..................... create a clear partition table
	121	* n ..................... create new partition
	122	* p ............. primary partition
	123	* 1 ............. first partition
	124	* 2048 .......... first sector is 2048
	125	* +1M ........... make the partition 1Mb big
	126	* t 1 ................... change first partition ID
	127	* 53 ............ change the ID to 0x53 (OnTrack DM6 Aux3)
	128	* <create other partitions>
	129	* w ..................... write partition table to disk
	130
	131	The partition layout is ready, next the special partition must be filled with
	132	proper contents. The contents is generated by running the following command
	133	(see chapter 2)):
	134
	135	$ ./tools/mxsboot sd u-boot.sb u-boot.sd
	136
	137	The resulting file, "u-boot.sd", shall then be written to the partition. In this
	138	case, we assume the first partition of the SD card is /dev/mmcblk0p1:
	139
	140	$ dd if=u-boot.sd of=/dev/mmcblk0p1
	141
	142	Last step is to insert the card into MX28 based board and boot.
	143
	144	NOTE: If the user needs to adjust the start sector, the "mxsboot" tool contains
	145	a "-p" switch for that purpose. The "-p" switch takes the sector number as
	146	an argument.
	147
e9fd0a00 FE	148	4) Installation of U-Boot into NAND flash
e9fd0a00 FE	149	-----------------------------------------
419ea2d8	150
84286c22 FE	151	To boot a MX28 based board from NAND, set the boot mode DIP switches according
84286c22 FE	152	to i.MX28 manual chapter 12.2.1 (Table 12-2), PORT=GPMI, NAND 1.8 V.
419ea2d8 FE	153
	154	There are two possibilities when preparing an image writable to NAND flash.
	155
	156	I) The NAND wasn't written at all yet or the BCB is broken
	157	----------------------------------------------------------
	158	In this case, both BCB (FCB and DBBT) and firmware needs to be
	159	written to NAND. To generate NAND image containing all these,
	160	there is a tool called "mxsboot" in the "tools/" directory. The tool
	161	is invoked on "u-boot.sb" file from chapter 2):
	162
	163	$ ./tools/mxsboot nand u-boot.sb u-boot.nand
	164
	165	NOTE: The above invokation works for NAND flash with geometry of
	166	2048b per page, 64b OOB data, 128kb erase size. If your chip
	167	has a different geometry, please use:
	168
	169	-w <size> change page size (default 2048 b)
	170	-o <size> change oob size (default 64 b)
	171	-e <size> change erase size (default 131072 b)
	172
	173	The geometry information can be obtained from running U-Boot
	174	on the MX28 board by issuing the "nand info" command.
	175
	176	The resulting file, "u-boot.nand" can be written directly to NAND
	177	from the U-Boot prompt. To simplify the process, the U-Boot default
	178	environment contains script "update_nand_full" to update the system.
	179
	180	This script expects a working TFTP server containing the file
	181	"u-boot.nand" in it's root directory. This can be changed by
	182	adjusting the "update_nand_full_filename" varible.
	183
	184	To update the system, run the following in U-Boot prompt:
	185
	186	=> run update_nand_full
	187
	188	In case you would only need to update the bootloader in future,
	189	see II) below.
	190
	191	II) The NAND was already written with a good BCB
	192	------------------------------------------------
	193	This part applies after the part I) above was done at least once.
	194
	195	If part I) above was done correctly already, there is no need to
	196	write the FCB and DBBT parts of NAND again. It's possible to upgrade
	197	only the bootloader image.
	198
	199	To simplify the process of firmware update, the U-Boot default
	200	environment contains script "update_nand_firmware" to update only
	201	the firmware, without rewriting FCB and DBBT.
	202
	203	This script expects a working TFTP server containing the file
	204	"u-boot.sb" in it's root directory. This can be changed by
	205	adjusting the "update_nand_firmware_filename" varible.
	206
	207	To update the system, run the following in U-Boot prompt:
	208
	209	=> run update_nand_firmware
	210
	211	III) Special settings for the update scripts
	212	--------------------------------------------
	213	There is a slight possibility of the user wanting to adjust the
	214	STRIDE and COUNT options of the NAND boot. For description of these,
	215	see i.MX28 manual section 12.12.1.2 and 12.12.1.3.
	216
217	The update scripts take this possibility into account. In case the
218	user changes STRIDE by blowing fuses, the user also has to change
219	"update_nand_stride" variable. In case the user changes COUNT by
220	blowing fuses, the user also has to change "update_nand_count"
221	variable for the update scripts to work correctly.
222
223	In case the user needs to boot a firmware image bigger than 1Mb, the
224	user has to adjust the "update_nand_firmware_maxsz" variable for the
225	update scripts to work properly.