Gitiles
Code Review Sign In
gerrit.devboardsforandroid.linaro.org / platform / external / u-boot / bce8837071617a13f8e28f60400ee826b3f8a308 / . / doc / README.mxsimage
blob: 88a2caf3e62ab8bb7600ee6f1176d9bcec230a8a [file] [log] [blame]
Marek Vasutbce88372013-08-26 20:43:33 +0200[diff] [blame^]1Freescale i.MX233/i.MX28 SB image generator via mkimage
2=======================================================
3
4This tool allows user to produce SB BootStream encrypted with a zero key.
5Such a BootStream is then bootable on i.MX23/i.MX28.
6
7Usage -- producing image:
8=========================
9The mxsimage tool is targeted to be a simple replacement for the elftosb2 .
10To 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
15The output bootstream file is usually using the .sb file extension. Note
16that the example configuration files for producing bootable BootStream with
17the U-Boot bootloader can be found under arch/arm/boot/cpu/arm926ejs/mxs/
18directory. 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
23Each configuration file uses very simple instruction semantics and a few
24additional rules have to be followed so that a useful image can be produced.
25These 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).
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- If the verbose output from the BootROM is enabled, the BootROM will produce a
143 letter on the Debug UART for each instruction it started processing. Here is a
144 mapping between the above instructions and the BootROM verbose output:
145
146 H -- SB Image header loaded
147 T -- TAG instruction
148 N -- NOOP instruction
149 L -- LOAD instruction
150 F -- FILL instruction
151 J -- JUMP instruction
152 C -- CALL instruction
153 M -- MODE instruction
154
155Usage -- verifying image:
156=========================
157
158The mxsimage can also verify and dump contents of an image. Use the following
159syntax to verify and dump contents of an image:
160
161 mkimage -l <input bootstream file>
162
163This will output all the information from the SB image header and all the
164instructions contained in the SB image. It will also check if the various
165checksums in the SB image are correct.