Eric Lee / smarc-uboot

Download as
Browse Code ยป

Commit 49f36f64066b6cd9ac23d08b2b7af63b5ed9717d

Authored by Breno Lima
Committed by Ye Li
1 parent 39eed8d144
Exists in smarc_8mm-imx_v2018.03_4.14.98_2.0.0_ga and in 5 other branches smarc-imx6_v2018.03_4.14.98_2.0.0_ga, smarc-imx7_v2018.03_4.14.98_2.0.0_ga, smarc-imx_v2018.03_4.14.78_1.0.0_ga, smarc_8m-imx_v2018.03_4.14.98_2.0.0_ga, smarc_8m_00d0-imx_v2018.03_4.14.98_2.0.0_ga

MLK-19722-8 doc: imx: Improve i.MX documentation naming 

There is no need to have README in all i.MX documents name.
Remove README from i.MX docs name and add .txt file extension.

Signed-off-by: Breno Lima <breno.lima@nxp.com>
Reviewed-by: Ye Li <ye.li@nxp.com>

Showing 16 changed files with 967 additions and 967 deletions Side-by-side Diff

doc/imx/common/README.imx25
View file @ 49f36f6
1   -U-Boot for Freescale i.MX25
2   -
3   -This file contains information for the port of U-Boot to the Freescale i.MX25
4   -SoC.
5   -
6   -1. CONVENTIONS FOR FUSE ASSIGNMENTS
7   ------------------------------------
8   -
9   -1.1 MAC Address: It is stored in the words 26 to 31 of fuse bank 0, using the
10   - natural MAC byte order (i.e. MSB first).
doc/imx/common/README.imx27
View file @ 49f36f6
1   -U-Boot for Freescale i.MX27
2   -
3   -This file contains information for the port of U-Boot to the Freescale i.MX27
4   -SoC.
5   -
6   -1. CONVENTIONS FOR FUSE ASSIGNMENTS
7   ------------------------------------
8   -
9   -1.1 MAC Address: It is stored in the words 4 to 9 of fuse bank 0, using the
10   - reversed MAC byte order (i.e. LSB first).
doc/imx/common/README.imx5
View file @ 49f36f6
1   -U-Boot for Freescale i.MX5x
2   -
3   -This file contains information for the port of U-Boot to the Freescale
4   -i.MX5x SoCs.
5   -
6   -1. CONFIGURATION OPTIONS/SETTINGS
7   ----------------------------------
8   -
9   -1.1 CONFIG_MX51_PLL_ERRATA: Workaround for i.MX51 PLL errata.
10   - This option should be enabled by all boards using the i.MX51 silicon
11   - version up until (including) 3.0 running at 800MHz.
12   - The PLL's in the i.MX51 processor can go out of lock due to a metastable
13   - condition in an analog flip-flop when used at high frequencies.
14   - This workaround implements an undocumented feature in the PLL (dither
15   - mode), which causes the effect of this failure to be much lower (in terms
16   - of frequency deviation), avoiding system failure, or at least decreasing
17   - the likelihood of system failure.
18   -
19   -1.2 CONFIG_SYS_MAIN_PWR_ON: Trigger MAIN_PWR_ON upon startup.
20   - This option should be enabled for boards having a SYS_ON_OFF_CTL signal
21   - connected to GPIO1[23] and triggering the MAIN_PWR_ON signal like in the
22   - reference designs.
23   -
24   -2. CONVENTIONS FOR FUSE ASSIGNMENTS
25   ------------------------------------
26   -
27   -2.1 MAC Address: It is stored in the words 9 to 14 of fuse bank 1, using the
28   - natural MAC byte order (i.e. MSB first).
29   -
30   - This is an example how to program an example MAC address 01:23:45:67:89:ab
31   - into the eFuses. Assure that the programming voltage is available and then
32   - execute:
33   -
34   - => fuse prog -y 1 9 01 23 45 67 89 ab
35   -
36   - After programming a MAC address, consider locking the MAC fuses. This is
37   - done by programming the MAC_ADDR_LOCK fuse, which is bit 4 of word 0 in
38   - bank 1:
39   -
40   - => fuse prog -y 1 0 10
doc/imx/common/README.imx6
View file @ 49f36f6
1   -U-Boot for Freescale i.MX6
2   -
3   -This file contains information for the port of U-Boot to the Freescale i.MX6
4   -SoC.
5   -
6   -1. CONVENTIONS FOR FUSE ASSIGNMENTS
7   ------------------------------------
8   -
9   -1.1 MAC Address: It is stored in fuse bank 4, with the 32 lsbs in word 2 and the
10   - 16 msbs in word 3[15:0].
11   - For i.MX6SX and i.MX6UL, they have two MAC addresses. The second MAC address
12   - is stored in fuse bank 4, with the 16 lsb in word 3[31:16] and the 32 msbs in
13   - word 4.
14   -
15   -Example:
16   -
17   -For reading the MAC address fuses on a MX6Q:
18   -
19   -- The MAC address is stored in two fuse addresses (the fuse addresses are
20   -described in the Fusemap Descriptions table from the mx6q Reference Manual):
21   -
22   -0x620[31:0] - MAC_ADDR[31:0]
23   -0x630[15:0] - MAC_ADDR[47:32]
24   -
25   -In order to use the fuse API, we need to pass the bank and word values, which
26   -are calculated as below:
27   -
28   -Fuse address for the lower MAC address: 0x620
29   -Base address for the fuses: 0x400
30   -
31   -(0x620 - 0x400)/0x10 = 0x22 = 34 decimal
32   -
33   -As the fuses are arranged in banks of 8 words:
34   -
35   -34 / 8 = 4 and the remainder is 2, so in this case:
36   -
37   -bank = 4
38   -word = 2
39   -
40   -And the U-Boot command would be:
41   -
42   -=> fuse read 4 2
43   -Reading bank 4:
44   -
45   -Word 0x00000002: 9f027772
46   -
47   -Doing the same for the upper MAC address:
48   -
49   -Fuse address for the upper MAC address: 0x630
50   -Base address for the fuses: 0x400
51   -
52   -(0x630 - 0x400)/0x10 = 0x23 = 35 decimal
53   -
54   -As the fuses are arranged in banks of 8 words:
55   -
56   -35 / 8 = 4 and the remainder is 3, so in this case:
57   -
58   -bank = 4
59   -word = 3
60   -
61   -And the U-Boot command would be:
62   -
63   -=> fuse read 4 3
64   -Reading bank 4:
65   -
66   -Word 0x00000003: 00000004
67   -
68   -,which matches the ethaddr value:
69   -=> echo ${ethaddr}
70   -00:04:9f:02:77:72
71   -
72   -Some other useful hints:
73   -
74   -- The 'bank' and 'word' numbers can be easily obtained from the mx6 Reference
75   -Manual. For the mx6quad case, please check the "46.5 OCOTP Memory Map/Register
76   -Definition" from the "i.MX 6Dual/6Quad Applications Processor Reference Manual,
77   -Rev. 1, 04/2013" document. For example, for the MAC fuses we have:
78   -
79   -Address:
80   -21B_C620 Value of OTP Bank4 Word2 (MAC Address)(OCOTP_MAC0)
81   -
82   -21B_C630 Value of OTP Bank4 Word3 (MAC Address)(OCOTP_MAC1)
83   -
84   -- The command '=> fuse read 4 2 2' reads the whole MAC addresses at once:
85   -
86   -=> fuse read 4 2 2
87   -Reading bank 4:
88   -
89   -Word 0x00000002: 9f027772 00000004
doc/imx/common/README.mxs
View file @ 49f36f6
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.
doc/imx/common/imx25.txt
Diff comments   View file @ 49f36f6
  1 +U-Boot for Freescale i.MX25
  2 +
  3 +This file contains information for the port of U-Boot to the Freescale i.MX25
  4 +SoC.
  5 +
  6 +1. CONVENTIONS FOR FUSE ASSIGNMENTS
  7 +-----------------------------------
  8 +
  9 +1.1 MAC Address: It is stored in the words 26 to 31 of fuse bank 0, using the
  10 + natural MAC byte order (i.e. MSB first).
