Application Storage InterfaceApplication Interface

Description

Application interface for interfacing with the bootloader storage.

The Storage Interface is only available on bootloaders that declare they support BOOTLOADER_CAPABILITY_STORAGE.

Data Structures

struct  BootloaderStorageSlot_t
 Information about a storage slot.
 
struct  BootloaderStorageImplementationInformation_t
 Information about the bootloader storage implementation.
 
struct  BootloaderStorageInformation_t
 Information about the bootloader storage.
 
struct  BootloaderEraseStatus_t
 Erase status struct.
 
struct  BootloaderStorageFunctions
 Storage API accessible from the application.
 

Macros

#define BOOTLOADER_STORAGE_IMPL_INFO_VERSION   (0x0201)
 Current version of the BootloaderStorageImplementationInformation_t struct.
 
#define BOOTLOADER_STORAGE_IMPL_INFO_VERSION_MAJOR   (0x0200)
 Major version of the BootloaderStorageImplementationInformation_t struct.
 
#define BOOTLOADER_STORAGE_IMPL_INFO_VERSION_MAJOR_MASK   (0xFF00)
 Major version mask for BOOTLOADER_STORAGE_IMPL_INFO_VERSION.
 
#define BOOTLOADER_STORAGE_IMPL_CAPABILITY_ERASE_SUPPORTED   (1 << 0)
 Spiflash capability indicating that it supports erase.
 
#define BOOTLOADER_STORAGE_IMPL_CAPABILITY_PAGE_ERASE_REQUIRED   (1 << 1)
 Spiflash capability indicating it requires full page erases before new data can be written.
 
#define BOOTLOADER_STORAGE_IMPL_CAPABILITY_BLOCKING_WRITE   (1 << 2)
 Spiflash capability indicating that the write function is blocking.
 
#define BOOTLOADER_STORAGE_IMPL_CAPABILITY_BLOCKING_ERASE   (1 << 3)
 Spiflash capability indicating that the erase function is blocking.
 
#define BOOTLOADER_STORAGE_VERIFICATION_CONTEXT_SIZE   (384)
 Context size for bootloader verification context.
 

Typedefs

typedef struct BootloaderStorageFunctions BootloaderStorageFunctions_t
 Storage API accessible from the application.
 

Enumerations

enum  BootloaderStorageType_t {
  SPIFLASH,
  INTERNAL_FLASH,
  CUSTOM_STORAGE
}
 Possible storage types.
 

Functions

void bootloader_getStorageInfo (BootloaderStorageInformation_t *info)
 
int32_t bootloader_getStorageSlotInfo (uint32_t slotId, BootloaderStorageSlot_t *slot)
 
int32_t bootloader_readStorage (uint32_t slotId, uint32_t offset, uint8_t *buffer, size_t length)
 
int32_t bootloader_writeStorage (uint32_t slotId, uint32_t offset, uint8_t *buffer, size_t length)
 
int32_t bootloader_eraseWriteStorage (uint32_t slotId, uint32_t offset, uint8_t *buffer, size_t length)
 
int32_t bootloader_eraseStorageSlot (uint32_t slotId)
 
int32_t bootloader_initChunkedEraseStorageSlot (uint32_t slotId, BootloaderEraseStatus_t *eraseStat)
 
int32_t bootloader_chunkedEraseStorageSlot (BootloaderEraseStatus_t *eraseStat)
 
int32_t bootloader_setImagesToBootload (int32_t *slotIds, size_t length)
 
int32_t bootloader_getImagesToBootload (int32_t *slotIds, size_t length)
 
int32_t bootloader_appendImageToBootloadList (int32_t slotId)
 
int32_t bootloader_setImageToBootload (int32_t slotId)
 
int32_t bootloader_initVerifyImage (uint32_t slotId, void *context, size_t contextSize)
 
int32_t bootloader_continueVerifyImage (void *context, BootloaderParserCallback_t metadataCallback)
 
int32_t bootloader_verifyImage (uint32_t slotId, BootloaderParserCallback_t metadataCallback)
 
int32_t bootloader_getImageInfo (uint32_t slotId, ApplicationData_t *appInfo, uint32_t *bootloaderVersion)
 
bool bootloader_storageIsBusy (void)
 
int32_t bootloader_readRawStorage (uint32_t address, uint8_t *buffer, size_t length)
 
int32_t bootloader_writeRawStorage (uint32_t address, uint8_t *buffer, size_t length)
 
int32_t bootloader_eraseRawStorage (uint32_t address, size_t length)
 

Enumeration Type Documentation

enum BootloaderStorageType_t

Possible storage types.

Enumerator
SPIFLASH 

Storage backend is a SPI flash.

INTERNAL_FLASH 

Storage backend is internal flash.

CUSTOM_STORAGE 

Storage backend is custom.

Definition at line 39 of file btl_interface_storage.h.

Function Documentation

void bootloader_getStorageInfo ( BootloaderStorageInformation_t *  info)

