Storage

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_OKon success
BOOTLOADER_ERROR_INIT_STORAGEon 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_OKon success
BOOTLOADER_ERROR_INIT_STORAGEon failure
void storage_getInfo ( BootloaderStorageInformation_t info)

Get information about the storage plugin running on the device.

Parameters
[out]infoPointer 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]slotIdSlot ID to get info about
[out]slotPointer 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]contextParsing context. Should be allocated by the application and initialized by calling storage_initParseSlot before calling this function.
[out]appInfoPointer to ApplicationData_t struct
[out]bootloaderVersionPointer 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]slotIdSlot to check for valid image
[in]contextPointer to BootloaderParserContext_t struct
[in]contextSizeLength 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]contextPointer to BootloaderImageParsingContext_t struct
[in]metadataCallbackFunctionpointer 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
slotIdSlot 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
slotIdSlot ID to bootload from
versionVersion 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
slotIdSlot ID to bootload from
versionCached 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
slotIdID 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
slotIdID of the slot.
offsetThe offset into the slot in bytes.
bufferPointer to buffer to store read data in.
numBytesNumber 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
slotIdID of the slot.
offsetThe offset into the slot in bytes.
dataPointer to data to write.
numBytesLength 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
addressThe raw address of the storage.
bufferPointer to the buffer to store read data in.
numBytesNumber 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
addressThe raw address of the storage.
dataPointer to data to write.
numBytesLength 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
addressStart address of the region to erase
lengthNumber 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