Search by Tags

Update Lib API

 

Article updated at 28 Oct 2017
Compare with Revision




Attention: 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_REGIONINFO 

Macros

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

Functions

void  UDLGetLibVersion (DWORD *pVerMaj, DWORD *pVerMin, DWORD *pBuild)
UDL_RET_TYPE UDLInit (void)
UDL_RET_TYPE UDLDeInit (void)
UDL_RET_TYPE UDLUpdateRegInfo (UDL_REGION_ID regID)
UDL_REGIONINFO *pRegInfo, PUDL_CALBACK_PROC_2 ReadFileProgress, BOOL validate)
UDL_RET_TYPE UDLReleaseBinFile (void)
UDL_RET_TYPE UDLCheckRange (UDL_REGION_ID *pAllowedRegions, DWORD start, DWORD length)
UDL_REGIONINFO *pRegInfoArray)
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)
UDL_RET_TYPE UDLDoUpdate (PUDL_CALBACK_PROC_2 EraseProgress, PUDL_CALBACK_PROC_3 SectionInfo, PUDL_CALBACK_PROC_2 WriteProgress)
UDL_RET_TYPE UDLEraseRegion (UDL_REGION_ID regID, PUDL_CALBACK_PROC_2 EraseProgress)
UDL_RET_TYPE UDLReboot (BOOL clean)
UDL_RET_TYPE UDLSaveRegistry (void)
UDL_RET_TYPE UDLClearRegistry (void)
UDL_RET_TYPE UDLTegraFlashUpdate (TCHAR *pNB0Path, PUDL_CALBACK_PROC_3 SectionInfo, PUDL_CALBACK_PROC_2 WriteProgress)
UDL_RET_TYPE UDLTegraWipeFlashDisk ()
Completly wipes the flash of a tegra module including flash meta information. More...
UDL_RET_TYPE UDLPxaSSUpdate (TCHAR *pSSPath, PUDL_CALBACK_PROC_3 SectionInfo, PUDL_CALBACK_PROC_2 WriteProgress)

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.

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

#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

UpdateLib type definitions.

Enumerator
UDL_NO_REGION 
UDL_BOOTLOADER 
UDL_CONFIG_BLOCK 
UDL_OS_IMAGE 
UDL_REGISTRY 
UDL_FILE_SYSTEM 
UDL_2ND_BOOTLOADER 
UDL_CPLD 
UDL_ANY_BIN_REGION 

General, unknown region.

UDL_ALL_REGIONS 
Enumerator
UDL_SUCCESS 

No Error, Function returned sucessfully.

UDL_ERROR 

General Error.

UDL_USER_ABORT 

The user aborted this function (e.g. via callback function).

UDL_NOT_INITIALIZED 

The update lib (UDL) is not initialized.

UDL_HW_NOT_SUPPORTED 

The current HW (module) is not supported.

UDL_INVALID_FILE_PATH 

The file path is corrupt or file is nonexistent.

UDL_INVALID_BIN_FILE 

The bin file is corrupt or format not supported.

UDL_INVALID_FILE_VERSION 

The bin file version is not supported by this lib.

UDL_FILE_WRITE_ERROR 

Could not write to the file (e.g. disk is full).

UDL_INSUFFICIENT_MEMORY 

Allocating of memory failed or not enough memory.

UDL_RANGE_VERIFICATION_FAILED 

The given range overwrites not allowed regions.

UDL_REGION_NOT_FOUND 

The requested region was not found in flash.

UDL_REGION_INVALID 

Cannot backup invalid regions (e.g. possible when FlashFileSystem driver not loaded).

UDL_FLASH_INIT_ERROR 

Error during initialization of the flash device.

UDL_FLASH_READ_ERROR 

Error during flash read.

UDL_FLASH_WRITE_ERROR 

Error during flash write.

UDL_FLASH_ERASE_ERROR 

Error during flash erase.

UDL_CRC_ERROR 

CRC error occured.

UDL_WRITE_VERIFICATION_FAILED 

The flash verification after writing failed.

UDL_FILE_SYSTEM_ERROR 

Error during backup or update of FileSystem region.

UDL_FILE_SYSTEM_DRIVER_LOAD_ERROR 

Error during loading or unloading the file system driver.

UDL_FILE_SYSTEM_FORMATING_ERROR 

Error during formating of store or partitions.

UDL_CPLD_NOT_FOUND 

No CPLD found or CPLD version not supported.

UDL_CPLD_READ_WRITE_ERROR 

Error during CPLD read or write.

UDL_DISMOUNT_ERROR 

Dismounting flashdisk error.

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)
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 Value Type: UDL_RET_TYPE

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.

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

Remarks: Call this function after UDLSetBinFile when bin file is not needed anymore (e.g. after UDLDoUpdate).

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.

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 )