# Hexagon Semihosting Specification

This document describes the Semihosting inteface for the Qualcomm® Hexagon™ DSP.
Semihosting is an interface that allows an application running on targets
like a simulator or debugger to use system resources from the host.
This includes I/O devices such as file system, console, etc.

Hexagon Semihosting is implemented by QEMU and Hexagon-sim.

## Semihosting Interface

Semihosting operations are requested through the `trap0()` instruction with
cause code 0 (i.e. `trap0(#0)`). The code for the desired semihosting operation
must be provided at register `r00`. There are two ways of passing arguments:

- **r01 array**: arguments are stored in an array of 32-bit elements, and
the address of the array is passed through `r01`.
- **direct passing**: arguments are given directly through `r01`, `r02`, and so
on.

The majority of the operations use “r01 array”, but some use the second
interface. This is specified in each operation’s descriptions below.

The return value, if any, will be stored in `r00`. If the operation may
provide an error code on failure (i.e. `errno`), it is set at `r01`.

If there’s no return value, the value of `r00` after `trap0` is undefined.

## Operations

These are the semihosting operations/calls for Hexagon.

Some platforms might not implement all of these, but they should accept
all of these operation numbers and return an error code together with `ENOSYS`
if the operation is not implemented.

In the case of operations that don’t return errors, like counter readers,
they may instead return a static zero (this is implementation defined).

Making a semihosting call with an unknown operation number is undefined
behavior and targets will usually core dump and abort.

* * *

### SYS\_OPEN (0x1)

| Description | Opens/creates a file for reading or writing. |
| --- | --- |
| Interface | r01 array |

**Input**

1. The address of a null-terminated char array, containing the file path.
2. The mode to open/create the file (see available modes below).
3. The length of the file path (excluding the null byte).

Available modes are:

| 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| O\_RDONLY | O\_RDONLY | O\_BINARY | O\_RDWR | O\_RDWR | O\_BINARY | O\_WRONLY | O\_CREAT | O\_TRUNC | O\_WRONLY | O\_CREAT | O\_TRUNC | O\_BINARY | O\_RDWR | O\_CREAT | O\_TRUNC | O\_RDWR | O\_CREAT | O\_TRUNC | O\_BINARY | O\_WRONLY | O\_APPEND | O\_CREAT | O\_WRONLY | O\_APPEND | O\_CREAT | O\_BINARY | O\_RDWR | O\_APPEND | O\_CREAT | O\_RDWR | O\_APPEND | O\_CREAT | O\_BINARY | O\_RDWR | O\_CREAT | O\_RDWR | O\_CREAT | O\_EXCL |

**Output**

On success, `r0` contains the file descriptor number. On error, `r0` is set to
-1 and `r1` contains the `errno` number.

Notes:

- File descriptors 0, 1, and 2 – corresponding to default input, output, and
error streams – should be open by default.

* * *

### SYS\_CLOSE (0x2)

| Description | Closes a file descriptor previously opened with <cite>SYS_OPEN</cite> |
| --- | --- |
| Interface | r01 array |

**Input**

1. The file descriptor.

**Output**

Returns 0 on success or -1 on error, with `r1` set to the associated `errno`.

* * *

### SYS\_WRITEC (0x3)

| Description | Writes a single char to default output stream. |
| --- | --- |
| Interface | r01 array |

**Input**

1. The character.

**Output**

No output.

* * *

### SYS\_WRITE0 (0x4)

| Description | Writes a null-terminated string to default output stream. |
| --- | --- |
| Interface | r01 array |

**Input**

1. The address of the null-terminated string.

**Output**

No output.

* * *

### SYS\_WRITE (0x5)

| Description | Writes an array of bytes to a file. |
| --- | --- |
| Interface | r01 array |

**Input**

Takes three arguments in this order:

1. The file descriptor.
2. The address of the byte array.
3. The length of the array, in bytes.

**Output**

Returns 0 on success or -1 on error, with `r1` set to the associated `errno`.

* * *

### SYS\_READ (0x6)

| Description | Reads a number of bytes from a file into a buffer. |
| --- | --- |
| Interface | r01 array |

**Input**

1. The file descriptor.
2. The address of a previously allocated byte array where the data will be
saved to.
3. The number of bytes to be read.

