Description

Storage plugin.

This plugin 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

Internal Flash

The Internal Flash storage implementation utilizes the internal Flash of the device for upgrade image storage.

SPI Flash

The SPI Flash storage implementation supports a variety of SPI Flash parts including the following:

Spansion S25FL208K (8Mbit)
Winbond W25X20BV (2Mbit), W25Q80BV (8Mbit)
Macronix MX25L2006E (2Mbit), MX25L4006E (4Mbit), MX25L8006E (8Mbit), MX25R8035F (8Mbit low power), MX25L1606E (16Mbit), MX25U1635E (16Mbit 2Volt), MX25R6435F (64Mbit low power)
Atmel/Adesto AT25DF041A (4Mbit), AT25DF081A (8Mbit)
Numonyx/Micron M25P20 (2Mbit), M25P40 (4Mbit), M25P80 (8Mbit), M25P16 (16Mbit)
ISSI IS25LQ025B (256Kbit), IS25LQ512B (512Kbit), IS25LQ010B (1Mbit), IS25LQ020B (2Mbit), IS25LQ040B (4Mbit)

The subset of supported devices can be configured at compile time using the configuration defines given in SPI Flash Configurations . Including support for multiple devices requires more Flash space in the bootloader.The SPI Flash storage implementation does not support any write protection functionality.

Modules
Bootload Info
Indicates which firmware update image should be bootloaded next.

SPI Flash Configurations
Configuration parameters for SPI flashes.

Data Structures
struct	BootloaderStorageLayout_t
	Information about the storage backend.

Macros
#define	BOOTLOADER_STORAGE_FUNCTIONS_VERSION 0x00000100
	Version number for bootloader storage functions struct.

Functions
int32_t	storage_init (void)

int32_t	storage_main (void)

int32_t	storage_shutdown (void)

void	storage_getInfo ( BootloaderStorageInformation_t *info)

int32_t	storage_getSlotInfo (uint32_t slotId, BootloaderStorageSlot_t *slot)

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

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

int32_t	storage_verifySlot ( BootloaderParserContext_t *context, BootloaderParserCallback_t metadataCallback)

bool	storage_upgradeSeFromSlot (uint32_t slotId)

bool	storage_bootloadBootloaderFromSlot (uint32_t slotId, uint32_t version)

bool	storage_bootloadApplicationFromSlot (uint32_t slotId, uint32_t version)

int32_t	storage_eraseSlot (uint32_t slotId)

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

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

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

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

int32_t	storage_getDMAchannel (void)

int32_t	storage_eraseRaw (uint32_t address, size_t length)

bool	storage_isBusy (void)

Function Documentation

int32_t storage_init ( void )

Initialize the storage plugin.

Returns: Error code indicating success or failure.

Return values

`BOOTLOADER_OK`	on success
`BOOTLOADER_ERROR_INIT_STORAGE`	on failure

int32_t storage_main ( void )

Main function for storage plugin.

Returns: BOOTLOADER_OK on success, else error code

int32_t storage_shutdown ( void )

Shutdown storage plugin.

Returns: Error code indicating success or failure.

Return values

`BOOTLOADER_OK`	on success
`BOOTLOADER_ERROR_INIT_STORAGE`	on failure

void storage_getInfo ( BootloaderStorageInformation_t * info )

Get information about the storage plugin running on the device.

Parameters

[out] info Pointer to BootloaderStorageInformation_t struct

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: BOOTLOADER_OK on success, else error code in BOOTLOADER_ERROR_STORAGE_BASE range

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

Get information about the contents of a storage slot

Note: storage_initParseSlot must 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.

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.

Returns: BOOTLOADER_OK on success

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: BOOTLOADER_OK on success, else error code in BOOTLOADER_ERROR_PARSE_BASE range

int32_t storage_verifySlot	(	BootloaderParserContext_t *	`context,`
		BootloaderParserCallback_t	`metadataCallback`
	)

Check the given slot for a valid 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.

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.

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

bool storage_upgradeSeFromSlot ( uint32_t slotId )

Upgrade SE using image contained in a slot.

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

Parameters

slotId Slot ID to bootload from

Returns: True if the operation succeeded

bool storage_bootloadBootloaderFromSlot	(	uint32_t	`slotId,`
		uint32_t	`version`
	)

Bootload a bootloader image contained in a slot

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

Parameters

`slotId`	Slot ID to bootload from
`version`	Version number of new bootloader

Returns: True if operation succeeded

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

Bootload an image contained in a slot.

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

Parameters

`slotId`	Slot ID to bootload from
`version`	Cached version number of the image contained in the slot (used for downgrade prevention)

Returns: True if the operation succeeded

int32_t storage_eraseSlot ( uint32_t slotId )

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

Parameters

slotId ID of the slot.

Returns: BOOTLOADER_OK on success, else error code in BOOTLOADER_ERROR_STORAGE_BASE range

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

`slotId`	ID of the slot.
`offset`	The offset into the slot in bytes.
`buffer`	Pointer to buffer to store read data in.
`numBytes`	Number of bytes to read.

Returns: BOOTLOADER_OK on success, else error code in BOOTLOADER_ERROR_STORAGE_BASE range

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

`slotId`	ID of the slot.
`offset`	The offset into the slot in bytes.
`data`	Pointer to data to write.
`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

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

Read number of words from raw storage.

Parameters

`address`	The raw address of the storage.
`buffer`	Pointer to the buffer to store read data in.
`numBytes`	Number of bytes to read.

Returns: BOOTLOADER_OK on success, else error code in BOOTLOADER_ERROR_STORAGE_BASE range

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

Write a number of words to raw storage.

Parameters

`address`	The raw address of the storage.
`data`	Pointer to data to write.
`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

int32_t storage_getDMAchannel ( void )

Get allocated DMA channel for MSC write

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

int32_t storage_eraseRaw	(	uint32_t	`address,`
		size_t	`length`
	)

Erase the raw storage.

Parameters

`address`	Start address of the region to erase
`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

bool storage_isBusy ( void )

Poll the storage implementation and check whether it is busy.

Returns: True if the storage is busy

Storage Plugin

Description

Storage Implementations

Internal Flash

SPI Flash

Modules

Data Structures

Macros

Functions

Function Documentation

Storage
Plugin