Secure Bootloader Sample Reference Function Documentation

BL_CheckRemapAddressSpace

uint32_t BL_CheckRemapAddressSpace(uint32_t base, uint32_t address)

Location: bl_check.h:87

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

Returns:

The adjusted address.

Parameters

Direction	Name	Description
	base	The base address of the application being checked.
	address	The given address in either bootloader or application space.

BL_CheckGetApplicationSize

uint32_t BL_CheckGetApplicationSize(uint32_t address)

Location: bl_check.h:95

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

Returns:

the size derived from the application or zero if invalid.

Parameters

Direction	Name	Description
	address	The address of the base of the vector table.

BL_CheckRelocatedApplicationSize

uint32_t BL_CheckRelocatedApplicationSize(uint32_t address)

Location: bl_check.h:103

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

Returns:

the size derived from the application or zero if invalid.

Parameters

Direction	Name	Description
	address	The address of the base of the vector table.

BL_CheckIfImageUpdateAvailable

BL_UpdateType_t BL_CheckIfImageUpdateAvailable()

Location: bl_check.h:116

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

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

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.
Returns:
Type of image update available in download area.

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.
Returns:
Type of image update available in download area.

BL_CheckIfSecureImageUpdateAvailable

bool BL_CheckIfSecureImageUpdateAvailable()

Location: bl_check.h:132

Check for a valid update using the secure file format.

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

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.
Returns:
True if the image has security signature, false otherwise.

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.
Returns:
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)

Location: bl_check.h:144

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

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)

Location: bl_configuration.h:85

Helper function to return the configuration area status.

Returns:

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

Parameters

Direction	Name	Description
	configBase	Defines the base address of the configuration block.

BL_AdjustConfigAddress

uint32_t * BL_AdjustConfigAddress(uint32_t imageAddress, uint32_t imageSize)

Location: bl_configuration.h:93

Used to get the address for the image config block.

Returns:

the address for the config block

Parameters

Direction	Name	Description
	imageAddress	The start address of the image you are getting the config block for.
	imageSize	The size of the whole image including its certificates

BL_ConfigCertificateAddress

uint32_t BL_ConfigCertificateAddress(BL_AppConfiguration_t * configBase, BL_LoaderCertType_t cert)

Location: bl_configuration.h:101

Fetch the address of the requested structure.

Returns:

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

Parameters

Direction	Name	Description
	configBase	Defines the base address of the configuration block.
	cert	A requested certificate.

BL_FCSInitialize

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

Location: bl_fcs.h:86

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

Returns:

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

Parameters

Direction	Name	Description
	buffer	A buffer of bytes to be FCS'd.
	length	The number of bytes.
	fcs	The expected FCS value.

BL_FCSQuery

BL_FCSAlgorithm_t BL_FCSQuery()

Location: bl_fcs.h:92

Query the currently selected FCS algorithm.

Returns:

The currently selected algorithm.

BL_FCSAuthenticationRequired

bool BL_FCSAuthenticationRequired()

Location: bl_fcs.h:99

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

Returns:

True if authentication is required

BL_FCSSelect

BL_FCSStatus_t BL_FCSSelect(BL_FCSAlgorithm_t algo)

Location: bl_fcs.h:108

Select a specific FCS algorithm.

Returns:

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

Parameters

Direction	Name	Description
	algo	Selected from BL_FCSAlgorithm_t.

BL_FCSCheck

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

Location: bl_fcs.h:119

Check the validity of a buffer against a given FCS.

Returns:

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

Parameters

Direction	Name	Description
	buffer	A buffer of bytes to calculate a FCS over.
	length	The number of bytes.
	fcs	The expected FCS value.

BL_FCSCalculate

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

Location: bl_fcs.h:130

Calculate the FCS of a given buffer.

Returns:

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

Parameters

Direction	Name	Description
	buffer	A buffer of bytes to calculate a FCS over.
	length	The number of bytes.
	fcs	The calculated FCS value.

BL_FCSAccumulateCRC

uint32_t BL_FCSAccumulateCRC(uint8_t * buffer, size_t length)

Location: bl_fcs.h:141

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

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.

Parameters

Direction	Name	Description
	buffer	A buffer of bytes to calculate a CRC on.
	length	The number of bytes.

BL_FlashInitialize

void BL_FlashInitialize()

Location: bl_flash.h:55

Initialize the flash subsystem.

BL_FlashSaveSector

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

Location: bl_flash.h:67

Save a buffer to a specified flash address.

Returns:

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.

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.

BL_ImageInitialize

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

Location: bl_image.h:98

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

Returns:

The type of image recognized.

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.

BL_ImageAddress

uint32_t BL_ImageAddress(uint32_t address)

Location: bl_image.h:107

Convert an address to take into account potential offsets.

Returns:

The converted address.

Parameters

Direction	Name	Description
	address	The address in an image.

BL_ImageAddressRange

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

Location: bl_image.h:118

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

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)

Location: bl_image.h:127

Copy a possibly split memory range to a contiguous buffer.

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)

Location: bl_image.h:135

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

Returns:

Status code indicating if the save operation failed

Parameters

Direction	Name	Description
	operation	Defines the address and length of the block to be saved.

