SB Loader

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:
[legend]

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