Storage#

Storage component.

This component provides the bootloader with multiple storage options. All storage implementations have to provide a slot-based API to access image files to be bootloaded.

Some storage implementations also support a raw storage API to access the underlying storage medium. This can be used by applications to store other data in parts of the storage medium that are not used for bootloading.

Storage Implementations#

Modules#

BootloaderStorageLayout_t

SPI Flash

Internal Flash

Flash Using JEDEC SFDP Standard

Bootload Info

SPI Flash Configurations

SPI Flash Configurations using SFDP

Functions#

int32_t
storage_init(void)

Initialize the storage component.

int32_t
storage_main(void)

Main function for storage component.

int32_t
storage_shutdown(void)

Shutdown storage component.

void
storage_getInfo(BootloaderStorageInformation_t *info)

Get information about the storage component running on the device.

int32_t
storage_getSlotInfo(uint32_t slotId, BootloaderStorageSlot_t *slot)

Get information about the layout of a storage slot.

int32_t
storage_getSlotMetadata(BootloaderParserContext_t *context, ApplicationData_t *appInfo, uint32_t *bootloaderVersion)

Get information about the contents of a storage slot.

int32_t
storage_initParseSlot(uint32_t slotId, BootloaderParserContext_t *context, size_t contextSize)

Initialize the context variable for checking a slot and trying to parse the image contained in it.

int32_t
storage_verifySlot(BootloaderParserContext_t *context, BootloaderParserCallback_t metadataCallback)

Check the given slot for a valid image.

bool
storage_upgradeSeFromSlot(uint32_t slotId)

Upgrade SE using image contained in a slot.

bool
storage_bootloadBootloaderFromSlot(uint32_t slotId, uint32_t version)

Bootload a bootloader image contained in a slot.

bool
storage_bootloadApplicationFromSlot(uint32_t slotId, uint32_t version, uint32_t deltaGBLLen)

Bootload an image contained in a slot.

int32_t
storage_eraseSlot(uint32_t slotId)

Erase the contents of a storage slot including all data and metadata.

int32_t
storage_readSlot(uint32_t slotId, uint32_t offset, uint8_t *buffer, size_t numBytes)

Read a number of words from a storage slot.

int32_t
storage_writeSlot(uint32_t slotId, uint32_t offset, uint8_t *data, size_t numBytes)

Write a number of words to a storage slot.

int32_t
storage_readRaw(uint32_t address, uint8_t *buffer, size_t numBytes)

Read number of words from raw storage.

int32_t
storage_writeRaw(uint32_t address, uint8_t *data, size_t numBytes)

Write a number of words to raw storage.

int32_t
storage_getDMAchannel(void)

Get allocated DMA channel for MSC write.

int32_t
storage_eraseRaw(uint32_t address, size_t length)

Erase the raw storage.

bool
storage_isBusy(void)

Poll the storage implementation and check whether it is busy.

uint32_t
storage_getSpiUsartPPUSATD(uint32_t *ppusatdNr)

Get PPUSATD word of the (E)USART in use.

Macros#

#define
BOOTLOADER_STORAGE_FUNCTIONS_VERSION 0x00000100

Version number for bootloader storage functions struct.

Function Documentation#

storage_init#

int32_t storage_init (void )

Initialize the storage component.

Parameters
N/A

Returns

  • Error code indicating success or failure.

Return values

  • BOOTLOADER_OK: on success

  • BOOTLOADER_ERROR_INIT_STORAGE: on failure


Definition at line 68 of file platform/bootloader/storage/btl_storage.h

storage_main#

int32_t storage_main (void )

Main function for storage component.

Parameters
N/A

Returns


Definition at line 75 of file platform/bootloader/storage/btl_storage.h

storage_shutdown#

int32_t storage_shutdown (void )

Shutdown storage component.

Parameters
N/A

Returns

  • Error code indicating success or failure.

Return values

  • BOOTLOADER_OK: on success

  • BOOTLOADER_ERROR_INIT_STORAGE: on failure


