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

Booting U-Boot on a MXS processor
=================================

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

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

The term "MXS" refers to a family of Freescale SoCs that is composed by MX23
and MX28.

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 MXS based board
3) Installation of U-Boot for a MXS based board to SD card
4) Installation of U-Boot into NAND flash on a MX28 based board
5) Installation of U-Boot into SPI NOR flash on a MX28 based board

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

To make a MXS based board bootable, some tools are necessary. The only
mandatory tool is the "mxsboot" tool found in U-Boot source tree. The
tool is built automatically when compiling U-Boot for i.MX23 or i.MX28.

The production of BootStream image is handled via "mkimage", which is
also part of the U-Boot source tree. The "mkimage" requires OpenSSL
development libraries to be installed. In case of Debian and derivates,
this is installed by running:

	$ sudo apt-get install libssl-dev

NOTE: The "elftosb" tool distributed by Freescale Semiconductor is no
      longer necessary for general use of U-Boot on i.MX23 and i.MX28.
      The mkimage supports generation of BootStream images encrypted
      with a zero key, which is the vast majority of use-cases. In
      case you do need to produce image encrypted with non-zero key
      or other special features, please use the "elftosb" tool,
      otherwise continue to section 2). The installation procedure of
      the "elftosb" is outlined below:

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 MXS based board
-------------------------------------------

Compiling the U-Boot for a MXS 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 MXS based board

	$ make <mxs_based_board_name>_config

Examples:

1. For building U-Boot for Aries M28EVK board:

	$ make m28evk_config

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

	$ make mx28evk_config

3. For building U-Boot for Freescale MX23EVK board:

	$ make mx23evk_config

4. For building U-Boot for Olimex MX23 Olinuxino board:

	$ make mx23_olinuxino_config

Lastly, compile U-Boot and prepare a "BootStream". The "BootStream" is a special
type of file, which MXS CPUs 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.

NOTE: The process that produces u-boot.sb uses the mkimage to generate the
      BootStream. The BootStream is encrypted with zero key. In case you need
      some special features of the BootStream and plan on using the "elftosb"
      tool instead, the invocation to produce a compatible BootStream with the
      one produced by mkimage is outlined below. For further details, refer to
      the documentation bundled with the "elftosb" package.

	$ elftosb -zf imx23 -c arch/arm/cpu/arm926ejs/mxs/u-boot-imx23.bd \
		-o u-boot.sb
	$ elftosb -zf imx28 -c arch/arm/cpu/arm926ejs/mxs/u-boot-imx28.bd \
		-o u-boot.sb

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

To boot a MXS based board from SD, set the boot mode DIP switches according to
to MX28 manual, section 12.2.1 (Table 12-2) or MX23 manual, section 35.1.2
(Table 35-3).

The SD card used 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 the MXS 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 on a MX28 based board
---------------------------------------------------------------

To boot a MX28 based board from NAND, set the boot mode DIP switches according
to MX28 manual section 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" variable.

	   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" variable.

	   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 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.

5) Installation of U-Boot into SPI NOR flash on a MX28 based board
------------------------------------------------------------------

The u-boot.sb file can be directly written to SPI NOR from U-Boot prompt.

Load u-boot.sb into RAM, this can be done in several ways and one way is to use
tftp:
       => tftp u-boot.sb 0x42000000

Probe the SPI NOR flash:
       => sf probe

(SPI NOR should be succesfully detected in this step)

Erase the blocks where U-Boot binary will be written to:
       => sf erase 0x0 0x80000

Write u-boot.sb to SPI NOR:
       => sf write 0x42000000 0 0x80000

Power off the board and set the boot mode DIP switches to boot from the SPI NOR
according to MX28 manual section 12.2.1 (Table 12-2)

Last step is to power up the board and U-Boot should start from SPI NOR.
Commit	Line	Data
a187559e	1	Booting U-Boot on a MXS processor
54965b61	2	=================================
419ea2d8	3
54965b61 FE	4	This document describes the MXS U-Boot port. This document mostly covers topics
54965b61 FE	5	related to making the module/board bootable.
419ea2d8 FE	6
	7	Terminology
	8	-----------
	9
54965b61 FE	10	The term "MXS" refers to a family of Freescale SoCs that is composed by MX23
	11	and MX28.
	12