Get information about the storage plugin.

Parameters
[out]infoInformation about the storage plugin.
int32_t bootloader_getStorageSlotInfo ( uint32_t  slotId,
BootloaderStorageSlot_t *  slot 
)

Get information about a storage slot.

Parameters
[in]slotIdID of the slot to get information about
[out]slotInformation about the storage slot
Returns
BOOTLOADER_OK on success, else error code in BOOTLOADER_ERROR_STORAGE_BASE range
int32_t bootloader_readStorage ( uint32_t  slotId,
uint32_t  offset,
uint8_t *  buffer,
size_t  length 
)

Read data from a storage slot.

Parameters
[in]slotIdID of the slot
[in]offsetOffset into the slot to start reading from
[out]bufferBuffer to store the data
[in]lengthAmount of data to read
Returns
BOOTLOADER_OK on success, else error code in BOOTLOADER_ERROR_STORAGE_BASE range
int32_t bootloader_writeStorage ( uint32_t  slotId,
uint32_t  offset,
uint8_t *  buffer,
size_t  length 
)

Write data to a storage slot.

Parameters
[in]slotIdID of the slot
[in]offsetOffset into the slot to start writing to
[in]bufferBuffer to read data to write from
[in]lengthAmount of data to write
Returns
BOOTLOADER_OK on success, else error code in BOOTLOADER_ERROR_STORAGE_BASE range
int32_t bootloader_eraseWriteStorage ( uint32_t  slotId,
uint32_t  offset,
uint8_t *  buffer,
size_t  length 
)

Erase and write data to a storage slot.

Note
This function automatically erases the following Flash page whenever the written data crosses a page boundary. In other words, the function cannot be used to perform multiple sequential writes to the same address range unless the range starts at a page boundary. For a sequential write, the first call to this function should have a start address at a page boundary. Otherwise, the corresponding page of the starting address needs to be erased explicitly.
Parameters
[in]slotIdID of the slot
[in]offsetOffset into the slot to start writing to
[in]bufferBuffer to read data to write from
[in]lengthAmount of data to write
Returns
BOOTLOADER_OK on success, else error code in BOOTLOADER_ERROR_STORAGE_BASE range
int32_t bootloader_eraseStorageSlot ( uint32_t  slotId)

Erase all contents of a storage slot.

Parameters
[in]slotIdID of the slot
Returns
BOOTLOADER_OK on success, else error code in BOOTLOADER_ERROR_STORAGE_BASE range
int32_t bootloader_initChunkedEraseStorageSlot ( uint32_t  slotId,
BootloaderEraseStatus_t *  eraseStat 
)

Initialize chunked erase of a storage slot.

Note
This function must be called before calling bootloader_chunkedEraseStorageSlot in a loop.
Parameters
[in]slotIdID of the slot
[in]eraseStatErase status struct
Returns
BOOTLOADER_OK on success, else error code in BOOTLOADER_ERROR_STORAGE_BASE range
int32_t bootloader_chunkedEraseStorageSlot ( BootloaderEraseStatus_t *  eraseStat)

Erase one page from a storage slot according to the struct BootloaderEraseStatus_t.

Note
bootloader_initChunkedEraseStorageSlot must be called before calling this function, in order to prepare BootloaderEraseStatus_t.
This can be called sequentially to, for example, erase all contents of a storage slot.
Parameters
[in]eraseStatErase status struct
Returns
BOOTLOADER_ERROR_STORAGE_CONTINUE if erasing a page was successful. Erase can be continued by calling this function again. BOOTLOADER_OK if the entire slot has been erased, else error code in BOOTLOADER_ERROR_STORAGE_BASE range
int32_t bootloader_setImagesToBootload ( int32_t *  slotIds,
size_t  length 
)

Set a prioritized list of images to attempt to bootload. The last call to this function determines which slot will be installed when bootloader_rebootAndInstall is called.

Parameters
[in]slotIdsPrioritized list of slot IDs to attempt to bootload. The first image to pass verification will be bootloaded.
[in]lengthLength of the slotIds array
Returns
BOOTLOADER_OK on success, else error code in BOOTLOADER_ERROR_BOOTLOAD_BASE range
int32_t bootloader_getImagesToBootload ( int32_t *  slotIds,
size_t  length 
)

Get the prioritized list of images the bootloader will attempt to bootload.

Parameters
[out]slotIdsPrioritized list of slot IDs to attempt to bootload. The first image to pass verification will be bootloaded.
[in]lengthLength of the slotIds array
Returns
BOOTLOADER_OK on success, else error code in BOOTLOADER_ERROR_BOOTLOAD_BASE range
int32_t bootloader_appendImageToBootloadList ( int32_t  slotId)

Append a single image to the list of images to attempt to bootload.

Parameters
[in]slotIdID of the slot to append
Returns
BOOTLOADER_OK on success, else error code in BOOTLOADER_ERROR_BOOTLOAD_BASE range
int32_t bootloader_setImageToBootload ( int32_t  slotId)

