blob: ed2e5688562ac1af55a7c6213f5f3eb825e055b8 [file] [log] [blame]
Fabio Estevam54965b62013-05-03 15:08:00 -03001Booting U-boot on a MXS processor
2=================================
Fabio Estevam419ea2d2012-03-24 12:42:21 +00003
Fabio Estevam54965b62013-05-03 15:08:00 -03004This document describes the MXS U-Boot port. This document mostly covers topics
5related to making the module/board bootable.
Fabio Estevam419ea2d2012-03-24 12:42:21 +00006
7Terminology
8-----------
9
Fabio Estevam54965b62013-05-03 15:08:00 -030010The term "MXS" refers to a family of Freescale SoCs that is composed by MX23
11and MX28.
12
Fabio Estevam419ea2d2012-03-24 12:42:21 +000013The 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
Fabio Estevam54965b62013-05-03 15:08:00 -0300232) 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
Fabio Estevama81c90f2014-06-10 00:03:59 -0300265) Installation of U-boot into SPI NOR flash on a MX28 based board
Fabio Estevam419ea2d2012-03-24 12:42:21 +000027
281) Prerequisites
29----------------
30
Marek Vasut6654f332013-09-24 17:39:17 +020031To make a MXS based board bootable, some tools are necessary. The only
32mandatory tool is the "mxsboot" tool found in U-Boot source tree. The
33tool is built automatically when compiling U-Boot for i.MX23 or i.MX28.
34
35The production of BootStream image is handled via "mkimage", which is
36also part of the U-Boot source tree. The "mkimage" requires OpenSSL
37development libraries to be installed. In case of Debian and derivates,
38this is installed by running:
39
40 $ sudo apt-get install libssl-dev
41
42NOTE: 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:
Fabio Estevam419ea2d2012-03-24 12:42:21 +000050
51Firstly, obtain the elftosb archive from the following location:
52
Anatolij Gustschin9de1c222012-06-27 04:14:29 +000053 ftp://ftp.denx.de/pub/tools/elftosb-10.12.01.tar.gz
Fabio Estevam419ea2d2012-03-24 12:42:21 +000054
55We use a $VER variable here to denote the current version. At the time of
56writing of this document, that is "10.12.01". To obtain the file from command
57line, use:
58
59 $ VER="10.12.01"
Anatolij Gustschin9de1c222012-06-27 04:14:29 +000060 $ wget ftp://ftp.denx.de/pub/tools/elftosb-${VER}.tar.gz
Fabio Estevam419ea2d2012-03-24 12:42:21 +000061
62Extract the file:
63
64 $ tar xzf elftosb-${VER}.tar.gz
65
66Compile 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
71Optionally, remove debugging symbols from elftosb:
72
73 $ strip bld/linux/elftosb
74
75Finally, install the "elftosb" binary. The "install" target is missing, so just
76copy the binary by hand:
77
78 $ sudo cp bld/linux/elftosb /usr/local/bin/
79
80Make sure the "elftosb" binary can be found in your $PATH, in this case this
81means "/usr/local/bin/" has to be in your $PATH.
82
Fabio Estevam54965b62013-05-03 15:08:00 -0300832) Compiling U-Boot for a MXS based board
Fabio Estevam419ea2d2012-03-24 12:42:21 +000084-------------------------------------------
85
Fabio Estevam54965b62013-05-03 15:08:00 -030086Compiling the U-Boot for a MXS board is straightforward and done as compiling
Fabio Estevam84286c22013-05-03 15:07:57 -030087U-Boot for any other ARM device. For cross-compiler setup, please refer to
88ELDK5.0 documentation. First, clean up the source code:
Fabio Estevam419ea2d2012-03-24 12:42:21 +000089
90 $ make mrproper
91
Fabio Estevam54965b62013-05-03 15:08:00 -030092Next, configure U-Boot for a MXS based board
Fabio Estevam419ea2d2012-03-24 12:42:21 +000093
Fabio Estevam54965b62013-05-03 15:08:00 -030094 $ make <mxs_based_board_name>_config
Fabio Estevam419ea2d2012-03-24 12:42:21 +000095
96Examples:
97
981. For building U-boot for Denx M28EVK board:
99
100 $ make m28evk_config
101
1022. For building U-boot for Freescale MX28EVK board:
103
104 $ make mx28evk_config
105
Fabio Estevam54965b62013-05-03 15:08:00 -03001063. For building U-boot for Freescale MX23EVK board:
107
108 $ make mx23evk_config
109
1104. For building U-boot for Olimex MX23 Olinuxino board:
111
112 $ make mx23_olinuxino_config
113
Fabio Estevam419ea2d2012-03-24 12:42:21 +0000114Lastly, compile U-Boot and prepare a "BootStream". The "BootStream" is a special
Fabio Estevam54965b62013-05-03 15:08:00 -0300115type of file, which MXS CPUs can boot. This is handled by the following
Fabio Estevam419ea2d2012-03-24 12:42:21 +0000116command:
117
118 $ make u-boot.sb
119
120HINT: 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
123The code produces "u-boot.sb" file. This file needs to be augmented with a
124proper header to allow successful boot from SD or NAND. Adding the header is
125discussed in the following chapters.
126
Marek Vasut6654f332013-09-24 17:39:17 +0200127NOTE: 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
Fabio Estevam54965b62013-05-03 15:08:00 -03001393) Installation of U-Boot for a MXS based board to SD card
140----------------------------------------------------------
Fabio Estevam419ea2d2012-03-24 12:42:21 +0000141
Fabio Estevam54965b62013-05-03 15:08:00 -0300142To boot a MXS based board from SD, set the boot mode DIP switches according to
143to MX28 manual, section 12.2.1 (Table 12-2) or MX23 manual, section 35.1.2
144(Table 35-3).
Fabio Estevam419ea2d2012-03-24 12:42:21 +0000145
Fabio Estevam7333eca2013-05-03 15:07:59 -0300146The SD card used to boot U-Boot must contain a DOS partition table, which in
147turn carries a partition of special type and which contains a special header.
148The rest of partitions in the DOS partition table can be used by the user.
Fabio Estevam419ea2d2012-03-24 12:42:21 +0000149
150To prepare such partition, use your favourite partitioning tool. The partition
151must 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
157For example in Linux fdisk, the sequence for a clear card follows. Be sure to
158run 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
171The partition layout is ready, next the special partition must be filled with
172proper 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
177The resulting file, "u-boot.sd", shall then be written to the partition. In this
178case, we assume the first partition of the SD card is /dev/mmcblk0p1:
179
180 $ dd if=u-boot.sd of=/dev/mmcblk0p1
181
Fabio Estevam54965b62013-05-03 15:08:00 -0300182Last step is to insert the card into the MXS based board and boot.
Fabio Estevam419ea2d2012-03-24 12:42:21 +0000183
184NOTE: 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
Fabio Estevam54965b62013-05-03 15:08:00 -03001884) Installation of U-Boot into NAND flash on a MX28 based board
189---------------------------------------------------------------
Fabio Estevam419ea2d2012-03-24 12:42:21 +0000190
Fabio Estevam84286c22013-05-03 15:07:57 -0300191To boot a MX28 based board from NAND, set the boot mode DIP switches according
Fabio Estevam54965b62013-05-03 15:08:00 -0300192to MX28 manual section 12.2.1 (Table 12-2), PORT=GPMI, NAND 1.8 V.
Fabio Estevam419ea2d2012-03-24 12:42:21 +0000193
194There 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" varible.
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" varible.
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,
Fabio Estevam54965b62013-05-03 15:08:00 -0300255 see MX28 manual section 12.12.1.2 and 12.12.1.3.
Fabio Estevam419ea2d2012-03-24 12:42:21 +0000256
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.
Fabio Estevama81c90f2014-06-10 00:03:59 -0300266
2675) Installation of U-Boot into SPI NOR flash on a MX28 based board
268------------------------------------------------------------------
269
270The u-boot.sb file can be directly written to SPI NOR from U-boot prompt.
271
272Load u-boot.sb into RAM, this can be done in several ways and one way is to use
273tftp:
274 => tftp u-boot.sb 0x42000000
275
276Probe the SPI NOR flash:
277 => sf probe
278
279(SPI NOR should be succesfully detected in this step)
280
281Erase the blocks where U-boot binary will be written to:
282 => sf erase 0x0 0x80000
283
284Write u-boot.sb to SPI NOR:
285 => sf write 0x42000000 0 0x80000
286
287Power off the board and set the boot mode DIP switches to boot from the SPI NOR
288according to MX28 manual section 12.2.1 (Table 12-2)
289
290Last step is to power up the board and U-boot should start from SPI NOR.