419ea2d8 FE	13	The dollar symbol ($) introduces a snipped of shell code. This shall be typed
	14	into the unix command prompt in U-Boot source code root directory.
	15
	16	The (=>) introduces a snipped of code that should by typed into U-Boot command
	17	prompt
	18
	19	Contents
	20	--------
	21
	22	1) Prerequisites
54965b61 FE	23	2) Compiling U-Boot for a MXS based board
	24	3) Installation of U-Boot for a MXS based board to SD card
	25	4) Installation of U-Boot into NAND flash on a MX28 based board
a187559e	26	5) Installation of U-Boot into SPI NOR flash on a MX28 based board
419ea2d8 FE	27
	28	1) Prerequisites
	29	----------------
	30
6654f33c MV	31	To make a MXS based board bootable, some tools are necessary. The only
	32	mandatory tool is the "mxsboot" tool found in U-Boot source tree. The
	33	tool is built automatically when compiling U-Boot for i.MX23 or i.MX28.
	34
	35	The production of BootStream image is handled via "mkimage", which is
	36	also part of the U-Boot source tree. The "mkimage" requires OpenSSL
	37	development libraries to be installed. In case of Debian and derivates,
	38	this is installed by running:
	39
	40	$ sudo apt-get install libssl-dev
	41
	42	NOTE: The "elftosb" tool distributed by Freescale Semiconductor is no
	43	longer necessary for general use of U-Boot on i.MX23 and i.MX28.
	44	The mkimage supports generation of BootStream images encrypted
	45	with a zero key, which is the vast majority of use-cases. In
	46	case you do need to produce image encrypted with non-zero key
	47	or other special features, please use the "elftosb" tool,
	48	otherwise continue to section 2). The installation procedure of
	49	the "elftosb" is outlined below:
419ea2d8 FE	50
	51	Firstly, obtain the elftosb archive from the following location:
	52
9de1c22f	53	ftp://ftp.denx.de/pub/tools/elftosb-10.12.01.tar.gz
419ea2d8 FE	54
	55	We use a $VER variable here to denote the current version. At the time of
	56	writing of this document, that is "10.12.01". To obtain the file from command
	57	line, use:
	58
	59	$ VER="10.12.01"
9de1c22f	60	$ wget ftp://ftp.denx.de/pub/tools/elftosb-${VER}.tar.gz
419ea2d8 FE	61
	62	Extract the file:
	63
	64	$ tar xzf elftosb-${VER}.tar.gz
	65
	66	Compile the file. We need to manually tell the linker to use also libm:
	67
	68	$ cd elftosb-${VER}/
	69	$ make LIBS="-lstdc++ -lm" elftosb
	70
	71	Optionally, remove debugging symbols from elftosb:
	72
	73	$ strip bld/linux/elftosb
	74
	75	Finally, install the "elftosb" binary. The "install" target is missing, so just
	76	copy the binary by hand:
	77
	78	$ sudo cp bld/linux/elftosb /usr/local/bin/
	79
	80	Make sure the "elftosb" binary can be found in your $PATH, in this case this
	81	means "/usr/local/bin/" has to be in your $PATH.
	82
54965b61	83	2) Compiling U-Boot for a MXS based board
419ea2d8 FE	84	-------------------------------------------
419ea2d8 FE	85
54965b61	86	Compiling the U-Boot for a MXS board is straightforward and done as compiling
84286c22 FE	87	U-Boot for any other ARM device. For cross-compiler setup, please refer to
84286c22 FE	88	ELDK5.0 documentation. First, clean up the source code:
419ea2d8 FE	89
	90	$ make mrproper
	91
54965b61	92	Next, configure U-Boot for a MXS based board
419ea2d8	93
54965b61	94	$ make <mxs_based_board_name>_config
419ea2d8 FE	95
	96	Examples:
	97
fcea480d	98	1. For building U-Boot for Aries M28EVK board:
419ea2d8 FE	99
	100	$ make m28evk_config
	101
a187559e	102	2. For building U-Boot for Freescale MX28EVK board:
419ea2d8 FE	103
	104	$ make mx28evk_config
	105
a187559e	106	3. For building U-Boot for Freescale MX23EVK board:
54965b61 FE	107
	108	$ make mx23evk_config
	109
