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
  23 1) Prerequisites
  24 ----------------
  25
  26 To make a MX28 based board bootable, some tools are necessary. The first one
  27 is the "elftosb" tool distributed by Freescale Semiconductor. The other one
  28 is the "mxsboot" tool found in U-Boot source tree.
  29
  30 Firstly, obtain the elftosb archive from the following location:
  31
  32         http://foss.doredevelopment.dk/mirrors/imx/elftosb-10.12.01.tar.gz
  33
  34 We use a $VER variable here to denote the current version. At the time of
  35 writing of this document, that is "10.12.01". To obtain the file from command
  36 line, use:
  37
  38         $ VER="10.12.01"
  39         $ wget http://foss.doredevelopment.dk/mirrors/imx/elftosb-${VER}.tar.gz
  40
  41 Extract the file:
  42
  43         $ tar xzf elftosb-${VER}.tar.gz
  44
  45 Compile the file. We need to manually tell the linker to use also libm:
  46
  47         $ cd elftosb-${VER}/
  48         $ make LIBS="-lstdc++ -lm" elftosb
  49
  50 Optionally, remove debugging symbols from elftosb:
  51
  52         $ strip bld/linux/elftosb
  53
  54 Finally, install the "elftosb" binary. The "install" target is missing, so just
  55 copy the binary by hand:
  56
  57         $ sudo cp bld/linux/elftosb /usr/local/bin/
  58
  59 Make sure the "elftosb" binary can be found in your $PATH, in this case this
  60 means "/usr/local/bin/" has to be in your $PATH.
  61
  62 2) Compiling U-Boot for a MX28 based board
  63 -------------------------------------------
  64
  65 Compiling the U-Boot for a MX28 board is straightforward and done as compiling U-Boot
  66 for any other ARM device. For cross-compiler setup, please refer to ELDK5.0
  67 documentation. First, clean up the source code:
  68
  69         $ make mrproper
  70
  71 Next, configure U-Boot for a MX28 based board
  72
  73         $ make <mx28_based_board_name>_config
  74
  75 Examples:
  76
  77 1. For building U-boot for Denx M28EVK board:
  78
  79         $ make m28evk_config
  80
  81 2. For building U-boot for Freescale MX28EVK board:
  82
  83         $ make mx28evk_config
  84
  85 Lastly, compile U-Boot and prepare a "BootStream". The "BootStream" is a special
  86 type of file, which the i.MX28 CPU can boot. This is handled by the following
  87 command:
  88
  89         $ make u-boot.sb
  90
  91 HINT: To speed-up the build process, you can add -j<N>, where N is number of
  92       compiler instances that'll run in parallel.
  93
  94 The code produces "u-boot.sb" file. This file needs to be augmented with a
  95 proper header to allow successful boot from SD or NAND. Adding the header is
  96 discussed in the following chapters.
  97
  98 3) Installation of U-Boot for a MX28 based board to SD card
  99 -----------------------------------------------------------
 100
 101 To boot a MX28 based board from SD, set the boot mode DIP switches according
 102 to i.MX28 manual chapter 12.2.1 (Table 12-2), PORT=SSP0, SD/MMC master on
 103 SSP0, 3.3V.
 104
 105
 106 An SD card the i.MX28 CPU can use to boot U-Boot must contain a DOS partition
 107 table, which in turn carries a partition of special type and which contains a
 108 special header. The rest of partitions in the DOS partition table can be used
 109 by the user.
 110
 111 To prepare such partition, use your favourite partitioning tool. The partition
 112 must have the following parameters:
 113
 114         * Start sector .......... sector 2048
 115         * Partition size ........ at least 1024 kb
 116         * Partition type ........ 0x53 (sometimes "OnTrack DM6 Aux3")
 117
 118 For example in Linux fdisk, the sequence for a clear card follows. Be sure to
 119 run fdisk with the option "-u=sectors" to set units to sectors:
 120
 121         * o ..................... create a clear partition table
 122         * n ..................... create new partition
 123                 * p ............. primary partition
 124                 * 1 ............. first partition
 125                 * 2048 .......... first sector is 2048
 126                 * +1M ........... make the partition 1Mb big
 127         * t 1 ................... change first partition ID
 128                 * 53 ............ change the ID to 0x53 (OnTrack DM6 Aux3)
 129         * <create other partitions>
 130         * w ..................... write partition table to disk
 131
 132 The partition layout is ready, next the special partition must be filled with
 133 proper contents. The contents is generated by running the following command
 134 (see chapter 2)):
 135
 136         $ ./tools/mxsboot sd u-boot.sb u-boot.sd
 137
 138 The resulting file, "u-boot.sd", shall then be written to the partition. In this
 139 case, we assume the first partition of the SD card is /dev/mmcblk0p1:
 140
 141         $ dd if=u-boot.sd of=/dev/mmcblk0p1
 142
 143 Last step is to insert the card into MX28 based board and boot.
 144
 145 NOTE: If the user needs to adjust the start sector, the "mxsboot" tool contains
 146       a "-p" switch for that purpose. The "-p" switch takes the sector number as
 147       an argument.
 148
 149 4) Installation of U-Boot for NAND flash
 150 -----------------------------------------------
 151
 152 To boot a MX28 based board from NAND, set the boot mode DIP switches according to i.MX28
 153 manual chapter 12.2.1 (Table 12-2), PORT=GPMI, NAND 1.8 V.
 154
 155 There are two possibilities when preparing an image writable to NAND flash.
 156
 157         I) The NAND wasn't written at all yet or the BCB is broken
 158         ----------------------------------------------------------
 159            In this case, both BCB (FCB and DBBT) and firmware needs to be
 160            written to NAND. To generate NAND image containing all these,
 161            there is a tool called "mxsboot" in the "tools/" directory. The tool
 162            is invoked on "u-boot.sb" file from chapter 2):
 163
 164                  $ ./tools/mxsboot nand u-boot.sb u-boot.nand
 165
 166            NOTE: The above invokation works for NAND flash with geometry of
 167                  2048b per page, 64b OOB data, 128kb erase size. If your chip
 168                  has a different geometry, please use:
 169
 170                  -w <size>      change page size (default 2048 b)
 171                  -o <size>      change oob size (default 64 b)
 172                  -e <size>      change erase size (default 131072 b)
 173
 174                  The geometry information can be obtained from running U-Boot
 175                  on the MX28 board by issuing the "nand info" command.
 176
 177            The resulting file, "u-boot.nand" can be written directly to NAND
 178            from the U-Boot prompt. To simplify the process, the U-Boot default
 179            environment contains script "update_nand_full" to update the system.
 180
 181            This script expects a working TFTP server containing the file
 182            "u-boot.nand" in it's root directory. This can be changed by
 183            adjusting the "update_nand_full_filename" varible.
 184
 185            To update the system, run the following in U-Boot prompt:
 186
 187                  => run update_nand_full
 188
 189            In case you would only need to update the bootloader in future,
 190            see II) below.
 191
 192         II) The NAND was already written with a good BCB
 193         ------------------------------------------------
 194            This part applies after the part I) above was done at least once.
 195
 196            If part I) above was done correctly already, there is no need to
 197            write the FCB and DBBT parts of NAND again. It's possible to upgrade
 198            only the bootloader image.
 199
 200            To simplify the process of firmware update, the U-Boot default
 201            environment contains script "update_nand_firmware" to update only
 202            the firmware, without rewriting FCB and DBBT.
 203
 204            This script expects a working TFTP server containing the file
 205            "u-boot.sb" in it's root directory. This can be changed by
 206            adjusting the "update_nand_firmware_filename" varible.
 207
 208            To update the system, run the following in U-Boot prompt:
 209
 210                  => run update_nand_firmware
 211
 212         III) Special settings for the update scripts
 213         --------------------------------------------
 214            There is a slight possibility of the user wanting to adjust the
 215            STRIDE and COUNT options of the NAND boot. For description of these,
 216            see i.MX28 manual section 12.12.1.2 and 12.12.1.3.
 217
 218            The update scripts take this possibility into account. In case the
 219            user changes STRIDE by blowing fuses, the user also has to change
 220            "update_nand_stride" variable. In case the user changes COUNT by
 221            blowing fuses, the user also has to change "update_nand_count"
 222            variable for the update scripts to work correctly.
 223
 224            In case the user needs to boot a firmware image bigger than 1Mb, the
 225            user has to adjust the "update_nand_firmware_maxsz" variable for the
 226            update scripts to work properly.