This is the documentation for the latest (main) development branch of Zephyr. If you are looking for the documentation of previous releases, use the drop-down menu on the left and select the desired version.

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

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:
Return values:

  • 0 – on success.

  • -1 – on failure.

long semihost_flen(long fd)

Query the size of a file.

Parameters:
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.