Flash 下载
以下内容自动抽取自 sdk-headers/HFLinkDriver_flash.h ,含 37 个公开函数及全部公开类型。函数指针回调类型不单独列出,见所属结构体成员说明。
枚举
-
enum HFLink_FlashSessionState
Download session state; after a failure the session can only go through the unified cleanup into CLOSED.
Values:
-
enumerator HFLINK_FLASH_SESSION_CREATED
-
enumerator HFLINK_FLASH_SESSION_PREPARED
-
enumerator HFLINK_FLASH_SESSION_RUNNING
-
enumerator HFLINK_FLASH_SESSION_CLEANING
-
enumerator HFLINK_FLASH_SESSION_CLOSED
-
enumerator HFLINK_FLASH_SESSION_FAILED
-
enumerator HFLINK_FLASH_SESSION_CREATED
-
enum HFLink_FlashImageFormat
Input image format.
Values:
-
enumerator HFLINK_FLASH_IMAGE_AUTO
-
enumerator HFLINK_FLASH_IMAGE_ELF
-
enumerator HFLINK_FLASH_IMAGE_BIN
-
enumerator HFLINK_FLASH_IMAGE_IHEX
-
enumerator HFLINK_FLASH_IMAGE_AUTO
-
enum HFLink_FlashEraseMode
Erase policy; chip erase must be explicitly selected by the caller.
Values:
-
enumerator HFLINK_FLASH_ERASE_SECTORS
-
enumerator HFLINK_FLASH_ERASE_CHIP
-
enumerator HFLINK_FLASH_ERASE_SECTORS
-
enum HFLink_FlashProgressPhase
Progress phase identifier; each execution invokes prescan/erase/program/verify callbacks in order, each with independent progress. The prescan phase (skip-optimization probe) only appears when erase runs without force_prog.
Values:
-
enumerator HFLINK_FLASH_PROGRESS_PHASE_ERASE
-
enumerator HFLINK_FLASH_PROGRESS_PHASE_PROGRAM
-
enumerator HFLINK_FLASH_PROGRESS_PHASE_VERIFY
-
enumerator HFLINK_FLASH_PROGRESS_PHASE_PRESCAN
-
enumerator HFLINK_FLASH_PROGRESS_PHASE_ERASE
-
enum HFLink_FlashTransport
User connection selection for the offline Pack planner; only constrains topology, never touches a probe.
Values:
-
enumerator HFLINK_FLASH_TRANSPORT_SWD
-
enumerator HFLINK_FLASH_TRANSPORT_JTAG
-
enumerator HFLINK_FLASH_TRANSPORT_SWD
-
enum HFLink_FlashPlanOperationType
Operation types shared by dry-run and the production state machine.
Values:
-
enumerator HFLINK_FLASH_PLAN_PRESERVE_READ
-
enumerator HFLINK_FLASH_PLAN_ERASE_SECTOR
-
enumerator HFLINK_FLASH_PLAN_ERASE_CHIP
-
enumerator HFLINK_FLASH_PLAN_PROGRAM_PAGE
-
enumerator HFLINK_FLASH_PLAN_VERIFY
-
enumerator HFLINK_FLASH_PLAN_PRESERVE_READ
-
enum HFLink_FlashExecutionPhase
High-level execution phase bitmask.
Values:
-
enumerator HFLINK_FLASH_EXECUTE_ERASE
-
enumerator HFLINK_FLASH_EXECUTE_PROGRAM
-
enumerator HFLINK_FLASH_EXECUTE_VERIFY
-
enumerator HFLINK_FLASH_EXECUTE_ALL
-
enumerator HFLINK_FLASH_EXECUTE_ERASE
结构体
-
struct HFLink_FlashSector
FLM FlashDevice sector layout entry.
-
struct HFLink_FlashDevice
Physical flash chip and its FLM geometry.
Public Members
-
uint16_t version
FLM FlashDevice ABI version.
-
char name[128]
Device name provided by the FLM.
-
uint16_t device_type
FLM FlashDevice device type.
-
uint64_t start
Flash start address.
-
uint64_t size
Total flash capacity in bytes.
-
uint32_t page_size
Minimum programming page size in bytes.
-
uint32_t erased_value
Byte value after erase.
-
uint32_t program_timeout_ms
Per-page programming timeout in milliseconds.
-
uint32_t erase_timeout_ms
Per-sector erase timeout in milliseconds.
-
HFLink_FlashSector *sectors
Sector layout array.
-
size_t sector_count
Number of sector layout entries.
-
uint16_t version
-
struct HFLink_FlashImageOptions
Address-space and processor constraints attached to each segment at image load time.
Public Members
-
uint64_t binary_base
BIN load base address.
-
int has_binary_base
Must be 1 for BIN; an explicit base of 0 is allowed.
-
const char *processor_name
Optional Pname; may be freed after the function returns.
-
uint64_t address_space
Optional ADIv6 address space.
-
int has_address_space
Whether address_space is valid.
-
uint64_t binary_base
-
struct HFLink_FlashImageSegmentInfo
Borrowed view of a sparse image segment.
-
struct HFLink_FlashPlanOptions
Explicit disambiguation and execution options of the planner.
Public Members
-
const char *algorithm_path
Optional external FLM override path; when bank_index is set it overrides that bank, otherwise it must uniquely match the geometry of one candidate bank.
-
int restore_after_erase
Whether to save/restore image-uncovered regions after erase (explicit switch, the caller must set it).
0 = disabled (default): uncovered regions stay in the erased state after erase (erase = erasing); the download flow also does not preserve old content. 1 = enabled: uncovered regions are read back and saved before erase, then written back after erase/program (old content preserved). The planner decides when generating PRESERVE_READ operations; unrelated to the execution phase bitmask.
-
int force_prog
Force full erase and program of every sector, disabling the two skip optimizations.
0 = disabled (default): before erasing, each touched sector is compared against its expected final content (on-target CRC in Turbo mode, read-back compare in Classic mode); sectors that already match are skipped entirely (no erase, no program) and blank sectors skip the erase only. 1 = enabled: always erase and program every sector regardless of current content.
-
HFLink_FlashProgressCallback progress_callback
Optional: phase progress callback; one-shot APIs (Erase/WriteImage/VerifyImage/ ProgramEx) inject it into the internally created Session.
-
const char *algorithm_path
-
struct HFLink_FlashOfflineOptions
Public Members
-
HFLink_FlashTransport transport
Must be explicitly SWD or JTAG.
-
uint32_t clock_hz
Must be non-zero; only validated/displayed, does not drive hardware.
-
HFLink_FlashTransport transport
-
struct HFLink_FlashBankInfo
Borrowed view of a candidate/activated flash bank.
-
struct HFLink_FlashPlanOperationInfo
Borrowed view of a plan operation.
Public Members
-
size_t image_segment_index
SIZE_MAX when not directly mapped to a segment.
-
size_t image_segment_index
-
struct HFLink_FlashProgramOptions
Optional actions after a complete successful download.
备注
Reset and run execute after the Flash gate, FLM and device transaction locks are all released; by default no post action is performed.
Public Members
-
const char *processor_name
Optional execution core Pname; plans with multiple execution cores need explicit disambiguation.
-
const char *processor_name
API
-
int HFLink_FlashImage_Create(HFLink_FlashImage **out_image)
Create an empty sparse image.
-
int HFLink_FlashImage_AddSegment(HFLink_FlashImage *image, uint64_t address, const void *data, size_t size, const HFLink_FlashImageOptions *options)
Add a segment to the image; data and Pname are deep-copied.
备注
Any overlap within the same (Pname, address-space) returns HFLINK_ERR_PLAN_CONFLICT.
-
int HFLink_FlashImage_Open(const char *path, HFLink_FlashImageFormat format, const HFLink_FlashImageOptions *options, HFLink_FlashImage **out_image)
Create a sparse image from an ELF, BIN or Intel HEX file.
-
void HFLink_FlashImage_Destroy(HFLink_FlashImage *image)
Destroy the image; may be passed NULL.
-
size_t HFLink_FlashImage_GetSegmentCount(const HFLink_FlashImage *image)
Return the number of segments.
-
int HFLink_FlashImage_GetSegment(const HFLink_FlashImage *image, size_t index, HFLink_FlashImageSegmentInfo *out_segment)
Return a borrowed view of the segment in deterministic address order.
-
int HFLink_FlashPlan_Create(HFLink_PackDebugSession *pack_session, const HFLink_FlashImage *image, const HFLink_FlashPlanOptions *options, HFLink_FlashPlan **out_plan)
Build a deterministic plan from Pack algorithms and the image; when image is NULL only candidate banks are probed.
备注
Each bank covers the intersection of the pdsc algorithm range and the FLM FlashDevice range; algorithms whose intersection is empty are skipped with a warning instead of failing the whole plan.
- 返回:
Returns HFLINK_ERR_PLAN_CONFLICT on overlapping candidates or when an algorithm shared by multiple cores is not explicitly selected.
-
void HFLink_FlashPlan_Destroy(HFLink_FlashPlan *plan)
Destroy the plan and its parsed FLM/bank resources; may be passed NULL.
-
size_t HFLink_FlashPlan_GetBankCount(const HFLink_FlashPlan *plan)
-
int HFLink_FlashPlan_GetBank(const HFLink_FlashPlan *plan, size_t index, HFLink_FlashBankInfo *out_bank)
-
int HFLink_FlashPlan_GetBankSectors(const HFLink_FlashPlan *plan, size_t bank_index, const HFLink_FlashSector **out_sectors, size_t *out_count)
Return the FLM sector region table of the given bank (borrowed view, invalid after the plan is destroyed).
备注
Sector addresses are offsets relative to bank.device_start; the region table is a compressed representation of "repeated same-size sectors" whose last region ends at the bank end address (see the trimming semantics of flash_plan_collect_sectors in the driver). Sectors outside the bank effective range (the pdsc/FLM intersection) are trimmed away.
- 参数:
plan -- A probed/created plan; returns HFLINK_ERR_NOT_INITIALIZED when bank_index is out of range or out_sectors/out_count is NULL.
-
size_t HFLink_FlashPlan_GetOperationCount(const HFLink_FlashPlan *plan)
-
int HFLink_FlashPlan_GetOperation(const HFLink_FlashPlan *plan, size_t index, HFLink_FlashPlanOperationInfo *out_operation)
-
int HFLink_FlashSession_Create(HFLink_PackDebugSession *pack_session, HFLink_FlashPlan *plan, HFLink_FlashSession **out_session)
Create an execution session bound to the Pack Session and a deterministic plan; plan must cover the session lifetime.
-
int HFLink_FlashSession_SetProgressCallback(HFLink_FlashSession *session, HFLink_FlashProgressCallback callback, void *userdata)
Register the phase progress callback; pass NULL to clear it.
备注
The callback fires synchronously on the thread calling the execution API, and all trigger points are after the device transaction lock is released; it may be called at any time before ExecutePhases (the session is not executed concurrently, no locking needed).
-
int HFLink_FlashSession_ExecutePhases(HFLink_FlashSession *session, uint32_t phases)
Execute the given phases and always complete FLM/Core/Hook cleanup.
-
int HFLink_FlashSession_Execute(HFLink_FlashSession *session)
Execute the full erase/program/verify chain.
-
void HFLink_FlashSession_Destroy(HFLink_FlashSession *session)
Destroy a closed or not-yet-executed session; may be passed NULL.
-
HFLink_FlashSessionState HFLink_FlashSession_GetState(const HFLink_FlashSession *session)
-
int HFLink_FlashSession_GetPrimaryError(const HFLink_FlashSession *session)
-
int HFLink_FlashSession_GetCleanupError(const HFLink_FlashSession *session)
-
int HFLink_Flash_ProbeBanks(HFLink_PackDebugSession *pack_session, HFLink_FlashPlan **out_plan)
Resolve all candidate banks without accessing hardware.
-
int HFLink_Flash_DryRun(HFLink_PackDebugSession *pack_session, const HFLink_FlashImage *image, const HFLink_FlashPlanOptions *options, HFLink_FlashPlan **out_plan)
Generate a structured dry-run without accessing hardware.
-
int HFLink_Flash_ProbePackBanks(const char *device_selector, const HFLink_FlashOfflineOptions *offline_options, HFLink_FlashPlan **out_plan)
Query Pack/FLM only and list banks offline; never enumerates, opens or accesses a physical probe.
-
int HFLink_Flash_ProbeAlgorithm(const char *flm_path, uint64_t ram_start, uint64_t ram_size, HFLink_FlashDevice **out_device)
Parse a single CMSIS FLM file and return its FlashDevice geometry (page size / erased value / device range / sector table).
Lets a GUI obtain the real geometry of each download algorithm independently (without relying on the plan's representative-algorithm deduplication/fallback).
- 参数:
flm_path -- Absolute FLM (ELF) path.
ram_start -- Target RAM workspace start (for resolving entry symbols; may be 0).
ram_size -- Target RAM workspace size (may be 0).
out_device -- On success returns a deep copy of FlashDevice (with the sector table); the caller frees it with HFLink_FlashDevice_Free.
- 返回:
HFLINK_OK on success; otherwise a negative error code and *out_device is set to NULL.
-
void HFLink_FlashDevice_Free(HFLink_FlashDevice *device)
Free the FlashDevice returned by HFLink_Flash_ProbeAlgorithm().
-
int HFLink_Flash_DryRunPack(const char *device_selector, const HFLink_FlashOfflineOptions *offline_options, const HFLink_FlashImage *image, const HFLink_FlashPlanOptions *options, HFLink_FlashPlan **out_plan)
Generate a structured plan from Pack, FLM and the image before any hardware access.
-
int HFLink_Flash_ExecutePhases(HFLink_PackDebugSession *pack_session, const HFLink_FlashImage *image, const HFLink_FlashPlanOptions *options, uint32_t phases, int *primary_error, int *cleanup_error)
Execute the given phases through the unified Plan/Session service and return the primary and cleanup errors separately.
-
int HFLink_Flash_Erase(HFLink_PackDebugSession *pack_session, const HFLink_FlashImage *image, const HFLink_FlashPlanOptions *options, int *primary_error, int *cleanup_error)
Perform sector/chip erase over the image range; no programming or verification.
-
int HFLink_Flash_WriteImage(HFLink_PackDebugSession *pack_session, const HFLink_FlashImage *image, const HFLink_FlashPlanOptions *options, int *primary_error, int *cleanup_error)
Program the image only; does not erase implicitly.
-
int HFLink_Flash_VerifyImage(HFLink_PackDebugSession *pack_session, const HFLink_FlashImage *image, const HFLink_FlashPlanOptions *options, int *primary_error, int *cleanup_error)
Read back and verify along the selected memory access path after DebugCodeMemRemap.
-
int HFLink_Flash_Program(HFLink_PackDebugSession *pack_session, const HFLink_FlashImage *image, const HFLink_FlashPlanOptions *options, int *primary_error, int *cleanup_error)
Convenient one-shot complete download; internally uses the same Plan/Session service.
-
int HFLink_Flash_ProgramEx(HFLink_PackDebugSession *pack_session, const HFLink_FlashImage *image, const HFLink_FlashPlanOptions *options, const HFLink_FlashProgramOptions *post_options, int *primary_error, int *cleanup_error)
Complete download and perform the optional default reset and resume after the transaction is fully cleaned up.
备注
When post_options is NULL this is exactly equivalent to HFLink_Flash_Program(); a post action failure is returned as the primary error.
-
int HFLink_Flash_SetTurboMode(HFLink_CoreSightContext *context, int enable)
Select the flash execution mode: 0 = Classic synchronous runner, 1 = Turbo accelerated shell runner (default).
Writes the CoreSight context predefined variable __FlashMode; FlashSession reads it before creating the runner to select the sole executor. When Turbo mode is unavailable, RAM is insufficient or startup fails, it returns an error directly without falling back to Classic.
- 参数:
context -- An examined CoreSight context (to be bound by a future FlashSession)
enable -- Non-zero enables Turbo; 0 switches back to synchronous RPC
- 返回:
HFLINK_OK or HFLINK_ERR; returns HFLINK_ERR when context is NULL or the value is invalid
-
int HFLink_Flash_GetTurboMode(HFLink_CoreSightContext *context, int *out_enable)
Read the context's current __FlashMode (0 = Classic, 1 = Turbo).
- 参数:
context -- CoreSight context
out_enable -- Outputs 0 / 1; returns HFLINK_ERR when context is NULL
- 返回:
HFLINK_OK; HFLINK_ERR on invalid arguments
-
int HFLink_Flash_SetVerifyMode(HFLink_CoreSightContext *context, HFLink_FlashVerifyMode mode)
Set __FlashVerifyMode; defaults to HFLINK_FLASH_VERIFY_CRC.
-
int HFLink_Flash_GetVerifyMode(HFLink_CoreSightContext *context, HFLink_FlashVerifyMode *out_mode)
Read the current __FlashVerifyMode.