Semihosting APIs

Enumerations
enum	semihost_instr {   SEMIHOST_OPEN = 0x01 , SEMIHOST_ISTTY = 0x09 , SEMIHOST_WRITE = 0x05 , SEMIHOST_READ = 0x06 ,   SEMIHOST_CLOSE = 0x02 , SEMIHOST_FLEN = 0x0C , SEMIHOST_SEEK = 0x0A , SEMIHOST_TMPNAM = 0x0D ,   SEMIHOST_REMOVE = 0x0E , SEMIHOST_RENAME = 0x0F , SEMIHOST_WRITEC = 0x03 , SEMIHOST_WRITE0 = 0x04 ,   SEMIHOST_READC = 0x07 , SEMIHOST_CLOCK = 0x10 , SEMIHOST_ELAPSED = 0x30 , SEMIHOST_TICKFREQ = 0x31 ,   SEMIHOST_TIME = 0x11 , SEMIHOST_ERRNO = 0x13 , SEMIHOST_GET_CMDLINE = 0x15 , SEMIHOST_HEAPINFO = 0x16 ,   SEMIHOST_ISERROR = 0x08 , SEMIHOST_SYSTEM = 0x12 }
	Semihosting instructions. More...
enum	semihost_open_mode {   SEMIHOST_OPEN_R = 0 , SEMIHOST_OPEN_RB = 1 , SEMIHOST_OPEN_R_PLUS = 2 , SEMIHOST_OPEN_RB_PLUS = 3 ,   SEMIHOST_OPEN_W = 4 , SEMIHOST_OPEN_WB = 5 , SEMIHOST_OPEN_W_PLUS = 6 , SEMIHOST_OPEN_WB_PLUS = 7 ,   SEMIHOST_OPEN_A = 8 , SEMIHOST_OPEN_AB = 9 , SEMIHOST_OPEN_A_PLUS = 10 , SEMIHOST_OPEN_AB_PLUS = 11 }
	Modes to open a file with. More...

Functions
long	semihost_exec (enum semihost_instr instr, void *args)
	Manually execute a semihosting instruction.
char	semihost_poll_in (void)
	Read a byte from the console.
void	semihost_poll_out (char c)
	Write a byte to the console.
long	semihost_open (const char *path, long mode)
	Open a file on the host system.
long	semihost_close (long fd)
	Close a file.
long	semihost_flen (long fd)
	Query the size of a file.
long	semihost_seek (long fd, long offset)
	Seeks to an absolute position in a file.
long	semihost_read (long fd, void *buf, long len)
	Read the contents of a file into a buffer.
long	semihost_write (long fd, const void *buf, long len)
	Write the contents of a buffer into a file.

Detailed Description

Enumeration Type Documentation

semihost_instr

enum semihost_instr

#include <zephyr/arch/common/semihost.h>

Semihosting instructions.

Enumerator
SEMIHOST_OPEN	Open a file or stream on the host system.
SEMIHOST_ISTTY	Check whether a file is associated with a stream/terminal.
SEMIHOST_WRITE	Write to a file or stream.
SEMIHOST_READ	Read from a file at the current cursor position.
SEMIHOST_CLOSE	Closes a file on the host which has been opened by SEMIHOST_OPEN.
SEMIHOST_FLEN	Get the length of a file.
SEMIHOST_SEEK	Set the file cursor to a given position in a file.
SEMIHOST_TMPNAM	Get a temporary absolute file path to create a temporary file.
SEMIHOST_REMOVE	Remove a file on the host system. Possibly insecure!
SEMIHOST_RENAME	Rename a file on the host system. Possibly insecure!
SEMIHOST_WRITEC	Write one character to the debug terminal.
SEMIHOST_WRITE0	Write a NULL terminated string to the debug terminal.
SEMIHOST_READC	Read one character from the debug terminal.
SEMIHOST_CLOCK
SEMIHOST_ELAPSED
SEMIHOST_TICKFREQ
SEMIHOST_TIME
SEMIHOST_ERRNO	Retrieve the errno variable from semihosting operations.
SEMIHOST_GET_CMDLINE	Get commandline parameters for the application to run with.
SEMIHOST_HEAPINFO
SEMIHOST_ISERROR
SEMIHOST_SYSTEM

semihost_open_mode

enum semihost_open_mode

#include <zephyr/arch/common/semihost.h>

Modes to open a file with.

Behaviour corresponds to equivalent fopen strings. i.e. SEMIHOST_OPEN_RB_PLUS == "rb+"

Enumerator
SEMIHOST_OPEN_R
SEMIHOST_OPEN_RB
SEMIHOST_OPEN_R_PLUS
SEMIHOST_OPEN_RB_PLUS
SEMIHOST_OPEN_W
SEMIHOST_OPEN_WB
SEMIHOST_OPEN_W_PLUS
SEMIHOST_OPEN_WB_PLUS
SEMIHOST_OPEN_A
SEMIHOST_OPEN_AB
SEMIHOST_OPEN_A_PLUS
SEMIHOST_OPEN_AB_PLUS

Function Documentation

semihost_close()

long semihost_close

(

long

fd

)

#include <zephyr/arch/common/semihost.h>

Close a file.

Parameters

fd	handle returned by semihost_open.

Return values

0	on success.
-1	on failure.

semihost_exec()

long semihost_exec	(	enum semihost_instr	instr,
		void *	args
	)

#include <zephyr/arch/common/semihost.h>

Manually execute a semihosting instruction.

Parameters

instr	instruction code to run
args	instruction specific arguments

Returns

integer return code of instruction

semihost_flen()

long semihost_flen

(

long

fd

)

#include <zephyr/arch/common/semihost.h>

Query the size of a file.

Parameters

fd	handle returned by semihost_open.

Return values

positive	file size on success.
-1	on failure.

semihost_open()

long semihost_open	(	const char *	path,
		long	mode
	)

#include <zephyr/arch/common/semihost.h>

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.

semihost_poll_in()

char semihost_poll_in

(

void

)

#include <zephyr/arch/common/semihost.h>

Read a byte from the console.

Returns

char byte read from the console.

semihost_poll_out()

void semihost_poll_out

(

char

c

)

#include <zephyr/arch/common/semihost.h>

Write a byte to the console.

Parameters

c	byte to write to console

semihost_read()

long semihost_read	(	long	fd,
		void *	buf,
		long	len
	)

#include <zephyr/arch/common/semihost.h>

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.

semihost_seek()

long semihost_seek	(	long	fd,
		long	offset
	)

#include <zephyr/arch/common/semihost.h>

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.

semihost_write()

long semihost_write	(	long	fd,
		const void *	buf,
		long	len
	)

#include <zephyr/arch/common/semihost.h>

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.