doc/README.mx28_common

   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
  22 4) Installation of U-Boot into NAND flash
  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
  33         ftp://ftp.denx.de/pub/tools/elftosb-10.12.01.tar.gz
  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"
  40         $ wget ftp://ftp.denx.de/pub/tools/elftosb-${VER}.tar.gz
  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
  66 Compiling the U-Boot for a MX28 board is straightforward and done as compiling U-Boot
  67 for any other ARM device. For cross-compiler setup, please refer to ELDK5.0
  68 documentation. First, clean up the source code:
  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
 103 to i.MX28 manual chapter 12.2.1 (Table 12-2), PORT=SSP0, SD/MMC master on
 104 SSP0, 3.3V.
 105
 106
 107 An SD card the i.MX28 CPU can use to boot U-Boot must contain a DOS partition
 108 table, which in turn carries a partition of special type and which contains a
 109 special header. The rest of partitions in the DOS partition table can be used
 110 by the user.
 111
 112 To prepare such partition, use your favourite partitioning tool. The partition
 113 must have the following parameters:
 114
 115         * Start sector .......... sector 2048
 116         * Partition size ........ at least 1024 kb
 117         * Partition type ........ 0x53 (sometimes "OnTrack DM6 Aux3")
 118
 119 For example in Linux fdisk, the sequence for a clear card follows. Be sure to
 120 run fdisk with the option "-u=sectors" to set units to sectors:
 121
 122         * o ..................... create a clear partition table
 123         * n ..................... create new partition
 124                 * p ............. primary partition
 125                 * 1 ............. first partition
 126                 * 2048 .......... first sector is 2048
 127                 * +1M ........... make the partition 1Mb big
 128         * t 1 ................... change first partition ID
 129                 * 53 ............ change the ID to 0x53 (OnTrack DM6 Aux3)
 130         * <create other partitions>
 131         * w ..................... write partition table to disk
 132
 133 The partition layout is ready, next the special partition must be filled with
 134 proper contents. The contents is generated by running the following command
 135 (see chapter 2)):
 136
 137         $ ./tools/mxsboot sd u-boot.sb u-boot.sd
 138
 139 The resulting file, "u-boot.sd", shall then be written to the partition. In this
 140 case, we assume the first partition of the SD card is /dev/mmcblk0p1:
 141
 142         $ dd if=u-boot.sd of=/dev/mmcblk0p1
 143
 144 Last step is to insert the card into MX28 based board and boot.
 145
 146 NOTE: If the user needs to adjust the start sector, the "mxsboot" tool contains
 147       a "-p" switch for that purpose. The "-p" switch takes the sector number as
 148       an argument.
 149
 150 4) Installation of U-Boot into NAND flash
 151 -----------------------------------------
 152
 153 To boot a MX28 based board from NAND, set the boot mode DIP switches according to i.MX28
 154 manual chapter 12.2.1 (Table 12-2), PORT=GPMI, NAND 1.8 V.
 155
 156 There are two possibilities when preparing an image writable to NAND flash.
 157
 158         I) The NAND wasn't written at all yet or the BCB is broken
 159         ----------------------------------------------------------
 160            In this case, both BCB (FCB and DBBT) and firmware needs to be
 161            written to NAND. To generate NAND image containing all these,
 162            there is a tool called "mxsboot" in the "tools/" directory. The tool
 163            is invoked on "u-boot.sb" file from chapter 2):
 164
 165                  $ ./tools/mxsboot nand u-boot.sb u-boot.nand
 166
 167            NOTE: The above invokation works for NAND flash with geometry of
 168                  2048b per page, 64b OOB data, 128kb erase size. If your chip
 169                  has a different geometry, please use:
 170
 171                  -w <size>      change page size (default 2048 b)
 172                  -o <size>      change oob size (default 64 b)
 173                  -e <size>      change erase size (default 131072 b)
 174
 175                  The geometry information can be obtained from running U-Boot
 176                  on the MX28 board by issuing the "nand info" command.
 177
 178            The resulting file, "u-boot.nand" can be written directly to NAND
 179            from the U-Boot prompt. To simplify the process, the U-Boot default
 180            environment contains script "update_nand_full" to update the system.
 181
 182            This script expects a working TFTP server containing the file
 183            "u-boot.nand" in it's root directory. This can be changed by
 184            adjusting the "update_nand_full_filename" varible.
 185
 186            To update the system, run the following in U-Boot prompt:
 187
 188                  => run update_nand_full
 189
 190            In case you would only need to update the bootloader in future,
 191            see II) below.
 192
 193         II) The NAND was already written with a good BCB
 194         ------------------------------------------------
 195            This part applies after the part I) above was done at least once.
 196
 197            If part I) above was done correctly already, there is no need to
 198            write the FCB and DBBT parts of NAND again. It's possible to upgrade
 199            only the bootloader image.
 200
 201            To simplify the process of firmware update, the U-Boot default
 202            environment contains script "update_nand_firmware" to update only
 203            the firmware, without rewriting FCB and DBBT.
 204
 205            This script expects a working TFTP server containing the file
 206            "u-boot.sb" in it's root directory. This can be changed by
 207            adjusting the "update_nand_firmware_filename" varible.
 208
 209            To update the system, run the following in U-Boot prompt:
 210
 211                  => run update_nand_firmware
 212
 213         III) Special settings for the update scripts
 214         --------------------------------------------
 215            There is a slight possibility of the user wanting to adjust the
 216            STRIDE and COUNT options of the NAND boot. For description of these,
 217            see i.MX28 manual section 12.12.1.2 and 12.12.1.3.
 218
 219            The update scripts take this possibility into account. In case the
 220            user changes STRIDE by blowing fuses, the user also has to change
 221            "update_nand_stride" variable. In case the user changes COUNT by
 222            blowing fuses, the user also has to change "update_nand_count"
 223            variable for the update scripts to work correctly.
 224
 225            In case the user needs to boot a firmware image bigger than 1Mb, the
 226            user has to adjust the "update_nand_firmware_maxsz" variable for the
 227            update scripts to work properly.