README 7.02 KB
Newer Older
Marek Vasut's avatar
Marek Vasut committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14
Freescale i.MX233/i.MX28 SB image generator
===========================================

This tool allows user to produce SB BootStream encrypted with a zero key.
Such a BootStream is then bootable on i.MX23/i.MX28.

Build:
======
1) Install libssl-dev or similar OpenSSL development package. The tool
   is using OpenSSL to encrypt the image with zero key.

2) Compile the tool by running simple "make" command . The produced binary
   will be called "mxssb" and will reside in the current directory.

15 16
Usage -- producing image:
=========================
Marek Vasut's avatar
Marek Vasut committed
17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37
The MXSSB tool is targetted to be a simple replacement for the elftosb2 .
To generate an image, simply write an image configuration file and run:

 mxssb -c <path to configuration file> -o <output bootstream file>

The output bootstream file is usually using the .sb file extension. For
early boot debugging purposes, a verbose output from the BootROM can be
enabled by adding the "-v" option to "mxssb" command line. Note that the
example configuration files for producing bootable BootStream with the
U-Boot bootloader can be found in the MXSSB source distribution. See the
following files:

 mxsimage.mx23.cfg -- This is an example configuration for i.MX23
 mxsimage.mx28.cfg -- This is an example configuration for i.MX28

Each configuration file uses very simple instruction semantics and a few
additional rules have to be followed so that a useful image can be produced.
These semantics and rules will be outlined now.

- Each line of the configuration file contains exactly one instruction.
- Every numeric value must be encoded in hexadecimal and in format 0xabcdef12 .
38 39
- The configuration file is a concatenation of blocks called "sections" and
  optionally "DCD blocks" (see below).
Marek Vasut's avatar
Marek Vasut committed
40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72
  - Each "section" is started by the "SECTION" instruction.
  - The "SECTION" instruction has the following semantics:

      SECTION u32_section_number [BOOTABLE]
      - u32_section_number :: User-selected ID of the section
      - BOOTABLE           :: Sets the section as bootable

  - A bootable section is one from which the BootROM starts executing
    subsequent instructions or code. Exactly one section must be selected
    as bootable, usually the one containing the instructions and data to
    load the bootloader.

  - A "SECTION" must be immediatelly followed by a "TAG" instruction.
  - The "TAG" instruction has the following semantics:

      TAG [LAST]
      - LAST               :: Flag denoting the last section in the file

  - After a "TAG" unstruction, any of the following instructions may follow
    in any order and any quantity:

      NOOP
      - This instruction does nothing

      LOAD     u32_address string_filename
      - Instructs the BootROM to load file pointed by "string_filename" onto
        address "u32_address".

      LOAD IVT u32_address u32_IVT_entry_point
      - Crafts and loads IVT onto address "u32_address" with the entry point
        of u32_IVT_entry_point.
      - i.MX28-specific instruction!

73 74 75 76 77
      LOAD DCD u32_address u32_DCD_block_ID
      - Loads the DCD block with ID "u32_DCD_block_ID" onto address
        "u32_address" and executes the contents of this DCD block
      - i.MX28-specific instruction!

Marek Vasut's avatar
Marek Vasut committed
78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104
      FILL u32_address u32_pattern u32_length
      - Starts to write memory from addres "u32_address" with a pattern
        specified by "u32_pattern". Writes exactly "u32_length" bytes of the
	pattern.

      JUMP [HAB] u32_address [u32_r0_arg]
      - Jumps onto memory address specified by "u32_address" by setting this
        address in PT. The BootROM will pass the "u32_r0_arg" value in ARM
	register "r0" to the executed code if this option is specified.
	Otherwise, ARM register "r0" will default to value 0x00000000. The
	optional "HAB" flag is i.MX28-specific flag turning on the HAB boot.

      CALL [HAB] u32_address [u32_r0_arg]
      - See JUMP instruction above, as the operation is exactly the same with
        one difference. The CALL instruction does allow returning into the
	BootROM from the executed code. U-Boot makes use of this in it's SPL
	code.

      MODE string_mode
      - Restart the CPU and start booting from device specified by the
	"string_mode" argument. The "string_mode" differs for each CPU
	and can be:
         i.MX23, string_mode = USB/I2C/SPI1_FLASH/SPI2_FLASH/NAND_BCH
                               JTAG/SPI3_EEPROM/SD_SSP0/SD_SSP1
         i.MX28, string_mode = USB/I2C/SPI2_FLASH/SPI3_FLASH/NAND_BCH
                               JTAG/SPI2_EEPROM/SD_SSP0/SD_SSP1

105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129
  - An optional "DCD" blocks can be added at the begining of the configuration
    file. Note that the DCD is only supported on i.MX28.
    - The DCD blocks must be inserted before the first "section" in the
      configuration file.
    - The DCD block has the following semantics:

        DCD u32_DCD_block_ID
	- u32_DCD_block_ID	:: The ID number of the DCD block, must match
				   the ID number used by "LOAD DCD" instruction.

    - The DCD block must be followed by one of the following instructions. All
      of the instructions operate either on 1, 2 or 4 bytes. This is selected by
      the 'n' suffix of the instruction:

	WRITE.n u32_address u32_value
	- Write the "u32_value" to the "u32_address" address.

	ORR.n u32_address u32_value
	- Read the "u32_address", perform a bitwise-OR with the "u32_value" and
	  write the result back to "u32_address".

	ANDC.n u32_address u32_value
	- Read the "u32_address", perform a bitwise-AND with the complement of
	  "u32_value" and write the result back to "u32_address".

130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150
	EQZ.n u32_address u32_count
	- Read the "u32_address" at most "u32_count" times and test if the value
	  read is zero. If it is, break the loop earlier.

	NEZ.n u32_address u32_count
	- Read the "u32_address" at most "u32_count" times and test if the value
	  read is non-zero. If it is, break the loop earlier.

	EQ.n u32_address u32_mask
	- Read the "u32_address" in a loop and test if the result masked with
	  "u32_mask" equals the "u32_mask". If the values are equal, break the
	  reading loop.

	NEQ.n u32_address u32_mask
	- Read the "u32_address" in a loop and test if the result masked with
	  "u32_mask" does not equal the "u32_mask". If the values are not equal,
	  break the reading loop.

	NOOP
	- This instruction does nothing.

Marek Vasut's avatar
Marek Vasut committed
151 152 153 154 155 156 157 158 159 160 161 162 163
- If the verbose output from the BootROM is enabled by passing the "-v" option
  to MXSSB, the BootROM will produce a letter on the Debug UART for each
  instruction it started processing. Here is a mapping between the above
  instructions and the BootROM verbose output:

   H -- SB Image header loaded
   T -- TAG instruction
   N -- NOOP instruction
   L -- LOAD instruction
   F -- FILL instruction
   J -- JUMP instruction
   C -- CALL instruction
   M -- MODE instruction
164 165 166 167 168 169 170 171 172 173 174 175

Usage -- verifying image:
=========================

The MXSSB can also verify and dump contents of an image. Use the following
syntax to verify and dump contents of an image:

 mxssb -i <input bootstream file>

This will output all the information from the SB image header and all the
instructions contained in the SB image. It will also check if the various
checksums in the SB image are correct.