SB file loader state machine. More...

Collaboration diagram for SB Loader:

Modules
	SB File Format
	SB file format definitions.

Data Structures
struct	boot_cmd_t
	Boot command definition. More...

struct	boot_hdr1_t
	Definition for boot image file header chunk 1. More...

struct	boot_hdr2_t
	Definition for boot image file header chunk 2. More...

struct	ldr_Context_t
	Loader context definition. More...

struct	ldr_buf_t

Typedefs
typedef uint8_t	chunk_t[BYTES_PER_CHUNK]

typedef status_t(*	pLdrFnc_t) (ldr_Context_t *)
	Function pointer definition for all loader action functions.

typedef status_t(*	pJumpFnc_t) (uint32_t)
	Jump command function pointer definition.

typedef status_t(*	pCallFnc_t) (uint32_t, uint32_t *)
	Call command function pointer definition.

Enumerations
enum	_sbloader_status { kStatusRomLdrSectionOverrun = MAKE_STATUS(kStatusGroup_SBLoader, 0), kStatusRomLdrSignature = MAKE_STATUS(kStatusGroup_SBLoader, 1), kStatusRomLdrSectionLength = MAKE_STATUS(kStatusGroup_SBLoader, 2), kStatusRomLdrUnencryptedOnly = MAKE_STATUS(kStatusGroup_SBLoader, 3), kStatusRomLdrEOFReached = MAKE_STATUS(kStatusGroup_SBLoader, 4), kStatusRomLdrChecksum = MAKE_STATUS(kStatusGroup_SBLoader, 5), kStatusRomLdrCrc32Error = MAKE_STATUS(kStatusGroup_SBLoader, 6), kStatusRomLdrUnknownCommand = MAKE_STATUS(kStatusGroup_SBLoader, 7), kStatusRomLdrIdNotFound = MAKE_STATUS(kStatusGroup_SBLoader, 8), kStatusRomLdrDataUnderrun = MAKE_STATUS(kStatusGroup_SBLoader, 9), kStatusRomLdrJumpReturned = MAKE_STATUS(kStatusGroup_SBLoader, 10), kStatusRomLdrCallFailed = MAKE_STATUS(kStatusGroup_SBLoader, 11), kStatusRomLdrKeyNotFound = MAKE_STATUS(kStatusGroup_SBLoader, 12), kStatusRomLdrSecureOnly = MAKE_STATUS(kStatusGroup_SBLoader, 13), kStatusRomLdrResetReturned = MAKE_STATUS(kStatusGroup_SBLoader, 14) }
	SB loader status codes.

enum	_ldr_memory_space { kLdrMemorySpace_Internal, kLdrMemorySpace_eMMC0, kLdrMemorySpace_SD0, kLdrMemorySpace_SDRAM0, kLdrMemorySpace_IFR0, kLdrMemorySpace_eFuse0, kLdrMemorySpace_OTP0 }
	Memory Space constants.

enum	_ldr_memory_ctrl { kLdrMemoryCtrl_InternalFlash, kLdrMemoryCtrl_QSPI0, kLdrMemoryCtrl_PNOR0 }
	Memory Controller constants.

Functions
status_t	sbloader_init (void)
	Initialize the loader state machine.

status_t	sbloader_pump (uint8_t *data, uint32_t length)
	Pump the loader state machine.

status_t	sbloader_finalize ()
	Implement jump or reset command.

status_t	ldr_GoToNextSection (ldr_Context_t *)
	Loader utilities. More...

status_t	sbloader_handle_chunk (void)
	Handles the chunk in the s_loaderBuf.

status_t	ldr_DoHeader (ldr_Context_t *)
	Loader action (context.Action) functions for header processing. More...

status_t	ldr_DoHeader1 (ldr_Context_t *context)
	Loader action function processes header chunk 1. More...

status_t	ldr_DoHeader2 (ldr_Context_t *context)
	Loader action function processes header chunk 2. More...

status_t	ldr_DoHeaderMac (ldr_Context_t *context)
	Loader action function finishes CBC-MAC over final header chunks. More...

status_t	ldr_DoKeyTest (ldr_Context_t *context)
	Loader action function tests for a key dictionary match. More...

status_t	ldr_DoGetDek (ldr_Context_t *context)
	Loader action function processes a key dictionary match. More...

status_t	ldr_DoInit (ldr_Context_t *)
	Loader action (context.Action) functions for command processing.