Set a single image to attempt to bootload.

Parameters
[in]slotIdID of the slot
Returns
BOOTLOADER_OK on success, else error code in BOOTLOADER_ERROR_BOOTLOAD_BASE range
int32_t bootloader_initVerifyImage ( uint32_t  slotId,
void *  context,
size_t  contextSize 
)

Initialize image verification.

Initialize verification of an upgrade image stored in a bootloader storage slot.

Note
This function must be called before calling bootloader_continueVerifyImage in a loop.
The context pointer must point to memory allocated by the caller. The required size of this context may depend on the version of the bootloader. The required size for the bootloader associated with this version of the application interface is given by the define BOOTLOADER_STORAGE_VERIFICATION_CONTEXT_SIZE.
Instead of calling bootloader_initVerifyImage followed by bootloader_continueVerifyImage, call bootloader_verifyImage if no time-critical tasks are needed and sufficient stack space is available for the automatically allocated context. The purpose of the init-and-continue functions is to allow the caller to service system needs during verification.
Parameters
[in]slotIdID of the slot to check.
contextPointer to memory used to hold the parser context.
[in]contextSizeSize of the context. An error is returned if the supplied context is too small.
Returns
BOOTLOADER_OK if the image parser was initialized, else error code.
int32_t bootloader_continueVerifyImage ( void *  context,
BootloaderParserCallback_t  metadataCallback 
)

Continue image verification.

Continue verification of an upgrade image stored in a bootloader storage slot.

Note
This function must be called in a loop until anything other than BOOTLOADER_ERROR_PARSE_CONTINUE is returned.
bootloader_initVerifyImage must be called before calling this function to reset the parser.
Instead of calling bootloader_initVerifyImage followed by bootloader_continueVerifyImage, call bootloader_verifyImage if no time-critical tasks are needed. The purpose of the init-and-continue functions is to allow the caller to service system needs during verification.
Parameters
contextPointer to a context structure that has been initialized by calling bootloader_initVerifyImage()
[in]metadataCallbackFunction pointer which gets called when the binary metadata in the image is currently verified. Set to NULL if not required.
Returns
BOOTLOADER_ERROR_PARSE_CONTINUE if parsing was successful, and the parser expects more data. BOOTLOADER_ERROR_PARSE_SUCCESS if the parser has successfully parsed the image and it passes verification. Else error code.
int32_t bootloader_verifyImage ( uint32_t  slotId,
BootloaderParserCallback_t  metadataCallback 
)

Verify that the image in the given storage slot is valid.

Parameters
[in]slotIdID of the slot to check
[in]metadataCallbackFunction pointer which gets called when binary metadata is present in the storage slot. Set to NULL if not required.
Note
This function allocates a context structure of the size given by BOOTLOADER_STORAGE_VERIFICATION_CONTEXT_SIZE on the caller's stack. To manage memory and allocate the context elsewhere (on the heap, as a global variable, and so on), use bootloader_initVerifyImage and bootloader_continueVerifyImage functions instead.
Returns
BOOTLOADER_OK if the image is valid, else error code.
int32_t bootloader_getImageInfo ( uint32_t  slotId,
ApplicationData_t *  appInfo,
uint32_t *  bootloaderVersion 
)

Get application and bootloader upgrade metadata from the storage slot.

Parameters
[in]slotIdID of the slot to check
[out]appInfoPointer to ApplicationData_t struct
[out]bootloaderVersionPointer to an integer representing bootloader version
Returns
BOOTLOADER_OK if metadata was filled successfully
bool bootloader_storageIsBusy ( void  )

Check whether the bootloader storage is busy.

Returns
True if the storage is busy
int32_t bootloader_readRawStorage ( uint32_t  address,
uint8_t *  buffer,
size_t  length 
)

Read raw data from storage.

Parameters
[in]addressAddress to start reading from
[out]bufferBuffer to store the data
[in]lengthAmount of data to read
Returns
BOOTLOADER_OK on success, else error code in BOOTLOADER_ERROR_STORAGE_BASE range
int32_t bootloader_writeRawStorage ( uint32_t  address,
uint8_t *  buffer,
size_t  length 
)

Write data to storage.

Parameters
[in]addressAddress to start writing to
[in]bufferBuffer to read data to write from
[in]lengthAmount of data to write
Returns
BOOTLOADER_OK on success, else error code in BOOTLOADER_ERROR_STORAGE_BASE range
int32_t bootloader_eraseRawStorage ( uint32_t  address,
size_t  length 
)

Erase data from storage.

Note
Erasing storage must adhere to the limitations of the underlying storage medium, such as requiring full page erases. Use bootloader_getStorageInfo to learn the limitations of the configured storage medium.
Parameters
[in]addressAddress to start erasing from
[in]lengthLength of data to erase
Returns
BOOTLOADER_OK on success, else error code in BOOTLOADER_ERROR_STORAGE_BASE range