Note: the application is responsible for allocating enough space. Requesting
to read more bytes than what was allocated will result in undefined behavior.

**Output**

Returns 0 on success or -1 on error, with `r1` set to the associated `errno`.

* * *

### SYS\_READC (0x7)

| Description | Reads a byte from default input stream. |
| --- | --- |
| Interface | - |

**Input**

No input.

**Output**

Returns the byte read on success or `EOF` if either there is no
byte to be read or an error occurred, in which case, `r1` set to the
associated `errno`.

* * *

### SYS\_ISERROR (0x8)

| Description | Indentifies whether a return code from a previous semihosting call<br>is an error or not. |
| --- | --- |
| Interface | r01 array |

**Input**

1. The integer code to be tested.

**Output**

Returns 0 if the integer is not an error code, or non-zero if it is an error.

* * *

### SYS\_ISTTY (0x9)

| Description | Checks whether a given file descriptor refers to a terminal type<br>device. |
| --- | --- |
| Interface | r01 array |

**Input**

1. The file descriptor.

**Output**

Returns 1 if the file descriptor refers to a terminal type device or 0
otherwise.

* * *

### SYS\_SEEK (0xa)

| Description | Sets the offset of a file descriptor into the file. |
| --- | --- |
| Interface | r01 array |

**Input**

1. The file descriptor.
2. The new offset in bytes since the beginning of the file.

**Output**

Returns the newly set offset on success or -1 on error, with `r1` set to the
associated `errno`.

* * *

### SYS\_FLEN (0xc)

| Description | Retrieves the file length from an open file descriptor. |
| --- | --- |
| Interface | r01 array |

**Input**

1. The file descriptor.

**Output**

Returns the file’s length in bytes on success or -1 on error, with `r1` set to
the associated `errno`.

* * *

### SYS\_TMPNAM (0xd)

| Description | Composes a file name on a temporary directory using the given ID. |
| --- | --- |
| Interface | r01 array |

**Input**

1. A pointer to a string buffer, where the file path will be stored.
2. An integer identifier to be used in the file name.
3. The length of the buffer in bytes.

**Output**

Returns 0 on success or -1 on error.

* * *

### SYS\_REMOVE (0xe)

| Description | Unlinks a file from the file system. |
| --- | --- |
| Interface | r01 array |

**Input**

1. A string containing the file path.
2. The length of the string in bytes.

**Output**

Returns 0 on success or -1 on error, with `r1` set to the associated `errno`.

* * *

### SYS\_RENAME (0xf)

| Description | Renames a file. |
| --- | --- |
| Interface | r01 array |

**Input**

1. A string containing the original file path.
2. The length of the first string in bytes.
3. A string containing the new file path.
4. The length of the second string in bytes.

**Output**

Returns 0 on success or -1 on error, with `r1` set to the associated `errno`.

* * *

### SYS\_CLOCK (0x10)

| Description | Returns the number of seconds since an arbitrary point in time. |
| --- | --- |
| Interface | - |

**Input**

No input.

**Output**

On success, `r0` contains the number of seconds since an arbitrary time,
guaranteed to be equal to or older than the execution start time. This can be
used to calculate time intervals.

On error, `r0` is set to -1 and `r1` is set to the associated `errno`.

* * *

### SYS\_TIME (0x11)

| Description | Returns the number of seconds since Unix Epoch. |
| --- | --- |
| Interface | - |

**Input**

No input.

**Output**

On success, `r0` contains the value of time in seconds since 0 hours, 0
minutes, 0 seconds, January 1, 1970, Coordinated Universal Time.

On error, `r0` is set to -1 and `r1` is set to the associated `errno`.

* * *

### SYS\_SYSTEM (0x12)

| Description | Executes a system command on the host. |
| --- | --- |
| Interface | r01 array |

**Input**

1. A string with the command to be executed.
2. The length of the string.

**Output**

Returns the command’s exit status or -1 if an error occurred, with `r1` set
to the associated `errno`. This can be `ENOSYS` if the platform doesn’t
support the `SYS_SYSTEM` semihosting call.

* * *

### SYS\_ERRNO (0x13)

| Description | Return’s |
| --- | --- |
| Interface | - |

**Input**

No input.

**Output**

Returns the `errno` from the host target libc.

