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