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

Type	Direction	Argument Name	Description
void	N/A

Returns

Error code indicating success or failure.

Return values

BOOTLOADER_OK: on success
BOOTLOADER_ERROR_INIT_STORAGE: on failure

storage_main#

int32_t storage_main (void )

Main function for storage component.

Parameters

Type	Direction	Argument Name	Description
void	N/A

Returns

BOOTLOADER_OK on success, else error code

storage_shutdown#

int32_t storage_shutdown (void )

Shutdown storage component.

Parameters

Type	Direction	Argument Name	Description
void	N/A

Returns

Error code indicating success or failure.

Return values

BOOTLOADER_OK: on success
BOOTLOADER_ERROR_INIT_STORAGE: on failure

storage_getInfo#

void storage_getInfo (BootloaderStorageInformation_t * info)

Get information about the storage component running on the device.

Parameters

Type	Direction	Argument Name	Description
BootloaderStorageInformation_t *	[out]	info	Pointer to BootloaderStorageInformation_t struct

storage_getSlotInfo#

int32_t storage_getSlotInfo (uint32_t slotId, BootloaderStorageSlot_t * slot)

Get information about the layout of a storage slot.

Parameters

Type	Direction	Argument Name	Description
uint32_t	[in]	slotId	Slot ID to get info about
BootloaderStorageSlot_t *	[out]	slot	Pointer to BootloaderStorageSlot_t struct

Returns

BOOTLOADER_OK on success, else error code in BOOTLOADER_ERROR_STORAGE_BASE range

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

Type	Direction	Argument Name	Description
BootloaderParserContext_t *	[in]	context	Parsing context. Should be allocated by the application and initialized by calling storage_initParseSlot before calling this function.
ApplicationData_t *	[out]	appInfo	Pointer to ApplicationData_t struct
uint32_t *	[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

BOOTLOADER_OK on success

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

Type	Direction	Argument Name	Description
uint32_t	[in]	slotId	Slot to check for valid image
BootloaderParserContext_t *	[in]	context	Pointer to BootloaderParserContext_t struct
size_t	[in]	contextSize	Length of the context struct

Returns

BOOTLOADER_OK on success, else error code in BOOTLOADER_ERROR_PARSE_BASE range

storage_verifySlot#

int32_t storage_verifySlot (BootloaderParserContext_t * context, BootloaderParserCallback_t metadataCallback)

Check the given slot for a valid image.

Parameters

Type	Direction	Argument Name	Description
BootloaderParserContext_t *	[in]	context	Pointer to BootloaderImageParsingContext_t struct
BootloaderParserCallback_t	[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

BOOTLOADER_ERROR_PARSE_CONTINUE if the parsing is not complete, BOOTLOADER_ERROR_PARSE_SUCCESS on success.

storage_upgradeSeFromSlot#

bool storage_upgradeSeFromSlot (uint32_t slotId)

Upgrade SE using image contained in a slot.

Parameters

Type	Direction	Argument Name	Description
uint32_t	N/A	slotId	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

storage_bootloadBootloaderFromSlot#

bool storage_bootloadBootloaderFromSlot (uint32_t slotId, uint32_t version)

Bootload a bootloader image contained in a slot.

Parameters

Type	Direction	Argument Name	Description
uint32_t	N/A	slotId	Slot ID to bootload from
uint32_t	N/A	version	Version number of new bootloader

Note

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

Returns

True if operation succeeded

storage_bootloadApplicationFromSlot#

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

Bootload an image contained in a slot.

Parameters

Type	Direction	Argument Name	Description
uint32_t	N/A	slotId	Slot ID to bootload from
uint32_t	N/A	version	Cached version number of the image contained in the slot (used for downgrade prevention)
uint32_t	N/A	deltaGBLLen	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

storage_eraseSlot#

int32_t storage_eraseSlot (uint32_t slotId)

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

Parameters

Type	Direction	Argument Name	Description
uint32_t	N/A	slotId	ID of the slot.

Returns

BOOTLOADER_OK on success, else error code in BOOTLOADER_ERROR_STORAGE_BASE range

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

Type	Direction	Argument Name	Description
uint32_t	N/A	slotId	ID of the slot.
uint32_t	N/A	offset	The offset into the slot in bytes.
uint8_t *	N/A	buffer	Pointer to buffer to store read data in.
size_t	N/A	numBytes	Number of bytes to read.

Returns

BOOTLOADER_OK on success, else error code in BOOTLOADER_ERROR_STORAGE_BASE range

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

Type	Direction	Argument Name	Description
uint32_t	N/A	slotId	ID of the slot.
uint32_t	N/A	offset	The offset into the slot in bytes.
uint8_t *	N/A	data	Pointer to data to write.
size_t	N/A	numBytes	Length of data to write. Must be a multiple of 4.

Returns

BOOTLOADER_OK on success, else error code in BOOTLOADER_ERROR_STORAGE_BASE range

storage_readRaw#

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

Read number of words from raw storage.

Parameters

Type	Direction	Argument Name	Description
uint32_t	N/A	address	The raw address of the storage.
uint8_t *	N/A	buffer	Pointer to the buffer to store read data in.
size_t	N/A	numBytes	Number of bytes to read.

Returns

BOOTLOADER_OK on success, else error code in BOOTLOADER_ERROR_STORAGE_BASE range

storage_writeRaw#

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

Write a number of words to raw storage.

Parameters

Type	Direction	Argument Name	Description
uint32_t	N/A	address	The raw address of the storage.
uint8_t *	N/A	data	Pointer to data to write.
size_t	N/A	numBytes	Length of data to write. Must be a multiple of 4.

Returns

BOOTLOADER_OK on success, else error code in BOOTLOADER_ERROR_STORAGE_BASE range

storage_getDMAchannel#

int32_t storage_getDMAchannel (void )

Get allocated DMA channel for MSC write.

Parameters

Type	Direction	Argument Name	Description
void	N/A

Returns

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

storage_eraseRaw#

int32_t storage_eraseRaw (uint32_t address, size_t length)

Erase the raw storage.

Parameters

Type	Direction	Argument Name	Description
uint32_t	N/A	address	Start address of the region to erase
size_t	N/A	length	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

BOOTLOADER_OK on success, else error code in BOOTLOADER_ERROR_STORAGE_BASE range

storage_isBusy#

bool storage_isBusy (void )

Poll the storage implementation and check whether it is busy.

Parameters

Type	Direction	Argument Name	Description
void	N/A

Returns

True if the storage is busy

storage_getSpiUsartPPUSATD#

uint32_t storage_getSpiUsartPPUSATD (uint32_t * ppusatdNr)

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

Parameters

Type	Direction	Argument Name	Description
uint32_t *	N/A	ppusatdNr	PPUSATD register number

Returns

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