Secure Bootloader Sample Reference Function Documentation
BL_CheckRemapAddressSpace
uint32_t BL_CheckRemapAddressSpace(uint32_t base, uint32_t address)
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
BL_CheckGetApplicationSize
uint32_t BL_CheckGetApplicationSize(uint32_t address)
Location: bl_check.h:95
Parameters
Direction | Name | Description |
---|---|---|
|
address |
The address of the base of the vector table. |
Return
BL_CheckRelocatedApplicationSize
uint32_t BL_CheckRelocatedApplicationSize(uint32_t address)
Location: bl_check.h:103
Parameters
Direction | Name | Description |
---|---|---|
|
address |
The address of the base of the vector table. |
Return
BL_CheckIfImageUpdateAvailable
BL_UpdateType_t BL_CheckIfImageUpdateAvailable()
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()
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)
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)
Location: bl_configuration.h:85
Parameters
Direction | Name | Description |
---|---|---|
|
configBase |
Defines the base address of the configuration block. |
Return
BL_ConfigCertificateAddress
uint32_t BL_ConfigCertificateAddress(BL_AppConfiguration_t * configBase, BL_LoaderCertType_t cert)
Location: bl_configuration.h:93
Parameters
Direction | Name | Description |
---|---|---|
|
configBase |
Defines the base address of the configuration block. |
|
cert |
A requested certificate. |
Return
BL_FCSInitialize
BL_FCSStatus_t BL_FCSInitialize(uint8_t * buffer, size_t length, BL_FCS_t fcs)
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_FCSQuery
BL_FCSAlgorithm_t BL_FCSQuery()
Location: bl_fcs.h:92
Return
BL_FCSAuthenticationRequired
bool BL_FCSAuthenticationRequired()
Location: bl_fcs.h:99
Return
BL_FCSSelect
BL_FCSStatus_t BL_FCSSelect(BL_FCSAlgorithm_t algo)
Location: bl_fcs.h:108
Parameters
Direction | Name | Description |
---|---|---|
|
algo |
Selected from BL_FCSAlgorithm_t. |
Return
BL_FCSCheck
BL_FCSStatus_t BL_FCSCheck(uint8_t * buffer, size_t length, BL_FCS_t 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_FCSCalculate
BL_FCSStatus_t BL_FCSCalculate(uint8_t * buffer, size_t length, BL_FCS_t * fcs)
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_FCSAccumulateCRC
uint32_t BL_FCSAccumulateCRC(uint8_t * buffer, size_t 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()
Location: bl_flash.h:55
BL_FlashSaveSector
FlashStatus_t BL_FlashSaveSector(uint8_t * address, size_t length, uint8_t * buffer)
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
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)
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
BL_ImageAddress
uint32_t BL_ImageAddress(uint32_t address)
Location: bl_image.h:107
Parameters
Direction | Name | Description |
---|---|---|
|
address |
The address in an image. |
Return
BL_ImageAddressRange
void BL_ImageAddressRange(uint8_t * address, size_t length, BL_ImageSplitRange_t * range)
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)
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)
Location: bl_image.h:135
Parameters
Direction | Name | Description |
---|---|---|
|
operation |
Defines the address and length of the block to be saved. |
Return
BL_ImageVerify
BL_ImageStatus_t BL_ImageVerify()
Location: bl_image.h:144
Return
BL_ImageAuthenticate
BL_ImageStatus_t BL_ImageAuthenticate(BL_ImageType_t imageType, uint32_t * address, size_t length, bool verifyImages)
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_ImageAuthenticateCurrent
BL_ImageStatus_t BL_ImageAuthenticateCurrent()
Location: bl_image.h:167
Return
BL_ImageIsValid
bool BL_ImageIsValid(uint32_t address, size_t length)
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
BL_ImageSaveAddress
uint32_t BL_ImageSaveAddress(BL_ImageType_t imageType, uint32_t address)
Location: bl_image.h:185
Parameters
Direction | Name | Description |
---|---|---|
|
imageType |
The type of the image being authenticated. |
|
address |
The requested address |
Return
BL_ImageStartApplication
void BL_ImageStartApplication(uint32_t imageBaseAddress)
Location: bl_image.h:192
Parameters
Direction | Name | Description |
---|---|---|
|
imageBaseAddress |
The base address of the image to be started |
BL_LoaderPerformFirmwareLoad
void BL_LoaderPerformFirmwareLoad()
Location: bl_loader.h:147
BL_LoaderCertificateAddress
uint32_t BL_LoaderCertificateAddress(BL_LoaderCertType_t cert)
Location: bl_loader.h:154
Parameters
Direction | Name | Description |
---|---|---|
|
cert |
A requested certificate. |
Return
BL_RecoveryInitialize
void BL_RecoveryInitialize()
Location: bl_recovery.h:57
BL_TargetInitialize
void BL_TargetInitialize()
Location: bl_target.h:77
BL_TargetReset
void BL_TargetReset()
Location: bl_target.h:82
BL_TickerInitialize
void BL_TickerInitialize()
Location: bl_ticker.h:58
BL_TickerTime
uint32_t BL_TickerTime()
Location: bl_ticker.h:64
Return
SysTick_Handler
void SysTick_Handler()
Location: bl_ticker.h:69
BL_TraceInitialize
void BL_TraceInitialize()
Location: bl_trace.h:70
BL_UARTInitialize
void BL_UARTInitialize()
Location: bl_uart.h:102
BL_UARTReceiveAsync
BL_UARTStatus_t BL_UARTReceiveAsync(uint8_t * buffer, size_t length)
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
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)
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
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)
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
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)
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
NOTE: There must be no pending transmit operation pending when this is invoked.
BL_UARTSendComplete
BL_UARTStatus_t BL_UARTSendComplete()
Location: bl_uart.h:188
Return
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
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
NOTE: There must be no pending transmit operation pending when this is invoked.
NOTE: This is a blocking operation.
BL_UpdateInitialize
void BL_UpdateInitialize()
Location: bl_update.h:60
BL_UpdateRequested
bool BL_UpdateRequested()
Location: bl_update.h:66
Return
BL_UpdateProcessPendingImages
void BL_UpdateProcessPendingImages()
Location: bl_update.h:73
BL_ImageSelectAndStartApplication
void BL_ImageSelectAndStartApplication()
Location: bl_update.h:90
BL_VersionsGetInformation
void BL_VersionsGetInformation(BL_BootAppVersion_t * version, uint32_t address)
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)
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()
Location: bl_watchdog.h:64
BL_WatchdogSetHoldTime
void BL_WatchdogSetHoldTime(uint32_t 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()
Location: bl_watchdog.h:82