doc/README.mx28_common - uboot/armada - Git at Google

 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), PORT=SSP0, SD/MMC master on
 SSP0, 3.3V.


 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.
	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), PORT=SSP0, SD/MMC master on
	SSP0, 3.3V.


	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.