a187559e	110	4. For building U-Boot for Olimex MX23 Olinuxino board:
54965b61 FE	111
	112	$ make mx23_olinuxino_config
	113
419ea2d8	114	Lastly, compile U-Boot and prepare a "BootStream". The "BootStream" is a special
54965b61	115	type of file, which MXS CPUs can boot. This is handled by the following
419ea2d8 FE	116	command:
	117
	118	$ make u-boot.sb
	119
	120	HINT: To speed-up the build process, you can add -j<N>, where N is number of
	121	compiler instances that'll run in parallel.
	122
	123	The code produces "u-boot.sb" file. This file needs to be augmented with a
	124	proper header to allow successful boot from SD or NAND. Adding the header is
	125	discussed in the following chapters.
	126
6654f33c MV	127	NOTE: The process that produces u-boot.sb uses the mkimage to generate the
	128	BootStream. The BootStream is encrypted with zero key. In case you need
	129	some special features of the BootStream and plan on using the "elftosb"
	130	tool instead, the invocation to produce a compatible BootStream with the
	131	one produced by mkimage is outlined below. For further details, refer to
	132	the documentation bundled with the "elftosb" package.
	133
	134	$ elftosb -zf imx23 -c arch/arm/cpu/arm926ejs/mxs/u-boot-imx23.bd \
	135	-o u-boot.sb
	136	$ elftosb -zf imx28 -c arch/arm/cpu/arm926ejs/mxs/u-boot-imx28.bd \
	137	-o u-boot.sb
	138
54965b61 FE	139	3) Installation of U-Boot for a MXS based board to SD card
54965b61 FE	140	----------------------------------------------------------
419ea2d8	141
54965b61 FE	142	To boot a MXS based board from SD, set the boot mode DIP switches according to
	143	to MX28 manual, section 12.2.1 (Table 12-2) or MX23 manual, section 35.1.2
	144	(Table 35-3).
419ea2d8	145
7333eca5 FE	146	The SD card used to boot U-Boot must contain a DOS partition table, which in
	147	turn carries a partition of special type and which contains a special header.
	148	The rest of partitions in the DOS partition table can be used by the user.
419ea2d8 FE	149
	150	To prepare such partition, use your favourite partitioning tool. The partition
	151	must have the following parameters:
	152
	153	* Start sector .......... sector 2048
	154	* Partition size ........ at least 1024 kb
	155	* Partition type ........ 0x53 (sometimes "OnTrack DM6 Aux3")
	156
	157	For example in Linux fdisk, the sequence for a clear card follows. Be sure to
	158	run fdisk with the option "-u=sectors" to set units to sectors:
	159
	160	* o ..................... create a clear partition table
	161	* n ..................... create new partition
	162	* p ............. primary partition
	163	* 1 ............. first partition
	164	* 2048 .......... first sector is 2048
	165	* +1M ........... make the partition 1Mb big
	166	* t 1 ................... change first partition ID
	167	* 53 ............ change the ID to 0x53 (OnTrack DM6 Aux3)
	168	* <create other partitions>
	169	* w ..................... write partition table to disk
	170
	171	The partition layout is ready, next the special partition must be filled with
	172	proper contents. The contents is generated by running the following command
	173	(see chapter 2)):
	174
	175	$ ./tools/mxsboot sd u-boot.sb u-boot.sd
	176
	177	The resulting file, "u-boot.sd", shall then be written to the partition. In this
	178	case, we assume the first partition of the SD card is /dev/mmcblk0p1:
	179
	180	$ dd if=u-boot.sd of=/dev/mmcblk0p1
	181
54965b61	182	Last step is to insert the card into the MXS based board and boot.
419ea2d8 FE	183
	184	NOTE: If the user needs to adjust the start sector, the "mxsboot" tool contains
	185	a "-p" switch for that purpose. The "-p" switch takes the sector number as
	186	an argument.
	187
