Application bootloader and generic EEPROM Interface.

Data Structures

struct HalEepromInformationType
This structure defines a variety of information about the attached external EEPROM device.

Macros

#define EEPROM_PAGE_SIZE (128ul)
Definition of an EEPROM page size, in bytes. This definition is deprecated, and should no longer be used.
#define EEPROM_FIRST_PAGE (0)
Define the location of the first page in EEPROM. This definition is deprecated, and should no longer be used.
#define EEPROM_IMAGE_START ( EEPROM_FIRST_PAGE * EEPROM_PAGE_SIZE )
Define the location of the image start in EEPROM as a function of the EEPROM_FIRST_PAGE and EEPROM_PAGE_SIZE . This definition is deprecated, and should no longer be used.
#define EEPROM_SUCCESS 0U
Define EEPROM success status.
#define EEPROM_ERR 1U
Define EEPROM error status.
#define EEPROM_ERR_MASK 0x80U
Define EEPROM error mask.
#define EEPROM_ERR_PG_BOUNDARY 0x81U
Define EEPROM page boundary error.
#define EEPROM_ERR_PG_SZ 0x82U
Define EEPROM page size error.
#define EEPROM_ERR_WRT_DATA 0x83U
Define EEPROM write data error.
#define EEPROM_ERR_IMG_SZ 0x84U
Define EEPROM image too large error.
#define EEPROM_ERR_ADDR 0x85U
Define EEPROM invalid address error.
#define EEPROM_ERR_INVALID_CHIP 0x86U
Define EEPROM chip initialization error.
#define EEPROM_ERR_ERASE_REQUIRED 0x87U
Define EEPROM erase required error.
#define EEPROM_ERR_NO_ERASE_SUPPORT 0x88U
Define EEPROM error for no erase support.

EEPROM interaction functions.

uint8_t halEepromInit (void)
Initialize EEPROM. Note: some earlier drivers may assert instead of returning an error if initialization fails.
void halEepromShutdown (void)
Shutdown the EEPROM to conserve power.
const HalEepromInformationType * halEepromInfo (void)
Call this function to get information about the external EEPROM and its capabilities.
uint32_t halEepromSize (void)
Return the size of the EEPROM.
bool halEepromBusy (void)
Determine if the exernal EEPROM is still busy performing the last operation, such as a write or an erase.
uint8_t halEepromRead (uint32_t address, uint8_t *data, uint16_t len)
Read from the external EEPROM.
uint8_t halEepromWrite (uint32_t address, const uint8_t *data, uint16_t len)
Write to the external EEPROM.
uint8_t halEepromErase (uint32_t address, uint32_t totalLength)
Erases the specified region of the external EEPROM.
#define EEPROM_INFO_VERSION (0x0202)
The current version of the HalEepromInformationType data structure.
#define EEPROM_INFO_MAJOR_VERSION (0x0200)
The current version of the HalEepromInformationType data structure.
#define EEPROM_INFO_MAJOR_VERSION_MASK (0xFF00)
The current version of the HalEepromInformationType data structure.
#define EEPROM_INFO_MIN_VERSION_WITH_WORD_SIZE_SUPPORT 0x0102U
The current version of the HalEepromInformationType data structure.
#define EEPROM_CAPABILITIES_ERASE_SUPPORTED (0x0001U)
Eeprom capabilites mask that indicates the erase API is supported.
#define EEPROM_CAPABILITIES_PAGE_ERASE_REQD (0x0002U)
Eeprom capabilites mask that indicates page erasing is required before new data can be written to a device.
#define EEPROM_CAPABILITIES_BLOCKING_WRITE (0x0004U)
Eeprom capabilites mask that indicates that the write routine is blocking on this device.
#define EEPROM_CAPABILITIES_BLOCKING_ERASE (0x0008U)
Eeprom capabilites mask that indicates that the erase routine is blocking on this device.
#define EEPROM_CAPABILITIES_PART_ERASE_SECONDS (0x0010U)
Eeprom capabilities mask that indicateds that the partEraseTime field of HalEepromInformationType is in seconds instead of the usual millisecondss.

Required Custom Functions

void bootloaderInit ()
Drives the app bootloader. If the ::runRecovery parameter is ::true, the recovery mode should be activated, otherwise it should attempt to install an image. This function should not return. It should always exit by resetting the the bootloader.
void bootloaderInitCustom ()
Drives the app bootloader. If the ::runRecovery parameter is ::true, the recovery mode should be activated, otherwise it should attempt to install an image. This function should not return. It should always exit by resetting the the bootloader.
void bootloaderAction (bool runRecovery)
Drives the app bootloader. If the ::runRecovery parameter is ::true, the recovery mode should be activated, otherwise it should attempt to install an image. This function should not return. It should always exit by resetting the the bootloader.

