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.