status_t	ldr_DoCommand (ldr_Context_t *context)
	Loader boot command parsing function. More...

status_t	ldr_DoLoadBytes (ldr_Context_t *context)
	Loader action function loads the trailing "ragged edge bytes". More...

status_t	ldr_DoLoadChunks (ldr_Context_t *context)
	Loader action function loads data chunks. More...

status_t	ldr_DoLoadCmd (ldr_Context_t *context)
	Loader "load" command handler. More...

status_t	ldr_DoFillCmd (ldr_Context_t *context)
	Loader "fill" command handler. More...

status_t	ldr_DoJumpCmd (ldr_Context_t *context)
	Loader "jump" command handler. More...

status_t	ldr_DoCallCmd (ldr_Context_t *context)
	Loader "call" command handler. More...

status_t	ldr_DoTagCmd (ldr_Context_t *context)
	Loader "tag" command handler. More...

status_t	ldr_DoEraseCmd (ldr_Context_t *context)
	Loader "erase" command handler. More...

status_t	ldr_DoResetCmd (ldr_Context_t *context)
	Loader "reset" command handler. More...

status_t	ldr_DoMemEnableCmd (ldr_Context_t *context)
	Loader "memory enable" command handler. More...

status_t	ldr_DoProgramCmd (ldr_Context_t *context)
	Loader "program" command handler. More...

Variables
static ldr_Context_t	s_loaderContext
	static loader context data.

static ldr_buf_t	s_loaderBuf
	static buffer queueing up a chunk worth of data

static uint32_t	s_aesKey [AES_128_KEY_SIZE_WORDS]

Usage Information

SB file loader state machine.

Data Structure Documentation

struct boot_cmd_t

Boot command definition.

Data Fields
uint32_t	address	address argument
uint8_t	checksum	8-bit checksum over command chunk
uint32_t	count	count argument
uint32_t	data	data argument
uint16_t	flags	command flags (modifier)
uint8_t	tag	command tag (identifier)

struct boot_hdr1_t

Definition for boot image file header chunk 1.

Data Fields
uint32_t	fileChunks	total chunks in the file
uint16_t	fileFlags	global file flags
uint32_t	hash	last 32-bits of SHA-1 hash
uint8_t	major	major file format version
uint8_t	minor	minor file format version
uint32_t	signature	must equal "STMP"

struct boot_hdr2_t

Definition for boot image file header chunk 2.

Data Fields
uint32_t	bootOffset	chunk offset to the first boot section
uint32_t	bootSectID	section ID of the first boot section
uint16_t	hdrChunks	number of chunks in the header
uint16_t	keyCount	number of keys in the key dictionary
uint16_t	keyOffset	chunk offset to the key dictionary
uint16_t	sectCount	number of sections in the image

struct _ldr_Context

Loader context definition.

Collaboration diagram for ldr_Context_t:

Data Fields
pLdrFnc_t	Action
boot_cmd_t	bootCmd
uint32_t	bootSectChunks
crc32_data_t	crc32
chunk_t	dek
uint32_t	fileChunks
uint16_t	fileFlags
chunk_t	initVector
uint16_t	keyCount
uint32_t	objectID
uint32_t	receivedChunks
chunk_t	scratchPad
uint32_t	sectChunks
uint32_t	skipCount
bool	skipToEnd
uint8_t *	src

struct _ldr_buf

Data Fields
chunk_t	data
uint32_t	fillPosition

Function Documentation

status_t ldr_DoCallCmd ( ldr_Context_t * context )

Loader "call" command handler.

Implements the action function for the boot "call" command.

Parameters

[in] context Pointer to a loader context structure.

Precondition: context->bootCmd contains the boot command.

Postcondition: *context is setup to get the next boot command.; context->objectID is set to the next boot section or image ID.

Returns: Return code from plugin or ldr_GoToNextSection.

status_t ldr_DoCommand ( ldr_Context_t * context )

Loader boot command parsing function.

Implements the action function for parsing a boot command. Performs generic integrity tests and flag handling, then calls the appropriate command handler function based on the command tag.

Parameters

[in] context Pointer to a loader context structure.

Precondition: context->bootCmd contains the boot command.

Return values

kStatusRomLdrChecksum	if command checksum failed.
kStatusRomLdrUnknownCommand	if command tag is not recognized.
Return	code from the boot command handler function.

