]> git.kernelconcepts.de Git - karo-tx-uboot.git/blob - doc/README.mxs
ARM: vexpress: convert to common timer code
[karo-tx-uboot.git] / 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.