1Booting U-boot on a MXS processor 2================================= 3 4This document describes the MXS U-Boot port. This document mostly covers topics 5related to making the module/board bootable. 6 7Terminology 8----------- 9 10The term "MXS" refers to a family of Freescale SoCs that is composed by MX23 11and MX28. 12 13The dollar symbol ($) introduces a snipped of shell code. This shall be typed 14into the unix command prompt in U-Boot source code root directory. 15 16The (=>) introduces a snipped of code that should by typed into U-Boot command 17prompt 18 19Contents 20-------- 21 221) Prerequisites 232) Compiling U-Boot for a MXS based board 243) Installation of U-Boot for a MXS based board to SD card 254) Installation of U-Boot into NAND flash on a MX28 based board 26 271) Prerequisites 28---------------- 29 30To make a MXS based board bootable, some tools are necessary. The only 31mandatory tool is the "mxsboot" tool found in U-Boot source tree. The 32tool is built automatically when compiling U-Boot for i.MX23 or i.MX28. 33 34The production of BootStream image is handled via "mkimage", which is 35also part of the U-Boot source tree. The "mkimage" requires OpenSSL 36development libraries to be installed. In case of Debian and derivates, 37this is installed by running: 38 39 $ sudo apt-get install libssl-dev 40 41NOTE: 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 50Firstly, obtain the elftosb archive from the following location: 51 52 ftp://ftp.denx.de/pub/tools/elftosb-10.12.01.tar.gz 53 54We use a $VER variable here to denote the current version. At the time of 55writing of this document, that is "10.12.01". To obtain the file from command 56line, use: 57 58 $ VER="10.12.01" 59 $ wget ftp://ftp.denx.de/pub/tools/elftosb-${VER}.tar.gz 60 61Extract the file: 62 63 $ tar xzf elftosb-${VER}.tar.gz 64 65Compile 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 70Optionally, remove debugging symbols from elftosb: 71 72 $ strip bld/linux/elftosb 73 74Finally, install the "elftosb" binary. The "install" target is missing, so just 75copy the binary by hand: 76 77 $ sudo cp bld/linux/elftosb /usr/local/bin/ 78 79Make sure the "elftosb" binary can be found in your $PATH, in this case this 80means "/usr/local/bin/" has to be in your $PATH. 81 822) Compiling U-Boot for a MXS based board 83------------------------------------------- 84 85Compiling the U-Boot for a MXS board is straightforward and done as compiling 86U-Boot for any other ARM device. For cross-compiler setup, please refer to 87ELDK5.0 documentation. First, clean up the source code: 88 89 $ make mrproper 90 91Next, configure U-Boot for a MXS based board 92 93 $ make <mxs_based_board_name>_config 94 95Examples: 96 971. For building U-boot for Denx M28EVK board: 98 99 $ make m28evk_config 100 1012. For building U-boot for Freescale MX28EVK board: 102 103 $ make mx28evk_config 104 1053. For building U-boot for Freescale MX23EVK board: 106 107 $ make mx23evk_config 108 1094. For building U-boot for Olimex MX23 Olinuxino board: 110 111 $ make mx23_olinuxino_config 112 113Lastly, compile U-Boot and prepare a "BootStream". The "BootStream" is a special 114type of file, which MXS CPUs can boot. This is handled by the following 115command: 116 117 $ make u-boot.sb 118 119HINT: 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 122The code produces "u-boot.sb" file. This file needs to be augmented with a 123proper header to allow successful boot from SD or NAND. Adding the header is 124discussed in the following chapters. 125 126NOTE: 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 1383) Installation of U-Boot for a MXS based board to SD card 139---------------------------------------------------------- 140 141To boot a MXS based board from SD, set the boot mode DIP switches according to 142to MX28 manual, section 12.2.1 (Table 12-2) or MX23 manual, section 35.1.2 143(Table 35-3). 144 145The SD card used to boot U-Boot must contain a DOS partition table, which in 146turn carries a partition of special type and which contains a special header. 147The rest of partitions in the DOS partition table can be used by the user. 148 149To prepare such partition, use your favourite partitioning tool. The partition 150must 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 156For example in Linux fdisk, the sequence for a clear card follows. Be sure to 157run 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 170The partition layout is ready, next the special partition must be filled with 171proper 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 176The resulting file, "u-boot.sd", shall then be written to the partition. In this 177case, we assume the first partition of the SD card is /dev/mmcblk0p1: 178 179 $ dd if=u-boot.sd of=/dev/mmcblk0p1 180 181Last step is to insert the card into the MXS based board and boot. 182 183NOTE: 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 1874) Installation of U-Boot into NAND flash on a MX28 based board 188--------------------------------------------------------------- 189 190To boot a MX28 based board from NAND, set the boot mode DIP switches according 191to MX28 manual section 12.2.1 (Table 12-2), PORT=GPMI, NAND 1.8 V. 192 193There 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. 265