Flash 下载

以下内容自动抽取自 sdk-headers/HFLinkDriver_flash.h ,含 37 个公开函数及全部公开类型。函数指针回调类型不单独列出,见所属结构体成员说明。

枚举

Download session state; after a failure the session can only go through the unified cleanup into CLOSED.

Values:

Input image format.

Values:

Erase policy; chip erase must be explicitly selected by the caller.

Values:

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:

User connection selection for the offline Pack planner; only constrains topology, never touches a probe.

Values:

Operation types shared by dry-run and the production state machine.

Values:

High-level execution phase bitmask.

Values:

Reset scope after a successful download; values match HFLink_ResetScope but avoid a circular dependency of the public header.

Values:

Flash verify mode. Classic always ignores this value and performs byte-by-byte readback comparison.

Values:

结构体

FLM FlashDevice sector layout entry.

Public Members

Sector size in bytes.

Sector offset relative to the flash start address.

Physical flash chip and its FLM geometry.

Public Members

FLM FlashDevice ABI version.

Device name provided by the FLM.

FLM FlashDevice device type.

Flash start address.

Total flash capacity in bytes.

Minimum programming page size in bytes.

Byte value after erase.

Per-page programming timeout in milliseconds.

Per-sector erase timeout in milliseconds.

Sector layout array.

Number of sector layout entries.

Address-space and processor constraints attached to each segment at image load time.

Public Members

BIN load base address.

Must be 1 for BIN; an explicit base of 0 is allowed.

Optional Pname; may be freed after the function returns.

Optional ADIv6 address space.

Whether address_space is valid.

Borrowed view of a sparse image segment.

Public Members

Owned by the image; becomes invalid after Destroy.

Owned by the image; may be empty.

Source ELF section name (".text" etc.), owned by the image; empty for non-ELF images or unnamed sections.

Explicit disambiguation and execution options of the planner.

Public Members

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.

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.

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.

Optional: phase progress callback; one-shot APIs (Erase/WriteImage/VerifyImage/ ProgramEx) inject it into the internally created Session.

Public Members

Must be explicitly SWD or JTAG.

Must be non-zero; only validated/displayed, does not drive hardware.

Borrowed view of a candidate/activated flash bank.

Public Members

FLM FlashDevice start address (base of sector addresses).

FLM FlashDevice total size (end of the last sector region).

Effective bank size: intersection of the pdsc algorithm range and the FLM device range.

Borrowed view of a plan operation.

Public Members

SIZE_MAX when not directly mapped to a segment.

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

Optional execution core Pname; plans with multiple execution cores need explicit disambiguation.

API

Create an empty sparse image.

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.

Create a sparse image from an ELF, BIN or Intel HEX file.

Destroy the image; may be passed NULL.

Return the number of segments.

Return a borrowed view of the segment in deterministic address order.

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.

Destroy the plan and its parsed FLM/bank resources; may be passed NULL.

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.

Create an execution session bound to the Pack Session and a deterministic plan; plan must cover the session lifetime.

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

Execute the given phases and always complete FLM/Core/Hook cleanup.

Execute the full erase/program/verify chain.

Destroy a closed or not-yet-executed session; may be passed NULL.

Resolve all candidate banks without accessing hardware.

Generate a structured dry-run without accessing hardware.

Query Pack/FLM only and list banks offline; never enumerates, opens or accesses a physical probe.

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.

Free the FlashDevice returned by HFLink_Flash_ProbeAlgorithm().

Generate a structured plan from Pack, FLM and the image before any hardware access.

Execute the given phases through the unified Plan/Session service and return the primary and cleanup errors separately.

Perform sector/chip erase over the image range; no programming or verification.

Program the image only; does not erase implicitly.

Read back and verify along the selected memory access path after DebugCodeMemRemap.

Convenient one-shot complete download; internally uses the same Plan/Session service.

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.

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

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

Set __FlashVerifyMode; defaults to HFLINK_FLASH_VERIFY_CRC.

Read the current __FlashVerifyMode.