[U-Boot] [PATCH 15/20] M28: Add doc/README.m28 documentation

Stefano Babic
2011-11-10T13:14:11Z

On 11/09/2011 10:18 AM, Marek Vasut wrote:
> Signed-off-by: Marek Vasut <marek.vasut@gmail.com>
> Cc: Stefano Babic <sbabic@denx.de>
> Cc: Wolfgang Denk <wd@denx.de>
> Cc: Detlev Zundel <dzu@denx.de>
> ---
> doc/README.m28 | 223 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
> 1 files changed, 223 insertions(+), 0 deletions(-)
> create mode 100644 doc/README.m28
>
> diff --git a/doc/README.m28 b/doc/README.m28
> new file mode 100644
> index 0000000..b749ce0
> --- /dev/null
> +++ b/doc/README.m28
> @@ -0,0 +1,223 @@
> +DENX M28EVK
> +===========
> +
> +This document describes the DENX M28/M28EVK 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
> +--------
> +
> +0) Files of the M28/M28EVK port
> +1) Prerequisites
> +2) Compiling U-Boot for M28
> +3) Installation of U-Boot for M28EVK to SD card
> +4) Installation of U-Boot for M28 to NAND flash
> +
> +0) Files of the M28/M28EVK port
> +-------------------------------
> +
> +arch/arm/cpu/arm926ejs/mx28/ - The CPU support code for the Freescale i.MX28
> +arch/arm/include/asm/arch-mx28/ - Header files for the Freescale i.MX28
> +board/denx/m28evk/ - M28EVK board specific files
> +include/configs/m28evk.h - M28EVK configuration file
> +
> +1) Prerequisites
> +----------------
> +
> +To make the M28 module or the M28 module or M28EVK board bootable, some tools
> +are necessary. The first one is the "elftosb" tool distributed by Freescale
> +Semiconductor. The other tool is the "mxsboot" tool found in U-Boot source tree.
> +
> +Firstly, obtain the elftosb archive from the following location:
> +
> + http://foss.doredevelopment.dk/mirrors/imx/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 http://foss.doredevelopment.dk/mirrors/imx/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 M28
> +---------------------------
> +
> +Compiling the U-Boot for M28 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 M28EVK:
> +
> + $ make m28evk_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 M28EVK to SD card
> +-----------------------------------------------
> +
> +To boot an M28 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 is the following:
> +
> + * 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 M28EVK 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 for M28 to NAND flash
> +-----------------------------------------------
> +
> +To boot an M28 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 M28 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.

Applied to u-boot-imx, thanks.

Best regards,
Stefano Babic

--
=====================================================================
DENX Software Engineering GmbH, MD: Wolfgang Denk & Detlev Zundel
HRB 165235 Munich, Office: Kirchenstr.5, D-82194 Groebenzell, Germany
Phone: +49-8142-66989-0 Fax: +49-8142-66989-80 Email: office at denx.de
=====================================================================