Semihosting Guide
Overview
Semihosting is a mechanism that enables code running on ARM and RISC-V targets to communicate and use the Input/Output facilities on a host computer that is running a debugger or emulator.
More complete documentation on the available functionality is available at the ARM Github documentation.
The RISC-V functionality borrows from the ARM definitions, as described at the RISC-V Github documentation.
File Operations
Semihosting enables files on the host computer to be opened, read, and modified by an application. This can be useful when attempting to validate the behaviour of code across datasets that are larger than what can fit into ROM of an emulated platform. File paths can be either absolute, or relative to the directory of the running process.
const char *path = "./data.bin";
long file_len, bytes_read, fd;
uint8_t buffer[16];
/* Open the data file for reading */
fd = semihost_open(path, SEMIHOST_OPEN_RB);
if (fd < 0) {
return -ENOENT;
}
/* Read all data from the file */
file_len = semihost_flen(fd);
while(file_len > 0) {
bytes_read = semihost_read(fd, buffer, MIN(file_len, sizeof(buffer)));
if (bytes_read < 0) {
break;
}
/* Process read data */
do_data_processing(buffer, bytes_read);
/* Update remaining length */
file_len -= bytes_read;
}
/* Close the file */
semihost_close(fd);
Additional Functionality
Additional functionality is available by running semihosting instructions
directly with semihost_exec() with one of the instructions defined
in semihost_instr. For complete documentation on the required
arguments and return codes, see the ARM Github documentation.
API Reference
- group semihost
Enums
-
enum semihost_instr
Semihosting instructions.
Values:
-
enumerator SEMIHOST_OPEN = 0x01
Open a file or stream on the host system.
-
enumerator SEMIHOST_ISTTY = 0x09
Check whether a file is associated with a stream/terminal.
-
enumerator SEMIHOST_WRITE = 0x05
Write to a file or stream.
-
enumerator SEMIHOST_READ = 0x06
Read from a file at the current cursor position.
-
enumerator SEMIHOST_CLOSE = 0x02
Closes a file on the host which has been opened by SEMIHOST_OPEN.
-
enumerator SEMIHOST_FLEN = 0x0C
Get the length of a file.
-
enumerator SEMIHOST_SEEK = 0x0A
Set the file cursor to a given position in a file.
-
enumerator SEMIHOST_TMPNAM = 0x0D
Get a temporary absolute file path to create a temporary file.
-
enumerator SEMIHOST_REMOVE = 0x0E
Remove a file on the host system.
Possibly insecure!
-
enumerator SEMIHOST_RENAME = 0x0F
Rename a file on the host system.
Possibly insecure!
-
enumerator SEMIHOST_WRITEC = 0x03
Write one character to the debug terminal.
-
enumerator SEMIHOST_WRITE0 = 0x04
Write a NULL terminated string to the debug terminal.
-
enumerator SEMIHOST_READC = 0x07
Read one character from the debug terminal.
-
enumerator SEMIHOST_CLOCK = 0x10
-
enumerator SEMIHOST_ELAPSED = 0x30
-
enumerator SEMIHOST_TICKFREQ = 0x31
-
enumerator SEMIHOST_TIME = 0x11
-
enumerator SEMIHOST_ERRNO = 0x13
Retrieve the errno variable from semihosting operations.
-
enumerator SEMIHOST_GET_CMDLINE = 0x15
Get commandline parameters for the application to run with.
-
enumerator SEMIHOST_HEAPINFO = 0x16
-
enumerator SEMIHOST_ISERROR = 0x08
-
enumerator SEMIHOST_SYSTEM = 0x12
-
enumerator SEMIHOST_OPEN = 0x01
-
enum semihost_open_mode
Modes to open a file with.
Behaviour corresponds to equivalent fopen strings. i.e. SEMIHOST_OPEN_RB_PLUS == “rb+”
Values:
-
enumerator SEMIHOST_OPEN_R = 0
-
enumerator SEMIHOST_OPEN_RB = 1
-
enumerator SEMIHOST_OPEN_R_PLUS = 2
-
enumerator SEMIHOST_OPEN_RB_PLUS = 3
-
enumerator SEMIHOST_OPEN_W = 4
-
enumerator SEMIHOST_OPEN_WB = 5
-
enumerator SEMIHOST_OPEN_W_PLUS = 6
-
enumerator SEMIHOST_OPEN_WB_PLUS = 7
-
enumerator SEMIHOST_OPEN_A = 8
-
enumerator SEMIHOST_OPEN_AB = 9
-
enumerator SEMIHOST_OPEN_A_PLUS = 10
-
enumerator SEMIHOST_OPEN_AB_PLUS = 11
-
enumerator SEMIHOST_OPEN_R = 0
Functions
-
long semihost_exec(enum semihost_instr instr, void *args)
Manually execute a semihosting instruction.
- Parameters:
instr – instruction code to run
args – instruction specific arguments
- Returns:
integer return code of instruction
-
char semihost_poll_in(void)
Read a byte from the console.
- Returns:
char byte read from the console.
-
void semihost_poll_out(char c)
Write a byte to the console.
- Parameters:
c – byte to write to console
-
long semihost_open(const char *path, long mode)
Open a file on the host system.
- Parameters:
path – file path to open. Can be absolute or relative to current directory of the running process.
mode – value from semihost_open_mode.
- Return values:
handle – positive handle on success.
-1 – on failure.
-
long semihost_close(long fd)
Close a file.
- Parameters:
fd – handle returned by semihost_open.
- Return values:
0 – on success.
-1 – on failure.
-
long semihost_flen(long fd)
Query the size of a file.
- Parameters:
fd – handle returned by semihost_open.
- Return values:
positive – file size on success.
-1 – on failure.
-
long semihost_seek(long fd, long offset)
Seeks to an absolute position in a file.
- Parameters:
fd – handle returned by semihost_open.
offset – offset from the start of the file in bytes.
- Return values:
0 – on success.
-errno – negative error code on failure.
-
long semihost_read(long fd, void *buf, long len)
Read the contents of a file into a buffer.
- Parameters:
fd – handle returned by semihost_open.
buf – buffer to read data into.
len – number of bytes to read.
- Return values:
read – number of bytes read on success.
-errno – negative error code on failure.
-
long semihost_write(long fd, const void *buf, long len)
Write the contents of a buffer into a file.
- Parameters:
fd – handle returned by semihost_open.
buf – buffer to write data from.
len – number of bytes to write.
- Return values:
0 – on success.
-errno – negative error code on failure.
-
enum semihost_instr