BL_ImageVerify

BL_ImageStatus_t BL_ImageVerify()

Location: bl_image.h:144

Verify the most recently loaded image.

Returns:

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)

Location: bl_image.h:157

Authenticate a loaded image.

Returns:

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

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.

BL_ImageAuthenticateCurrent

BL_ImageStatus_t BL_ImageAuthenticateCurrent()

Location: bl_image.h:167

Authenticate the most recently loaded image.

Returns:

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)

Location: bl_image.h:176

Check if there is a valid image to start.

Returns:

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

Parameters

Direction	Name	Description
	address	The address of the image in flash.
	length	The length of the image in bytes.

BL_ImageSaveAddress

uint32_t BL_ImageSaveAddress(BL_ImageType_t imageType, uint32_t address)

Location: bl_image.h:185

Return the download address corresponding to the requested address.

Returns:

The download address

Parameters

Direction	Name	Description
	imageType	The type of the image being authenticated.
	address	The requested address

BL_ImageStartApplication

void BL_ImageStartApplication(uint32_t imageBaseAddress)

Location: bl_image.h:192

Start the image stored in flash.

Parameters

Direction	Name	Description
	imageBaseAddress	The base address of the image to be started

BL_LoaderPerformFirmwareLoad

void BL_LoaderPerformFirmwareLoad()

Location: bl_loader.h:147

Perform a firmware update over the UART interface.

BL_LoaderCertificateAddress

uint32_t BL_LoaderCertificateAddress(BL_LoaderCertType_t cert)

Location: bl_loader.h:154

Fetch the address of the requested structure.

Returns:

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

Parameters

Direction	Name	Description
	cert	A requested certificate.

BL_RecoveryInitialize

void BL_RecoveryInitialize()

Location: bl_recovery.h:57

Define the initialization routine for the Debug Catch feature.

BL_TargetInitialize

void BL_TargetInitialize()

Location: bl_target.h:66

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

BL_TargetReset

void BL_TargetReset()

Location: bl_target.h:71

Reset the device using NVIC.

BL_TickerInitialize

void BL_TickerInitialize()

Location: bl_ticker.h:58

Initialize the timer tick.

BL_TickerTime

uint32_t BL_TickerTime()

Location: bl_ticker.h:64

Get the current timer tick value.

Returns:

The time since the ticker was initialized in ms.

SysTick_Handler

void SysTick_Handler()

Location: bl_ticker.h:69

System tick interrupt handler, required by the ticker.

BL_TraceInitialize

void BL_TraceInitialize()

Location: bl_trace.h:70

Initialize the trace sub-system.

BL_UARTInitialize

void BL_UARTInitialize()

Location: bl_uart.h:102

Initialize the UART subsystem.

BL_UARTReceiveAsync

BL_UARTStatus_t BL_UARTReceiveAsync(uint8_t * buffer, size_t length)

Location: bl_uart.h:119

Start receiving a fixed length data buffer using the UART.

Returns:

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.

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)

BL_UARTReceiveComplete

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

Location: bl_uart.h:137

Complete the reception of an executing receive operation.

Returns:

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.

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.

BL_UARTReceive

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

Location: bl_uart.h:161

Receiving a fixed length data buffer using the UART.

Returns:

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.

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.

BL_UARTSendAsync

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

Location: bl_uart.h:175

Start sending a fixed length data buffer using the UART.

Returns:

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.

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.

BL_UARTSendComplete

BL_UARTStatus_t BL_UARTSendComplete()

Location: bl_uart.h:188

Complete the transmission of an executing send operation.

Returns:

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)

Location: bl_uart.h:205

Send a fixed length data buffer using the UART.

Returns:

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.

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.

BL_UpdateInitialize

void BL_UpdateInitialize()

Location: bl_update.h:60

Initialize the firmware update component.

BL_UpdateRequested

bool BL_UpdateRequested()

Location: bl_update.h:66

Check if a firmware update is being requested.

Returns:

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

BL_UpdateProcessPendingImages

void BL_UpdateProcessPendingImages()

Location: bl_update.h:73

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.

BL_ImageSelectAndStartApplication

void BL_ImageSelectAndStartApplication()

Location: bl_update.h:90

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.

BL_VersionsGetInformation

void BL_VersionsGetInformation(BL_BootAppVersion_t * version, uint32_t address)

Location: bl_versions.h:101

Get the version information from a suitable application.

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)

Location: bl_versions.h:108

Fetch the hello response from the bootloader.

Parameters

Direction	Name	Description
	response	The structure into which the hello response should be copied.

BL_WatchdogInitialize

void BL_WatchdogInitialize()

Location: bl_watchdog.h:64

Initialise the watchdog module.

BL_WatchdogSetHoldTime

void BL_WatchdogSetHoldTime(uint32_t seconds)

Location: bl_watchdog.h:76

Set the watchdog hold off time to seconds.

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.

Parameters

Direction	Name	Description
	seconds	The number of seconds to allow before the watchdog bites.

WATCHDOG_IRQHandler

void WATCHDOG_IRQHandler()

Location: bl_watchdog.h:82

Define an interrupt handler for the watchdog interrupt.