Secure Bootloader Sample Reference Function Documentation

 

BL_CheckRemapAddressSpace

uint32_t BL_CheckRemapAddressSpace(uint32_t base, uint32_t address)

 

Determine download address based on given address which may be in bootloader or application space.

 

Location: bl_check.h:87

 

Parameters

Direction Name Description

base

The base address of the application being checked.

address

The given address in either bootloader or application space.

 


Return


The adjusted address.

 

BL_CheckGetApplicationSize

uint32_t BL_CheckGetApplicationSize(uint32_t address)

 

Fetch the application size from a buffer defined by base address of the application vector table.

 

Location: bl_check.h:95

 

Parameters

Direction Name Description

address

The address of the base of the vector table.

 


Return


the size derived from the application or zero if invalid.

 

BL_CheckRelocatedApplicationSize

uint32_t BL_CheckRelocatedApplicationSize(uint32_t address)

 

Fetch the application size from a buffer defined by base address of the application vector table.

 

Location: bl_check.h:103

 

Parameters

Direction Name Description

address

The address of the base of the vector table.

 


Return


the size derived from the application or zero if invalid.

 

BL_CheckIfImageUpdateAvailable

BL_UpdateType_t BL_CheckIfImageUpdateAvailable()

 

Check for a valid update using the non-secure file format.

 

When dealing with a non-secure image, the following checks must be made:

 

Location: bl_check.h:116

 

  • The address must be properly aligned and within a sensible range.
  • The stack pointer resides in RAM, is 64 bit aligned, allows 10 words.
  • The reset ISR follows the vector table address The address to check for a valid image. extent The maximum extent of the area holding the image.

    Return


    Type of image update available in download area.

 

BL_CheckIfSecureImageUpdateAvailable

bool BL_CheckIfSecureImageUpdateAvailable()

 

Check for a valid update using the secure file format.

 

When dealing with a secure image, the following checks must be made:

 

Location: bl_check.h:132

 

  • The address must be properly aligned and within a sensible range.
  • The stack pointer resides in RAM, is 64 bit aligned, allows 10 words.
  • The reset ISR follows the vector table.
  • The full certificate chain must be authenticated. updateType The type of update being requested. address The address to check for a valid image. extent The maximum extent of the area holding the image.

    Return


    True if the image has security signature, false otherwise.

 

BL_CheckFindSecondaryImageLocation

void BL_CheckFindSecondaryImageLocation(uint32_t primaryBase, uint32_t primaryExtent, uint32_t * secondaryBase, uint32_t * secondaryExtent)

 

Based on a primary image address, calculate the potential location and extent of any secondary image.

 

Location: bl_check.h:144

 

Parameters

Direction Name Description

primaryBase

The base address of the primary image, used to locate the secondary one.

primaryExtent

The maximum extent of the primary application;

secondaryBase

secondaryExtent

 

BL_ConfigIsValid

BL_ConfigStatus_t BL_ConfigIsValid(BL_AppConfiguration_t * configBase)

 

Helper function to return the configuration area status.

 

Location: bl_configuration.h:85

 

Parameters

Direction Name Description

configBase

Defines the base address of the configuration block.

 


Return


BL_CONFIG_OKAY if the configuration area has a valid CRC, BL_CONFIG_CORRUPT otherwise.

 

BL_ConfigCertificateAddress

uint32_t BL_ConfigCertificateAddress(BL_AppConfiguration_t * configBase, BL_LoaderCertType_t cert)

 

Fetch the address of the requested structure.

 

Location: bl_configuration.h:93

 

Parameters

Direction Name Description

configBase

Defines the base address of the configuration block.

cert

A requested certificate.

 


Return


The address of the requested certificate or zero if invalid request.

 

BL_FCSInitialize

BL_FCSStatus_t BL_FCSInitialize(uint8_t * buffer, size_t length, BL_FCS_t fcs)

 

Initialize the FCS module, deriving the selected algorithm from the provided sample data.

 

Location: bl_fcs.h:86

 

Parameters

Direction Name Description

buffer

A buffer of bytes to be FCS'd.

length

The number of bytes.