54965b61 FE	188	4) Installation of U-Boot into NAND flash on a MX28 based board
54965b61 FE	189	---------------------------------------------------------------
419ea2d8	190
84286c22	191	To boot a MX28 based board from NAND, set the boot mode DIP switches according
54965b61	192	to MX28 manual section 12.2.1 (Table 12-2), PORT=GPMI, NAND 1.8 V.
419ea2d8 FE	193
	194	There are two possibilities when preparing an image writable to NAND flash.
	195
	196	I) The NAND wasn't written at all yet or the BCB is broken
	197	----------------------------------------------------------
	198	In this case, both BCB (FCB and DBBT) and firmware needs to be
	199	written to NAND. To generate NAND image containing all these,
	200	there is a tool called "mxsboot" in the "tools/" directory. The tool
	201	is invoked on "u-boot.sb" file from chapter 2):
	202
	203	$ ./tools/mxsboot nand u-boot.sb u-boot.nand
	204
	205	NOTE: The above invokation works for NAND flash with geometry of
	206	2048b per page, 64b OOB data, 128kb erase size. If your chip
	207	has a different geometry, please use:
	208
	209	-w <size> change page size (default 2048 b)
	210	-o <size> change oob size (default 64 b)
	211	-e <size> change erase size (default 131072 b)
	212
	213	The geometry information can be obtained from running U-Boot
	214	on the MX28 board by issuing the "nand info" command.
	215
	216	The resulting file, "u-boot.nand" can be written directly to NAND
	217	from the U-Boot prompt. To simplify the process, the U-Boot default
	218	environment contains script "update_nand_full" to update the system.
	219
	220	This script expects a working TFTP server containing the file
	221	"u-boot.nand" in it's root directory. This can be changed by
1cc0a9f4	222	adjusting the "update_nand_full_filename" variable.
419ea2d8 FE	223
	224	To update the system, run the following in U-Boot prompt:
	225
	226	=> run update_nand_full
	227
	228	In case you would only need to update the bootloader in future,
	229	see II) below.
	230
	231	II) The NAND was already written with a good BCB
	232	------------------------------------------------
	233	This part applies after the part I) above was done at least once.
	234
	235	If part I) above was done correctly already, there is no need to
	236	write the FCB and DBBT parts of NAND again. It's possible to upgrade
	237	only the bootloader image.
	238
	239	To simplify the process of firmware update, the U-Boot default
	240	environment contains script "update_nand_firmware" to update only
	241	the firmware, without rewriting FCB and DBBT.
	242
	243	This script expects a working TFTP server containing the file
	244	"u-boot.sb" in it's root directory. This can be changed by
1cc0a9f4	245	adjusting the "update_nand_firmware_filename" variable.
419ea2d8 FE	246
	247	To update the system, run the following in U-Boot prompt:
	248
	249	=> run update_nand_firmware
	250
	251	III) Special settings for the update scripts
	252	--------------------------------------------
	253	There is a slight possibility of the user wanting to adjust the
	254	STRIDE and COUNT options of the NAND boot. For description of these,
54965b61	255	see MX28 manual section 12.12.1.2 and 12.12.1.3.
419ea2d8 FE	256
	257	The update scripts take this possibility into account. In case the
	258	user changes STRIDE by blowing fuses, the user also has to change
	259	"update_nand_stride" variable. In case the user changes COUNT by
	260	blowing fuses, the user also has to change "update_nand_count"
	261	variable for the update scripts to work correctly.
	262
	263	In case the user needs to boot a firmware image bigger than 1Mb, the
	264	user has to adjust the "update_nand_firmware_maxsz" variable for the
	265	update scripts to work properly.
a81c90f4 FE	266
	267	5) Installation of U-Boot into SPI NOR flash on a MX28 based board
	268	------------------------------------------------------------------
	269
a187559e	270	The u-boot.sb file can be directly written to SPI NOR from U-Boot prompt.
a81c90f4 FE	271
	272	Load u-boot.sb into RAM, this can be done in several ways and one way is to use
	273	tftp:
	274	=> tftp u-boot.sb 0x42000000
	275
	276	Probe the SPI NOR flash:
	277	=> sf probe
	278
	279	(SPI NOR should be succesfully detected in this step)
	280
a187559e	281	Erase the blocks where U-Boot binary will be written to:
a81c90f4 FE	282	=> sf erase 0x0 0x80000
	283
	284	Write u-boot.sb to SPI NOR:
	285	=> sf write 0x42000000 0 0x80000
	286
	287	Power off the board and set the boot mode DIP switches to boot from the SPI NOR
	288	according to MX28 manual section 12.2.1 (Table 12-2)
	289
a187559e	290	Last step is to power up the board and U-Boot should start from SPI NOR.