doc: imx: mkimage: reorganize i.MX mkimage documentation
authorBreno Matheus Lima <breno.lima@nxp.com>
Wed, 10 Oct 2018 01:10:35 +0000 (01:10 +0000)
committerStefano Babic <sbabic@denx.de>
Mon, 22 Oct 2018 12:22:42 +0000 (14:22 +0200)
The following documents describe the image type used by the mkimage
tool to generate U-Boot images for i.MX devices.

- README.imximage
- README.mxsimage

Move all mkimage related document to doc/imx/mkimage for a better
directory structure.

Signed-off-by: Breno Lima <breno.lima@nxp.com>
doc/imx/README.imximage [deleted file]
doc/imx/README.mxsimage [deleted file]
doc/imx/mkimage/README.imximage [new file with mode: 0644]
doc/imx/mkimage/README.mxsimage [new file with mode: 0644]

diff --git a/doc/imx/README.imximage b/doc/imx/README.imximage
deleted file mode 100644 (file)
index 803682f..0000000
+++ /dev/null
@@ -1,239 +0,0 @@
----------------------------------------------
-Imximage Boot Image generation using mkimage
----------------------------------------------
-
-This document describes how to set up a U-Boot image that can be booted
-by Freescale MX25, MX35, MX51, MX53 and MX6 processors via internal boot
-mode.
-
-These processors can boot directly from NAND, SPI flash and SD card flash
-using its internal boot ROM support. MX6 processors additionally support
-boot from NOR flash and SATA disks. All processors can boot from an internal
-UART, if booting from device media fails.
-Booting from NOR flash does not require to use this image type.
-
-For more details refer Chapter 2 - System Boot and section 2.14
-(flash header description) of the processor's manual.
-
-Command syntax:
---------------
-./tools/mkimage -l <mx u-boot_file>
-               to list the imx image file details
-
-./tools/mkimage -T imximage \
-               -n <board specific configuration file> \
-               -e <execution address> -d <u-boot binary>  <output image file>
-
-For example, for the mx51evk board:
-./tools/mkimage -n ./board/freescale/mx51evk/imximage.cfg \
-               -T imximage -e 0x97800000  \
-               -d u-boot.bin u-boot.imx
-
-You can generate directly the image when you compile u-boot with:
-
-$ make u-boot.imx
-
-The output image can be flashed on the board SPI flash or on a SD card.
-In both cases, you have to copy the image at the offset required for the
-chosen media devices (0x400 for both SPI flash or SD card).
-
-Please check Freescale documentation for further details.
-
-Board specific configuration file specifications:
--------------------------------------------------
-1. This file must present in the $(BOARDDIR) and the name should be
-       imximage.cfg (since this is used in Makefile).
-2. This file can have empty lines and lines starting with "#" as first
-       character to put comments.
-3. This file can have configuration command lines as mentioned below,
-       any other information in this file is treated as invalid.
-
-Configuration command line syntax:
----------------------------------
-1. Each command line is must have two strings, first one command or address
-       and second one data string
-2. Following are the valid command strings and associated data strings:-
-       Command string          data string
-       --------------          -----------
-       IMXIMAGE_VERSION        1/2
-                               1 is for mx25/mx35/mx51 compatible,
-                               2 is for mx53/mx6 compatible,
-                               others is invalid and error is generated.
-                               This command need appear the fist before
-                               other valid commands in configuration file.
-
-       BOOT_OFFSET             value
-
-                               This command is parallel to BOOT_FROM and
-                               is preferred over BOOT_FROM.
-
-                               value:  Offset of the image header, this
-                                       value shall be set to one of the
-                                       values found in the file:
-                                               arch/arm/include/asm/\
-                                               mach-imx/imximage.cfg
-                               Example:
-                               BOOT_OFFSET FLASH_OFFSET_STANDARD
-
-       BOOT_FROM               nand/spi/sd/onenand/nor/sata
-
-                               This command is parallel to BOOT_OFFSET and
-                               is to be deprecated in favor of BOOT_OFFSET.
-
-                               Example:
-                               BOOT_FROM spi
-
-       CSF                     value
-
-                               Total size of CSF (Command Sequence File)
-                               used for Secure Boot/ High Assurance Boot
-                               (HAB).
-
-                               Using this command will populate the IVT
-                               (Initial Vector Table) CSF pointer and adjust
-                               the length fields only. The CSF itself needs
-                               to be generated with Freescale tools and
-                               'manually' appended to the u-boot.imx file.
-
-                               The CSF is then simply concatenated
-                               to the u-boot image, making a signed bootloader,
-                               that the processor can verify
-                               if the fuses for the keys are burned.
-
-                               Further infos how to configure the SOC to verify
-                               the bootloader can be found in the "High
-                               Assurance Boot Version Application Programming
-                               Interface Reference Manual" as part of the
-                               Freescale Code Signing Tool, available on the
-                               manufacturer's website.
-
-                               Example:
-                               CSF 0x2000
-
-       DATA                    type address value
-
-                               type: word=4, halfword=2, byte=1
-                               address: physycal register address
-                               value: value to be set in register
-                               All values are in in hexadecimal.
-                               Example (write to IOMUXC):
-                               DATA 4 0x73FA88a0 0x200
-
-The processor support up to 60 register programming commands for IMXIMAGE_VERSION 1
-and 220 register programming commands for IMXIMAGE_VERSION 2.
-An error is generated if more commands are found in the configuration file.
-
-3. All commands are optional to program.
-
-Setup a SD Card for booting
---------------------------------
-
-The following example prepare a SD card with u-boot and a FAT partition
-to be used to stored the kernel to be booted.
-I will set the SD in the most compatible mode, setting it with
-255 heads and 63 sectors, as suggested from several documentation and
-howto on line (I took as reference the preparation of a SD Card for the
-Beagleboard, running u-boot as bootloader).
-
-You should start clearing the partitions table on the SD card. Because
-the u-boot image must be stored at the offset 0x400, it must be assured
-that there is no partition at that address. A new SD card is already
-formatted with FAT filesystem and the partition starts from the first
-cylinder, so we need to change it.
-
-You can do all steps with fdisk. If the device for the SD card is
-/dev/mmcblk0, the following commands make the job:
-
-1. Start the fdisk utility (as superuser)
-       fdisk /dev/mmcblk0
-
-2. Clear the actual partition
-
-Command (m for help): o
-
-3. Print card info:
-
-Command (m for help): p
-Disk /dev/mmcblk0: 1981 MB, 1981284352 bytes
-
-In my case, I have a 2 GB card. I need the size to set later the correct value
-for the cylinders.
-
-4. Go to expert mode:
-
-Command (m for help): x
-
-5. Set card geometry
-
-Expert command (m for help): h
-Number of heads (1-256, default 4): 255
-
-Expert command (m for help): s
-Number of sectors (1-63, default 16): 63
-Warning: setting sector offset for DOS compatiblity
-
-We have set 255 heads, 63 sector. We have to set the cylinder.
-The value to be set can be calculated with:
-
-       cilynder = <total size> / <heads> / <sectors> / <blocksize>
-
-in this example,
-       1981284352 / 255 / 63 / 512 = 239.x = 239
-
-
-Expert command (m for help): c
-Number of cylinders (1-1048576, default 60032): 239
-
-6. Leave the expert mode
-Expert command (m for help): r
-
-7. Set up a partition
-
-Now set a partition table to store the kernel or whatever you want. Of course,
-you can set additional partitions to store rootfs, data, etc.
-In my example I want to set a single partition. I must take care
-to not overwrite the space where I will put u-boot.
-
-Command (m for help): n
-Command action
-   e   extended
-   p   primary partition (1-4)
-p
-Partition number (1-4): 1
-First cylinder (1-239, default 1): 3
-Last cylinder, +cylinders or +size{K,M,G} (3-239, default 239): +100M
-
-Command (m for help): p
-
-Disk /dev/mmcblk0: 1967 MB, 1967128576 bytes
-255 heads, 63 sectors/track, 239 cylinders
-Units = cylinders of 16065 * 512 = 8225280 bytes
-Disk identifier: 0xb712a870
-
-       Device Boot      Start         End      Blocks   Id  System
-/dev/mmcblk0p1              3          16      112455   83  Linux
-
-I have set 100MB, leaving the first 2 sectors free. I will copy u-boot
-there.
-
-8. Write the partition table and exit.
-
-Command (m for help): w
-The partition table has been altered!
-
-Calling ioctl() to re-read partition table.
-
-9. Copy u-boot.imx on the SD card
-
-I use dd:
-
-dd if=u-boot.imx of=/dev/mmcblk0 bs=512 seek=2
-
-This command copies the u-boot image at the address 0x400, as required
-by the processor.
-
-Now remove your card from the PC and go to the target. If evrything went right,
-the u-boot prompt should come after power on.
-
-------------------------------------------------
-Author: Stefano babic <sbabic@denx.de>
diff --git a/doc/imx/README.mxsimage b/doc/imx/README.mxsimage
deleted file mode 100644 (file)
index c3975ee..0000000
+++ /dev/null
@@ -1,170 +0,0 @@
-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.
diff --git a/doc/imx/mkimage/README.imximage b/doc/imx/mkimage/README.imximage
new file mode 100644 (file)
index 0000000..803682f
--- /dev/null
@@ -0,0 +1,239 @@
+---------------------------------------------
+Imximage Boot Image generation using mkimage
+---------------------------------------------
+
+This document describes how to set up a U-Boot image that can be booted
+by Freescale MX25, MX35, MX51, MX53 and MX6 processors via internal boot
+mode.
+
+These processors can boot directly from NAND, SPI flash and SD card flash
+using its internal boot ROM support. MX6 processors additionally support
+boot from NOR flash and SATA disks. All processors can boot from an internal
+UART, if booting from device media fails.
+Booting from NOR flash does not require to use this image type.
+
+For more details refer Chapter 2 - System Boot and section 2.14
+(flash header description) of the processor's manual.
+
+Command syntax:
+--------------
+./tools/mkimage -l <mx u-boot_file>
+               to list the imx image file details
+
+./tools/mkimage -T imximage \
+               -n <board specific configuration file> \
+               -e <execution address> -d <u-boot binary>  <output image file>
+
+For example, for the mx51evk board:
+./tools/mkimage -n ./board/freescale/mx51evk/imximage.cfg \
+               -T imximage -e 0x97800000  \
+               -d u-boot.bin u-boot.imx
+
+You can generate directly the image when you compile u-boot with:
+
+$ make u-boot.imx
+
+The output image can be flashed on the board SPI flash or on a SD card.
+In both cases, you have to copy the image at the offset required for the
+chosen media devices (0x400 for both SPI flash or SD card).
+
+Please check Freescale documentation for further details.
+
+Board specific configuration file specifications:
+-------------------------------------------------
+1. This file must present in the $(BOARDDIR) and the name should be
+       imximage.cfg (since this is used in Makefile).
+2. This file can have empty lines and lines starting with "#" as first
+       character to put comments.
+3. This file can have configuration command lines as mentioned below,
+       any other information in this file is treated as invalid.
+
+Configuration command line syntax:
+---------------------------------
+1. Each command line is must have two strings, first one command or address
+       and second one data string
+2. Following are the valid command strings and associated data strings:-
+       Command string          data string
+       --------------          -----------
+       IMXIMAGE_VERSION        1/2
+                               1 is for mx25/mx35/mx51 compatible,
+                               2 is for mx53/mx6 compatible,
+                               others is invalid and error is generated.
+                               This command need appear the fist before
+                               other valid commands in configuration file.
+
+       BOOT_OFFSET             value
+
+                               This command is parallel to BOOT_FROM and
+                               is preferred over BOOT_FROM.
+
+                               value:  Offset of the image header, this
+                                       value shall be set to one of the
+                                       values found in the file:
+                                               arch/arm/include/asm/\
+                                               mach-imx/imximage.cfg
+                               Example:
+                               BOOT_OFFSET FLASH_OFFSET_STANDARD
+
+       BOOT_FROM               nand/spi/sd/onenand/nor/sata
+
+                               This command is parallel to BOOT_OFFSET and
+                               is to be deprecated in favor of BOOT_OFFSET.
+
+                               Example:
+                               BOOT_FROM spi
+
+       CSF                     value
+
+                               Total size of CSF (Command Sequence File)
+                               used for Secure Boot/ High Assurance Boot
+                               (HAB).
+
+                               Using this command will populate the IVT
+                               (Initial Vector Table) CSF pointer and adjust
+                               the length fields only. The CSF itself needs
+                               to be generated with Freescale tools and
+                               'manually' appended to the u-boot.imx file.
+
+                               The CSF is then simply concatenated
+                               to the u-boot image, making a signed bootloader,
+                               that the processor can verify
+                               if the fuses for the keys are burned.
+
+                               Further infos how to configure the SOC to verify
+                               the bootloader can be found in the "High
+                               Assurance Boot Version Application Programming
+                               Interface Reference Manual" as part of the
+                               Freescale Code Signing Tool, available on the
+                               manufacturer's website.
+
+                               Example:
+                               CSF 0x2000
+
+       DATA                    type address value
+
+                               type: word=4, halfword=2, byte=1
+                               address: physycal register address
+                               value: value to be set in register
+                               All values are in in hexadecimal.
+                               Example (write to IOMUXC):
+                               DATA 4 0x73FA88a0 0x200
+
+The processor support up to 60 register programming commands for IMXIMAGE_VERSION 1
+and 220 register programming commands for IMXIMAGE_VERSION 2.
+An error is generated if more commands are found in the configuration file.
+
+3. All commands are optional to program.
+
+Setup a SD Card for booting
+--------------------------------
+
+The following example prepare a SD card with u-boot and a FAT partition
+to be used to stored the kernel to be booted.
+I will set the SD in the most compatible mode, setting it with
+255 heads and 63 sectors, as suggested from several documentation and
+howto on line (I took as reference the preparation of a SD Card for the
+Beagleboard, running u-boot as bootloader).
+
+You should start clearing the partitions table on the SD card. Because
+the u-boot image must be stored at the offset 0x400, it must be assured
+that there is no partition at that address. A new SD card is already
+formatted with FAT filesystem and the partition starts from the first
+cylinder, so we need to change it.
+
+You can do all steps with fdisk. If the device for the SD card is
+/dev/mmcblk0, the following commands make the job:
+
+1. Start the fdisk utility (as superuser)
+       fdisk /dev/mmcblk0
+
+2. Clear the actual partition
+
+Command (m for help): o
+
+3. Print card info:
+
+Command (m for help): p
+Disk /dev/mmcblk0: 1981 MB, 1981284352 bytes
+
+In my case, I have a 2 GB card. I need the size to set later the correct value
+for the cylinders.
+
+4. Go to expert mode:
+
+Command (m for help): x
+
+5. Set card geometry
+
+Expert command (m for help): h
+Number of heads (1-256, default 4): 255
+
+Expert command (m for help): s
+Number of sectors (1-63, default 16): 63
+Warning: setting sector offset for DOS compatiblity
+
+We have set 255 heads, 63 sector. We have to set the cylinder.
+The value to be set can be calculated with:
+
+       cilynder = <total size> / <heads> / <sectors> / <blocksize>
+
+in this example,
+       1981284352 / 255 / 63 / 512 = 239.x = 239
+
+
+Expert command (m for help): c
+Number of cylinders (1-1048576, default 60032): 239
+
+6. Leave the expert mode
+Expert command (m for help): r
+
+7. Set up a partition
+
+Now set a partition table to store the kernel or whatever you want. Of course,
+you can set additional partitions to store rootfs, data, etc.
+In my example I want to set a single partition. I must take care
+to not overwrite the space where I will put u-boot.
+
+Command (m for help): n
+Command action
+   e   extended
+   p   primary partition (1-4)
+p
+Partition number (1-4): 1
+First cylinder (1-239, default 1): 3
+Last cylinder, +cylinders or +size{K,M,G} (3-239, default 239): +100M
+
+Command (m for help): p
+
+Disk /dev/mmcblk0: 1967 MB, 1967128576 bytes
+255 heads, 63 sectors/track, 239 cylinders
+Units = cylinders of 16065 * 512 = 8225280 bytes
+Disk identifier: 0xb712a870
+
+       Device Boot      Start         End      Blocks   Id  System
+/dev/mmcblk0p1              3          16      112455   83  Linux
+
+I have set 100MB, leaving the first 2 sectors free. I will copy u-boot
+there.
+
+8. Write the partition table and exit.
+
+Command (m for help): w
+The partition table has been altered!
+
+Calling ioctl() to re-read partition table.
+
+9. Copy u-boot.imx on the SD card
+
+I use dd:
+
+dd if=u-boot.imx of=/dev/mmcblk0 bs=512 seek=2
+
+This command copies the u-boot image at the address 0x400, as required
+by the processor.
+
+Now remove your card from the PC and go to the target. If evrything went right,
+the u-boot prompt should come after power on.
+
+------------------------------------------------
+Author: Stefano babic <sbabic@denx.de>
diff --git a/doc/imx/mkimage/README.mxsimage b/doc/imx/mkimage/README.mxsimage
new file mode 100644 (file)
index 0000000..c3975ee
--- /dev/null
@@ -0,0 +1,170 @@
+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.