Application Storage Interface#

BootloaderStorageType_t#

BootloaderStorageType_t

Possible storage types.

bootloader_getStorageInfo#

void bootloader_getStorageInfo (BootloaderStorageInformation_t * info)

Get information about the storage component.

bootloader_getStorageSlotInfo#

int32_t bootloader_getStorageSlotInfo (uint32_t slotId, BootloaderStorageSlot_t * slot)

Get information about a storage slot.

Returns

• BOOTLOADER_OK on success, else error code in BOOTLOADER_ERROR_STORAGE_BASE range

bootloader_readStorage#

int32_t bootloader_readStorage (uint32_t slotId, uint32_t offset, uint8_t * buffer, size_t length)

Read data from a storage slot.

Returns

• BOOTLOADER_OK on success, else error code in BOOTLOADER_ERROR_STORAGE_BASE range

bootloader_writeStorage#

int32_t bootloader_writeStorage (uint32_t slotId, uint32_t offset, uint8_t * buffer, size_t length)

Write data to a storage slot.

Note

• If DMA-based MSC write is enabled on the bootloader, writing data from flash to flash is not supported on Series-1 devices. DMA-based MSC write is enabled, both offset and buffer should be word aligned. In case the buffer is not aligned, the normal write procedure is used instead of DMA.

Returns

• BOOTLOADER_OK on success, else error code in BOOTLOADER_ERROR_STORAGE_BASE range

bootloader_eraseWriteStorage#

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 can't 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. If DMA-based MSC write is enabled on the bootloader, writing data from flash to flash is not supported on Series-1 devices.

Returns

• BOOTLOADER_OK on success, else error code in BOOTLOADER_ERROR_STORAGE_BASE range

bootloader_eraseStorageSlot#

int32_t bootloader_eraseStorageSlot (uint32_t slotId)

Erase all contents of a storage slot.

Returns

• BOOTLOADER_OK on success, else error code in BOOTLOADER_ERROR_STORAGE_BASE range

bootloader_initChunkedEraseStorageSlot#

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.

Returns

• BOOTLOADER_OK on success, else error code in BOOTLOADER_ERROR_STORAGE_BASE range

bootloader_chunkedEraseStorageSlot#

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.

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

bootloader_setImagesToBootload#

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.

Returns

• BOOTLOADER_OK on success, else error code in BOOTLOADER_ERROR_BOOTLOAD_BASE range

bootloader_getImagesToBootload#

int32_t bootloader_getImagesToBootload (int32_t * slotIds, size_t length)

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

Returns

• BOOTLOADER_OK on success, else error code in BOOTLOADER_ERROR_BOOTLOAD_BASE range

bootloader_appendImageToBootloadList#

int32_t bootloader_appendImageToBootloadList (int32_t slotId)

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

Returns

• BOOTLOADER_OK on success, else error code in BOOTLOADER_ERROR_BOOTLOAD_BASE range

bootloader_setImageToBootload#

int32_t bootloader_setImageToBootload (int32_t slotId)

Set a single image to attempt to bootload.

Returns

• BOOTLOADER_OK on success, else error code in BOOTLOADER_ERROR_BOOTLOAD_BASE range

bootloader_initVerifyImage#

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 caller must ensure that the context pointer is 32 bit aligned. 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.

Returns

• BOOTLOADER_OK if the image parser was initialized, else error code.

bootloader_continueVerifyImage#

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.

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.

bootloader_verifyImage#

int32_t bootloader_verifyImage (uint32_t slotId, BootloaderParserCallback_t metadataCallback)

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

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.

bootloader_getImageInfo#

int32_t bootloader_getImageInfo (uint32_t slotId, ApplicationData_t * appInfo, uint32_t * bootloaderVersion)

Get application and bootloader upgrade metadata from the storage slot.

Returns

• BOOTLOADER_OK if metadata was filled successfully

bootloader_storageIsBusy#

bool bootloader_storageIsBusy (void )

Check whether the bootloader storage is busy.

Returns

• True if the storage is busy

bootloader_readRawStorage#

int32_t bootloader_readRawStorage (uint32_t address, uint8_t * buffer, size_t length)

Read raw data from storage.

Returns

• BOOTLOADER_OK on success, else error code in BOOTLOADER_ERROR_STORAGE_BASE range

bootloader_writeRawStorage#

int32_t bootloader_writeRawStorage (uint32_t address, uint8_t * buffer, size_t length)

Write data to storage.

Note

• If DMA-based MSC write is enabled on the bootloader, writing data from flash to flash is not supported on Series-1 devices.

Returns

• BOOTLOADER_OK on success, else error code in BOOTLOADER_ERROR_STORAGE_BASE range

bootloader_eraseRawStorage#

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 about the limitations of the configured storage medium.

Returns

• BOOTLOADER_OK on success, else error code in BOOTLOADER_ERROR_STORAGE_BASE range

bootloader_getAllocatedDMAChannel#

int32_t bootloader_getAllocatedDMAChannel (void )

Get allocated DMA channel for MSC write.

Returns

• A positive number channel. -1 if DMA-based MSC write is not enabled. Otherwise, the error code BOOTLOADER_ERROR_INIT_STORAGE.