Commit 99830d57 authored by Marek Vasut's avatar Marek Vasut
Browse files

mxssb: Add README

Documentation is a must, add proper README file for this tool.
Signed-off-by: Marek Vasut's avatarMarek Vasut <>
parent a9639e8e
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.
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.
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 .
- The configuration file is a concatenation of blocks called "sections".
- 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:
- 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:
- 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!
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
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
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
i.MX28, string_mode = USB/I2C/SPI2_FLASH/SPI3_FLASH/NAND_BCH
- 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
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment