doc/README.ti-secure

README on how boot images are created for secure TI devices

CONFIG_TI_SECURE_DEVICE:
Secure TI devices require a boot image that is authenticated by ROM
code to function. Without this, even JTAG remains locked and the
device is essentially useless. In order to create a valid boot image for
a secure device from TI, the initial public software image must be signed
and combined with various headers, certificates, and other binary images.

Information on the details on the complete boot image format can be obtained
from Texas Instruments. The tools used to generate boot images for secure
devices are part of a secure development package (SECDEV) that can be
downloaded from:

	http://www.ti.com/mysecuresoftware (login required)

The secure development package is access controlled due to NDA and export
control restrictions. Access must be requested and granted by TI before the
package is viewable and downloadable. Contact TI, either online or by way
of a local TI representative, to request access.

When CONFIG_TI_SECURE_DEVICE is set, the U-Boot SPL build process requires
the presence and use of these tools in order to create a viable boot image.
The build process will look for the environment variable TI_SECURE_DEV_PKG,
which should be the path of the installed SECDEV package. If the
TI_SECURE_DEV_PKG variable is not defined or if it is defined but doesn't
point to a valid SECDEV package, a warning is issued during the build to
indicate that a final secure bootable image was not created.

Within the SECDEV package exists an image creation script:

${TI_SECURE_DEV_PKG}/scripts/create-boot-image.sh

This is called as part of the SPL/u-boot build process. As the secure boot
image formats and requirements differ between secure SOC from TI, the
purpose of this script is to abstract these details as much as possible.

The script is basically the only required interface to the TI SECDEV package
for secure TI devices.

Invoking the script for AM43xx Secure Devices
=============================================

create-boot-image.sh <IMAGE_FLAG> <INPUT_FILE> <OUTPUT_FILE> <SPL_LOAD_ADDR>

<IMAGE_FLAG> is a value that specifies the type of the image to generate OR
the action the image generation tool will take. Valid values are:
	SPI_X-LOADER - Generates an image for SPI flash (byte swapped)
	XIP_X-LOADER - Generates a single stage u-boot for NOR/QSPI XiP
	ISSW - Generates an image for all other boot modes

<INPUT_FILE> is the full path and filename of the public world boot loader
binary file (depending on the boot media, this is usually either
u-boot-spl.bin or u-boot.bin).

<OUTPUT_FILE> is the full path and filename of the final secure image. The
output binary images should be used in place of the standard non-secure
binary images (see the platform-specific user's guides and releases notes
for how the non-secure images are typically used)
	u-boot-spl_HS_SPI_X-LOADER - byte swapped boot image for SPI flash
	u-boot_HS_XIP_X-LOADER - boot image for NOR or QSPI flash
	u-boot-spl_HS_ISSW - boot image for all other boot media

<SPL_LOAD_ADDR> is the address at which SOC ROM should load the <INPUT_FILE>

Invoking the script for DRA7xx/AM57xx Secure Devices
====================================================

create-boot-image.sh <IMAGE_TYPE> <INPUT_FILE> <OUTPUT_FILE>

<IMAGE_TYPE> is a value that specifies the type of the image to generate OR
the action the image generation tool will take. Valid values are:
	X-LOADER - Generates an image for NOR or QSPI boot modes
	MLO - Generates an image for SD/MMC/eMMC boot modes
	ULO - Generates an image for USB/UART peripheral boot modes
	Note: ULO is not yet used by the u-boot build process

<INPUT_FILE> is the full path and filename of the public world boot loader
binary file (for this platform, this is always u-boot-spl.bin).

<OUTPUT_FILE> is the full path and filename of the final secure image. The
output binary images should be used in place of the standard non-secure
binary images (see the platform-specific user's guides and releases notes
for how the non-secure images are typically used)
	u-boot-spl_HS_MLO - boot image for SD/MMC/eMMC. This image is
		copied to a file named MLO, which is the name that
		the device ROM bootloader requires for loading from
		the FAT partition of an SD card (same as on
		non-secure devices)
	u-boot-spl_HS_X-LOADER - boot image for all other flash memories
		including QSPI and NOR flash