[people/ms/u-boot.git] / doc / README.mxsimage

Freescale i.MX233/i.MX28 SB image generator via mkimage
=======================================================

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

Usage -- producing image:
=========================
The mxsimage tool is targeted to be a simple replacement for the elftosb2 .
To generate an image, write an image configuration file and run:

 mkimage -A arm -O u-boot -T mxsimage -n <path to configuration file> \
	 <output bootstream file>

The output bootstream file is usually using the .sb file extension. Note
that the example configuration files for producing bootable BootStream with
the U-Boot bootloader can be found under arch/arm/boot/cpu/arm926ejs/mxs/
directory. 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 .
- The configuration file is a concatenation of blocks called "sections" and
  optionally "DCD blocks" (see below), and optional flags lines.
  - 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!

      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!

      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

  - 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".

	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.

  - An optional flags lines can be one of the following:

	DISPLAYPROGRESS
	- Enable boot progress output form the BootROM.

- If the boot progress output from the BootROM is enabled, 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 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

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

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

 mkimage -l <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.
Commit	Line	Data
bce88370 MV	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> \
93e14596	13	<output bootstream file>
bce88370 MV	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
7a139959	30	optionally "DCD blocks" (see below), and optional flags lines.
bce88370 MV	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
93e14596	57	address "u32_address".
bce88370 MV	58
	59	LOAD IVT u32_address u32_IVT_entry_point
	60	- Crafts and loads IVT onto address "u32_address" with the entry point
93e14596	61	of u32_IVT_entry_point.
bce88370 MV	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
93e14596	66	"u32_address" and executes the contents of this DCD block
bce88370 MV	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
93e14596	71	specified by "u32_pattern". Writes exactly "u32_length" bytes of the
bce88370 MV	72	pattern.
	73
	74	JUMP [HAB] u32_address [u32_r0_arg]
	75	- Jumps onto memory address specified by "u32_address" by setting this
93e14596	76	address in PT. The BootROM will pass the "u32_r0_arg" value in ARM
bce88370 MV	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
93e14596	83	one difference. The CALL instruction does allow returning into the
bce88370 MV	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:
93e14596 WD	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
bce88370 MV	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
93e14596	102	DCD u32_DCD_block_ID
bce88370 MV	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
7a139959 AI	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:
bce88370 MV	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.