This operation is available for compatibility reasons, but it is more advisable
to directly read the error code from `r1` on semihosting operations that do
return it, as the host `errno` could change in-between two semihosting calls.

* * *

### SYS\_GET\_CMDLINE (0x15)

| Description | Retrieves the command line used to invoke the program. |
| --- | --- |
| Interface | r01 array |

**Input**

1. A string buffer where the cmdline will be stored.
2. The length of the buffer in bytes.

**Output**

Returns the number of bytes not read due to insufficient space (including 0
if the whole cmdline fit into the provided string buffer); or -1 on error, with
`r1` set to the associated `errno`.

* * *

### SYS\_HEAPINFO (0x16)

| Description | Retrieves heap and stack information. |
| --- | --- |
| Interface | r01 array |

**Input**

1. The pointer to a `struct heap_info` buffer.

The struct is defined as:

struct heap_info {int heap_base;int heap_limit;int stack_base;int stack_limit;
    };
    Copy to clipboard

**Output**

On success, returns the address of the `struct heap_info` that was passed as
input. The struct is filled with the retrieved values. On error, returns -1
and sets `r1` to the associated `errno`.

* * *

### RESERVED (0x17)

* * *

### SYS\_EXCEPTION or SYS\_EXIT (0x18)

| Description | Requests the target to exit with the given exit code. |
| --- | --- |
| Interface | direct passing |

**Input**

The exit code at `r02`.

**Output**

No output.

* * *

### RESERVED (0x30)

* * *

### RESERVED (0x31)

* * *

### SYS\_READ\_CYCLES (0x40)

| Description | Retrieves an estimate for the calling thread’s cycle counter. |
| --- | --- |
| Interface | - |

**Input**

No input.

**Output**

Returns the instruction counter on the register pair `r1:0`.

* * *

### SYS\_PROF\_ON (0x41)

| Description | Enables application profiling. This feature is implementation-defined,<br>please check the simulator (or other software) documentation. |
| --- | --- |
| Interface | - |

**Input**

No input.

**Output**

Returns 0 on success or -1 on error, with `r1` set to the associated `errno`.

* * *

### SYS\_PROF\_OFF (0x42)

| Description | Disables application profiling. This feature is implementation-defined,<br>please check the simulator (or other software) documentation. |
| --- | --- |
| Interface | - |

**Input**

No input.

**Output**

Returns 0 on success or -1 on error, with `r1` set to the associated `errno`.

* * *

### SYS\_WRITECREG (0x43)

| Description | Writes a character to the standard output stream. |
| --- | --- |
| Interface | direct passing |

**Input**

The char to be written.

**Output**

No output.

* * *

### SYS\_READ\_TCYCLES (0x44)

