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...
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) |
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 } |
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.
| #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 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) |
| enum UDL_REGION_ID |
| enum UDL_RET_TYPE |
| 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.
| [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)
|
| [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)
|
| [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)
|
| 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.
| [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 |
| UDL_SUCCESS | |
| UDL_NOT_INITIALIZED | |
| UDL_RANGE_VERIFICATION_FAILED |
| UDL_RET_TYPE UDLClearRegistry | ( | void | ) |
Clear the registry in flash.
| 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.
| [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)
|
| [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)
|
| [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)
|
| 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.
| [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)
|
| 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.
| [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).
| [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
| 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.
| UDL_SUCCESS | |
| UDL_HW_NOT_SUPPORTED | |
| UDL_FLASH_INIT_ERROR | Remarks: UDLInit has to be called once before any of the following functions:
|
| 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.
| [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)
|
| [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)
|
| 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.
| [in] | clean | - TRUE: Perform a coldboot (clean reboot).
|
| 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
| 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:
| 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.
| [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)
|
| [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_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.
| [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)
|
| [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)
|
| 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.
| 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 | ) |
