Modules#
See Application for detailed documentation.
License#
Copyright 2018 Silicon Laboratories Inc. www.silabs.com
The licensor of this software is Silicon Laboratories Inc. Your use of this software is governed by the terms of Silicon Labs Master Software License Agreement (MSLA) available at www.silabs.com/about-us/legal/master-software-license-agreement. This software is distributed to you in Source Code format and is governed by the sections of the MSLA applicable to Source Code.
/***************************************************************************/
#ifndef __BOOTLOADER_EEPROM_H__
#define __BOOTLOADER_EEPROM_H__
#define EEPROM_PAGE_SIZE (128ul)
#define EEPROM_FIRST_PAGE (0)
#define EEPROM_IMAGE_START (EEPROM_FIRST_PAGE * EEPROM_PAGE_SIZE)
#define EEPROM_SUCCESS 0U
#define EEPROM_ERR 1U
#define EEPROM_ERR_MASK 0x80U
#define EEPROM_ERR_PG_BOUNDARY 0x81U
#define EEPROM_ERR_PG_SZ 0x82U
#define EEPROM_ERR_WRT_DATA 0x83U
#define EEPROM_ERR_IMG_SZ 0x84U
#define EEPROM_ERR_ADDR 0x85U
#define EEPROM_ERR_INVALID_CHIP 0x86U
#define EEPROM_ERR_ERASE_REQUIRED 0x87U
#define EEPROM_ERR_NO_ERASE_SUPPORT 0x88U
uint8_t halEepromInit(void);
void halEepromShutdown(void);
typedef struct {
uint16_t version;
uint16_t capabilitiesMask;
uint16_t pageEraseMs;
uint16_t partEraseTime;
uint32_t pageSize;
uint32_t partSize;
const char * const partDescription;
uint8_t wordSizeBytes;
} HalEepromInformationType;
#define EEPROM_INFO_VERSION (0x0202)
#define EEPROM_INFO_MAJOR_VERSION (0x0200)
#define EEPROM_INFO_MAJOR_VERSION_MASK (0xFF00)
// *** Eeprom info version history: ***
// 0x0202 - Changed partEraseMs to be called partEraseTime and added an
// EEPROM_CAPABILITIES field to indicate if partEraseTime is in
// seconds or milliseconds.
// 0x0102 - Added a word size field to specify the number of bytes per flash
// word in the EEPROM. Writes should always be aligned to the word
// size and have a length that is a multiple of the word size.
// 0x0101 - Initial version
#define EEPROM_INFO_MIN_VERSION_WITH_WORD_SIZE_SUPPORT 0x0102U
#define EEPROM_CAPABILITIES_ERASE_SUPPORTED (0x0001U)
#define EEPROM_CAPABILITIES_PAGE_ERASE_REQD (0x0002U)
#define EEPROM_CAPABILITIES_BLOCKING_WRITE (0x0004U)
#define EEPROM_CAPABILITIES_BLOCKING_ERASE (0x0008U)
#define EEPROM_CAPABILITIES_PART_ERASE_SECONDS (0x0010U)
const HalEepromInformationType *halEepromInfo(void);
uint32_t halEepromSize(void);
bool halEepromBusy(void);
uint8_t halEepromRead(uint32_t address, uint8_t *data, uint16_t len);
uint8_t halEepromWrite(uint32_t address, const uint8_t *data, uint16_t len);
uint8_t halEepromErase(uint32_t address, uint32_t totalLength);
#ifndef DOXYGEN_SHOULD_SKIP_THIS
// This structure holds information about where we left off when last accessing
// the eeprom.
typedef struct {
uint32_t address;
uint16_t pages;
uint16_t pageBufFinger;
uint16_t pageBufLen;
uint8_t pageBuf[EEPROM_PAGE_SIZE];
} EepromStateType;
#endif //DOXYGEN_SHOULD_SKIP_THIS
#endif //__BOOTLOADER_EEPROM_H__
EEPROM interaction functions.#
The current version of the HalEepromInformationType data structure.
The current version of the HalEepromInformationType data structure.
The current version of the HalEepromInformationType data structure.
The current version of the HalEepromInformationType data structure.
Eeprom capabilites mask that indicates the erase API is supported.
Eeprom capabilites mask that indicates page erasing is required before new data can be written to a device.
Eeprom capabilites mask that indicates that the write routine is blocking on this device.
Eeprom capabilites mask that indicates that the erase routine is blocking on this device.
Eeprom capabilities mask that indicateds that the partEraseTime field of HalEepromInformationType is in seconds instead of the usual millisecondss.
Initialize EEPROM. Note: some earlier drivers may assert instead of returning an error if initialization fails.
Shutdown the EEPROM to conserve power.
Call this function to get information about the external EEPROM and its capabilities.
Return the size of the EEPROM.
Determine if the exernal EEPROM is still busy performing the last operation, such as a write or an erase.
Read from the external EEPROM.
Write to the external EEPROM.
Erases the specified region of the external EEPROM.
Macros#
Definition of an EEPROM page size, in bytes. This definition is deprecated, and should no longer be used.
Define the location of the first page in EEPROM. This definition is deprecated, and should no longer be used.
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 status.
Define EEPROM error status.
Define EEPROM error mask.
Define EEPROM page boundary error.
Define EEPROM page size error.
Define EEPROM write data error.
Define EEPROM image too large error.
Define EEPROM invalid address error.
Define EEPROM chip initialization error.
Define EEPROM erase required error.
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.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| void | N/A |
Returns
halEepromShutdown#
void halEepromShutdown (void )
Shutdown the EEPROM to conserve power.
| 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.
| 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.
| 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.
| 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.
| 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
halEepromWrite#
uint8_t halEepromWrite (uint32_t address, const uint8_t * data, uint16_t len)
Write to the external EEPROM.
| 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.
| 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