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