fcs

The expected FCS value.

 


Return


BL_FCS_NO_ERROR if the FCS algorithm can be identified. BL_FCS_UNRECOGNIZED if the FCS algorithm cannot be identified.

 

BL_FCSQuery

BL_FCSAlgorithm_t BL_FCSQuery()

 

Query the currently selected FCS algorithm.

 

Location: bl_fcs.h:92

 


Return


The currently selected algorithm.

 

BL_FCSAuthenticationRequired

bool BL_FCSAuthenticationRequired()

 

Provides a mechanism to determine if the loading process should apply authentication to the protocol and images.

 

Location: bl_fcs.h:99

 


Return


True if authentication is required

 

BL_FCSSelect

BL_FCSStatus_t BL_FCSSelect(BL_FCSAlgorithm_t algo)

 

Select a specific FCS algorithm.

 

Location: bl_fcs.h:108

 

Parameters

Direction Name Description

algo

Selected from BL_FCSAlgorithm_t.

 


Return


BL_FCS_NO_ERROR If the algorithm is valid. BL_FCS_UNRECOGNIZED If the algorithm is not valid.

 

BL_FCSCheck

BL_FCSStatus_t BL_FCSCheck(uint8_t * buffer, size_t length, BL_FCS_t fcs)

 

Check the validity of a buffer against a given FCS.

 

Location: bl_fcs.h:119

 

Parameters

Direction Name Description

buffer

A buffer of bytes to calculate a FCS over.

length

The number of bytes.

fcs

The expected FCS value.

 


Return


BL_FCS_VALID if the FCS matches the data. BL_FCS_INVALID if the FCS does not match the data.

 

BL_FCSCalculate

BL_FCSStatus_t BL_FCSCalculate(uint8_t * buffer, size_t length, BL_FCS_t * fcs)

 

Calculate the FCS of a given buffer.

 

Location: bl_fcs.h:130

 

Parameters

Direction Name Description

buffer

A buffer of bytes to calculate a FCS over.

length

The number of bytes.

fcs

The calculated FCS value.

 


Return


BL_FCS_NO_ERROR if the FCS can be calculated. BL_FCS_INVALID if an error is detected when calculating the FCS.

 

BL_FCSAccumulateCRC

uint32_t BL_FCSAccumulateCRC(uint8_t * buffer, size_t length)

 

Helper method to accumulate a CRC given a buffer and a length.

 

Location: bl_fcs.h:141

 

Parameters

Direction Name Description

buffer

A buffer of bytes to calculate a CRC on.

length

The number of bytes.

 

NOTE: This is expected to be used for RAM buffers where the use of the flash copier can't be used. The CRC engine should be initialised prior to calling this function.

 

BL_FlashInitialize

void BL_FlashInitialize()

 

Initialize the flash subsystem.

 

Location: bl_flash.h:55

 

BL_FlashSaveSector

FlashStatus_t BL_FlashSaveSector(uint8_t * address, size_t length, uint8_t * buffer)

 

Save a buffer to a specified flash address.

 

Location: bl_flash.h:67

 

Parameters

Direction Name Description

address

The address in flash to save the buffer.

length

The number of bytes to save.

buffer

A pointer to a buffer of data to be written.

 


Return


FLASH_ERR_NONE if the operation is successful otherwise an error code the flash library.

 

NOTE: The start address is expected to start on a sector boundary.

 

BL_ImageInitialize

BL_ImageType_t BL_ImageInitialize(uint8_t * address, size_t length, uint32_t crc)

 

Initialize the image module for a specific set of image attributes.

 

Location: bl_image.h:98

 

Parameters

Direction Name Description

address

The base address of the image being loaded.

length

The length of the image in bytes.

crc

the crc of the image being loaded.

 


Return


The type of image recognized.

 

BL_ImageAddress

uint32_t BL_ImageAddress(uint32_t address)

 

Convert an address to take into account potential offsets.

 

Location: bl_image.h:107

 

Parameters

Direction Name Description

address

The address in an image.

 


Return


The converted address.

 

BL_ImageAddressRange

