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 Aries 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. 291