Eric Lee / smarc-uboot

Download as
Browse Code ยป

Commit 57310be619b009bd7df804702d1bad724bc87430

Authored by Breno Lima
Committed by Ye Li
1 parent 27373a1723
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-4 doc: imx: mkimage: reorganize i.MX mkimage documentation 

The following documents describe the image type used by the mkimage
tool to generate U-Boot images for i.MX devices.

- README.imximage
- README.mxsimage

Move all mkimage related document to doc/imx/mkimage for a better
directory structure.

Signed-off-by: Breno Lima <breno.lima@nxp.com>

Showing 4 changed files with 409 additions and 409 deletions Inline Diff

doc/imx/README.imximage
View file @ 57310be
1 --------------------------------------------- File was deleted
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>
240 1 ---------------------------------------------
doc/imx/README.mxsimage
View file @ 57310be
1 Freescale i.MX233/i.MX28 SB image generator via mkimage File was deleted
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.
171 1 Freescale i.MX233/i.MX28 SB image generator via mkimage
doc/imx/mkimage/README.imximage
Diff comments   View file @ 57310be
File was created 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>
240
doc/imx/mkimage/README.mxsimage
Diff comments   View file @ 57310be
File was created 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.
171