Alias for [SYS_READ_CYCLES](https://docs.qualcomm.com/doc/80-N2040-101/topic/semihosting-specification.html#sys-read-cycles-0x40).

* * *

### RESERVED (0x45)

* * *

### RESERVED (0x46)

* * *

### SYS\_READ\_ICOUNT (0x47)

| Description | Retrieves the number of instructions executed by the calling thread. |
| --- | --- |
| Interface | - |

**Input**

No input.

**Output**

Returns the instruction counter on the register pair `r1:0`.

* * *

### SYS\_PROF\_STATSRESET (0x48)

| Description | Resets the profiling statistics. This feature is implementation-defined,<br>please check the simulator (or other software) documentation. |
| --- | --- |
| Interface | - |

**Input**

No input.

**Output**

Returns 0 on success or -1 on error, with `r1` set to the associated `errno`.

* * *

### SYS\_DUMP\_PMU\_STATS (0x4a)

| Description | Dumps the PMU statistics to host file system. This feature is<br>implementation-defined, please check the simulator (or other software)<br>documentation. |
| --- | --- |
| Interface | - |

**Input**

No input.

**Output**

Returns 0 on success or -1 on error, with `r1` set to the associated `errno`.

* * *

### RESERVED (0x50)

* * *

### RESERVED (0x51)

* * *

### SYS\_READ\_PCYCLES (0x52)

| Description | Retrieves the <cite>pcycle</cite> value. |
| --- | --- |
| Interface | - |

**Input**

No input.

**Output**

Retrieves the 64-bit cycle counter from the `pcycle` register and saves it
at the register pair `r1:0`.

* * *

### RESERVED (0x53)

* * *

### SYS\_COREDUMP (0xCD)

| Description | Prints a dump of the core registers to the default output stream, to<br>be used for a crash on an unhandled/fatal exception. Register <cite>ssr</cite><br>is used to derive and print the exception value. |
| --- | --- |
| Interface | - |

**Input**

No input.

**Output**

No output.

* * *

### RESERVED (0x75)

* * *

### RESERVED (0x76)

* * *

### SYS\_FTELL (0x100)

| Description | Retrieves the current offset of the file position indicator on an open<br>file descriptor. |
| --- | --- |
| Interface | r01 array |

**Input**

1. The file descriptor.

**Output**

Returns the offset on success or -1 on error, with `r1` set to the associated
`errno`.

* * *

### SYS\_FSTAT (0x101) / SYS\_STAT (0x103)

| Description | Retrieves stat information for a file. |
| --- | --- |
| Interface | r01 array |

**Input**

1. The file descriptor in case of `SYS_FSTAT`, or the null-terminated file path
for `SYS_STAT`.
2. The address of a `struct stat` buffer which will be filled in.

The stat struct is defined as:

struct stat {
        uint64_t dev;
        uint64_t ino;
        uint32_t mode;
        uint32_t nlink;
        uint64_t rdev;
        uint32_t size;
        uint32_t __pad1;
        uint32_t atime;
        uint32_t mtime;
        uint32_t ctime;
        uint32_t __pad2;
    };
    Copy to clipboard

**Output**

Returns 0 on success or -1 on error, with `r1` set to the associated `errno`.

* * *

### RESERVED (0x102)

* * *

### SYS\_GETCWD (0x104)

| Description | Retrieves the path of the current working directory. |
| --- | --- |
| Interface | r01 array |

**Input**

1. The address for a character buffer array.
2. The length of the array in bytes.

**Output**

Returns the buffer array on success or `(char *)0` on error, with `r1` set to
the associated `errno`. A buffer that is too small will cause an `ERANGE`.

* * *

### SYS\_ACCESS (0x105)

| Description | Checks the acessibility of the file. |
| --- | --- |
| Interface | r01 array |

**Input**

1. A null-terminated string containing the file’s path.
2. The access check mode. Accepted values are the same as the `access()`
libc function.

**Output**

Returns 0 on success or -1 on error, with `r1` set to the associated `errno`.

* * *

### RESERVED (0x106)

* * *

### RESERVED (0x107)

* * *

### SYS\_OPENDIR (0x180)

| Description | Opens a directory for listing and returns an index associated with it<br>to be used for subsequent operations. |
| --- | --- |
| Interface | direct passing |

**Input**

A null-terminated string containing the directory path.

**Output**

Returns the dirent pointer on success or 0 on error, with `r1` set to the
associated `errno`.

* * *

### SYS\_CLOSEDIR (0x181)

| Description | Closes a directory previously opened with <cite>SYS_OPENDIR</cite>. |
| --- | --- |
| Interface | direct passing |

**Input**

The directory index as returned by `SYS_OPENDIR`.

**Output**

Returns 0 on success or -1 on error, with `r1` set to the associated `errno`.

* * *

### SYS\_READDIR (0x182)

| Description | Reads a directory and returns the next entry. |
| --- | --- |
| Interface | direct passing |

**Input**

1. The directory index as returned by `SYS_OPENDIR`.
2. A pointer to a `struct dirent` buffer, which will be filled in.

The dirent struct is defined as follows:

struct dirent {
        long d_ino;
        char d_name[MAXNAMLEN];
    };
    Copy to clipboard

**Output**

- On success, `r0` contains the dirent pointer.
- If there are no more entries, both `r0` and `r1` are set to 0.
- If an error occurred, `r0` is set to 0 and `r1` to the associated `errno`.

* * *

### RESERVED (0x183)

* * *

### RESERVED (0x184)

* * *

### SYS\_EXEC (0x185)

Deprecated.

* * *

### SYS\_FTRUNC (0x186)

| Description | Truncates/extends a file to a given size. |
| --- | --- |
| Interface | r01 array |

**Input**

1. The file descriptor.
2. The new size of the file.

**Output**

Returns 0 on success or -1 on error, with `r1` set to the associated `errno`.

Last Published: Nov 19, 2025