Semihosting
以下内容自动抽取自 sdk-headers/HFLinkDriver_semihosting.h ,含 21 个公开函数及全部公开类型。函数指针回调类型不单独列出,见所属结构体成员说明。
API
-
HFLink_SemihostingHandle *HFLink_Semihosting_Create(HFLink_CoreSightTarget *target)
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.
-
void HFLink_Semihosting_Destroy(HFLink_SemihostingHandle *handle)
Destroy the handler and close all host files still open (fd >= 3).
- 参数:
handle -- May be NULL.
-
int HFLink_Semihosting_Enable(HFLink_SemihostingHandle *handle)
Enable the handler; while disabled TryHandle returns HFLINK_SEMIHOSTING_NOT_HANDLED immediately.
- 返回:
HFLINK_OK on success; HFLINK_ERR_NOT_INITIALIZED if handle is NULL.
-
int HFLink_Semihosting_Disable(HFLink_SemihostingHandle *handle)
Disable the handler (configuration is kept, the handle is not destroyed).
- 返回:
HFLINK_OK on success; HFLINK_ERR_NOT_INITIALIZED if handle is NULL.
-
int HFLink_Semihosting_SetWorkingDirectory(HFLink_SemihostingHandle *handle, const char *directory)
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.
-
int HFLink_Semihosting_SetOutputCallback(HFLink_SemihostingHandle *handle, HFLink_SemihostingOutputCallback callback, void *userdata)
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.
-
int HFLink_Semihosting_SetCmdLine(HFLink_SemihostingHandle *handle, const char *command_line)
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.
-
int HFLink_Semihosting_SetExitHalt(HFLink_SemihostingHandle *handle, int halt)
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.
-
int HFLink_Semihosting_SetSystemEnabled(HFLink_SemihostingHandle *handle, int enabled)
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.
-
int HFLink_Semihosting_SetLuaState(HFLink_SemihostingHandle *handle, HFLink_LuaState *state)
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.
-
int HFLink_Semihosting_Dispatch(HFLink_SemihostingHandle *handle, uint32_t opcode, uint64_t argument, uint32_t *result)
Dispatch a request directly; used by GDB/test paths. Returns the value the target should write back to R0.
-
int HFLink_Semihosting_TryHandle(HFLink_SemihostingHandle *handle)
Detect and handle a Thumb
BKPT #0xABwhile the target is halted.
-
int HFLink_Semihosting_IsExitRequested(const HFLink_SemihostingHandle *handle, uint32_t *reason)
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.
-
uint32_t HFLink_SemihostingRequest_GetOpcode(const HFLink_SemihostingRequest *request)
Return the request opcode (target R0); 0 when request is NULL.
-
uint64_t HFLink_SemihostingRequest_GetArgument(const HFLink_SemihostingRequest *request)
Return the request argument (target R1); 0 when request is NULL.
-
int HFLink_SemihostingRequest_ReadU32(HFLink_SemihostingRequest *request, uint32_t index, uint32_t *value)
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.
-
int HFLink_SemihostingRequest_WriteU32(HFLink_SemihostingRequest *request, uint32_t index, uint32_t value)
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.
-
int HFLink_SemihostingRequest_ReadMemory(HFLink_SemihostingRequest *request, uint64_t address, uint32_t size, uint8_t *buffer)
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.
-
int HFLink_SemihostingRequest_WriteMemory(HFLink_SemihostingRequest *request, uint64_t address, uint32_t size, const uint8_t *buffer)
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.
-
int HFLink_SemihostingRequest_SetResult(HFLink_SemihostingRequest *request, uint32_t value)
Set the R0 result value returned to the target.
- 返回:
HFLINK_OK on success; HFLINK_ERR_NOT_INITIALIZED if request is NULL.
-
int HFLink_SemihostingRequest_SetErrno(HFLink_SemihostingRequest *request, int value)
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.