Definition at line 84 of file platform/bootloader/storage/btl_storage.h

storage_getInfo#

void storage_getInfo (BootloaderStorageInformation_t * info)

Get information about the storage component running on the device.

Parameters
[out]info

Pointer to BootloaderStorageInformation_t struct


Definition at line 91 of file platform/bootloader/storage/btl_storage.h

storage_getSlotInfo#

int32_t storage_getSlotInfo (uint32_t slotId, BootloaderStorageSlot_t * slot)

Get information about the layout of a storage slot.

Parameters
[in]slotId

Slot ID to get info about

[out]slot

Pointer to BootloaderStorageSlot_t struct

Returns


Definition at line 102 of file platform/bootloader/storage/btl_storage.h

storage_getSlotMetadata#

int32_t storage_getSlotMetadata (BootloaderParserContext_t * context, ApplicationData_t * appInfo, uint32_t * bootloaderVersion)

Get information about the contents of a storage slot.

Parameters
[in]context

Parsing context. Should be allocated by the application and initialized by calling storage_initParseSlot before calling this function.

[out]appInfo

Pointer to ApplicationData_t struct

[out]bootloaderVersion

Pointer to an unsigned integer representing the bootloader version number.

Note

  • storage_initParseSlotmust be called before calling this function to initialize the context.

  • If the slot does not contain an application or a bootloader, the the corresponding values are set to zero.

Returns


Definition at line 123 of file platform/bootloader/storage/btl_storage.h

storage_initParseSlot#

int32_t storage_initParseSlot (uint32_t slotId, BootloaderParserContext_t * context, size_t contextSize)

Initialize the context variable for checking a slot and trying to parse the image contained in it.

Parameters
[in]slotId

Slot to check for valid image

[in]context

Pointer to BootloaderParserContext_t struct

[in]contextSize

Length of the context struct

Returns


Definition at line 138 of file platform/bootloader/storage/btl_storage.h

storage_verifySlot#

int32_t storage_verifySlot (BootloaderParserContext_t * context, BootloaderParserCallback_t metadataCallback)

Check the given slot for a valid image.

Parameters
[in]context

Pointer to BootloaderImageParsingContext_t struct

[in]metadataCallback

Functionpointer which will be called with any binary metadata that might be contained within the image.

Call this function continuously until it stops returning. BOOTLOADER_ERROR_PARSE_CONTINUE.

The function returns BOOTLOADER_ERROR_PARSE_SUCCESS if the image in the slot was successfully verified. For detailed information on the parsed image, see imageProperties in the context variable.

Returns


Definition at line 159 of file platform/bootloader/storage/btl_storage.h

storage_upgradeSeFromSlot#

bool storage_upgradeSeFromSlot (uint32_t slotId)

Upgrade SE using image contained in a slot.

Parameters
N/AslotId

Slot ID to bootload from

Note

  • This function assumes the image located in the slotId has been verified first.

Returns

  • True if the operation succeeded


Definition at line 172 of file platform/bootloader/storage/btl_storage.h

storage_bootloadBootloaderFromSlot#

bool storage_bootloadBootloaderFromSlot (uint32_t slotId, uint32_t version)

Bootload a bootloader image contained in a slot.

Parameters
N/AslotId

Slot ID to bootload from

N/Aversion

Version number of new bootloader

Note

  • This function assumes the image located in the slotId has been verified first.

Returns

  • True if operation succeeded


Definition at line 185 of file platform/bootloader/storage/btl_storage.h

storage_bootloadApplicationFromSlot#

bool storage_bootloadApplicationFromSlot (uint32_t slotId, uint32_t version, uint32_t deltaGBLLen)

Bootload an image contained in a slot.

Parameters
N/AslotId

Slot ID to bootload from

N/Aversion

Cached version number of the image contained in the slot (used for downgrade prevention)

N/AdeltaGBLLen

Length of the Delta GBL file.

