Modules#

Application#

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.

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()

void

bootloaderAction(bool runRecovery)

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.

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. Documentation#

halEepromInit#

uint8_t halEepromInit (void )

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

Parameters

Type	Direction	Argument Name	Description
void	N/A

Returns

EEPROM_SUCCESS or EEPROM_ERR_INVALID_CHIP

halEepromShutdown#

void halEepromShutdown (void )

Shutdown the EEPROM to conserve power.

Parameters

Type	Direction	Argument Name	Description
void	N/A

halEepromInfo#

const HalEepromInformationType* halEepromInfo (void )

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

Parameters

Type	Direction	Argument Name	Description
void	N/A

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

halEepromSize#

uint32_t halEepromSize (void )

Return the size of the EEPROM.

Parameters

Type	Direction	Argument Name	Description
void	N/A

   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

halEepromBusy#

bool halEepromBusy (void )

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

Parameters

Type	Direction	Argument Name	Description
void	N/A

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.

halEepromRead#

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

Read from the external EEPROM.

Parameters

Type	Direction	Argument Name	Description
uint32_t	N/A	address	The address to start reading from.
uint8_t *	N/A	data	A pointer to where read data is stored.
uint16_t	N/A	len	The length of data to read.

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.

Returns

EEPROM_SUCCESS or EEPROM_ERR

halEepromWrite#

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

Write to the external EEPROM.

Parameters

Type	Direction	Argument Name	Description
uint32_t	N/A	address	The address to start writing to.
const uint8_t *	N/A	data	A pointer to the data to write.
uint16_t	N/A	len	The length of data to write.

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.

Returns

EEPROM_SUCCESS or EEPROM_ERR

halEepromErase#

uint8_t halEepromErase (uint32_t address, uint32_t totalLength)

Erases the specified region of the external EEPROM.

Parameters

Type	Direction	Argument Name	Description
uint32_t	N/A	address	Address to start erasing
uint32_t	N/A	totalLength	Length of the region to be erased

   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.

Returns

EEPROM_SUCCESS or EEPROM_ERR.

Required Custom Functions Documentation#

bootloaderInit#

void bootloaderInit ( runRecovery)

Parameters

Type	Direction	Argument Name	Description
	N/A	runRecovery	If ::true, recover mode is activated. Otherwise, normal image installation is activated.

bootloaderInitCustom#

void bootloaderInitCustom ( runRecovery)

Parameters

Type	Direction	Argument Name	Description
	N/A	runRecovery	If ::true, recover mode is activated. Otherwise, normal image installation is activated.

bootloaderAction#

void bootloaderAction (bool runRecovery)

Parameters

Type	Direction	Argument Name	Description
bool	N/A	runRecovery	If ::true, recover mode is activated. Otherwise, normal image installation is activated.

Available Bootloader Library Functions Documentation#

recoveryMode#

BL_Status recoveryMode (void )

Activates recoveryMode to receive a new image over xmodem.

Parameters

Type	Direction	Argument Name	Description
void	N/A

Returns

BL_SUCCESS if an image was successfully received.

processImage#

BL_Status processImage (bool install)

Processes an image in the external eeprom.

Parameters

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