void BL_ImageAddressRange(uint8_t * address, size_t length, BL_ImageSplitRange_t * range)

 

Helper routine which allows access of the image as a contiguous block of addresses, wrapping around the reserved block.

 

Location: bl_image.h:118

 

Parameters

Direction Name Description

address

An address within an image that may need to be adjusted.

length

the length of the address range.

range

A split range object that indicates where the address range needs to be split.

 

BL_ImageCopyMemoryRange

void BL_ImageCopyMemoryRange(uint8_t * dst, BL_ImageSplitRange_t * range)

 

Copy a possibly split memory range to a contiguous buffer.

 

Location: bl_image.h:127

 

Parameters

Direction Name Description

dst

The destination buffer.

range

The range defining the source locations.

 

BL_ImageSaveBlock

BL_ImageStatus_t BL_ImageSaveBlock(BL_ImageOperation_t * operation)

 

Save a block of data from a RAM buffer to the next block in Flash.

 

Location: bl_image.h:135

 

Parameters

Direction Name Description

operation

Defines the address and length of the block to be saved.

 


Return


Status code indicating if the save operation failed

 

BL_ImageVerify

BL_ImageStatus_t BL_ImageVerify()

 

Verify the most recently loaded image.

 

Location: bl_image.h:144

 


Return


BL_IMAGE_NO_ERROR If the CRC matches the data. BL_IMAGE_VERIFY_ERROR If the CRC does not match the data.

 

BL_ImageAuthenticate

BL_ImageStatus_t BL_ImageAuthenticate(BL_ImageType_t imageType, uint32_t * address, size_t length, bool verifyImages)

 

Authenticate a loaded image.

 

Location: bl_image.h:157

 

Parameters

Direction Name Description

imageType

The type of the image being authenticated.

address

The base address of the image to be authenticated.

length

The size of the area in bytes.

verifyImages

Flag indicating that the s/w images must be validated.

 


Return


BL_IMAGE_NO_ERROR If the CRC matches the data. BL_IMAGE_AUTHENTICATE_ERROR If the authentication fails.

 

BL_ImageAuthenticateCurrent

BL_ImageStatus_t BL_ImageAuthenticateCurrent()

 

Authenticate the most recently loaded image.

 

Location: bl_image.h:167

 


Return


BL_IMAGE_NO_ERROR If the CRC matches the data. BL_IMAGE_AUTHENTICATE_ERROR If the authentication fails.

 

BL_ImageIsValid

bool BL_ImageIsValid(uint32_t address, size_t length)

 

Check if there is a valid image to start.

 

Location: bl_image.h:176

 

Parameters

Direction Name Description

address

The address of the image in flash.

length

The length of the image in bytes.

 


Return


True if there is a valid application to start. False otherwise.

 

BL_ImageSaveAddress

uint32_t BL_ImageSaveAddress(BL_ImageType_t imageType, uint32_t address)

 

Return the download address corresponding to the requested address.

 

Location: bl_image.h:185

 

Parameters

Direction Name Description

imageType

The type of the image being authenticated.

address

The requested address

 


Return


The download address

 

BL_ImageStartApplication

void BL_ImageStartApplication(uint32_t imageBaseAddress)

 

Start the image stored in flash.

 

Location: bl_image.h:192

 

Parameters

Direction Name Description

imageBaseAddress

The base address of the image to be started

 

BL_LoaderPerformFirmwareLoad

void BL_LoaderPerformFirmwareLoad()

 

Perform a firmware update over the UART interface.

 

Location: bl_loader.h:147

 

BL_LoaderCertificateAddress

uint32_t BL_LoaderCertificateAddress(BL_LoaderCertType_t cert)

 

Fetch the address of the requested structure.

 

Location: bl_loader.h:154

 

Parameters

Direction Name Description

cert

A requested certificate.

 


Return


The address of the requested certificate or zero if invalid request.

 

BL_RecoveryInitialize

void BL_RecoveryInitialize()

 

Define the initialization routine for the Debug Catch feature.

 

Location: bl_recovery.h:57

 

BL_TargetInitialize

void BL_TargetInitialize()

 

