tools/doimage_kw2/doimage_readme.txt - uboot/prism - Git at Google

 Doimage tool
 ============

 Doimage tool is used for preparation of binary image of boot loader for
 a various types of supported boot media.
 The tool is supplied in source code adopted for Linux compilation.
 Supported boot media types:
 - SPI flash
 - NAND flash
 - SATA
 - PEX
 - TWSI
 - UART

 Doimage supports a special secure boot mode. In this mode image and its headers
 are signed using private RSA key (up to 2048 bit).
 An appropriate signatures and public RSA key needed for verification are
 embedded in the image header preventing unauthorized boot image replacement.
 The validity of supplied RSA public key is then verified against eFuse values
 stored in SOC. Additionally the binary image can be encrypted using AES-128-CBC
 algorithm and then decrypted by the HW using key stored in SOC eFuse.

 Usage:
 ======
 Doimage uses list of parameters supplied in command line.
 Some parameters are mandatory and some are optional.
 Below is the command line format used by doimage utility:

 doimage <mandatory parameters> [optional parameters] image_in image_out [header_out]

 Mandatory parameters:
 =====================

 -T image_type   One of the following types:
       sata\uart\flash\bootrom\nand\hex\pex
       The "flash" type should be used for SPI flash images.
       If "sata" type is selected the command output will produce two
       files - header and image.

 -D image_dest   Hexadecimal RAM destination address used for copying the binary
       image during the boot stage.

 -E image_exec   Hexadecimal address in system RAM used for image execution
       (entry point). If selected image is "flash" and the image
       destination address is 0xFFFFFFFF then the image will be
       executed directly from flash media bypassing copy to RAM stage.
       In this case the execution address should be locates in SPI
       flash memory space.

 -S image_source   Hexadecimal byte offset of image from the boot media device
       start point. For sata devices the meaning is LBA offset in
       sectors from the beginning of disk.
       The parameter is mandatory only for sata and ignored for pex
       and twsi boot devices. If omitted, it assumed equal to 0 and
       the binary image is located next to the image headers.
       The offset must be aligned to 512 bytes boundary for nand boot
       devices. Typical offset value for sata devices is 0x3F

 -W hex_width   Mandatory only for "hex" image type.
       Possible values are 8,16,32,64 bytes.

 Mandatory parameters for NAND boot source:
 =========================================

 -L nand_blk_size
       NAND block size in KBytes (decimal int in range 64-16320).
       This parameter is ignored for flashes with  512B pages.
       Such small page flashes always use 16K block sizes

 -N nand_cell_typ
       NAND cell technology type (char: M for MLC, S for SLC)

 -P nand_pg_size
       NAND page size: (decimal 512, 2048, 4096 or 8192)\n");

 -C nand_ecc
       Option is IGNORED in this release (1=Hamming, 2=RS, 3=None)

 Optional parameters:
 ===================

 -M twsi_file   ASCII file name that contains the list of I2C init registers
       to be set by the HW.
       See the example file supplied with this utility

 -G exec_file   ascii file name that contains binary routine (ARM 5TE THUMB)
       to run before the bootloader image execution. The routine must contain
       an appropriate code for saving all registers at the routine start and
       restore them before return from the routine.

 -R regs_file   ASCII file name that contains the list of address-value
       pairs used for configuring the device registers before
       the binary image execution. Usually used for DRAM configuration.

 -X pre_pad   Hexadecimal number of bytes to be placed before the binary image.

 -X post_pad   Hexadecimal number of bytes to be placed after the binary image.

 -H header_mode   The header mode. Supported modes:
       -H 1 : creates one file (image_out) for header and image
       -H 2 : creates two files - (image_out) for image and
          (header_out) for header
       -H 3 : creates one file (image_out) for header only
       -H 4 : creates one file (image_out) for image only

 Secure mode parameters:
 ======================

 -Z prv_key   ASCII file name containing RSA private key up to 2048 bit length.
       The RSA key is used for creating signatures for the image header
       and binary image. Additionally it allows generation of public RSA
       key, which is embedded in the image header.
       The key file must be in TXT format - see the example key supplied
       with this utility.
       This parameter activates secure boot mode and enables all other
       secure mode parameters usage.

 -A aes_key   ASCII file name containing AES-128 symmetric key.
       The boot image (execpting the header) will be encrypted using
       AES-128-CBC algorithm. The key file must be in binary format
       (array of 16 bytes).
       See the example key file supplied with this utility.

 -J jtag_delay   Enable JTAG and delay the boot sequence execution
       by <jtag_delay> * 10 seconds.
       Used for overriding the eFuse value for devices with
       disabled JTAG functionality.

 -B hex_box_id   Hexadecimal Box ID in range of 0 to 0xffffffff

 F hex_flash_id   Hexadecimal Flash ID in range of 0 to 0xffff


 Usage examples:
 ==============

 1. Image for SPI flash. Secure mode is enabled. JTAG support is enabled.
 Delay boot execution by 10 sec for JTAG probe connection.
 Run custom executable with 2 parameters and DRAM registers configuration
 before running U-boot. Load U-boot into DRAM address 0x600000,
 entry point is 0x670000.

 doimage -T flash -D 0x600000 -E 0x670000 -Z rsa_priv.txt -A aes128.bin \
    -J 1 -B 0xDEADBEEF -F 0xBABE -R dramregs_400db_A.txt -G binhdr.bin -K 2 \
    u-boot-db88f6281abp.bin u-boot-db88f6281abp_400db_flash_secure.bin

 2. Image for NAND flash. Flash page size is 2K. Secure mode is enabled.
 JTAG support is enabled. Delay boot execution by 10 sec for JTAG probe connection.
 Run custom executable with 2 parameters and DRAM registers configuration
 before running U-boot. Load U-boot into DRAM address 0x600000,
 entry point is 0x670000.

 doimage -T nand -D 0x600000 -E 0x670000 -P 2048 -Z rsa_priv.txt -A aes128.bin \
    -J 1 -B 0xDEADBEEF -F 0xBABE -R dramregs_400db_A.txt -G binhdr.bin -K 2 \
    u-boot-db88f6281abp.bin u-boot-db88f6281abp_400db_nand_secure.bin

 3. Image for UART. Secure mode is disabled.

 doimage -T uart -D 0x600000 -E 0x670000 -R dramregs_400db_A.txt \
    u-boot-db88f6281abp.bin u-boot-db88f6281abp_400db_uart.bin

 4. Image for SATA disk. Secure mode is enabled. JTAG support is enabled.
 Delay boot execution by 10 sec for JTAG probe connection.
 Run custom executable with 2 parameters and DRAM registers configuration
 before running U-boot. Load U-boot into DRAM address 0x600000,
 entry point is 0x670000. U-boot image is located at LBA sector 0x3F.
 Create two images - one for header and one for application.

 doimage -T sata -D 0x600000 -E 0x670000 -S 0x3F -Z rsa_priv.txt -A aes128.bin \
    -J 1 -B 0xDEADBEEF -F 0xBABE -R dramregs_400db_A.txt -G binhdr.bin -K 2 \
    u-boot-db88f6281abp.bin u-boot-db88f6281abp_400db_sata_img_secure.bin \
    u-boot-db88f6281abp_400db_sata_hdr_secure.bin

 In order to copy SATA boot image and header to disk the following technique is used:
 1. Copy the header (first SATA device /dev/sda is uses as example)
    dd if=<header file name> of=/dev/sda seek=1
 2. Copy the boot image (u-boot) to the first partition (starting by default at LBAsector 63)
    dd if=<uboot with checksum> of=/dev/sda1
	Doimage tool
	============

	Doimage tool is used for preparation of binary image of boot loader for
	a various types of supported boot media.
	The tool is supplied in source code adopted for Linux compilation.
	Supported boot media types:
	- SPI flash
	- NAND flash
	- SATA
	- PEX
	- TWSI
	- UART

	Doimage supports a special secure boot mode. In this mode image and its headers
	are signed using private RSA key (up to 2048 bit).
	An appropriate signatures and public RSA key needed for verification are
	embedded in the image header preventing unauthorized boot image replacement.
	The validity of supplied RSA public key is then verified against eFuse values
	stored in SOC. Additionally the binary image can be encrypted using AES-128-CBC
	algorithm and then decrypted by the HW using key stored in SOC eFuse.

	Usage:
	======
	Doimage uses list of parameters supplied in command line.
	Some parameters are mandatory and some are optional.
	Below is the command line format used by doimage utility:

	doimage <mandatory parameters> [optional parameters] image_in image_out [header_out]

	Mandatory parameters:
	=====================

	-T image_type One of the following types:
	sata\uart\flash\bootrom\nand\hex\pex
	The "flash" type should be used for SPI flash images.
	If "sata" type is selected the command output will produce two
	files - header and image.

	-D image_dest Hexadecimal RAM destination address used for copying the binary
	image during the boot stage.

	-E image_exec Hexadecimal address in system RAM used for image execution
	(entry point). If selected image is "flash" and the image
	destination address is 0xFFFFFFFF then the image will be
	executed directly from flash media bypassing copy to RAM stage.
	In this case the execution address should be locates in SPI
	flash memory space.

	-S image_source Hexadecimal byte offset of image from the boot media device
	start point. For sata devices the meaning is LBA offset in
	sectors from the beginning of disk.
	The parameter is mandatory only for sata and ignored for pex
	and twsi boot devices. If omitted, it assumed equal to 0 and
	the binary image is located next to the image headers.
	The offset must be aligned to 512 bytes boundary for nand boot
	devices. Typical offset value for sata devices is 0x3F

	-W hex_width Mandatory only for "hex" image type.
	Possible values are 8,16,32,64 bytes.

	Mandatory parameters for NAND boot source:
	=========================================

	-L nand_blk_size
	NAND block size in KBytes (decimal int in range 64-16320).
	This parameter is ignored for flashes with 512B pages.
	Such small page flashes always use 16K block sizes

	-N nand_cell_typ
	NAND cell technology type (char: M for MLC, S for SLC)

	-P nand_pg_size
	NAND page size: (decimal 512, 2048, 4096 or 8192)\n");

	-C nand_ecc
	Option is IGNORED in this release (1=Hamming, 2=RS, 3=None)

	Optional parameters:
	===================

	-M twsi_file ASCII file name that contains the list of I2C init registers
	to be set by the HW.
	See the example file supplied with this utility

	-G exec_file ascii file name that contains binary routine (ARM 5TE THUMB)
	to run before the bootloader image execution. The routine must contain
	an appropriate code for saving all registers at the routine start and
	restore them before return from the routine.

	-R regs_file ASCII file name that contains the list of address-value
	pairs used for configuring the device registers before
	the binary image execution. Usually used for DRAM configuration.

	-X pre_pad Hexadecimal number of bytes to be placed before the binary image.

	-X post_pad Hexadecimal number of bytes to be placed after the binary image.

	-H header_mode The header mode. Supported modes:
	-H 1 : creates one file (image_out) for header and image
	-H 2 : creates two files - (image_out) for image and
	(header_out) for header
	-H 3 : creates one file (image_out) for header only
	-H 4 : creates one file (image_out) for image only

	Secure mode parameters:
	======================

	-Z prv_key ASCII file name containing RSA private key up to 2048 bit length.
	The RSA key is used for creating signatures for the image header
	and binary image. Additionally it allows generation of public RSA
	key, which is embedded in the image header.
	The key file must be in TXT format - see the example key supplied
	with this utility.
	This parameter activates secure boot mode and enables all other
	secure mode parameters usage.

	-A aes_key ASCII file name containing AES-128 symmetric key.
	The boot image (execpting the header) will be encrypted using
	AES-128-CBC algorithm. The key file must be in binary format
	(array of 16 bytes).
	See the example key file supplied with this utility.

	-J jtag_delay Enable JTAG and delay the boot sequence execution
	by <jtag_delay> * 10 seconds.
	Used for overriding the eFuse value for devices with
	disabled JTAG functionality.

	-B hex_box_id Hexadecimal Box ID in range of 0 to 0xffffffff

	F hex_flash_id Hexadecimal Flash ID in range of 0 to 0xffff


	Usage examples:
	==============

	1. Image for SPI flash. Secure mode is enabled. JTAG support is enabled.
	Delay boot execution by 10 sec for JTAG probe connection.
	Run custom executable with 2 parameters and DRAM registers configuration
	before running U-boot. Load U-boot into DRAM address 0x600000,
	entry point is 0x670000.

	doimage -T flash -D 0x600000 -E 0x670000 -Z rsa_priv.txt -A aes128.bin \
	-J 1 -B 0xDEADBEEF -F 0xBABE -R dramregs_400db_A.txt -G binhdr.bin -K 2 \
	u-boot-db88f6281abp.bin u-boot-db88f6281abp_400db_flash_secure.bin

	2. Image for NAND flash. Flash page size is 2K. Secure mode is enabled.
	JTAG support is enabled. Delay boot execution by 10 sec for JTAG probe connection.
	Run custom executable with 2 parameters and DRAM registers configuration
	before running U-boot. Load U-boot into DRAM address 0x600000,
	entry point is 0x670000.

	doimage -T nand -D 0x600000 -E 0x670000 -P 2048 -Z rsa_priv.txt -A aes128.bin \
	-J 1 -B 0xDEADBEEF -F 0xBABE -R dramregs_400db_A.txt -G binhdr.bin -K 2 \
	u-boot-db88f6281abp.bin u-boot-db88f6281abp_400db_nand_secure.bin

	3. Image for UART. Secure mode is disabled.

	doimage -T uart -D 0x600000 -E 0x670000 -R dramregs_400db_A.txt \
	u-boot-db88f6281abp.bin u-boot-db88f6281abp_400db_uart.bin

	4. Image for SATA disk. Secure mode is enabled. JTAG support is enabled.
	Delay boot execution by 10 sec for JTAG probe connection.
	Run custom executable with 2 parameters and DRAM registers configuration
	before running U-boot. Load U-boot into DRAM address 0x600000,
	entry point is 0x670000. U-boot image is located at LBA sector 0x3F.
	Create two images - one for header and one for application.

	doimage -T sata -D 0x600000 -E 0x670000 -S 0x3F -Z rsa_priv.txt -A aes128.bin \
	-J 1 -B 0xDEADBEEF -F 0xBABE -R dramregs_400db_A.txt -G binhdr.bin -K 2 \
	u-boot-db88f6281abp.bin u-boot-db88f6281abp_400db_sata_img_secure.bin \
	u-boot-db88f6281abp_400db_sata_hdr_secure.bin

	In order to copy SATA boot image and header to disk the following technique is used:
	1. Copy the header (first SATA device /dev/sda is uses as example)
	dd if=<header file name> of=/dev/sda seek=1
	2. Copy the boot image (u-boot) to the first partition (starting by default at LBAsector 63)
	dd if=<uboot with checksum> of=/dev/sda1