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