doc/imx/common/imx27.txt
Diff comments   View file @ 49f36f6
  1 +U-Boot for Freescale i.MX27
  2 +
  3 +This file contains information for the port of U-Boot to the Freescale i.MX27
  4 +SoC.
  5 +
  6 +1. CONVENTIONS FOR FUSE ASSIGNMENTS
  7 +-----------------------------------
  8 +
  9 +1.1 MAC Address: It is stored in the words 4 to 9 of fuse bank 0, using the
  10 + reversed MAC byte order (i.e. LSB first).
doc/imx/common/imx5.txt
Diff comments   View file @ 49f36f6
  1 +U-Boot for Freescale i.MX5x
  2 +
  3 +This file contains information for the port of U-Boot to the Freescale
  4 +i.MX5x SoCs.
  5 +
  6 +1. CONFIGURATION OPTIONS/SETTINGS
  7 +---------------------------------
  8 +
  9 +1.1 CONFIG_MX51_PLL_ERRATA: Workaround for i.MX51 PLL errata.
  10 + This option should be enabled by all boards using the i.MX51 silicon
  11 + version up until (including) 3.0 running at 800MHz.
  12 + The PLL's in the i.MX51 processor can go out of lock due to a metastable
  13 + condition in an analog flip-flop when used at high frequencies.
  14 + This workaround implements an undocumented feature in the PLL (dither
  15 + mode), which causes the effect of this failure to be much lower (in terms
  16 + of frequency deviation), avoiding system failure, or at least decreasing
  17 + the likelihood of system failure.
  18 +
  19 +1.2 CONFIG_SYS_MAIN_PWR_ON: Trigger MAIN_PWR_ON upon startup.
  20 + This option should be enabled for boards having a SYS_ON_OFF_CTL signal
  21 + connected to GPIO1[23] and triggering the MAIN_PWR_ON signal like in the
  22 + reference designs.
  23 +
  24 +2. CONVENTIONS FOR FUSE ASSIGNMENTS
  25 +-----------------------------------
  26 +
  27 +2.1 MAC Address: It is stored in the words 9 to 14 of fuse bank 1, using the
  28 + natural MAC byte order (i.e. MSB first).
  29 +
  30 + This is an example how to program an example MAC address 01:23:45:67:89:ab
  31 + into the eFuses. Assure that the programming voltage is available and then
  32 + execute:
  33 +
  34 + => fuse prog -y 1 9 01 23 45 67 89 ab
  35 +
  36 + After programming a MAC address, consider locking the MAC fuses. This is
  37 + done by programming the MAC_ADDR_LOCK fuse, which is bit 4 of word 0 in
  38 + bank 1:
  39 +
  40 + => fuse prog -y 1 0 10
doc/imx/common/imx6.txt
Diff comments   View file @ 49f36f6
  1 +U-Boot for Freescale i.MX6
  2 +
  3 +This file contains information for the port of U-Boot to the Freescale i.MX6
  4 +SoC.
  5 +
  6 +1. CONVENTIONS FOR FUSE ASSIGNMENTS
  7 +-----------------------------------
  8 +
  9 +1.1 MAC Address: It is stored in fuse bank 4, with the 32 lsbs in word 2 and the
  10 + 16 msbs in word 3[15:0].
  11 + For i.MX6SX and i.MX6UL, they have two MAC addresses. The second MAC address
  12 + is stored in fuse bank 4, with the 16 lsb in word 3[31:16] and the 32 msbs in
  13 + word 4.
  14 +
  15 +Example:
  16 +
  17 +For reading the MAC address fuses on a MX6Q:
  18 +
  19 +- The MAC address is stored in two fuse addresses (the fuse addresses are
  20 +described in the Fusemap Descriptions table from the mx6q Reference Manual):
  21 +
  22 +0x620[31:0] - MAC_ADDR[31:0]
  23 +0x630[15:0] - MAC_ADDR[47:32]
  24 +
  25 +In order to use the fuse API, we need to pass the bank and word values, which
  26 +are calculated as below:
  27 +
  28 +Fuse address for the lower MAC address: 0x620
  29 +Base address for the fuses: 0x400
  30 +
  31 +(0x620 - 0x400)/0x10 = 0x22 = 34 decimal
  32 +
  33 +As the fuses are arranged in banks of 8 words:
  34 +
  35 +34 / 8 = 4 and the remainder is 2, so in this case:
  36 +
  37 +bank = 4
  38 +word = 2
  39 +
  40 +And the U-Boot command would be:
  41 +
  42 +=> fuse read 4 2
  43 +Reading bank 4:
  44 +
  45 +Word 0x00000002: 9f027772
  46 +
  47 +Doing the same for the upper MAC address:
  48 +
  49 +Fuse address for the upper MAC address: 0x630
  50 +Base address for the fuses: 0x400
  51 +
  52 +(0x630 - 0x400)/0x10 = 0x23 = 35 decimal
  53 +
  54 +As the fuses are arranged in banks of 8 words:
  55 +
  56 +35 / 8 = 4 and the remainder is 3, so in this case:
  57 +
  58 +bank = 4
  59 +word = 3
  60 +
  61 +And the U-Boot command would be:
  62 +
  63 +=> fuse read 4 3
  64 +Reading bank 4:
  65 +
  66 +Word 0x00000003: 00000004
  67 +
  68 +,which matches the ethaddr value:
  69 +=> echo ${ethaddr}
  70 +00:04:9f:02:77:72
  71 +
  72 +Some other useful hints:
  73 +
  74 +- The 'bank' and 'word' numbers can be easily obtained from the mx6 Reference
  75 +Manual. For the mx6quad case, please check the "46.5 OCOTP Memory Map/Register
  76 +Definition" from the "i.MX 6Dual/6Quad Applications Processor Reference Manual,
  77 +Rev. 1, 04/2013" document. For example, for the MAC fuses we have:
  78 +
  79 +Address:
  80 +21B_C620 Value of OTP Bank4 Word2 (MAC Address)(OCOTP_MAC0)
  81 +
  82 +21B_C630 Value of OTP Bank4 Word3 (MAC Address)(OCOTP_MAC1)
  83 +
  84 +- The command '=> fuse read 4 2 2' reads the whole MAC addresses at once:
  85 +
  86 +=> fuse read 4 2 2
  87 +Reading bank 4:
  88 +
  89 +Word 0x00000002: 9f027772 00000004
doc/imx/common/mxs.txt
Diff comments   View file @ 49f36f6
  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.
