]> git.sur5r.net Git - u-boot/blob - doc/README.mxsimage
Merge branch 'master' of git://git.denx.de/u-boot-sunxi
[u-boot] / doc / README.mxsimage
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.