status_t ldr_DoEraseCmd ( ldr_Context_t * context )

Loader "erase" command handler.

Implements the action function for the boot "erase" command.

Parameters

[in] context Pointer to a loader context structure.

Precondition: context->bootCmd contains the boot command.

Postcondition: *context is setup to get the next boot command.; context->sectChunks is updated to the next section.

Return values

kStatus_Success
kStatus_InvalidArgument

status_t ldr_DoFillCmd ( ldr_Context_t * context )

Loader "fill" command handler.

Implements the action function for the boot "fill" command.

Parameters

[in] context Pointer to a loader context structure.

Precondition: context->bootCmd contains the boot command.

Postcondition: *context is left setup to get the next boot command.

Return values

kStatus_Success

status_t ldr_DoGetDek ( ldr_Context_t * context )

Loader action function processes a key dictionary match.

This loader action function is one of three functions used to parse the key dictionary. It is called after a match of the CBC-MAC is found and the session key (DEK) is decrypted. It saves the DEK in the boot context and then skips to the first boot command in the image. This function will only get called if CBC_MAC is supported

Parameters

[in] context Pointer to a loader context structure.

Precondition: context->src points to the the encrypted session key.; context->initVector contains the SHA-1 chunk from the header

Postcondition: *context is setup to decrypt the first boot command.; The session key is decrypted and stored in the context dek field

Returns: Return value from ldr_GoToNextSection().

status_t ldr_DoHeader ( ldr_Context_t * context )

Loader action (context.Action) functions for header processing.

Loader action function processes the first header chunk.

Processes the first header chunk of the boot image file, which saves the SHA-1 to the context initVector field, the CBC-MAC process is started here to handle the DEK if one is found

Parameters

[in] context Pointer to a loader context structure.

Precondition: context->src points at the current header chunk.

Postcondition: context->Action is set to process the next header chunk.

Return values

SUCCESS

status_t ldr_DoHeader1 ( ldr_Context_t * context )

Loader action function processes header chunk 1.

Processes the second header chunk of the boot image file, which contains the file signature, version, flags and chunk count.

Parameters

[in] context Pointer to a loader context structure.

Precondition: context->src points at the current header chunk.

Postcondition: context->Action is set to process the next header chunk.; context->fileChunks and fileFlags are set to the header values.

Return values

kStatus_Success
kStatusRomLdrSignature	if the signature or version are incorrect.

status_t ldr_DoHeader2 ( ldr_Context_t * context )

Loader action function processes header chunk 2.

Processes the third header chunk of the boot image file, which contains parameters for the first boot section and the key dictionary.

Parameters

[in] context Pointer to a loader context structure.

Precondition: context->src points at the current header chunk.

Postcondition: context->Action is set to process the next header chunk.; context->sectChunks, objectID and keyCount are set to the header values.

Return values

kStatus_Success
kStatusRomLdrSectionLength	if the bootOffset is out of range.
kStatusRomLdrUnencryptedOnly	if the unencrypted image is disabled.

status_t ldr_DoHeaderMac ( ldr_Context_t * context )

Loader action function finishes CBC-MAC over final header chunks.

Completes the CBC-MAC calculation over the remaining plaintext header. This function will only get called if CBC_MAC is supported

Parameters

[in] context Pointer to a loader context structure.

Precondition: context->src points at the current header chunk.; context->bootCmd.count = number of chunks left in plaintext header.

Postcondition: context->scratchPad contains the computed CBC-MAC.; context->bootCmd.count is updated.

Return values

SUCCESS

status_t ldr_DoJumpCmd ( ldr_Context_t * context )

Loader "jump" command handler.

Implements the action function for the boot "jump" command.

Parameters

[in] context Pointer to a loader context structure.

Precondition: context->bootCmd contains the boot command.

Return values

kStatusRomLdrJumpReturned if the plugin returns

status_t ldr_DoKeyTest ( ldr_Context_t * context )

Loader action function tests for a key dictionary match.

This loader action function is one of three functions used to parse the key dictionary. It is called after a CBC-MAC entry from the dictionary has been read. If the value read is equal to the computed CBC-MAC, then the next encrypted chunk holds the session key (DEK), and the next action function will decrypt the key. Otherwise if there are remaining entries in the dictionary, the next action will get the next CBC-MAC to test.

Parameters

[in] context Pointer to a loader context structure.