doc/imx/misc/README.sdp
View file @ 49f36f6
1   --------------
2   -SDP in U-Boot
3   --------------
4   -
5   -SDP stands for serial download protocol. It is the protocol used in NXP's
6   -i.MX SoCs ROM Serial Downloader and provides means to download a program
7   -image to the chip over USB and UART serial connection.
8   -
9   -The implementation in U-Boot uses the USB Downloader Gadget (g_dnl) to
10   -provide a SDP implementation over USB. This allows to download program
11   -images to the target in SPL/U-Boot using the same protocol/tooling the
12   -SoC's recovery mechanism is using.
13   -
14   -The SDP protocol over USB is a USB HID class protocol. USB HID class
15   -protocols allow to access a USB device without OS specific drivers. The
16   -U-Boot implementation has primarly been tested using the open source
17   -imx_loader utility (https://github.com/boundarydevices/imx_usb_loader).
18   -
19   -imx_usb_loader is a very nice tool by Boundary Devices that allow to
20   -install U-Boot without a JTAG debugger, using the USB boot mode as
21   -described in the manual. It is a replacement for Freescale's
22   -MFGTOOLS.
23   -
24   -The host side utilities are typically capable to interpret the i.MX
25   -specific image header (see doc/README.imximage). There are extensions
26   -for imx_loader's imx_usb utility which allow to interpret the U-Boot
27   -specific legacy image format (see mkimage(1)). Also the U-Boot side
28   -support beside the i.MX specific header the U-Boot legacy header.
29   -
30   -1. Using imx_usb_loader for first install with SPL
31   ---------------------------------------------------
32   -
33   -This implementation can be started in U-Boot using the sdp command
34   -(CONFIG_CMD_USB_SDP) or in SPL if Serial Downloader boot mode has been
35   -detected (CONFIG_SPL_USB_SDP_SUPPORT).
36   -
37   -A typical use case is downloading full U-Boot after SPL has been
38   -downloaded through the boot ROM's Serial Downloader. Using boot mode
39   -detection the SPL will run the SDP implementation automatically in
40   -this case:
41   -
42   - # imx_usb SPL
43   -
44   -Targets Serial Console:
45   -
46   - Trying to boot from USB SDP
47   - SDP: initialize...
48   - SDP: handle requests...
49   -
50   -At this point the SPL reenumerated as a new HID device and emulating
51   -the boot ROM's SDP protocol. The USB VID/PID will depend on standard
52   -U-Boot configurations CONFIG_G_DNL_(VENDOR|PRODUCT)_NUM. Make sure
53   -imx_usb is aware of the USB VID/PID for your device by adding a
54   -configuration entry in imx_usb.conf:
55   -
56   - 0x1b67:0x4fff, mx6_usb_sdp_spl.conf
57   -
58   -And the device specific configuration file mx6_usb_sdp_spl.conf:
59   -
60   - mx6_spl_sdp
61   - hid,uboot_header,1024,0x910000,0x10000000,1G,0x00900000,0x40000
62   -
63   -This allows to download the regular U-Boot with legacy image headers
64   -(u-boot.img) using a second invocation of imx_usb:
65   -
66   - # imx_usb u-boot.img
67   -
68   -Furthermore, when U-Boot is running the sdp command can be used to
69   -download and run scripts:
70   -
71   - # imx_usb script.scr
72   -
73   -imx_usb configuration files can be also used to download multiple
74   -files and of arbitrary types, e.g.
75   -
76   - mx6_usb_sdp_uboot
77   - hid,1024,0x10000000,1G,0x00907000,0x31000
78   - full.itb:load 0x12100000
79   - boot.scr:load 0x12000000,jump 0x12000000
80   -
81   -There is also a batch mode which allows imx_usb to handle multiple
82   -consecutive reenumerations by adding multiple VID/PID specifications
83   -in imx_usb.conf:
84   -
85   - 0x15a2:0x0061, mx6_usb_rom.conf, 0x1b67:0x4fff, mx6_usb_sdp_spl.conf
86   -
87   -In this mode the file to download (imx_usb job) needs to be specified
88   -in the configuration files.
89   -
90   -mx6_usb_rom.conf:
91   -
92   - mx6_qsb
93   - hid,1024,0x910000,0x10000000,1G,0x00900000,0x40000
94   - SPL:jump header2
95   -
96   -mx6_usb_sdp_spl.conf:
97   -
98   - mx6_spl_sdp
99   - hid,uboot_header,1024,0x10000000,1G,0x00907000,0x31000
100   - u-boot.img:jump header2
101   -
102   -With that SPL and U-Boot can be downloaded with a single invocation
103   -of imx_usb without arguments:
104   -
105   - # imx_usb
106   -
107   -2. Using imx_usb_loader non-SPL images
108   ----------------------------------------
109   -
110   -Booting in USB mode, the i.MX6 announces itself to the Linux Host as:
111   -
112   -Bus 001 Device 111: ID 15a2:0061 Freescale Semiconductor, Inc.
113   -
114   -imx_usb_loader is able to download a single file (u-boot.imx)
115   -to the board. For boards without SPL support, it is enough to
116   -issue the command:
117   -
118   - sudo ../imx_usb_loader/imx_usb -v u-boot.imx
doc/imx/misc/sdp.txt
Diff comments   View file @ 49f36f6
  1 +-------------
  2 +SDP in U-Boot
  3 +-------------
  4 +
  5 +SDP stands for serial download protocol. It is the protocol used in NXP's
  6 +i.MX SoCs ROM Serial Downloader and provides means to download a program
  7 +image to the chip over USB and UART serial connection.
  8 +
  9 +The implementation in U-Boot uses the USB Downloader Gadget (g_dnl) to
  10 +provide a SDP implementation over USB. This allows to download program
  11 +images to the target in SPL/U-Boot using the same protocol/tooling the
  12 +SoC's recovery mechanism is using.
  13 +
  14 +The SDP protocol over USB is a USB HID class protocol. USB HID class
  15 +protocols allow to access a USB device without OS specific drivers. The
  16 +U-Boot implementation has primarly been tested using the open source
  17 +imx_loader utility (https://github.com/boundarydevices/imx_usb_loader).
  18 +
  19 +imx_usb_loader is a very nice tool by Boundary Devices that allow to
  20 +install U-Boot without a JTAG debugger, using the USB boot mode as
  21 +described in the manual. It is a replacement for Freescale's
  22 +MFGTOOLS.
  23 +
  24 +The host side utilities are typically capable to interpret the i.MX
  25 +specific image header (see doc/README.imximage). There are extensions
  26 +for imx_loader's imx_usb utility which allow to interpret the U-Boot
  27 +specific legacy image format (see mkimage(1)). Also the U-Boot side
  28 +support beside the i.MX specific header the U-Boot legacy header.
  29 +
  30 +1. Using imx_usb_loader for first install with SPL
  31 +--------------------------------------------------
  32 +
  33 +This implementation can be started in U-Boot using the sdp command
  34 +(CONFIG_CMD_USB_SDP) or in SPL if Serial Downloader boot mode has been
  35 +detected (CONFIG_SPL_USB_SDP_SUPPORT).
  36 +
  37 +A typical use case is downloading full U-Boot after SPL has been
  38 +downloaded through the boot ROM's Serial Downloader. Using boot mode
  39 +detection the SPL will run the SDP implementation automatically in
  40 +this case:
  41 +
  42 + # imx_usb SPL
  43 +
  44 +Targets Serial Console:
  45 +
  46 + Trying to boot from USB SDP
  47 + SDP: initialize...
  48 + SDP: handle requests...
  49 +
  50 +At this point the SPL reenumerated as a new HID device and emulating
  51 +the boot ROM's SDP protocol. The USB VID/PID will depend on standard
  52 +U-Boot configurations CONFIG_G_DNL_(VENDOR|PRODUCT)_NUM. Make sure
  53 +imx_usb is aware of the USB VID/PID for your device by adding a
  54 +configuration entry in imx_usb.conf:
  55 +
  56 + 0x1b67:0x4fff, mx6_usb_sdp_spl.conf
  57 +
  58 +And the device specific configuration file mx6_usb_sdp_spl.conf:
  59 +
  60 + mx6_spl_sdp
  61 + hid,uboot_header,1024,0x910000,0x10000000,1G,0x00900000,0x40000
  62 +
  63 +This allows to download the regular U-Boot with legacy image headers
  64 +(u-boot.img) using a second invocation of imx_usb:
  65 +
  66 + # imx_usb u-boot.img
  67 +
  68 +Furthermore, when U-Boot is running the sdp command can be used to
  69 +download and run scripts:
  70 +
  71 + # imx_usb script.scr
  72 +
  73 +imx_usb configuration files can be also used to download multiple
  74 +files and of arbitrary types, e.g.
  75 +
  76 + mx6_usb_sdp_uboot
  77 + hid,1024,0x10000000,1G,0x00907000,0x31000
  78 + full.itb:load 0x12100000
  79 + boot.scr:load 0x12000000,jump 0x12000000
  80 +
  81 +There is also a batch mode which allows imx_usb to handle multiple
  82 +consecutive reenumerations by adding multiple VID/PID specifications
  83 +in imx_usb.conf:
  84 +
  85 + 0x15a2:0x0061, mx6_usb_rom.conf, 0x1b67:0x4fff, mx6_usb_sdp_spl.conf
  86 +
  87 +In this mode the file to download (imx_usb job) needs to be specified
  88 +in the configuration files.
  89 +
  90 +mx6_usb_rom.conf:
  91 +
  92 + mx6_qsb
  93 + hid,1024,0x910000,0x10000000,1G,0x00900000,0x40000
  94 + SPL:jump header2
  95 +
  96 +mx6_usb_sdp_spl.conf:
  97 +
  98 + mx6_spl_sdp
  99 + hid,uboot_header,1024,0x10000000,1G,0x00907000,0x31000
  100 + u-boot.img:jump header2
  101 +
  102 +With that SPL and U-Boot can be downloaded with a single invocation
  103 +of imx_usb without arguments:
  104 +
  105 + # imx_usb
  106 +
  107 +2. Using imx_usb_loader non-SPL images
  108 +---------------------------------------
  109 +
  110 +Booting in USB mode, the i.MX6 announces itself to the Linux Host as:
  111 +
  112 +Bus 001 Device 111: ID 15a2:0061 Freescale Semiconductor, Inc.
  113 +
  114 +imx_usb_loader is able to download a single file (u-boot.imx)
  115 +to the board. For boards without SPL support, it is enough to
  116 +issue the command:
  117 +
  118 + sudo ../imx_usb_loader/imx_usb -v u-boot.imx
doc/imx/mkimage/README.imximage
View file @ 49f36f6
1   ----------------------------------------------
2   -Imximage Boot Image generation using mkimage
3   ----------------------------------------------
4   -
5   -This document describes how to set up a U-Boot image that can be booted
6   -by Freescale MX25, MX35, MX51, MX53 and MX6 processors via internal boot
7   -mode.
8   -
9   -These processors can boot directly from NAND, SPI flash and SD card flash
10   -using its internal boot ROM support. MX6 processors additionally support
11   -boot from NOR flash and SATA disks. All processors can boot from an internal
12   -UART, if booting from device media fails.
13   -Booting from NOR flash does not require to use this image type.
14   -
15   -For more details refer Chapter 2 - System Boot and section 2.14
16   -(flash header description) of the processor's manual.
17   -
18   -Command syntax:
19   ---------------
20   -./tools/mkimage -l <mx u-boot_file>
21   - to list the imx image file details
22   -
23   -./tools/mkimage -T imximage \
24   - -n <board specific configuration file> \
25   - -e <execution address> -d <u-boot binary> <output image file>
26   -
27   -For example, for the mx51evk board:
28   -./tools/mkimage -n ./board/freescale/mx51evk/imximage.cfg \
29   - -T imximage -e 0x97800000 \
30   - -d u-boot.bin u-boot.imx
31   -
32   -You can generate directly the image when you compile u-boot with:
33   -
34   -$ make u-boot.imx
35   -
36   -The output image can be flashed on the board SPI flash or on a SD card.
37   -In both cases, you have to copy the image at the offset required for the
38   -chosen media devices (0x400 for both SPI flash or SD card).
39   -
40   -Please check Freescale documentation for further details.
41   -
42   -Board specific configuration file specifications:
43   --------------------------------------------------
44   -1. This file must present in the $(BOARDDIR) and the name should be
45   - imximage.cfg (since this is used in Makefile).
46   -2. This file can have empty lines and lines starting with "#" as first
47   - character to put comments.
48   -3. This file can have configuration command lines as mentioned below,
49   - any other information in this file is treated as invalid.
50   -
51   -Configuration command line syntax:
52   ----------------------------------
53   -1. Each command line is must have two strings, first one command or address
54   - and second one data string
55   -2. Following are the valid command strings and associated data strings:-
56   - Command string data string
57   - -------------- -----------
58   - IMXIMAGE_VERSION 1/2
59   - 1 is for mx25/mx35/mx51 compatible,
60   - 2 is for mx53/mx6 compatible,
61   - others is invalid and error is generated.
62   - This command need appear the fist before
63   - other valid commands in configuration file.
64   -
65   - BOOT_OFFSET value
66   -
67   - This command is parallel to BOOT_FROM and
68   - is preferred over BOOT_FROM.
69   -
70   - value: Offset of the image header, this
71   - value shall be set to one of the
72   - values found in the file:
73   - arch/arm/include/asm/\
74   - mach-imx/imximage.cfg
75   - Example:
76   - BOOT_OFFSET FLASH_OFFSET_STANDARD
77   -
78   - BOOT_FROM nand/spi/sd/onenand/nor/sata
79   -
80   - This command is parallel to BOOT_OFFSET and
81   - is to be deprecated in favor of BOOT_OFFSET.
82   -
83   - Example:
84   - BOOT_FROM spi
85   -
86   - CSF value
87   -
88   - Total size of CSF (Command Sequence File)
89   - used for Secure Boot/ High Assurance Boot
90   - (HAB).
91   -
92   - Using this command will populate the IVT
93   - (Initial Vector Table) CSF pointer and adjust
94   - the length fields only. The CSF itself needs
95   - to be generated with Freescale tools and
96   - 'manually' appended to the u-boot.imx file.
97   -
98   - The CSF is then simply concatenated
99   - to the u-boot image, making a signed bootloader,
100   - that the processor can verify
101   - if the fuses for the keys are burned.
102   -
103   - Further infos how to configure the SOC to verify
104   - the bootloader can be found in the "High
105   - Assurance Boot Version Application Programming
106   - Interface Reference Manual" as part of the
107   - Freescale Code Signing Tool, available on the
108   - manufacturer's website.
109   -
110   - Example:
111   - CSF 0x2000
112   -
113   - DATA type address value
114   -
115   - type: word=4, halfword=2, byte=1
116   - address: physycal register address
117   - value: value to be set in register
118   - All values are in in hexadecimal.
119   - Example (write to IOMUXC):
120   - DATA 4 0x73FA88a0 0x200
121   -
122   -The processor support up to 60 register programming commands for IMXIMAGE_VERSION 1
123   -and 220 register programming commands for IMXIMAGE_VERSION 2.
124   -An error is generated if more commands are found in the configuration file.
125   -
126   -3. All commands are optional to program.
127   -
128   -Setup a SD Card for booting
129   ---------------------------------
130   -
131   -The following example prepare a SD card with u-boot and a FAT partition
132   -to be used to stored the kernel to be booted.
133   -I will set the SD in the most compatible mode, setting it with
134   -255 heads and 63 sectors, as suggested from several documentation and
135   -howto on line (I took as reference the preparation of a SD Card for the
136   -Beagleboard, running u-boot as bootloader).
137   -
138   -You should start clearing the partitions table on the SD card. Because
139   -the u-boot image must be stored at the offset 0x400, it must be assured
140   -that there is no partition at that address. A new SD card is already
141   -formatted with FAT filesystem and the partition starts from the first
142   -cylinder, so we need to change it.
143   -
144   -You can do all steps with fdisk. If the device for the SD card is
145   -/dev/mmcblk0, the following commands make the job:
146   -
147   -1. Start the fdisk utility (as superuser)
148   - fdisk /dev/mmcblk0
149   -
150   -2. Clear the actual partition
151   -
152   -Command (m for help): o
153   -
154   -3. Print card info:
155   -
156   -Command (m for help): p
157   -Disk /dev/mmcblk0: 1981 MB, 1981284352 bytes
158   -
159   -In my case, I have a 2 GB card. I need the size to set later the correct value
160   -for the cylinders.
161   -
162   -4. Go to expert mode:
163   -
164   -Command (m for help): x
165   -
166   -5. Set card geometry
167   -
168   -Expert command (m for help): h
169   -Number of heads (1-256, default 4): 255
170   -
171   -Expert command (m for help): s
172   -Number of sectors (1-63, default 16): 63
173   -Warning: setting sector offset for DOS compatiblity
174   -
175   -We have set 255 heads, 63 sector. We have to set the cylinder.
176   -The value to be set can be calculated with:
177   -
178   - cilynder = <total size> / <heads> / <sectors> / <blocksize>
179   -
180   -in this example,
181   - 1981284352 / 255 / 63 / 512 = 239.x = 239
182   -
183   -
184   -Expert command (m for help): c
185   -Number of cylinders (1-1048576, default 60032): 239
186   -
187   -6. Leave the expert mode
188   -Expert command (m for help): r
189   -
190   -7. Set up a partition
191   -
192   -Now set a partition table to store the kernel or whatever you want. Of course,
193   -you can set additional partitions to store rootfs, data, etc.
194   -In my example I want to set a single partition. I must take care
195   -to not overwrite the space where I will put u-boot.
196   -
197   -Command (m for help): n
198   -Command action
199   - e extended
200   - p primary partition (1-4)
201   -p
202   -Partition number (1-4): 1
203   -First cylinder (1-239, default 1): 3
204   -Last cylinder, +cylinders or +size{K,M,G} (3-239, default 239): +100M
205   -
206   -Command (m for help): p
207   -
208   -Disk /dev/mmcblk0: 1967 MB, 1967128576 bytes
209   -255 heads, 63 sectors/track, 239 cylinders
210   -Units = cylinders of 16065 * 512 = 8225280 bytes
211   -Disk identifier: 0xb712a870
212   -
213   - Device Boot Start End Blocks Id System
214   -/dev/mmcblk0p1 3 16 112455 83 Linux
215   -
216   -I have set 100MB, leaving the first 2 sectors free. I will copy u-boot
217   -there.
218   -
219   -8. Write the partition table and exit.
220   -
221   -Command (m for help): w
222   -The partition table has been altered!
223   -
224   -Calling ioctl() to re-read partition table.
225   -
226   -9. Copy u-boot.imx on the SD card
227   -
228   -I use dd:
229   -
230   -dd if=u-boot.imx of=/dev/mmcblk0 bs=512 seek=2
231   -
232   -This command copies the u-boot image at the address 0x400, as required
233   -by the processor.
234   -
235   -Now remove your card from the PC and go to the target. If evrything went right,
236   -the u-boot prompt should come after power on.
237   -
238   -------------------------------------------------
239   -Author: Stefano babic <sbabic@denx.de>
doc/imx/mkimage/README.mxsimage
View file @ 49f36f6
1   -Freescale i.MX233/i.MX28 SB image generator via mkimage
2   -=======================================================
3   -
4   -This tool allows user to produce SB BootStream encrypted with a zero key.
5   -Such a BootStream is then bootable on i.MX23/i.MX28.
6   -
7   -Usage -- producing image:
8   -=========================
9   -The mxsimage tool is targeted to be a simple replacement for the elftosb2 .
10   -To generate an image, write an image configuration file and run:
11   -
12   - mkimage -A arm -O u-boot -T mxsimage -n <path to configuration file> \
13   - <output bootstream file>
14   -
15   -The output bootstream file is usually using the .sb file extension. Note
16   -that the example configuration files for producing bootable BootStream with
17   -the U-Boot bootloader can be found under arch/arm/boot/cpu/arm926ejs/mxs/
18   -directory. See the following files:
19   -
20   - mxsimage.mx23.cfg -- This is an example configuration for i.MX23
21   - mxsimage.mx28.cfg -- This is an example configuration for i.MX28
22   -
23   -Each configuration file uses very simple instruction semantics and a few
24   -additional rules have to be followed so that a useful image can be produced.
25   -These semantics and rules will be outlined now.
26   -
27   -- Each line of the configuration file contains exactly one instruction.
28   -- Every numeric value must be encoded in hexadecimal and in format 0xabcdef12 .
29   -- The configuration file is a concatenation of blocks called "sections" and
30   - optionally "DCD blocks" (see below), and optional flags lines.
31   - - Each "section" is started by the "SECTION" instruction.
32   - - The "SECTION" instruction has the following semantics:
33   -
34   - SECTION u32_section_number [BOOTABLE]
35   - - u32_section_number :: User-selected ID of the section
36   - - BOOTABLE :: Sets the section as bootable
37   -
38   - - A bootable section is one from which the BootROM starts executing
39   - subsequent instructions or code. Exactly one section must be selected
40   - as bootable, usually the one containing the instructions and data to
41   - load the bootloader.
42   -
43   - - A "SECTION" must be immediatelly followed by a "TAG" instruction.
44   - - The "TAG" instruction has the following semantics:
45   -
46   - TAG [LAST]
47   - - LAST :: Flag denoting the last section in the file
48   -
49   - - After a "TAG" unstruction, any of the following instructions may follow
50   - in any order and any quantity:
51   -
52   - NOOP
53   - - This instruction does nothing
54   -
55   - LOAD u32_address string_filename
56   - - Instructs the BootROM to load file pointed by "string_filename" onto
57   - address "u32_address".
58   -
59   - LOAD IVT u32_address u32_IVT_entry_point
60   - - Crafts and loads IVT onto address "u32_address" with the entry point
61   - of u32_IVT_entry_point.
62   - - i.MX28-specific instruction!
63   -
64   - LOAD DCD u32_address u32_DCD_block_ID
65   - - Loads the DCD block with ID "u32_DCD_block_ID" onto address
66   - "u32_address" and executes the contents of this DCD block
67   - - i.MX28-specific instruction!
68   -
69   - FILL u32_address u32_pattern u32_length
70   - - Starts to write memory from addres "u32_address" with a pattern
71   - specified by "u32_pattern". Writes exactly "u32_length" bytes of the
72   - pattern.
73   -
74   - JUMP [HAB] u32_address [u32_r0_arg]
75   - - Jumps onto memory address specified by "u32_address" by setting this
76   - address in PT. The BootROM will pass the "u32_r0_arg" value in ARM
77   - register "r0" to the executed code if this option is specified.
78   - Otherwise, ARM register "r0" will default to value 0x00000000. The
79   - optional "HAB" flag is i.MX28-specific flag turning on the HAB boot.
80   -
81   - CALL [HAB] u32_address [u32_r0_arg]
82   - - See JUMP instruction above, as the operation is exactly the same with
83   - one difference. The CALL instruction does allow returning into the
84   - BootROM from the executed code. U-Boot makes use of this in it's SPL
85   - code.
86   -
87   - MODE string_mode
88   - - Restart the CPU and start booting from device specified by the
89   - "string_mode" argument. The "string_mode" differs for each CPU
90   - and can be:
91   - i.MX23, string_mode = USB/I2C/SPI1_FLASH/SPI2_FLASH/NAND_BCH
92   - JTAG/SPI3_EEPROM/SD_SSP0/SD_SSP1
93   - i.MX28, string_mode = USB/I2C/SPI2_FLASH/SPI3_FLASH/NAND_BCH
94   - JTAG/SPI2_EEPROM/SD_SSP0/SD_SSP1
95   -
96   - - An optional "DCD" blocks can be added at the begining of the configuration
97   - file. Note that the DCD is only supported on i.MX28.
98   - - The DCD blocks must be inserted before the first "section" in the
99   - configuration file.
100   - - The DCD block has the following semantics:
101   -
102   - DCD u32_DCD_block_ID
103   - - u32_DCD_block_ID :: The ID number of the DCD block, must match
104   - the ID number used by "LOAD DCD" instruction.
105   -
106   - - The DCD block must be followed by one of the following instructions. All
107   - of the instructions operate either on 1, 2 or 4 bytes. This is selected by
108   - the 'n' suffix of the instruction:
109   -
110   - WRITE.n u32_address u32_value
111   - - Write the "u32_value" to the "u32_address" address.
112   -
113   - ORR.n u32_address u32_value
114   - - Read the "u32_address", perform a bitwise-OR with the "u32_value" and
115   - write the result back to "u32_address".
116   -
117   - ANDC.n u32_address u32_value
118   - - Read the "u32_address", perform a bitwise-AND with the complement of
119   - "u32_value" and write the result back to "u32_address".
120   -
121   - EQZ.n u32_address u32_count
122   - - Read the "u32_address" at most "u32_count" times and test if the value
123   - read is zero. If it is, break the loop earlier.
124   -
125   - NEZ.n u32_address u32_count
126   - - Read the "u32_address" at most "u32_count" times and test if the value
127   - read is non-zero. If it is, break the loop earlier.
128   -
129   - EQ.n u32_address u32_mask
130   - - Read the "u32_address" in a loop and test if the result masked with
131   - "u32_mask" equals the "u32_mask". If the values are equal, break the
132   - reading loop.
133   -
134   - NEQ.n u32_address u32_mask
135   - - Read the "u32_address" in a loop and test if the result masked with
136   - "u32_mask" does not equal the "u32_mask". If the values are not equal,
137   - break the reading loop.
138   -
139   - NOOP
140   - - This instruction does nothing.
141   -
142   - - An optional flags lines can be one of the following:
143   -
144   - DISPLAYPROGRESS
145   - - Enable boot progress output form the BootROM.
146   -
147   -- If the boot progress output from the BootROM is enabled, the BootROM will
148   - produce a letter on the Debug UART for each instruction it started processing.
149   - Here is a mapping between the above instructions and the BootROM output:
150   -
151   - H -- SB Image header loaded
152   - T -- TAG instruction
153   - N -- NOOP instruction
154   - L -- LOAD instruction
155   - F -- FILL instruction
156   - J -- JUMP instruction
157   - C -- CALL instruction
158   - M -- MODE instruction
159   -
160   -Usage -- verifying image:
161   -=========================
162   -
163   -The mxsimage can also verify and dump contents of an image. Use the following
164   -syntax to verify and dump contents of an image:
165   -
166   - mkimage -l <input bootstream file>
167   -
168   -This will output all the information from the SB image header and all the
169   -instructions contained in the SB image. It will also check if the various
170   -checksums in the SB image are correct.
doc/imx/mkimage/imximage.txt
Diff comments   View file @ 49f36f6
  1 +---------------------------------------------
  2 +Imximage Boot Image generation using mkimage
  3 +---------------------------------------------
  4 +
  5 +This document describes how to set up a U-Boot image that can be booted
  6 +by Freescale MX25, MX35, MX51, MX53 and MX6 processors via internal boot
  7 +mode.
  8 +
  9 +These processors can boot directly from NAND, SPI flash and SD card flash
  10 +using its internal boot ROM support. MX6 processors additionally support
  11 +boot from NOR flash and SATA disks. All processors can boot from an internal
  12 +UART, if booting from device media fails.
  13 +Booting from NOR flash does not require to use this image type.
  14 +
  15 +For more details refer Chapter 2 - System Boot and section 2.14
  16 +(flash header description) of the processor's manual.
  17 +
  18 +Command syntax:
  19 +--------------
  20 +./tools/mkimage -l <mx u-boot_file>
  21 + to list the imx image file details
  22 +
  23 +./tools/mkimage -T imximage \
  24 + -n <board specific configuration file> \
  25 + -e <execution address> -d <u-boot binary> <output image file>
  26 +
  27 +For example, for the mx51evk board:
  28 +./tools/mkimage -n ./board/freescale/mx51evk/imximage.cfg \
  29 + -T imximage -e 0x97800000 \
  30 + -d u-boot.bin u-boot.imx
  31 +
  32 +You can generate directly the image when you compile u-boot with:
  33 +
  34 +$ make u-boot.imx
  35 +
  36 +The output image can be flashed on the board SPI flash or on a SD card.
  37 +In both cases, you have to copy the image at the offset required for the
  38 +chosen media devices (0x400 for both SPI flash or SD card).
  39 +
  40 +Please check Freescale documentation for further details.
  41 +
  42 +Board specific configuration file specifications:
  43 +-------------------------------------------------
  44 +1. This file must present in the $(BOARDDIR) and the name should be
  45 + imximage.cfg (since this is used in Makefile).
  46 +2. This file can have empty lines and lines starting with "#" as first
  47 + character to put comments.
  48 +3. This file can have configuration command lines as mentioned below,
  49 + any other information in this file is treated as invalid.
  50 +
  51 +Configuration command line syntax:
  52 +---------------------------------
  53 +1. Each command line is must have two strings, first one command or address
  54 + and second one data string
  55 +2. Following are the valid command strings and associated data strings:-
  56 + Command string data string
  57 + -------------- -----------
  58 + IMXIMAGE_VERSION 1/2
  59 + 1 is for mx25/mx35/mx51 compatible,
  60 + 2 is for mx53/mx6 compatible,
  61 + others is invalid and error is generated.
  62 + This command need appear the fist before
  63 + other valid commands in configuration file.
  64 +
  65 + BOOT_OFFSET value
  66 +
  67 + This command is parallel to BOOT_FROM and
  68 + is preferred over BOOT_FROM.
  69 +
  70 + value: Offset of the image header, this
  71 + value shall be set to one of the
  72 + values found in the file:
  73 + arch/arm/include/asm/\
  74 + mach-imx/imximage.cfg
  75 + Example:
  76 + BOOT_OFFSET FLASH_OFFSET_STANDARD
  77 +
  78 + BOOT_FROM nand/spi/sd/onenand/nor/sata
  79 +
  80 + This command is parallel to BOOT_OFFSET and
  81 + is to be deprecated in favor of BOOT_OFFSET.
  82 +
  83 + Example:
  84 + BOOT_FROM spi
  85 +
  86 + CSF value
  87 +
  88 + Total size of CSF (Command Sequence File)
  89 + used for Secure Boot/ High Assurance Boot
  90 + (HAB).
  91 +
  92 + Using this command will populate the IVT
  93 + (Initial Vector Table) CSF pointer and adjust
  94 + the length fields only. The CSF itself needs
  95 + to be generated with Freescale tools and
  96 + 'manually' appended to the u-boot.imx file.
  97 +
  98 + The CSF is then simply concatenated
  99 + to the u-boot image, making a signed bootloader,
  100 + that the processor can verify
  101 + if the fuses for the keys are burned.
  102 +
  103 + Further infos how to configure the SOC to verify
  104 + the bootloader can be found in the "High
  105 + Assurance Boot Version Application Programming
  106 + Interface Reference Manual" as part of the
  107 + Freescale Code Signing Tool, available on the
  108 + manufacturer's website.
  109 +
  110 + Example:
  111 + CSF 0x2000
  112 +
  113 + DATA type address value
  114 +
  115 + type: word=4, halfword=2, byte=1
  116 + address: physycal register address
  117 + value: value to be set in register
  118 + All values are in in hexadecimal.
  119 + Example (write to IOMUXC):
  120 + DATA 4 0x73FA88a0 0x200
  121 +
  122 +The processor support up to 60 register programming commands for IMXIMAGE_VERSION 1
  123 +and 220 register programming commands for IMXIMAGE_VERSION 2.
  124 +An error is generated if more commands are found in the configuration file.
  125 +
  126 +3. All commands are optional to program.
  127 +
  128 +Setup a SD Card for booting
  129 +--------------------------------
  130 +
  131 +The following example prepare a SD card with u-boot and a FAT partition
  132 +to be used to stored the kernel to be booted.
  133 +I will set the SD in the most compatible mode, setting it with
  134 +255 heads and 63 sectors, as suggested from several documentation and
  135 +howto on line (I took as reference the preparation of a SD Card for the
  136 +Beagleboard, running u-boot as bootloader).
  137 +
  138 +You should start clearing the partitions table on the SD card. Because
  139 +the u-boot image must be stored at the offset 0x400, it must be assured
  140 +that there is no partition at that address. A new SD card is already
  141 +formatted with FAT filesystem and the partition starts from the first
  142 +cylinder, so we need to change it.
  143 +
  144 +You can do all steps with fdisk. If the device for the SD card is
  145 +/dev/mmcblk0, the following commands make the job:
  146 +
  147 +1. Start the fdisk utility (as superuser)
  148 + fdisk /dev/mmcblk0
  149 +
  150 +2. Clear the actual partition
  151 +
  152 +Command (m for help): o
  153 +
  154 +3. Print card info:
  155 +
  156 +Command (m for help): p
  157 +Disk /dev/mmcblk0: 1981 MB, 1981284352 bytes
  158 +
  159 +In my case, I have a 2 GB card. I need the size to set later the correct value
  160 +for the cylinders.
  161 +
  162 +4. Go to expert mode:
  163 +
  164 +Command (m for help): x
  165 +
  166 +5. Set card geometry
  167 +
  168 +Expert command (m for help): h
  169 +Number of heads (1-256, default 4): 255
  170 +
  171 +Expert command (m for help): s
  172 +Number of sectors (1-63, default 16): 63
  173 +Warning: setting sector offset for DOS compatiblity
  174 +
  175 +We have set 255 heads, 63 sector. We have to set the cylinder.
  176 +The value to be set can be calculated with:
  177 +
  178 + cilynder = <total size> / <heads> / <sectors> / <blocksize>
  179 +
  180 +in this example,
  181 + 1981284352 / 255 / 63 / 512 = 239.x = 239
  182 +
  183 +
  184 +Expert command (m for help): c
  185 +Number of cylinders (1-1048576, default 60032): 239
  186 +
  187 +6. Leave the expert mode
  188 +Expert command (m for help): r
  189 +
  190 +7. Set up a partition
  191 +
  192 +Now set a partition table to store the kernel or whatever you want. Of course,
  193 +you can set additional partitions to store rootfs, data, etc.
  194 +In my example I want to set a single partition. I must take care
  195 +to not overwrite the space where I will put u-boot.
  196 +
  197 +Command (m for help): n
  198 +Command action
  199 + e extended
  200 + p primary partition (1-4)
  201 +p
  202 +Partition number (1-4): 1
  203 +First cylinder (1-239, default 1): 3
  204 +Last cylinder, +cylinders or +size{K,M,G} (3-239, default 239): +100M
  205 +
  206 +Command (m for help): p
  207 +
  208 +Disk /dev/mmcblk0: 1967 MB, 1967128576 bytes
  209 +255 heads, 63 sectors/track, 239 cylinders
  210 +Units = cylinders of 16065 * 512 = 8225280 bytes
  211 +Disk identifier: 0xb712a870
  212 +
  213 + Device Boot Start End Blocks Id System
  214 +/dev/mmcblk0p1 3 16 112455 83 Linux
  215 +
  216 +I have set 100MB, leaving the first 2 sectors free. I will copy u-boot
  217 +there.
  218 +
  219 +8. Write the partition table and exit.
  220 +
  221 +Command (m for help): w
  222 +The partition table has been altered!
  223 +
  224 +Calling ioctl() to re-read partition table.
  225 +
  226 +9. Copy u-boot.imx on the SD card
  227 +
  228 +I use dd:
  229 +
  230 +dd if=u-boot.imx of=/dev/mmcblk0 bs=512 seek=2
  231 +
  232 +This command copies the u-boot image at the address 0x400, as required
  233 +by the processor.
  234 +
  235 +Now remove your card from the PC and go to the target. If evrything went right,
  236 +the u-boot prompt should come after power on.
  237 +
  238 +------------------------------------------------
  239 +Author: Stefano babic <sbabic@denx.de>
doc/imx/mkimage/mxsimage.txt
Diff comments   View file @ 49f36f6
  1 +Freescale i.MX233/i.MX28 SB image generator via mkimage
  2 +=======================================================
  3 +
  4 +This tool allows user to produce SB BootStream encrypted with a zero key.
  5 +Such a BootStream is then bootable on i.MX23/i.MX28.
  6 +
  7 +Usage -- producing image:
  8 +=========================
  9 +The mxsimage tool is targeted to be a simple replacement for the elftosb2 .
  10 +To generate an image, write an image configuration file and run:
  11 +
  12 + mkimage -A arm -O u-boot -T mxsimage -n <path to configuration file> \
  13 + <output bootstream file>
  14 +
  15 +The output bootstream file is usually using the .sb file extension. Note
  16 +that the example configuration files for producing bootable BootStream with
  17 +the U-Boot bootloader can be found under arch/arm/boot/cpu/arm926ejs/mxs/
  18 +directory. See the following files:
  19 +
  20 + mxsimage.mx23.cfg -- This is an example configuration for i.MX23
  21 + mxsimage.mx28.cfg -- This is an example configuration for i.MX28
  22 +
  23 +Each configuration file uses very simple instruction semantics and a few
  24 +additional rules have to be followed so that a useful image can be produced.
  25 +These semantics and rules will be outlined now.
  26 +
  27 +- Each line of the configuration file contains exactly one instruction.
  28 +- Every numeric value must be encoded in hexadecimal and in format 0xabcdef12 .
  29 +- The configuration file is a concatenation of blocks called "sections" and
  30 + optionally "DCD blocks" (see below), and optional flags lines.
  31 + - Each "section" is started by the "SECTION" instruction.
  32 + - The "SECTION" instruction has the following semantics:
  33 +
  34 + SECTION u32_section_number [BOOTABLE]
  35 + - u32_section_number :: User-selected ID of the section
  36 + - BOOTABLE :: Sets the section as bootable
  37 +
  38 + - A bootable section is one from which the BootROM starts executing
  39 + subsequent instructions or code. Exactly one section must be selected
  40 + as bootable, usually the one containing the instructions and data to
  41 + load the bootloader.
  42 +
  43 + - A "SECTION" must be immediatelly followed by a "TAG" instruction.
  44 + - The "TAG" instruction has the following semantics:
  45 +
  46 + TAG [LAST]
  47 + - LAST :: Flag denoting the last section in the file
  48 +
  49 + - After a "TAG" unstruction, any of the following instructions may follow
  50 + in any order and any quantity:
  51 +
  52 + NOOP
  53 + - This instruction does nothing
  54 +
  55 + LOAD u32_address string_filename
  56 + - Instructs the BootROM to load file pointed by "string_filename" onto
  57 + address "u32_address".
  58 +
  59 + LOAD IVT u32_address u32_IVT_entry_point
  60 + - Crafts and loads IVT onto address "u32_address" with the entry point
  61 + of u32_IVT_entry_point.
  62 + - i.MX28-specific instruction!
  63 +
  64 + LOAD DCD u32_address u32_DCD_block_ID
  65 + - Loads the DCD block with ID "u32_DCD_block_ID" onto address
  66 + "u32_address" and executes the contents of this DCD block
  67 + - i.MX28-specific instruction!
  68 +
  69 + FILL u32_address u32_pattern u32_length
  70 + - Starts to write memory from addres "u32_address" with a pattern
  71 + specified by "u32_pattern". Writes exactly "u32_length" bytes of the
  72 + pattern.
  73 +
  74 + JUMP [HAB] u32_address [u32_r0_arg]
  75 + - Jumps onto memory address specified by "u32_address" by setting this
  76 + address in PT. The BootROM will pass the "u32_r0_arg" value in ARM
  77 + register "r0" to the executed code if this option is specified.
  78 + Otherwise, ARM register "r0" will default to value 0x00000000. The
  79 + optional "HAB" flag is i.MX28-specific flag turning on the HAB boot.
  80 +
  81 + CALL [HAB] u32_address [u32_r0_arg]
  82 + - See JUMP instruction above, as the operation is exactly the same with
  83 + one difference. The CALL instruction does allow returning into the
  84 + BootROM from the executed code. U-Boot makes use of this in it's SPL
  85 + code.
  86 +
  87 + MODE string_mode
  88 + - Restart the CPU and start booting from device specified by the
  89 + "string_mode" argument. The "string_mode" differs for each CPU
  90 + and can be:
  91 + i.MX23, string_mode = USB/I2C/SPI1_FLASH/SPI2_FLASH/NAND_BCH
  92 + JTAG/SPI3_EEPROM/SD_SSP0/SD_SSP1
  93 + i.MX28, string_mode = USB/I2C/SPI2_FLASH/SPI3_FLASH/NAND_BCH
  94 + JTAG/SPI2_EEPROM/SD_SSP0/SD_SSP1
  95 +
  96 + - An optional "DCD" blocks can be added at the begining of the configuration
  97 + file. Note that the DCD is only supported on i.MX28.
  98 + - The DCD blocks must be inserted before the first "section" in the
  99 + configuration file.
  100 + - The DCD block has the following semantics:
  101 +
  102 + DCD u32_DCD_block_ID
  103 + - u32_DCD_block_ID :: The ID number of the DCD block, must match
  104 + the ID number used by "LOAD DCD" instruction.
  105 +
  106 + - The DCD block must be followed by one of the following instructions. All
  107 + of the instructions operate either on 1, 2 or 4 bytes. This is selected by
  108 + the 'n' suffix of the instruction:
  109 +
  110 + WRITE.n u32_address u32_value
  111 + - Write the "u32_value" to the "u32_address" address.
  112 +
  113 + ORR.n u32_address u32_value
  114 + - Read the "u32_address", perform a bitwise-OR with the "u32_value" and
  115 + write the result back to "u32_address".
  116 +
  117 + ANDC.n u32_address u32_value
  118 + - Read the "u32_address", perform a bitwise-AND with the complement of
  119 + "u32_value" and write the result back to "u32_address".
  120 +
  121 + EQZ.n u32_address u32_count
  122 + - Read the "u32_address" at most "u32_count" times and test if the value
  123 + read is zero. If it is, break the loop earlier.
  124 +
  125 + NEZ.n u32_address u32_count
  126 + - Read the "u32_address" at most "u32_count" times and test if the value
  127 + read is non-zero. If it is, break the loop earlier.
  128 +
  129 + EQ.n u32_address u32_mask
  130 + - Read the "u32_address" in a loop and test if the result masked with
  131 + "u32_mask" equals the "u32_mask". If the values are equal, break the
  132 + reading loop.
  133 +
  134 + NEQ.n u32_address u32_mask
  135 + - Read the "u32_address" in a loop and test if the result masked with
  136 + "u32_mask" does not equal the "u32_mask". If the values are not equal,
  137 + break the reading loop.
  138 +
  139 + NOOP
  140 + - This instruction does nothing.
  141 +
  142 + - An optional flags lines can be one of the following:
  143 +
  144 + DISPLAYPROGRESS
  145 + - Enable boot progress output form the BootROM.
  146 +
  147 +- If the boot progress output from the BootROM is enabled, the BootROM will
  148 + produce a letter on the Debug UART for each instruction it started processing.
  149 + Here is a mapping between the above instructions and the BootROM output:
  150 +
  151 + H -- SB Image header loaded
  152 + T -- TAG instruction
  153 + N -- NOOP instruction
  154 + L -- LOAD instruction
  155 + F -- FILL instruction
  156 + J -- JUMP instruction
  157 + C -- CALL instruction
  158 + M -- MODE instruction
  159 +
  160 +Usage -- verifying image:
  161 +=========================
  162 +
  163 +The mxsimage can also verify and dump contents of an image. Use the following
  164 +syntax to verify and dump contents of an image:
  165 +
  166 + mkimage -l <input bootstream file>
  167 +
  168 +This will output all the information from the SB image header and all the
  169 +instructions contained in the SB image. It will also check if the various
  170 +checksums in the SB image are correct.