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