include/zephyr/arch/common/semihost.h

/*
 * Copyright (c) 2022, Commonwealth Scientific and Industrial Research
 * Organisation (CSIRO) ABN 41 687 119 230.
 *
 * SPDX-License-Identifier: Apache-2.0
 *
 * Based on the ARM semihosting API from:
 * https://github.com/ARM-software/abi-aa/blob/main/semihosting/semihosting.rst
 *
 * RISC-V semihosting also follows these conventions:
 * https://github.com/riscv/riscv-semihosting-spec/blob/main/riscv-semihosting-spec.adoc
 */

/**
 * @file
 *
 * @brief public Semihosting APIs based on ARM definitions.
 * @defgroup semihost Semihosting APIs
 * @{
 */

#ifndef ZEPHYR_INCLUDE_ARCH_COMMON_SEMIHOST_H_
#define ZEPHYR_INCLUDE_ARCH_COMMON_SEMIHOST_H_

/** @brief Semihosting instructions */
enum semihost_instr {
	/*
	 * File I/O operations
	 */

	/** Open a file or stream on the host system. */
	SEMIHOST_OPEN   = 0x01,
	/** Check whether a file is associated with a stream/terminal */
	SEMIHOST_ISTTY  = 0x09,
	/** Write to a file or stream. */
	SEMIHOST_WRITE  = 0x05,
	/** Read from a file at the current cursor position. */
	SEMIHOST_READ   = 0x06,
	/** Closes a file on the host which has been opened by SEMIHOST_OPEN. */
	SEMIHOST_CLOSE  = 0x02,
	/** Get the length of a file. */
	SEMIHOST_FLEN   = 0x0C,
	/** Set the file cursor to a given position in a file. */
	SEMIHOST_SEEK   = 0x0A,
	/** Get a temporary absolute file path to create a temporary file. */
	SEMIHOST_TMPNAM = 0x0D,
	/** Remove a file on the host system. Possibly insecure! */
	SEMIHOST_REMOVE = 0x0E,
	/** Rename a file on the host system. Possibly insecure! */
	SEMIHOST_RENAME = 0x0F,

	/*
	 * Terminal I/O operations
	 */

	/** Write one character to the debug terminal. */
	SEMIHOST_WRITEC         = 0x03,
	/** Write a NULL terminated string to the debug terminal. */
	SEMIHOST_WRITE0         = 0x04,
	/** Read one character from the debug terminal. */
	SEMIHOST_READC          = 0x07,

	/*
	 * Time operations
	 */
	SEMIHOST_CLOCK          = 0x10,
	SEMIHOST_ELAPSED        = 0x30,
	SEMIHOST_TICKFREQ       = 0x31,
	SEMIHOST_TIME           = 0x11,

	/*
	 * System/Misc. operations
	 */

	/** Retrieve the errno variable from semihosting operations. */
	SEMIHOST_ERRNO          = 0x13,
	/** Get commandline parameters for the application to run with */
	SEMIHOST_GET_CMDLINE    = 0x15,
	SEMIHOST_HEAPINFO       = 0x16,
	SEMIHOST_ISERROR        = 0x08,
	SEMIHOST_SYSTEM         = 0x12
};

/**
 * @brief Modes to open a file with
 *
 * Behaviour corresponds to equivalent fopen strings.
 * i.e. SEMIHOST_OPEN_RB_PLUS == "rb+"
 */
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,
};

/**
 * @brief Manually execute a semihosting instruction
 *
 * @param instr instruction code to run
 * @param args instruction specific arguments
 *
 * @return integer return code of instruction
 */
long semihost_exec(enum semihost_instr instr, void *args);

/**
 * @brief Read a byte from the console
 *
 * @return char byte read from the console.
 */
char semihost_poll_in(void);

/**
 * @brief Write a byte to the console
 *
 * @param c byte to write to console
 */
void semihost_poll_out(char c);

/**
 * @brief Open a file on the host system
 *
 * @param path file path to open. Can be absolute or relative to current
 *             directory of the running process.
 * @param mode value from @ref semihost_open_mode.
 *
 * @retval handle positive handle on success.
 * @retval -1 on failure.
 */
long semihost_open(const char *path, long mode);

/**
 * @brief Close a file
 *
 * @param fd handle returned by @ref semihost_open.
 *
 * @retval 0 on success.
 * @retval -1 on failure.
 */
long semihost_close(long fd);

/**
 * @brief Query the size of a file
 *
 * @param fd handle returned by @ref semihost_open.
 *
 * @retval positive file size on success.
 * @retval -1 on failure.
 */
long semihost_flen(long fd);

/**
 * @brief Seeks to an absolute position in a file.
 *
 * @param fd handle returned by @ref semihost_open.
 * @param offset offset from the start of the file in bytes.
 *
 * @retval 0 on success.
 * @retval -errno negative error code on failure.
 */
long semihost_seek(long fd, long offset);

/**
 * @brief Read the contents of a file into a buffer.
 *
 * @param fd handle returned by @ref semihost_open.
 * @param buf buffer to read data into.
 * @param len number of bytes to read.
 *
 * @retval read number of bytes read on success.
 * @retval -errno negative error code on failure.
 */
long semihost_read(long fd, void *buf, long len);

/**
 * @brief Write the contents of a buffer into a file.
 *
 * @param fd handle returned by @ref semihost_open.
 * @param buf buffer to write data from.
 * @param len number of bytes to write.
 *
 * @retval 0 on success.
 * @retval -errno negative error code on failure.
 */
long semihost_write(long fd, const void *buf, long len);

/**
 * @}
 */

#endif /* ZEPHYR_INCLUDE_ARCH_COMMON_SEMIHOST_H_ */