doc/README.mxs

   1 Booting U-boot on a MXS processor
   2 =================================
   3
   4 This document describes the MXS U-Boot port. This document mostly covers topics
   5 related to making the module/board bootable.
   6
   7 Terminology
   8 -----------
   9
  10 The term "MXS" refers to a family of Freescale SoCs that is composed by MX23
  11 and MX28.
  12
  13 The dollar symbol ($) introduces a snipped of shell code. This shall be typed
  14 into the unix command prompt in U-Boot source code root directory.
  15
  16 The (=>) introduces a snipped of code that should by typed into U-Boot command
  17 prompt
  18
  19 Contents
  20 --------
  21
  22 1) Prerequisites
  23 2) Compiling U-Boot for a MXS based board
  24 3) Installation of U-Boot for a MXS based board to SD card
  25 4) Installation of U-Boot into NAND flash on a MX28 based board
  26
  27 1) Prerequisites
  28 ----------------
  29
  30 To make a MXS based board bootable, some tools are necessary. The only
  31 mandatory tool is the "mxsboot" tool found in U-Boot source tree. The
  32 tool is built automatically when compiling U-Boot for i.MX23 or i.MX28.
  33
  34 The production of BootStream image is handled via "mkimage", which is
  35 also part of the U-Boot source tree. The "mkimage" requires OpenSSL
  36 development libraries to be installed. In case of Debian and derivates,
  37 this is installed by running:
  38
  39         $ sudo apt-get install libssl-dev
  40
  41 NOTE: The "elftosb" tool distributed by Freescale Semiconductor is no
  42       longer necessary for general use of U-Boot on i.MX23 and i.MX28.
  43       The mkimage supports generation of BootStream images encrypted
  44       with a zero key, which is the vast majority of use-cases. In
  45       case you do need to produce image encrypted with non-zero key
  46       or other special features, please use the "elftosb" tool,
  47       otherwise continue to section 2). The installation procedure of
  48       the "elftosb" is outlined below:
  49
  50 Firstly, obtain the elftosb archive from the following location:
  51
  52         ftp://ftp.denx.de/pub/tools/elftosb-10.12.01.tar.gz
  53
  54 We use a $VER variable here to denote the current version. At the time of
  55 writing of this document, that is "10.12.01". To obtain the file from command
  56 line, use:
  57
  58         $ VER="10.12.01"
  59         $ wget ftp://ftp.denx.de/pub/tools/elftosb-${VER}.tar.gz
  60
  61 Extract the file:
  62
  63         $ tar xzf elftosb-${VER}.tar.gz
  64
  65 Compile the file. We need to manually tell the linker to use also libm:
  66
  67         $ cd elftosb-${VER}/
  68         $ make LIBS="-lstdc++ -lm" elftosb
  69
  70 Optionally, remove debugging symbols from elftosb:
  71
  72         $ strip bld/linux/elftosb
  73
  74 Finally, install the "elftosb" binary. The "install" target is missing, so just
  75 copy the binary by hand:
  76
  77         $ sudo cp bld/linux/elftosb /usr/local/bin/
  78
  79 Make sure the "elftosb" binary can be found in your $PATH, in this case this
  80 means "/usr/local/bin/" has to be in your $PATH.
  81
  82 2) Compiling U-Boot for a MXS based board
  83 -------------------------------------------
  84
  85 Compiling the U-Boot for a MXS board is straightforward and done as compiling
  86 U-Boot for any other ARM device. For cross-compiler setup, please refer to
  87 ELDK5.0 documentation. First, clean up the source code:
  88
  89         $ make mrproper
  90
  91 Next, configure U-Boot for a MXS based board
  92
  93         $ make <mxs_based_board_name>_config
  94
  95 Examples:
  96
  97 1. For building U-boot for Denx M28EVK board:
  98
  99         $ make m28evk_config
 100
 101 2. For building U-boot for Freescale MX28EVK board:
 102
 103         $ make mx28evk_config
 104
 105 3. For building U-boot for Freescale MX23EVK board:
 106
 107         $ make mx23evk_config
 108
 109 4. For building U-boot for Olimex MX23 Olinuxino board:
 110
 111         $ make mx23_olinuxino_config
 112
 113 Lastly, compile U-Boot and prepare a "BootStream". The "BootStream" is a special
 114 type of file, which MXS CPUs can boot. This is handled by the following
 115 command:
 116
 117         $ make u-boot.sb
 118
 119 HINT: To speed-up the build process, you can add -j<N>, where N is number of
 120       compiler instances that'll run in parallel.
 121
 122 The code produces "u-boot.sb" file. This file needs to be augmented with a
 123 proper header to allow successful boot from SD or NAND. Adding the header is
 124 discussed in the following chapters.
 125
 126 NOTE: The process that produces u-boot.sb uses the mkimage to generate the
 127       BootStream. The BootStream is encrypted with zero key. In case you need
 128       some special features of the BootStream and plan on using the "elftosb"
 129       tool instead, the invocation to produce a compatible BootStream with the
 130       one produced by mkimage is outlined below. For further details, refer to
 131       the documentation bundled with the "elftosb" package.
 132
 133         $ elftosb -zf imx23 -c arch/arm/cpu/arm926ejs/mxs/u-boot-imx23.bd \
 134                 -o u-boot.sb
 135         $ elftosb -zf imx28 -c arch/arm/cpu/arm926ejs/mxs/u-boot-imx28.bd \
 136                 -o u-boot.sb
 137
 138 3) Installation of U-Boot for a MXS based board to SD card
 139 ----------------------------------------------------------
 140
 141 To boot a MXS based board from SD, set the boot mode DIP switches according to
 142 to MX28 manual, section 12.2.1 (Table 12-2) or MX23 manual, section 35.1.2
 143 (Table 35-3).
 144
 145 The SD card used to boot U-Boot must contain a DOS partition table, which in
 146 turn carries a partition of special type and which contains a special header.
 147 The rest of partitions in the DOS partition table can be used by the user.
 148
 149 To prepare such partition, use your favourite partitioning tool. The partition
 150 must have the following parameters:
 151
 152         * Start sector .......... sector 2048
 153         * Partition size ........ at least 1024 kb
 154         * Partition type ........ 0x53 (sometimes "OnTrack DM6 Aux3")
 155
 156 For example in Linux fdisk, the sequence for a clear card follows. Be sure to
 157 run fdisk with the option "-u=sectors" to set units to sectors:
 158
 159         * o ..................... create a clear partition table
 160         * n ..................... create new partition
 161                 * p ............. primary partition
 162                 * 1 ............. first partition
 163                 * 2048 .......... first sector is 2048
 164                 * +1M ........... make the partition 1Mb big
 165         * t 1 ................... change first partition ID
 166                 * 53 ............ change the ID to 0x53 (OnTrack DM6 Aux3)
 167         * <create other partitions>
 168         * w ..................... write partition table to disk
 169
 170 The partition layout is ready, next the special partition must be filled with
 171 proper contents. The contents is generated by running the following command
 172 (see chapter 2)):
 173
 174         $ ./tools/mxsboot sd u-boot.sb u-boot.sd
 175
 176 The resulting file, "u-boot.sd", shall then be written to the partition. In this
 177 case, we assume the first partition of the SD card is /dev/mmcblk0p1:
 178
 179         $ dd if=u-boot.sd of=/dev/mmcblk0p1
 180
 181 Last step is to insert the card into the MXS based board and boot.
 182
 183 NOTE: If the user needs to adjust the start sector, the "mxsboot" tool contains
 184       a "-p" switch for that purpose. The "-p" switch takes the sector number as
 185       an argument.
 186
 187 4) Installation of U-Boot into NAND flash on a MX28 based board
 188 ---------------------------------------------------------------
 189
 190 To boot a MX28 based board from NAND, set the boot mode DIP switches according
 191 to MX28 manual section 12.2.1 (Table 12-2), PORT=GPMI, NAND 1.8 V.
 192
 193 There are two possibilities when preparing an image writable to NAND flash.
 194
 195         I) The NAND wasn't written at all yet or the BCB is broken
 196         ----------------------------------------------------------
 197            In this case, both BCB (FCB and DBBT) and firmware needs to be
 198            written to NAND. To generate NAND image containing all these,
 199            there is a tool called "mxsboot" in the "tools/" directory. The tool
 200            is invoked on "u-boot.sb" file from chapter 2):
 201
 202                  $ ./tools/mxsboot nand u-boot.sb u-boot.nand
 203
 204            NOTE: The above invokation works for NAND flash with geometry of
 205                  2048b per page, 64b OOB data, 128kb erase size. If your chip
 206                  has a different geometry, please use:
 207
 208                  -w <size>      change page size (default 2048 b)
 209                  -o <size>      change oob size (default 64 b)
 210                  -e <size>      change erase size (default 131072 b)
 211
 212                  The geometry information can be obtained from running U-Boot
 213                  on the MX28 board by issuing the "nand info" command.
 214
 215            The resulting file, "u-boot.nand" can be written directly to NAND
 216            from the U-Boot prompt. To simplify the process, the U-Boot default
 217            environment contains script "update_nand_full" to update the system.
 218
 219            This script expects a working TFTP server containing the file
 220            "u-boot.nand" in it's root directory. This can be changed by
 221            adjusting the "update_nand_full_filename" varible.
 222
 223            To update the system, run the following in U-Boot prompt:
 224
 225                  => run update_nand_full
 226
 227            In case you would only need to update the bootloader in future,
 228            see II) below.
 229
 230         II) The NAND was already written with a good BCB
 231         ------------------------------------------------
 232            This part applies after the part I) above was done at least once.
 233
 234            If part I) above was done correctly already, there is no need to
 235            write the FCB and DBBT parts of NAND again. It's possible to upgrade
 236            only the bootloader image.
 237
 238            To simplify the process of firmware update, the U-Boot default
 239            environment contains script "update_nand_firmware" to update only
 240            the firmware, without rewriting FCB and DBBT.
 241
 242            This script expects a working TFTP server containing the file
 243            "u-boot.sb" in it's root directory. This can be changed by
 244            adjusting the "update_nand_firmware_filename" varible.
 245
 246            To update the system, run the following in U-Boot prompt:
 247
 248                  => run update_nand_firmware
 249
 250         III) Special settings for the update scripts
 251         --------------------------------------------
 252            There is a slight possibility of the user wanting to adjust the
 253            STRIDE and COUNT options of the NAND boot. For description of these,
 254            see MX28 manual section 12.12.1.2 and 12.12.1.3.
 255
 256            The update scripts take this possibility into account. In case the
 257            user changes STRIDE by blowing fuses, the user also has to change
 258            "update_nand_stride" variable. In case the user changes COUNT by
 259            blowing fuses, the user also has to change "update_nand_count"
 260            variable for the update scripts to work correctly.
 261
 262            In case the user needs to boot a firmware image bigger than 1Mb, the
 263            user has to adjust the "update_nand_firmware_maxsz" variable for the
 264            update scripts to work properly.