Precondition: context->dek holds the CBC-MAC computed over the header.; context->src holds a CBC-MAC value from the dictionary.

Postcondition: if CBC-MAC matches we transition to decrypt the DEK; context->keyCount is updated to the remaining number of keys to test.

Return values

SUCCESS
ERROR_ROM_LDR_KEY_NOT_FOUND	if there are no more entries in the dictionary and a CBC-MAC match was not found.

status_t ldr_DoLoadBytes ( ldr_Context_t * context )

Loader action function loads the trailing "ragged edge bytes".

Implements the second of two action functions for the boot "load" command. The last move sequence for the load command moves the final payload chunk. This function checks the payload CRC, then copies the final load bytes to the load destination.

Parameters

[in] context Pointer to a loader context structure.

Precondition: context->bootCmd contains the boot command.; context->src contains the final decrypted payload chunk.; context->crc32 holds the CRC calculated over the entire payload.

Postcondition: *context is setup to get the next boot command.

status_t ldr_DoLoadChunks ( ldr_Context_t * context )

Loader action function loads data chunks.

Implements the first of two action functions for the boot "load" command. Loads one or more complete "chunk size" blocks of data.

If the amount of data remaining to load is one chunk or less, it sets the state sequence to move the next chunk. The action function is changed to ldr_DoLoadBytes, which will check the payload CRC and copy to the correct location.

Parameters

[in] context Pointer to a loader context structure.

Precondition: context->bootCmd contains the boot command.

Postcondition: context->bootCmd is adjusted to reflect the previous move.; context->Action is set to move the next received payload.

Return values

kStatus_Success

status_t ldr_DoLoadCmd ( ldr_Context_t * context )

Loader "load" command handler.

Implements the first command handler called for the boot "load" command. The load action is split into two functions:

ldr_DoLoadChunks, loads chunks
ldr_DoLoadBytes, loads the trailing "ragged edge bytes" This function initializes the context before calling load action.

Parameters

[in] context Pointer to a loader context structure.

status_t ldr_DoMemEnableCmd ( ldr_Context_t * context )

Loader "memory enable" command handler.

Implements the action function for the boot "memory enable" command.

Parameters

[in] context Pointer to a loader context structure.

Precondition: context->bootCmd contains the boot command.

Postcondition: *context is setup to get the next boot command.; context->sectChunks is updated to the next section.

Return values

kStatus_Success
kStatus_InvalidArgument

status_t ldr_DoProgramCmd ( ldr_Context_t * context )

Loader "program" command handler.

Implements the action function for the boot "program" command.

Parameters

[in] context Pointer to a loader context structure.

Precondition: context->bootCmd contains the boot command.

Postcondition: *context is left setup to get the next boot command.

Return values

kStatus_Success

status_t ldr_DoResetCmd ( ldr_Context_t * context )

Loader "reset" command handler.

Implements the action function for the boot "reset" command.

Parameters

[in] context Pointer to a loader context structure.

Precondition: context->bootCmd contains the boot command.

Postcondition: *context is setup to get the next boot command.; context->sectChunks is updated to the next section.

Return values

kStatus_Success

status_t ldr_DoTagCmd ( ldr_Context_t * context )

Loader "tag" command handler.

Implements the action function for the boot "tag" command.

Parameters

[in] context Pointer to a loader context structure.

Precondition: context->bootCmd contains the boot command.

Postcondition: *context is setup to get the next boot command.; context->sectChunks is updated to the next section.

Return values

kStatusRomLdrSectionLength	if new section count is out of range.
kStatusRomLdrIdNotFound	if no match and no more sections.
Return	code from ldr_GoToNextSection.

status_t ldr_GoToNextSection ( ldr_Context_t * context )

Loader utilities.

Skip ahead to the next "tag" command.

function will set up the skipCount to skip over the remainder of any section you are currently in. If encryption is enabled it will also re-init the encryption to begin on the new section it arrives at.

Return values

kStatus_Success
kStatusRomLdrEOFReached	if the end of the image file is reached.

Variable Documentation

uint32_t s_aesKey[AES_128_KEY_SIZE_WORDS]

static

Pointer for the aes which will for now be a null pointer unless in debug mode we will try to read from the config area

Modules

Data Structures

Typedefs

Enumerations

Functions

Variables

Usage Information

Data Structure Documentation

Function Documentation

Variable Documentation