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.

Application Hardware Abstraction Layer (HAL) API Reference > Custom Bootloader HAL

Data Structures

Macros

EEPROM interaction functions.

Required Custom Functions

Available Bootloader Library Functions

Detailed Description

Macro Definition Documentation

◆ EEPROM_CAPABILITIES_BLOCKING_ERASE

◆ EEPROM_CAPABILITIES_BLOCKING_WRITE

◆ EEPROM_CAPABILITIES_ERASE_SUPPORTED

◆ EEPROM_CAPABILITIES_PAGE_ERASE_REQD

◆ EEPROM_CAPABILITIES_PART_ERASE_SECONDS

◆ EEPROM_ERR

◆ EEPROM_ERR_ADDR

◆ EEPROM_ERR_ERASE_REQUIRED

◆ EEPROM_ERR_IMG_SZ

◆ EEPROM_ERR_INVALID_CHIP

◆ EEPROM_ERR_MASK

◆ EEPROM_ERR_NO_ERASE_SUPPORT

◆ EEPROM_ERR_PG_BOUNDARY

◆ EEPROM_ERR_PG_SZ

◆ EEPROM_ERR_WRT_DATA

◆ EEPROM_FIRST_PAGE

◆ EEPROM_IMAGE_START

◆ EEPROM_INFO_MAJOR_VERSION

◆ EEPROM_INFO_MAJOR_VERSION_MASK

◆ EEPROM_INFO_MIN_VERSION_WITH_WORD_SIZE_SUPPORT

◆ EEPROM_INFO_VERSION

◆ EEPROM_PAGE_SIZE

◆ EEPROM_SUCCESS

Function Documentation

◆ bootloaderAction()

◆ bootloaderInit()

◆ bootloaderInitCustom()

◆ halEepromBusy()

◆ halEepromErase()

◆ halEepromInfo()

◆ halEepromInit()

◆ halEepromRead()

◆ halEepromShutdown()

◆ halEepromSize()

◆ halEepromWrite()

◆ processImage()

◆ recoveryMode()

Application
Hardware Abstraction Layer (HAL) API Reference > Custom Bootloader HAL