Semihosting

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

API

Create a semihosting handler bound to the given target.

The working directory defaults to the host process current directory; file descriptors 0/1/2 are pre-populated with the host stdin/stdout/stderr.

参数:
  • target -- Target control handle (borrowed reference; the caller must keep it alive for the lifetime of this handle).

返回:

The handle on success; NULL on allocation failure or if the working directory could not be obtained.

Destroy the handler and close all host files still open (fd >= 3).

参数:
  • handle -- May be NULL.

Enable the handler; while disabled TryHandle returns HFLINK_SEMIHOSTING_NOT_HANDLED immediately.

返回:

HFLINK_OK on success; HFLINK_ERR_NOT_INITIALIZED if handle is NULL.

Disable the handler (configuration is kept, the handle is not destroyed).

返回:

HFLINK_OK on success; HFLINK_ERR_NOT_INITIALIZED if handle is NULL.

Set the root directory used to resolve relative paths (used by SYS_OPEN/REMOVE/RENAME/ TMPNAM).

备注

Relative paths containing a ".." segment are rejected during resolution before any disk access.

参数:
  • directory -- Non-empty directory string.

返回:

HFLINK_OK on success; HFLINK_ERR_NOT_INITIALIZED if an argument is NULL; HFLINK_ERR on allocation failure.

Set the console output callback (output of SYS_WRITEC/WRITE0 and SYS_WRITE to fd 1/2).

参数:
  • callback -- Pass NULL to restore the default (write to host stdout).

返回:

HFLINK_OK on success; HFLINK_ERR_NOT_INITIALIZED if handle is NULL.

Set the command line string returned by SYS_GET_CMDLINE.

参数:
  • command_line -- Pass NULL to clear it (SYS_GET_CMDLINE then fails).

返回:

HFLINK_OK on success; HFLINK_ERR_NOT_INITIALIZED if handle is NULL; HFLINK_ERR on allocation failure.

Set whether the target stays halted after SYS_EXIT.

参数:
  • halt -- Non-zero: the target stays at the breakpoint waiting for the debugger (default); zero: execution resumes automatically.

返回:

HFLINK_OK on success; HFLINK_ERR_NOT_INITIALIZED if handle is NULL.

Whether SYS_SYSTEM may execute host command lines.

备注

When enabled, target firmware can run arbitrary commands on the host; only enable this in fully trusted scenarios.

参数:
  • enabled -- Non-zero to allow; disabled by default (the request fails directly).

返回:

HFLINK_OK on success; HFLINK_ERR_NOT_INITIALIZED if handle is NULL.

Attach a Lua state; registered Lua handlers take priority over the built-in default implementation.

参数:
  • state -- Pass NULL to detach and fall back to the pure built-in implementation.

返回:

HFLINK_OK on success; HFLINK_ERR_NOT_INITIALIZED if handle is NULL.

Dispatch a request directly; used by GDB/test paths. Returns the value the target should write back to R0.

Detect and handle a Thumb BKPT #0xAB while the target is halted.

Query whether the target has requested exit (SYS_EXIT).

参数:
  • reason -- [out] Outputs the exit reason (the R1 value of the SYS_EXIT request); may be NULL.

返回:

1 if exit was requested; 0 if not; HFLINK_ERR_NOT_INITIALIZED if handle is NULL.

Return the request opcode (target R0); 0 when request is NULL.

Return the request argument (target R1); 0 when request is NULL.

Read the index-th u32 of the parameter block (argument + index*4, little-endian target memory).

返回:

HFLINK_OK on success; HFLINK_ERR on read failure or when value is NULL.

Write the index-th u32 of the parameter block (argument + index*4, little-endian).

返回:

HFLINK_OK on success; HFLINK_ERR_NOT_INITIALIZED if an argument is NULL; the corresponding error code on memory write failure.

Read target memory into a host buffer.

返回:

HFLINK_OK on success; HFLINK_ERR_NOT_INITIALIZED if an argument is NULL or size is 0; the corresponding error code on memory read failure.

Write a host buffer into target memory.

返回:

HFLINK_OK on success; HFLINK_ERR_NOT_INITIALIZED if an argument is NULL or size is 0; the corresponding error code on memory write failure.

Set the R0 result value returned to the target.

返回:

HFLINK_OK on success; HFLINK_ERR_NOT_INITIALIZED if request is NULL.

Set the host errno, which can later be queried by a SYS_ERRNO request.

返回:

HFLINK_OK on success; HFLINK_ERR_NOT_INITIALIZED if request is NULL.