Defiunition of the application bootloader interface.
Macros |
|
#define | BOOTLOADER_SEGMENT_SIZE_LOG2 6 |
This is the working unit of data for the app bootloader. We want it as big as possible, but it must be a factor of the NVM page size and fit into a single Zigbee packet. We choose 2^6 = 64 bytes.
|
|
#define | BOOTLOADER_SEGMENT_SIZE (1 << BOOTLOADER_SEGMENT_SIZE_LOG2 ) |
This is the working unit of data for the app bootloader. We want it as big as possible, but it must be a factor of the NVM page size and fit into a single Zigbee packet. We choose 2^6 = 64 bytes.
|
|
#define | BL_IMAGE_IS_VALID_CONTINUE ((uint16_t)0xFFFF) |
Define a numerical value for checking image validity when calling the image interface functions.
|
Functions |
|
uint8_t | halAppBootloaderInit (void) |
Call this function as part of your application initialization to ensure the storage mechanism is ready to use. Note: some earlier drivers may assert instead of returning an error if initialization fails.
|
|
const HalEepromInformationType * | halAppBootloaderInfo (void) |
Call this function to get information about the attached storage device and its capabilities.
|
|
void | halAppBootloaderShutdown (void) |
Call this function when you are done accessing the storage mechanism to ensure that it is returned to its lowest power state.
|
|
void | halAppBootloaderImageIsValidReset (void) |
Call this function once before checking for a valid image to reset the call flag.
|
|
uint16_t | halAppBootloaderImageIsValid (void) |
Reads the app image out of storage, calculates the total file CRC to verify the image is intact.
|
|
EmberStatus | halAppBootloaderInstallNewImage (void) |
Invokes the bootloader to install the application in storage. This function resets the device to start the bootloader code and does not return!
|
|
uint8_t | halAppBootloaderWriteRawStorage (uint32_t address, const uint8_t *data, uint16_t len) |
Writes data to the specified raw storage address and length without being restricted to any page size 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.
|
|
uint8_t | halAppBootloaderReadRawStorage (uint32_t address, uint8_t *data, uint16_t len) |
Reads data from the specified raw storage address and length without being restricted to any page size Note: Not all storage implementations support accesses that are not page aligned, refer to the
HalEepromInformationType
structure for more information.
|
|
uint8_t | halAppBootloaderEraseRawStorage (uint32_t address, uint32_t len) |
Erases the specified region of the storage 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
halAppBootloaderStorageBusy()
API may be used to determine when the last erase operation has completed. Erase timing information can be found in the
HalEepromInformationType
structure.
|
|
bool | halAppBootloaderStorageBusy (void) |
Determine if the attached storage device is still busy performing the last operation, such as a write or an erase.
|
|
uint8_t | halAppBootloaderReadDownloadSpace (uint16_t pageToBeRead, uint8_t *destRamBuffer) |
Converts pageToBeRead to an address and the calls storage read function. Note: This function is deprecated. It has been replaced by
halAppBootloaderReadRawStorage()
|
|
uint8_t | halAppBootloaderWriteDownloadSpace (uint16_t pageToBeWritten, uint8_t *RamPtr) |
Converts pageToBeWritten to an address and calls the storage write function. Note: This function is deprecated. It has been replaced by
halAppBootloaderWriteRawStorage()
|
|
uint8_t | halAppBootloaderGetImageData (uint32_t *timestamp, uint8_t *userData) |
Read the application image data from storage.
|
|
uint16_t | halAppBootloaderGetVersion (void) |
Returns the application bootloader version.
|
|
uint16_t | halAppBootloaderGetRecoveryVersion (void) |
Returns the recovery image version.
|
|
bool | halAppBootloaderSupportsIbr (void) |
Return a value indicating whether the app bootloader supports IBRs.
|
Detailed Description
Some functions in this file return an
EmberStatus
value. See
error-def.h
for definitions of all
EmberStatus
return values.
See
bootloader-interface-app.h
for source code.
Macro Definition Documentation
#define BL_IMAGE_IS_VALID_CONTINUE ((uint16_t)0xFFFF) |
#define BOOTLOADER_SEGMENT_SIZE (1 << BOOTLOADER_SEGMENT_SIZE_LOG2 ) |
#define BOOTLOADER_SEGMENT_SIZE_LOG2 6 |
Function Documentation
uint8_t halAppBootloaderEraseRawStorage | ( | uint32_t |
address,
|
uint32_t |
len
|
||
) |
- Parameters
-
address
Address to start erasing len
Length of the region to be erased
- Returns
- EEPROM_SUCCESS or EEPROM_ERR .
uint8_t halAppBootloaderGetImageData | ( | uint32_t * |
timestamp,
|
uint8_t * |
userData
|
||
) |
- Parameters
-
timestamp
write the image timestamp to this data pointer. userData
write the user data field to this buffer.
- Returns
- EEPROM_SUCCESS or EEPROM_ERR
uint16_t halAppBootloaderGetRecoveryVersion | ( | void |
|
) |
uint16_t halAppBootloaderGetVersion | ( | void |
|
) |
uint16_t halAppBootloaderImageIsValid | ( | void |
|
) |
Caller should loop calling this function while it returns BL_IMAGE_IS_VALID_CONTINUE to get final result. This allows caller to service system needs during validation.
Call halAppBootloaderImageIsValidReset() before calling halAppBootloaderImageIsValid() to reset the call flag.
Here is an example application call:
- Returns
-
One of the following:
- Number of pages in a valid image
- 0 for an invalid image
- BL_IMAGE_IS_VALID_CONTINUE (-1) to continue to iterate for the final result.
void halAppBootloaderImageIsValidReset | ( | void |
|
) |
const HalEepromInformationType * halAppBootloaderInfo | ( | void |
|
) |
- Returns
- A pointer to a HalEepromInformationType data structure, or NULL if the driver does not support this API
uint8_t halAppBootloaderInit | ( | void |
|
) |
- Returns
- EEPROM_SUCCESS or EEPROM_ERR_INVALID_CHIP
EmberStatus halAppBootloaderInstallNewImage | ( | void |
|
) |
uint8_t halAppBootloaderReadDownloadSpace | ( | uint16_t |
pageToBeRead,
|
uint8_t * |
destRamBuffer
|
||
) |
- Parameters
-
pageToBeRead
pass in the page to be read. This will be converted to the appropriate address. Pages are EEPROM_PAGE_SIZE long. destRamBuffer
a pointer to the buffer to write to.
- Returns
- EEPROM_SUCCESS or EEPROM_ERR .
uint8_t halAppBootloaderReadRawStorage | ( | uint32_t |
address,
|
uint8_t * |
data,
|
||
uint16_t |
len
|
||
) |
- Parameters
-
address
Address from which to start reading data data
A pointer to a buffer where data should be read into len
Length of the data to read
- Returns
- EEPROM_SUCCESS or EEPROM_ERR .
void halAppBootloaderShutdown | ( | void |
|
) |
bool halAppBootloaderStorageBusy | ( | void |
|
) |
- Returns
- true if still busy or false if not.
bool halAppBootloaderSupportsIbr | ( | void |
|
) |
- Returns
- true if the app bootloader supports IBRs, false otherwise
uint8_t halAppBootloaderWriteDownloadSpace | ( | uint16_t |
pageToBeWritten,
|
uint8_t * |
RamPtr
|
||
) |
- Parameters
-
pageToBeWritten
pass in the page to be written. This will be converted to the appropriate address. Pages are EEPROM_PAGE_SIZE long. RamPtr
a pointer to the data to be written.
- Returns
- EEPROM_SUCCESS or EEPROM_ERR
uint8_t halAppBootloaderWriteRawStorage | ( | uint32_t |
address,
|
const uint8_t * |
data,
|
||
uint16_t |
len
|
||
) |
- Parameters
-
address
Address to start writing data data
A pointer to the buffer of data to write. len
Length of the data to write
- Returns
- EEPROM_SUCCESS or EEPROM_ERR .