blob: 9159f93a97788c0f2db6037b7fe685003c4b3a38 [file] [log] [blame]
Marek Vasutbce88372013-08-26 20:43:33 +02001Freescale 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> \
Wolfgang Denk93e14592013-10-04 17:43:24 +020013 <output bootstream file>
Marek Vasutbce88372013-08-26 20:43:33 +020014
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
Alexey Ignatov7a139952014-10-12 01:43:30 +040030 optionally "DCD blocks" (see below), and optional flags lines.
Marek Vasutbce88372013-08-26 20:43:33 +020031 - 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
Michael Heimpold210594a2018-11-02 23:12:02 +010049 - After a "TAG" instruction, any of the following instructions may follow
Marek Vasutbce88372013-08-26 20:43:33 +020050 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
Wolfgang Denk93e14592013-10-04 17:43:24 +020057 address "u32_address".
Marek Vasutbce88372013-08-26 20:43:33 +020058
59 LOAD IVT u32_address u32_IVT_entry_point
60 - Crafts and loads IVT onto address "u32_address" with the entry point
Wolfgang Denk93e14592013-10-04 17:43:24 +020061 of u32_IVT_entry_point.
Marek Vasutbce88372013-08-26 20:43:33 +020062 - 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
Wolfgang Denk93e14592013-10-04 17:43:24 +020066 "u32_address" and executes the contents of this DCD block
Marek Vasutbce88372013-08-26 20:43:33 +020067 - 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
Wolfgang Denk93e14592013-10-04 17:43:24 +020071 specified by "u32_pattern". Writes exactly "u32_length" bytes of the
Marek Vasutbce88372013-08-26 20:43:33 +020072 pattern.
73
74 JUMP [HAB] u32_address [u32_r0_arg]
75 - Jumps onto memory address specified by "u32_address" by setting this
Wolfgang Denk93e14592013-10-04 17:43:24 +020076 address in PT. The BootROM will pass the "u32_r0_arg" value in ARM
Marek Vasutbce88372013-08-26 20:43:33 +020077 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
Wolfgang Denk93e14592013-10-04 17:43:24 +020083 one difference. The CALL instruction does allow returning into the
Marek Vasutbce88372013-08-26 20:43:33 +020084 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:
Wolfgang Denk93e14592013-10-04 17:43:24 +020091 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
Marek Vasutbce88372013-08-26 20:43:33 +020095
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
Wolfgang Denk93e14592013-10-04 17:43:24 +0200102 DCD u32_DCD_block_ID
Marek Vasutbce88372013-08-26 20:43:33 +0200103 - 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
Alexey Ignatov7a139952014-10-12 01:43:30 +0400142 - An optional flags lines can be one of the following:
143
144 DISPLAYPROGRESS
Michael Heimpold210594a2018-11-02 23:12:02 +0100145 - Enable boot progress output from the BootROM.
Alexey Ignatov7a139952014-10-12 01:43:30 +0400146
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:
Marek Vasutbce88372013-08-26 20:43:33 +0200150
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
160Usage -- verifying image:
161=========================
162
163The mxsimage can also verify and dump contents of an image. Use the following
164syntax to verify and dump contents of an image:
165
166 mkimage -l <input bootstream file>
167
168This will output all the information from the SB image header and all the
169instructions contained in the SB image. It will also check if the various
170checksums in the SB image are correct.