Target initialization function, loads the trim values and sets up the various clocks used in the system.

 

Location: bl_target.h:77

 

BL_TargetReset

void BL_TargetReset()

 

Reset the device using NVIC.

 

Location: bl_target.h:82

 

BL_TickerInitialize

void BL_TickerInitialize()

 

Initialize the timer tick.

 

Location: bl_ticker.h:58

 

BL_TickerTime

uint32_t BL_TickerTime()

 

Get the current timer tick value.

 

Location: bl_ticker.h:64

 


Return


The time since the ticker was initialized in ms.

 

SysTick_Handler

void SysTick_Handler()

 

System tick interrupt handler, required by the ticker.

 

Location: bl_ticker.h:69

 

BL_TraceInitialize

void BL_TraceInitialize()

 

Initialize the trace sub-system.

 

Location: bl_trace.h:70

 

BL_UARTInitialize

void BL_UARTInitialize()

 

Initialize the UART subsystem.

 

Location: bl_uart.h:102

 

BL_UARTReceiveAsync

BL_UARTStatus_t BL_UARTReceiveAsync(uint8_t * buffer, size_t length)

 

Start receiving a fixed length data buffer using the UART.

 

Location: bl_uart.h:119

 

Parameters

Direction Name Description

buffer

A pointer to a buffer in which to store the incoming data.

length

The number of bytes to store in the buffer. (> 0)

 


Return


BL_UART_NO_ERROR if the operation is started successfully. BL_UART_INVALID_PARAMETER if the length is zero. BL_UART_RX_BUSY if another receive operation is currently active.

 

NOTE: No checking is performed to ensure that the buffer is big enough to hold the requested number of bytes. The calling function must ensure this is valid.

NOTE: There must be no pending receive operation pending when this is invoked.

 

BL_UARTReceiveComplete

BL_UARTStatus_t BL_UARTReceiveComplete(uint8_t * buffer, size_t length, BL_FCS_t * fcs)

 

Complete the reception of an executing receive operation.

 

Location: bl_uart.h:137

 

Parameters

Direction Name Description

buffer

A pointer to a buffer in which to store the incoming data.

length

The number of bytes to store in the buffer. (> 0)

fcs

Indicating if a FCS should be calculated on the input. NULL indicates no FCS calculation needed.

 


Return


BL_UART_NO_ERROR if the operation completes successfully. BL_UART_RX_IDLE if there is no pending receive operation. BL_UART_RX_TIMEOUT if the receive operation timed out. BL_UART_BAD_FCS if the receive operation had an invalid FCS.

 

NOTE: There must be an existing receive operation pending.

NOTE: This is a blocking operation.

 

BL_UARTReceive

BL_UARTStatus_t BL_UARTReceive(uint8_t * buffer, size_t length, BL_FCS_t * fcs)

 

Receiving a fixed length data buffer using the UART.

 

Location: bl_uart.h:161

 

Parameters

Direction Name Description

buffer

A pointer to a buffer in which to store the incoming data.

length

The number of bytes to store in the buffer. (> 0)

fcs

Indicating if a FCS should be calculated on the input. NULL indicates no FCS calculation needed.

 


Return


BL_UART_NO_ERROR if the operation is started successfully. BL_UART_INVALID_PARAMETER if the length is zero. BL_UART_RX_BUSY if another receive operation is currently active. BL_UART_RX_TIMEOUT if the receive operation timed out. BL_UART_BAD_FCS if the receive operation had an invalid FCS.

 

NOTE: No checking is performed to ensure that the buffer is big enough to hold the requested number of bytes. The calling function must ensure this is valid.

NOTE: There must be no pending receive operation pending when this is invoked.

NOTE: This is a blocking operation.

 

BL_UARTSendAsync

BL_UARTStatus_t BL_UARTSendAsync(uint8_t * buffer, size_t length, BL_FCS_t * fcs)

 

Start sending a fixed length data buffer using the UART.

 

Location: bl_uart.h:175

 

Parameters

Direction Name Description

buffer

A pointer to a buffer holding the outgoing data.

length

The number of bytes to send. (> 0)

fcs

