Update Lib API
danger
this is a legacy library and thus not supported by Toradex anymore. We recommend that you use the new libraries for all Toradex modules. Please see the Toradex CE Libraries and Code Samples for up-to-date information.
This library allows you to backup and update (restore) one or multiple flash regions. At the moment the following regions are supported: Bootloader, Config Block, OS Image, Registry, FileSystem. More...
Data Structures
struct UDL_REGIONINFOMacros | |
#define | UDL_VER_MAJ 1 |
Version Info. More... | |
#define | UDL_VER_MIN 10 |
Library Subversion. More... | |
#define | UDL_VER_BUILD 0 |
Library Build. More... | |
#define | UDL_MAX_REGIONS 8 |
Region count + 1, adjust this value when inserting new regions. More... | |
#define | UDL_F_INVALID_REGION (1 << 0) |
This region is invalid (i.e. not found). More... | |
#define | UDL_F_FAILSAFE (1 << 1) |
Indicates that the fail safe feature is enabled. More... | |
#define | UDL_F_USE_ECC (1 << 2) |
Indicates to try to use ECC to read this region. More... | |
Typedefs | |
typedef BOOL(* | PUDL_CALBACK_PROC_P1 )(void *pParam1) |
typedef BOOL(* | PUDL_CALBACK_PROC_2 )(DWORD param1, DWORD param2) |
typedef BOOL(* | PUDL_CALBACK_PROC_3 )(DWORD param1, DWORD param2, DWORD param3) |
Enumerations | |
enum | UDL_REGION_ID { UDL_NO_REGION = 0, UDL_BOOTLOADER = 1 << 0, UDL_CONFIG_BLOCK = 1 << 1, UDL_OS_IMAGE = 1 << 2, UDL_REGISTRY = 1 << 3, UDL_FILE_SYSTEM = 1 << 4, UDL_2ND_BOOTLOADER = 1 << 5, UDL_CPLD = 1 << 10, UDL_ANY_BIN_REGION = 1 << 31, UDL_ALL_REGIONS = 0xFFFFFFFF } |
UpdateLib type definitions. More... | |
enum | UDL_RET_TYPE { UDL_SUCCESS = 0, UDL_ERROR, UDL_USER_ABORT, UDL_NOT_INITIALIZED, UDL_HW_NOT_SUPPORTED, UDL_INVALID_FILE_PATH, UDL_INVALID_BIN_FILE, UDL_INVALID_FILE_VERSION, UDL_FILE_WRITE_ERROR, UDL_INSUFFICIENT_MEMORY, UDL_RANGE_VERIFICATION_FAILED, UDL_REGION_NOT_FOUND, UDL_REGION_INVALID, UDL_FLASH_INIT_ERROR, UDL_FLASH_READ_ERROR, UDL_FLASH_WRITE_ERROR, UDL_FLASH_ERASE_ERROR, UDL_CRC_ERROR, UDL_WRITE_VERIFICATION_FAILED, UDL_FILE_SYSTEM_ERROR, UDL_FILE_SYSTEM_DRIVER_LOAD_ERROR, UDL_FILE_SYSTEM_FORMATING_ERROR, UDL_CPLD_NOT_FOUND, UDL_CPLD_READ_WRITE_ERROR, UDL_DISMOUNT_ERROR } |
Detailed Description
This library allows you to backup and update (restore) one or multiple flash regions.
At the moment the following regions are supported:
Bootloader, Config Block, OS Image, Registry, FileSystem.
At the moment the following regions are supported:
Bootloader, Config Block, OS Image, Registry, FileSystem.
- Copyright
- Copyright (c) 2012 Toradex AG
- Author
- roman.schnarwiler
- Rev
- 2844
- Date
- 2015-06-18 14:55:51 +0200 (Do, 18 Jun 2015)
- Target Platforms:
- PXAxxx,T20
- Caveats:
- When updating multiple flash regions these regions have to be contiguous.
It's not allowed to backup e.g. Bootloader and OS Image without backing-up the Config Block!
Only one store with the profile name "Internal Flash" is allowed when performing Flash filesystem backup/update.
Macro Definition Documentation
#define UDL_F_FAILSAFE (1 << 1) |
Indicates that the fail safe feature is enabled.
#define UDL_F_INVALID_REGION (1 << 0) |
This region is invalid (i.e. not found).
#define UDL_F_USE_ECC (1 << 2) |
Indicates to try to use ECC to read this region.
#define UDL_MAX_REGIONS 8 |
Region count + 1, adjust this value when inserting new regions.
#define UDL_VER_BUILD 0 |
Library Build.
#define UDL_VER_MAJ 1 |
Version Info.
Major Library Version
Major Library Version
#define UDL_VER_MIN 10 |
Library Subversion.
Typedef Documentation
typedef BOOL(* PUDL_CALBACK_PROC_2)(DWORD param1, DWORD param2) |
typedef BOOL(* PUDL_CALBACK_PROC_3)(DWORD param1, DWORD param2, DWORD param3) |
typedef BOOL(* PUDL_CALBACK_PROC_P1)(void *pParam1) |
Enumeration Type Documentation
enum UDL_REGION_ID |
enum UDL_RET_TYPE |
Function Documentation
UDL_RET_TYPE UDLBackupToFile | ( | TCHAR * | pBinPath, |
UDL_REGION_ID | backupRegions, | ||
PUDL_CALBACK_PROC_P1 | ImageInfo, | ||
PUDL_CALBACK_PROC_3 | SectionInfo, | ||
PUDL_CALBACK_PROC_2 | WriteProgress | ||
) |
Creates a backup of the given regions and saves it into a bin file.
- Parameters
[in] pBinPath Pointer to a TCHAR string containing the file path of the .bin file
for backup process.[in] backupRegions Defines the regions to backup from flash. UDL_ALL_REGIONS creates a backup
of all valid regions of a device.[in] ImageInfo Function pointer to a callback function which is called at the beginning
of the backup process returning total image start and size.
Set this parameter to NULL if not required.
BOOL ImageInfo(UDL_REGIONINFO *imgInfo)- pImgInfo: Pointer to UDL_RETIONINFO structure which includes the region
IDs, the total start and total length of the backup image. - Return Value:
- TRUE: Continue backup process
- FALSE: Stop backup and exit UDLBackUpToFile (UDL_USER_ABORT)
[in] SectionInfo Function pointer to a callback function which is called before backing-up
a new section returning information about the section.
Set this parameter to NULL if not required.
BOOL SectionInfo(DWORD SectionStart, DWORD SectionLen, DWORD SectionCRC)- SectionStart: Start of the current section
- SectionLen: Length of the current section
- SectionCRC: This value is always set to 0.
- Return Value:
- TRUE: Continue backup process
- FALSE: Stop backup and exit UDLBackUpToFile (UDL_USER_ABORT)
[in] WriteProgress Function pointer to a callback function which is called during
writing the bin file. Set this parameter to NULL if not required.
BOOL WriteProgress(DWORD writtenSectionLen, DWORD writtenTotalLen)- writtenSectionLen: Number of bytes of the current section which are already
written to the file. - writtenTotalLen: Total number of bytes which are already
written to the file. - Return Value:
- TRUE: Continue backup process
- FALSE: Stop backup and exit UDLBackUpToFile (UDL_USER_ABORT)
- pImgInfo: Pointer to UDL_RETIONINFO structure which includes the region
- Return values
UDL_SUCCESS UDL_NOT_INITIALIZED UDL_INVALID_FILE_PATH UDL_REGION_NOT_FOUND UDL_REGION_INVALID UDL_FILE_WRITE_ERROR UDL_MEM_ALLOC_FAILED UDL_USER_ABORT UDL_FLASH_READ_ERROR UDL_FILE_SYSTEM_ERROR
UDL_RET_TYPE UDLCheckRange | ( | UDL_REGION_ID * | pAllowedRegions, |
DWORD | start, | ||
DWORD | length | ||
) |
Checks the given range and reports an error if a not allowed region gets touched.
- Parameters
[in] start Start address of the range in flash [in] length Length of the range in flash [in,out] pAllowedRegions In: Pointer to a UDL_REGION_ID structure that contains the allowed regions
to be touched by the given range
Out: Returns the regions touched by the given range
- Return values
UDL_SUCCESS UDL_NOT_INITIALIZED UDL_RANGE_VERIFICATION_FAILED
UDL_RET_TYPE UDLClearRegistry | ( | void | ) |
Clear the registry in flash.
- Return values
UDL_SUCCESS UDL_ERROR Remarks: The registry in flash is cleared. This doesn't change the current registry in a running system. The effect of the cleared flash registry shows up after a coldboot only.
UDL_RET_TYPE UDLDeInit | ( | void | ) |
UDL_RET_TYPE UDLDoUpdate | ( | PUDL_CALBACK_PROC_2 | EraseProgress, |
PUDL_CALBACK_PROC_3 | SectionInfo, | ||
PUDL_CALBACK_PROC_2 | WriteProgress | ||
) |
Writes the content of the bin file set by UDLSetBinFile to flash.
- Parameters
[in] EraseProgress Function pointer to a callback function which is called during
erasing of the flash or formatting stores (no feedback during formatting).
Formatting mode: Driver unload/load indication: totsize = 0, done = 1
Formatting mode: Start format inication: totsize = 0, done = 2
Formatting mode: End format indication: totsize = 0, done = 3
Set this parameter to NULL if not required.
BOOL EraseProgress(DWORD done, DWORD totsize)- done: Number of bytes already erased.
- totsize: Total number of bytes to be erased.
- Return Value:
- TRUE: Continue erasing
- FALSE: Stop erasing and exit UDLDoUpdate with the following error codes:
UDL_USER_ABORT when formatting/unloading or UDL_FLASH_ERASE_ERROR when erasing
[in] SectionInfo Function pointer to a callback function which is called before updating
a new section returning information about the section.
Set this parameter to NULL if not required.
BOOL SectionInfo(DWORD SectionStart, DWORD SectionLen, DWORD SectionCRC)- SectionStart: Start of the current section
- SectionLen: Length of the current section
- SectionCRC: CRC of the current section
- Return Value:
- TRUE: Continue update process
- FALSE: Stop update process and exit UDLDoUpdate (UDL_USER_ABORT)
[in] WriteProgress Function pointer to a callback function which is called during
writing to the flash. Set this parameter to NULL if not required.
BOOL WriteProgress(DWORD writtenSectionLen, DWORD writtenTotalLen)- writtenSectionLen: Number of bytes of the current section which are already
written to the flash. - writtenTotalLen: Total number of bytes which are already
written to the flash. - Return Value:
- TRUE: Continue update process
- FALSE: Stop update process and exit UDLDoUpdate (UDL_USER_ABORT)
- Return values
UDL_SUCCESS UDL_NOT_INITIALIZED UDL_INVALID_FILE_PATH UDL_INVALID_BIN_FILE UDL_INVALID_FILE_VERSION UDL_MEM_ALLOC_FAILED UDL_FLASH_ERASE_ERROR UDL_FLASH_WRITE_ERROR UDL_FLASH_READ_ERROR UDL_USER_ABORT UDL_WRITE_VERIFICATION_FAILED UDL_FILE_SYSTEM_ERROR UDL_FILE_SYSTEM_DRIVER_LOAD_ERROR UDL_FILE_SYSTEM_FORMATING_ERROR UDL_CPLD_NOT_FOUND UDL_CPLD_READ_WRITE_ERROR
UDL_RET_TYPE UDLEraseRegion | ( | UDL_REGION_ID | regID, |
PUDL_CALBACK_PROC_2 | EraseProgress | ||
) |
Erases the specified regions in Flash.
- Parameters
[in] regID Defines the regions to delete. Regions don't have to be contiguous. [in] EraseProgress Function pointer to a callback function which is called during
erasing of the flash.
The totsize is replied for every single region separately.
Set this parameter to NULL if not required.
BOOL EraseProgress(DWORD done, DWORD totsize)- done: Number of bytes already erased.
- totsize: Total number of bytes to be erased.
- Return Value:
- TRUE: Continue erasing
- FALSE: Stop erasing and exit UDLEraseRegion (UDL_FLASH_ERASE_ERROR)
- Return values
UDL_SUCCESS UDL_NOT_INITIALIZED UDL_REGION_NOT_FOUND UDL_FLASH_ERASE_ERROR Remarks: Take care when using this function. This function performs a Flash erase action, not a formatting action! E.g. ConfigBlock also loses MAC address info etc.
void UDLGetLibVersion | ( | DWORD * | pVerMaj, |
DWORD * | pVerMin, | ||
DWORD * | pBuild | ||
) |
Returns the library Version.
- Parameters
[out] pVerMaj Returns the major version number. Set this parameter to NULL if not required. [out] pVerMin Returns the minor version number. Set this parameter to NULL if not required. [out] pBuild Returns the build number. Set this parameter to NULL if not required.
UDL_RET_TYPE UDLGetRegionInfo | ( | UDL_REGIONINFO * | pRegInfoTotal, |
UDL_REGIONINFO * | pRegInfoArray | ||
) |
Returns the information of one or multiple regions (start, length, usedBytes).
- Parameters
[in,out] pRegInfoTotal In: pRegInfoTotal->id defines the regions to retrieve the information
The other pRegInfoTotal fields are unused.
Out: pRegInfoTotal contains the information for all given region IDs.[out] pRegInfoArray The array contains a list of UDL_REGIONINFO structures for all given
region IDs. The list ends with an empty UDL_REGIONINFO
structure (id = UDL_NO_REGION)
This parameter could be set to NULL if not required.
- Return values
UDL_SUCCESS UDL_NOT_INITIALIZED UDL_REGION_NOT_FOUND
UDL_RET_TYPE UDLInit | ( | void | ) |
Initializes the UpdateLib. Updates the internal UDL_REGIONINFO structure for all regions.
See UDLUpdateRegInfo for more details.
See UDLUpdateRegInfo for more details.
- Return values
UDL_SUCCESS UDL_HW_NOT_SUPPORTED UDL_FLASH_INIT_ERROR Remarks: UDLInit has to be called once before any of the following functions: - UDLSetBinFile
- UDLCheckRange
- UDLGetRegionInfo
- UDLBackupToFile
- UDLDoUpdate
UDL_RET_TYPE UDLPxaSSUpdate | ( | TCHAR * | pSSPath, |
PUDL_CALBACK_PROC_3 | SectionInfo, | ||
PUDL_CALBACK_PROC_2 | WriteProgress | ||
) |
Writes the content of a SplashScreen bmz file to flash.
- Parameters
[in] pSSPath Pointer to a string containing the path of the bmz file [in] SectionInfo Function pointer to a callback function which is called before updating
a new section returning information about the section.
Set this parameter to NULL if not required.
BOOL SectionInfo(DWORD SectionStart, DWORD SectionLen, DWORD SectionCRC)- SectionStart: Start of the current section
- SectionLen: Length of the current section
- SectionCRC: CRC of the current section
- Return Value:
- TRUE: Continue update process
- FALSE: Stop update process and exit UDLDoUpdate (UDL_USER_ABORT)
[in] WriteProgress Function pointer to a callback function which is called during
writing to the flash. Set this parameter to NULL if not required.
BOOL WriteProgress(DWORD writtenSectionLen, DWORD writtenTotalLen)- writtenSectionLen: Number of bytes of the current section which are already
written to the flash. - writtenTotalLen: Total number of bytes which are already
written to the flash. - Return Value:
- TRUE: Continue update process
- FALSE: Stop update process and exit UDLDoUpdate (UDL_USER_ABORT)
- Return values
UDL_SUCCESS UDL_NOT_INITIALIZED UDL_INVALID_FILE_PATH UDL_FLASH_WRITE_ERROR UDL_USER_ABORT UDL_ERROR
UDL_RET_TYPE UDLReboot | ( | BOOL | clean | ) |
Reboots the system.
- Parameters
[in] clean - TRUE: Perform a coldboot (clean reboot). - FALSE: Perform a warmboot.
- Return values
UDL_SUCCESS (but this would never happen)
UDL_RET_TYPE UDLReleaseBinFile | ( | void | ) |
Release the bin file we set with UDLSetBinFile if not used anymore. Return Value Type: UDL_RET_TYPE
- Return values
UDL_SUCCESS File released UDL_ERROR Could not release file
UDL_RET_TYPE UDLSaveRegistry | ( | void | ) |
Save the registry to flash (RegFlush). Return Value Type: UDL_RET_TYPE:
- Return values
UDL_SUCCESS UDL_ERROR
UDL_RET_TYPE UDLSetBinFile | ( | TCHAR * | pBinPath, |
UDL_REGIONINFO * | pRegInfo, | ||
PUDL_CALBACK_PROC_2 | ReadFileProgress, | ||
BOOL | validate | ||
) |
Sets the bin file for a subsequent UDLDoUpdate command and returns some information
about the content of the bin file.
about the content of the bin file.
- Parameters
[in] pBinPath Pointer to a TCHAR string containing the file path of the .bin file
for update process.[in] ReadFileProgress Function pointer to a callback function which is called during
parsing/validating of the bin file. Set this parameter to NULL if not required.
BOOL ReadFileProgress(DWORD done, DWORD totsize)- done: Bytes already read from file
- totsize: Total number of bytes of the file
- Return Value:
- TRUE: Continue parsing the file.
- FALSE: Stop parsing the file and exit UDLSetBinFile (UDL_USER_ABORT)
[in] validate TRUE: - Validate the bin file (slower)
FALSE: - Don't validate the file (faster)[out] pRegInfo Returns the region info of the complete .bin file (start, length, usedBytes, id)
The pRegInfo.id value can be set to any combination of the following:- UDL_NO_REGION
- UDL_ANY_BIN_REGION (we don't differentiate all regions, we just return a general id)
- UDL_FILE_SYSTEM
- UDL_CPLD
- UDL_FAILSAFE (Caution! This bin file would overwrite the first bootloader,
therefore the whole image gets shifted to bl2start
defined in configblock. See UpdateLibDemo app as reference.)
Set pRegInfo to NULL if not required.
- Return values
UDL_SUCCESS UDL_NOT_INITIALIZED UDL_INVALID_FILE_PATH UDL_INVALID_BIN_FILE UDL_INVALID_FILE_VERSION UDL_CRC_ERROR UDL_USER_ABORT Remarks: Call UDLCheckRange or UDLDoUpdate after this call. The return value can be UDL_SUCCESS although the pRegInfo->id can be UDL_NO_REGION. This is e.g. the case when the bin file is valid but the current running HW doesn't support a certain bin file section (E.g. a CPLD update file on a Colibri PXA270).
UDL_RET_TYPE UDLTegraFlashUpdate | ( | TCHAR * | pNB0Path, |
PUDL_CALBACK_PROC_3 | SectionInfo, | ||
PUDL_CALBACK_PROC_2 | WriteProgress | ||
) |
Writes the content of an nb0 file to flash.
- Parameters
[in] pNB0Path Pointer to a string containing the path of the nb0 file [in] SectionInfo Function pointer to a callback function which is called before updating
a new section returning information about the section.
Set this parameter to NULL if not required.
BOOL SectionInfo(DWORD SectionStart, DWORD SectionLen, DWORD SectionCRC)- SectionStart: Start of the current section
- SectionLen: Length of the current section
- SectionCRC: CRC of the current section
- Return Value:
- TRUE: Continue update process
- FALSE: Stop update process and exit UDLDoUpdate (UDL_USER_ABORT)
[in] WriteProgress Function pointer to a callback function which is called during
writing to the flash. Set this parameter to NULL if not required.
BOOL WriteProgress(DWORD writtenSectionLen, DWORD writtenTotalLen)- writtenSectionLen: Number of bytes of the current section which are already
written to the flash. - writtenTotalLen: Total number of bytes which are already
written to the flash. - Return Value:
- TRUE: Continue update process
- FALSE: Stop update process and exit UDLDoUpdate (UDL_USER_ABORT)
- Return values
UDL_SUCCESS UDL_NOT_INITIALIZED UDL_INVALID_FILE_PATH UDL_INVALID_BIN_FILE UDL_MEM_ALLOC_FAILED UDL_FLASH_INIT_ERROR UDL_FLASH_WRITE_ERROR UDL_FLASH_READ_ERROR UDL_CRC_ERROR UDL_USER_ABORT UDL_INSUFFICIENT_MEMORY
UDL_RET_TYPE UDLTegraWipeFlashDisk | ( | ) |
Completly wipes the flash of a tegra module including flash meta information.
- Return values
UDL_SUCCESS UDL_FLASH_ERASE_ERROR UDL_FLASH_INIT_ERROR UDL_HW_NOT_SUPPORTED UDL_DISMOUNT_ERROR
UDL_RET_TYPE UDLUpdateRegInfo | ( | UDL_REGION_ID | regID | ) |