Available Bootloader Library Functions

Functions implemented by the bootloader library that may be used by custom functions.

BL_Status recoveryMode (void)
Activates recoveryMode to receive a new image over xmodem.
BL_Status processImage (bool install)
Processes an image in the external eeprom.

Detailed Description

Application bootloader and generic EEPROM Interface.

The file bootloader-eeprom.h defines generic EEPROM parameters.

Changing EEPROM size will change the size of the application image space without changing the size or relative location of the recovery and reserved sections. See eeprom.c for more information on modifying EEPROM functionality.

See bootloader-eeprom.h for source code.

See app-bootloader.h for source code.

Macro Definition Documentation

EEPROM_CAPABILITIES_BLOCKING_ERASE

#define EEPROM_CAPABILITIES_BLOCKING_ERASE   (0x0008U)

Eeprom capabilites mask that indicates that the erase routine is blocking on this device.

EEPROM_CAPABILITIES_BLOCKING_WRITE

#define EEPROM_CAPABILITIES_BLOCKING_WRITE   (0x0004U)

Eeprom capabilites mask that indicates that the write routine is blocking on this device.

EEPROM_CAPABILITIES_ERASE_SUPPORTED

#define EEPROM_CAPABILITIES_ERASE_SUPPORTED   (0x0001U)

Eeprom capabilites mask that indicates the erase API is supported.

EEPROM_CAPABILITIES_PAGE_ERASE_REQD

#define EEPROM_CAPABILITIES_PAGE_ERASE_REQD   (0x0002U)

Eeprom capabilites mask that indicates page erasing is required before new data can be written to a device.

EEPROM_CAPABILITIES_PART_ERASE_SECONDS

#define EEPROM_CAPABILITIES_PART_ERASE_SECONDS   (0x0010U)

Eeprom capabilities mask that indicateds that the partEraseTime field of HalEepromInformationType is in seconds instead of the usual millisecondss.

EEPROM_ERR

#define EEPROM_ERR   1U

Define EEPROM error status.

EEPROM_ERR_ADDR

#define EEPROM_ERR_ADDR   0x85U

Define EEPROM invalid address error.

EEPROM_ERR_ERASE_REQUIRED

#define EEPROM_ERR_ERASE_REQUIRED   0x87U

Define EEPROM erase required error.

EEPROM_ERR_IMG_SZ

#define EEPROM_ERR_IMG_SZ   0x84U

Define EEPROM image too large error.

EEPROM_ERR_INVALID_CHIP

#define EEPROM_ERR_INVALID_CHIP   0x86U

Define EEPROM chip initialization error.

EEPROM_ERR_MASK

#define EEPROM_ERR_MASK   0x80U

Define EEPROM error mask.

EEPROM_ERR_NO_ERASE_SUPPORT

#define EEPROM_ERR_NO_ERASE_SUPPORT   0x88U

Define EEPROM error for no erase support.

EEPROM_ERR_PG_BOUNDARY

#define EEPROM_ERR_PG_BOUNDARY   0x81U

Define EEPROM page boundary error.

EEPROM_ERR_PG_SZ

#define EEPROM_ERR_PG_SZ   0x82U

Define EEPROM page size error.

EEPROM_ERR_WRT_DATA

#define EEPROM_ERR_WRT_DATA   0x83U

Define EEPROM write data error.

EEPROM_FIRST_PAGE

#define EEPROM_FIRST_PAGE   (0)

Define the location of the first page in EEPROM. This definition is deprecated, and should no longer be used.

EEPROM_IMAGE_START

#define EEPROM_IMAGE_START   ( EEPROM_FIRST_PAGE * EEPROM_PAGE_SIZE )

Define the location of the image start in EEPROM as a function of the EEPROM_FIRST_PAGE and EEPROM_PAGE_SIZE . This definition is deprecated, and should no longer be used.

EEPROM_INFO_MAJOR_VERSION

#define EEPROM_INFO_MAJOR_VERSION   (0x0200)

The current version of the HalEepromInformationType data structure.

EEPROM_INFO_MAJOR_VERSION_MASK

#define EEPROM_INFO_MAJOR_VERSION_MASK   (0xFF00)

The current version of the HalEepromInformationType data structure.

EEPROM_INFO_MIN_VERSION_WITH_WORD_SIZE_SUPPORT

#define EEPROM_INFO_MIN_VERSION_WITH_WORD_SIZE_SUPPORT   0x0102U

The current version of the HalEepromInformationType data structure.

EEPROM_INFO_VERSION

#define EEPROM_INFO_VERSION   (0x0202)

The current version of the HalEepromInformationType data structure.

EEPROM_PAGE_SIZE

#define EEPROM_PAGE_SIZE   (128ul)

Definition of an EEPROM page size, in bytes. This definition is deprecated, and should no longer be used.