The FCS of the buffer to accompany the transmission.

 


Return


BL_UART_NO_ERROR if the operation is started successfully. BL_UART_INVALID_PARAMETER if the length is zero. BL_UART_TX_BUSY if another send operation is currently active.

 

NOTE: There must be no pending transmit operation pending when this is invoked.

 

BL_UARTSendComplete

BL_UARTStatus_t BL_UARTSendComplete()

 

Complete the transmission of an executing send operation.

 

Location: bl_uart.h:188

 


Return


BL_UART_NO_ERROR if the operation completes successfully. BL_UART_TX_IDLE if there is no pending receive operation. BL_UART_TX_TIMEOUT if the send operation timed out.

 

NOTE: There must be an existing transmit operation pending.

NOTE: This is a blocking operation.

 

BL_UARTSend

BL_UARTStatus_t BL_UARTSend(uint8_t * buffer, size_t length, BL_FCS_t * fcs)

 

Send a fixed length data buffer using the UART.

 

Location: bl_uart.h:205

 

Parameters

Direction Name Description

buffer

A pointer to a buffer holding the outgoing data.

length

The number of bytes to send. (> 0)

fcs

The FCS of the buffer to accompany the transmission.

 


Return


BL_UART_NO_ERROR if the operation is started successfully. BL_UART_INVALID_PARAMETER if the length is zero. BL_UART_TX_BUSY if another send operation is currently active. BL_UART_TX_TIMEOUT if the send operation timed out.

 

NOTE: There must be no pending transmit operation pending when this is invoked.

NOTE: This is a blocking operation.

 

BL_UpdateInitialize

void BL_UpdateInitialize()

 

Initialize the firmware update component.

 

Location: bl_update.h:60

 

BL_UpdateRequested

bool BL_UpdateRequested()

 

Check if a firmware update is being requested.

 

Location: bl_update.h:66

 


Return


True if the update pin has been pulled low. False otherwise.

 

BL_UpdateProcessPendingImages

void BL_UpdateProcessPendingImages()

 

This will check for any pending images which have previously been downloaded and if any are found will copy them to the appropriate location for execution.

 

Location: bl_update.h:73

 

BL_ImageSelectAndStartApplication

void BL_ImageSelectAndStartApplication()

 

This will attempt to start any images which are available.

 

This will first try to validate and if necessary authenticate the primary image. If this is successful it will then perform similar validation and authentication on the secondary image. If both the primary and secondary image validation is successful then it will start the secondary image. If only the primary image is valid then it will be started instead. If both the primary and secondary image fail the validation steps then no image will be started and the function will return to the caller and the bootloader will enter the loading state.

 

Location: bl_update.h:90

 

BL_VersionsGetInformation

void BL_VersionsGetInformation(BL_BootAppVersion_t * version, uint32_t address)

 

Get the version information from a suitable application.

 

Location: bl_versions.h:101

 

Parameters

Direction Name Description

version

The structure into which the information should be copied.

address

The base address of the application under consideration.

 

BL_VersionsGetHello

void BL_VersionsGetHello(BL_HelloResponse_t * response)

 

Fetch the hello response from the bootloader.

 

Location: bl_versions.h:108

 

Parameters

Direction Name Description

response

The structure into which the hello response should be copied.

 

BL_WatchdogInitialize

void BL_WatchdogInitialize()

 

Initialise the watchdog module.

 

Location: bl_watchdog.h:64

 

BL_WatchdogSetHoldTime

void BL_WatchdogSetHoldTime(uint32_t seconds)

 

Set the watchdog hold off time to seconds.

 

Location: bl_watchdog.h:76

 

Parameters

Direction Name Description

seconds

The number of seconds to allow before the watchdog bites.

 

NOTE: This allows the watchdog interrupt to fire but refreshes the watchdog itself until the requested number of seconds has elapsed. This is a crude mechanism to prevent long running calculations such as RSA key generation from causing a system reset.

 

WATCHDOG_IRQHandler

void WATCHDOG_IRQHandler()

 

Define an interrupt handler for the watchdog interrupt.

 

Location: bl_watchdog.h:82