StorageComponents

Description

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

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), MX25R3235F (32Mbit ultra low power) 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.
SPI Flash Configurations using SFDP
Configuration parameters for SPI flashes Using JEDEC SFDP Standard.

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)
uint32_t storage_getSpiUsartPPUSATD (uint32_t *ppusatdNr)

Function Documentation

int32_t storage_init ( void )

Initialize the storage component.

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 component.

Returns
BOOTLOADER_OK on success, else error code
int32_t storage_shutdown ( void )

Shutdown storage component.

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 component 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
uint32_t storage_getSpiUsartPPUSATD ( uint32_t * ppusatdNr )

Get PPUSATD word of the (E)USART in use

Parameters
ppusatdNr PPUSATD register number
Returns
Word representing the PPUSATD bit field of the (E)USART in use. 0 if not found.