EEPROM_SUCCESS

#define EEPROM_SUCCESS   0U

Define EEPROM success status.

Function Documentation

bootloaderAction()

void bootloaderAction ( bool runRecovery )

Drives the app bootloader. If the ::runRecovery parameter is ::true, the recovery mode should be activated, otherwise it should attempt to install an image. This function should not return. It should always exit by resetting the the bootloader.

Parameters
runRecovery If ::true, recover mode is activated. Otherwise, normal image installation is activated.

bootloaderInit()

void bootloaderInit ( )

Drives the app bootloader. If the ::runRecovery parameter is ::true, the recovery mode should be activated, otherwise it should attempt to install an image. This function should not return. It should always exit by resetting the the bootloader.

Parameters
runRecovery If ::true, recover mode is activated. Otherwise, normal image installation is activated.

bootloaderInitCustom()

void bootloaderInitCustom ( )

Drives the app bootloader. If the ::runRecovery parameter is ::true, the recovery mode should be activated, otherwise it should attempt to install an image. This function should not return. It should always exit by resetting the the bootloader.

Parameters
runRecovery If ::true, recover mode is activated. Otherwise, normal image installation is activated.

halEepromBusy()

bool halEepromBusy ( void )

Determine if the exernal EEPROM is still busy performing the last operation, such as a write or an erase.

The format of this call must not be altered. However, the content can be changed to work with a different device.

Returns
true if still busy or false if not.

halEepromErase()

uint8_t halEepromErase ( uint32_t address,
uint32_t totalLength
)

Erases the specified region of the external EEPROM.

The format of this call must not be altered. However, the content can be changed to work with a different device. Note: Most devices require the specified region to be page aligned, and will return an error if an unaligned region is specified. Note: Many devices take an extremely long time to perform an erase operation. When erasing a large region, it may be preferable to make multiple calls to this API so that other application functionality can be performed while the erase is in progress. The halEepromBusy() API may be used to determine when the last erase operation has completed. Erase timing information can be found in the HalEepromInformationType structure.

Parameters
address Address to start erasing
len Length of the region to be erased
Returns
EEPROM_SUCCESS or EEPROM_ERR .

halEepromInfo()

const HalEepromInformationType * halEepromInfo ( void )

Call this function to get information about the external EEPROM and its capabilities.

The format of this call must not be altered. However, the content can be changed to work with a different device.

Returns
A pointer to a HalEepromInformationType data structure, or NULL if the driver does not support this API

halEepromInit()

uint8_t halEepromInit ( void )

Initialize EEPROM. Note: some earlier drivers may assert instead of returning an error if initialization fails.

Returns
EEPROM_SUCCESS or EEPROM_ERR_INVALID_CHIP

halEepromRead()

uint8_t halEepromRead ( uint32_t address,
uint8_t * data,
uint16_t len
)

Read from the external EEPROM.

This is the standard external EEPROM read function. The format of this call must not be altered. However, the content can be changed to work with a different device. Note: Not all storage implementations support accesses that are not page aligned, refer to the HalEepromInformationType structure for more information.

Parameters
address The address to start reading from.
data A pointer to where read data is stored.
len The length of data to read.
Returns
EEPROM_SUCCESS or EEPROM_ERR

halEepromShutdown()

void halEepromShutdown ( void )

Shutdown the EEPROM to conserve power.

halEepromSize()

uint32_t halEepromSize ( void )

Return the size of the EEPROM.

The format of this call must not be altered. However, the content can be changed to work with a different device. Internal use only. No exposure to application

Returns
int32_t size

halEepromWrite()

uint8_t halEepromWrite ( uint32_t address,
const uint8_t * data,
uint16_t len
)

Write to the external EEPROM.

This is the standard external EEPROM write function. The format of this call must not be altered. However, the content can be changed to work with a different device. Note: Not all storage implementations support accesses that are not page aligned, refer to the HalEepromInformationType structure for more information. Note: Some storage devices require contents to be erased before new data can be written, and will return an EEPROM_ERR_ERASE_REQUIRED error if write is called on a location that is not already erased. Refer to the HalEepromInformationType structure to see if the attached storage device requires erasing.

Parameters
address The address to start writing to.
data A pointer to the data to write.
len The length of data to write.
Returns
EEPROM_SUCCESS or EEPROM_ERR

processImage()

BL_Status processImage ( bool install )

Processes an image in the external eeprom.

Parameters
install If ::false, it will simply validate the image without touching main flash. If ::true, the image will be programmed to main flash.
Returns
BL_SUCCESS if an image was successfully installed/validated

recoveryMode()

BL_Status recoveryMode ( void )

Activates recoveryMode to receive a new image over xmodem.

Returns
BL_SUCCESS if an image was successfully received.