Note

  • This function assumes the image located in slotId has been verified first.

Returns

  • True if the operation succeeded


Definition at line 200 of file platform/bootloader/storage/btl_storage.h

storage_eraseSlot#

int32_t storage_eraseSlot (uint32_t slotId)

Erase the contents of a storage slot including all data and metadata.

Parameters
N/AslotId

ID of the slot.

Returns


Definition at line 210 of file platform/bootloader/storage/btl_storage.h

storage_readSlot#

int32_t storage_readSlot (uint32_t slotId, uint32_t offset, uint8_t * buffer, size_t numBytes)

Read a number of words from a storage slot.

Parameters
N/AslotId

ID of the slot.

N/Aoffset

The offset into the slot in bytes.

N/Abuffer

Pointer to buffer to store read data in.

N/AnumBytes

Number of bytes to read.

Returns


Definition at line 223 of file platform/bootloader/storage/btl_storage.h

storage_writeSlot#

int32_t storage_writeSlot (uint32_t slotId, uint32_t offset, uint8_t * data, size_t numBytes)

Write a number of words to a storage slot.

Parameters
N/AslotId

ID of the slot.

N/Aoffset

The offset into the slot in bytes.

N/Adata

Pointer to data to write.

N/AnumBytes

Length of data to write. Must be a multiple of 4.

Returns


Definition at line 239 of file platform/bootloader/storage/btl_storage.h

storage_readRaw#

int32_t storage_readRaw (uint32_t address, uint8_t * buffer, size_t numBytes)

Read number of words from raw storage.

Parameters
N/Aaddress

The raw address of the storage.

N/Abuffer

Pointer to the buffer to store read data in.

N/AnumBytes

Number of bytes to read.

Returns


Definition at line 254 of file platform/bootloader/storage/btl_storage.h

storage_writeRaw#

int32_t storage_writeRaw (uint32_t address, uint8_t * data, size_t numBytes)

Write a number of words to raw storage.

Parameters
N/Aaddress

The raw address of the storage.

N/Adata

Pointer to data to write.

N/AnumBytes

Length of data to write. Must be a multiple of 4.

Returns


Definition at line 268 of file platform/bootloader/storage/btl_storage.h

storage_getDMAchannel#

int32_t storage_getDMAchannel (void )

Get allocated DMA channel for MSC write.

Parameters
N/A

Returns

  • A positive number channel. -1 if DMA-based MSC write is not enabled.


Definition at line 278 of file platform/bootloader/storage/btl_storage.h

storage_eraseRaw#

int32_t storage_eraseRaw (uint32_t address, size_t length)

Erase the raw storage.

Parameters
N/Aaddress

Start address of the region to erase

N/Alength

Number of bytes to erase

Note

  • Some devices, such as Flash-based storages, have restrictions on the alignment and size of erased regions. The details of the limitations of a particular storage can be found by reading the BootloaderStorageInformation_t struct using storage_getInfo.

Returns


Definition at line 294 of file platform/bootloader/storage/btl_storage.h

storage_isBusy#

bool storage_isBusy (void )

Poll the storage implementation and check whether it is busy.

Parameters
N/A

Returns

  • True if the storage is busy


Definition at line 301 of file platform/bootloader/storage/btl_storage.h

storage_getSpiUsartPPUSATD#

uint32_t storage_getSpiUsartPPUSATD (uint32_t * ppusatdNr)

Get PPUSATD word of the (E)USART in use.

Parameters
N/AppusatdNr

PPUSATD register number

Returns

  • Word representing the PPUSATD bit field of the (E)USART in use. 0 if not found.


Definition at line 311 of file platform/bootloader/storage/btl_storage.h

Macro Definition Documentation#

BOOTLOADER_STORAGE_FUNCTIONS_VERSION#

#define BOOTLOADER_STORAGE_FUNCTIONS_VERSION
Value:
0x00000100

Version number for bootloader storage functions struct.


Definition at line 49 of file platform/bootloader/storage/btl_storage.h