LCOV - code coverage report
Current view: top level - zephyr/arch/common - semihost.h Coverage Total Hit
Test: new.info Lines: 83.3 % 12 10
Test Date: 2025-09-05 20:47:19

            Line data    Source code
       1            1 : /*
       2              :  * Copyright (c) 2022, Commonwealth Scientific and Industrial Research
       3              :  * Organisation (CSIRO) ABN 41 687 119 230.
       4              :  *
       5              :  * SPDX-License-Identifier: Apache-2.0
       6              :  *
       7              :  * Based on the ARM semihosting API from:
       8              :  * https://github.com/ARM-software/abi-aa/blob/main/semihosting/semihosting.rst
       9              :  *
      10              :  * RISC-V semihosting also follows these conventions:
      11              :  * https://github.com/riscv-non-isa/riscv-semihosting/blob/main/riscv-semihosting.adoc
      12              :  */
      13              : 
      14              : /**
      15              :  * @file
      16              :  *
      17              :  * @brief public Semihosting APIs based on ARM definitions.
      18              :  * @defgroup semihost Semihosting APIs
      19              :  * @ingroup os_services
      20              :  * @{
      21              :  */
      22              : 
      23              : #ifndef ZEPHYR_INCLUDE_ARCH_COMMON_SEMIHOST_H_
      24              : #define ZEPHYR_INCLUDE_ARCH_COMMON_SEMIHOST_H_
      25              : 
      26              : /** @brief Semihosting instructions */
      27            0 : enum semihost_instr {
      28              :         /*
      29              :          * File I/O operations
      30              :          */
      31              : 
      32              :         /** Open a file or stream on the host system. */
      33              :         SEMIHOST_OPEN   = 0x01,
      34              :         /** Check whether a file is associated with a stream/terminal */
      35              :         SEMIHOST_ISTTY  = 0x09,
      36              :         /** Write to a file or stream. */
      37              :         SEMIHOST_WRITE  = 0x05,
      38              :         /** Read from a file at the current cursor position. */
      39              :         SEMIHOST_READ   = 0x06,
      40              :         /** Closes a file on the host which has been opened by SEMIHOST_OPEN. */
      41              :         SEMIHOST_CLOSE  = 0x02,
      42              :         /** Get the length of a file. */
      43              :         SEMIHOST_FLEN   = 0x0C,
      44              :         /** Set the file cursor to a given position in a file. */
      45              :         SEMIHOST_SEEK   = 0x0A,
      46              :         /** Get a temporary absolute file path to create a temporary file. */
      47              :         SEMIHOST_TMPNAM = 0x0D,
      48              :         /** Remove a file on the host system. Possibly insecure! */
      49              :         SEMIHOST_REMOVE = 0x0E,
      50              :         /** Rename a file on the host system. Possibly insecure! */
      51              :         SEMIHOST_RENAME = 0x0F,
      52              : 
      53              :         /*
      54              :          * Terminal I/O operations
      55              :          */
      56              : 
      57              :         /** Write one character to the debug terminal. */
      58              :         SEMIHOST_WRITEC         = 0x03,
      59              :         /** Write a NULL terminated string to the debug terminal. */
      60              :         SEMIHOST_WRITE0         = 0x04,
      61              :         /** Read one character from the debug terminal. */
      62              :         SEMIHOST_READC          = 0x07,
      63              : 
      64              :         /*
      65              :          * Time operations
      66              :          */
      67              :         SEMIHOST_CLOCK          = 0x10,
      68              :         SEMIHOST_ELAPSED        = 0x30,
      69              :         SEMIHOST_TICKFREQ       = 0x31,
      70              :         SEMIHOST_TIME           = 0x11,
      71              : 
      72              :         /*
      73              :          * System/Misc. operations
      74              :          */
      75              : 
      76              :         /** Retrieve the errno variable from semihosting operations. */
      77              :         SEMIHOST_ERRNO          = 0x13,
      78              :         /** Get commandline parameters for the application to run with */
      79              :         SEMIHOST_GET_CMDLINE    = 0x15,
      80              :         SEMIHOST_HEAPINFO       = 0x16,
      81              :         SEMIHOST_ISERROR        = 0x08,
      82              :         SEMIHOST_SYSTEM         = 0x12
      83              : };
      84              : 
      85              : /**
      86              :  * @brief Modes to open a file with
      87              :  *
      88              :  * Behaviour corresponds to equivalent fopen strings.
      89              :  * i.e. SEMIHOST_OPEN_RB_PLUS == "rb+"
      90              :  */
      91            0 : enum semihost_open_mode {
      92              :         SEMIHOST_OPEN_R         = 0,
      93              :         SEMIHOST_OPEN_RB        = 1,
      94              :         SEMIHOST_OPEN_R_PLUS    = 2,
      95              :         SEMIHOST_OPEN_RB_PLUS   = 3,
      96              :         SEMIHOST_OPEN_W         = 4,
      97              :         SEMIHOST_OPEN_WB        = 5,
      98              :         SEMIHOST_OPEN_W_PLUS    = 6,
      99              :         SEMIHOST_OPEN_WB_PLUS   = 7,
     100              :         SEMIHOST_OPEN_A         = 8,
     101              :         SEMIHOST_OPEN_AB        = 9,
     102              :         SEMIHOST_OPEN_A_PLUS    = 10,
     103              :         SEMIHOST_OPEN_AB_PLUS   = 11,
     104              : };
     105              : 
     106              : /**
     107              :  * @brief Manually execute a semihosting instruction
     108              :  *
     109              :  * @param instr instruction code to run
     110              :  * @param args instruction specific arguments
     111              :  *
     112              :  * @return integer return code of instruction
     113              :  */
     114            1 : long semihost_exec(enum semihost_instr instr, void *args);
     115              : 
     116              : /**
     117              :  * @brief Read a byte from the console
     118              :  *
     119              :  * @return char byte read from the console.
     120              :  */
     121            1 : char semihost_poll_in(void);
     122              : 
     123              : /**
     124              :  * @brief Write a byte to the console
     125              :  *
     126              :  * @param c byte to write to console
     127              :  */
     128            1 : void semihost_poll_out(char c);
     129              : 
     130              : /**
     131              :  * @brief Open a file on the host system
     132              :  *
     133              :  * @param path file path to open. Can be absolute or relative to current
     134              :  *             directory of the running process.
     135              :  * @param mode value from @ref semihost_open_mode.
     136              :  *
     137              :  * @retval handle positive handle on success.
     138              :  * @retval -1 on failure.
     139              :  */
     140            1 : long semihost_open(const char *path, long mode);
     141              : 
     142              : /**
     143              :  * @brief Close a file
     144              :  *
     145              :  * @param fd handle returned by @ref semihost_open.
     146              :  *
     147              :  * @retval 0 on success.
     148              :  * @retval -1 on failure.
     149              :  */
     150            1 : long semihost_close(long fd);
     151              : 
     152              : /**
     153              :  * @brief Query the size of a file
     154              :  *
     155              :  * @param fd handle returned by @ref semihost_open.
     156              :  *
     157              :  * @retval positive file size on success.
     158              :  * @retval -1 on failure.
     159              :  */
     160            1 : long semihost_flen(long fd);
     161              : 
     162              : /**
     163              :  * @brief Seeks to an absolute position in a file.
     164              :  *
     165              :  * @param fd handle returned by @ref semihost_open.
     166              :  * @param offset offset from the start of the file in bytes.
     167              :  *
     168              :  * @retval 0 on success.
     169              :  * @retval -errno negative error code on failure.
     170              :  */
     171            1 : long semihost_seek(long fd, long offset);
     172              : 
     173              : /**
     174              :  * @brief Read the contents of a file into a buffer.
     175              :  *
     176              :  * @param fd handle returned by @ref semihost_open.
     177              :  * @param buf buffer to read data into.
     178              :  * @param len number of bytes to read.
     179              :  *
     180              :  * @retval read number of bytes read on success.
     181              :  * @retval -errno negative error code on failure.
     182              :  */
     183            1 : long semihost_read(long fd, void *buf, long len);
     184              : 
     185              : /**
     186              :  * @brief Write the contents of a buffer into a file.
     187              :  *
     188              :  * @param fd handle returned by @ref semihost_open.
     189              :  * @param buf buffer to write data from.
     190              :  * @param len number of bytes to write.
     191              :  *
     192              :  * @retval 0 on success.
     193              :  * @retval -errno negative error code on failure.
     194              :  */
     195            1 : long semihost_write(long fd, const void *buf, long len);
     196              : 
     197              : /**
     198              :  * @}
     199              :  */
     200              : 
     201              : #endif /* ZEPHYR_INCLUDE_ARCH_COMMON_SEMIHOST_H_ */
        

Generated by: LCOV version 2.0-1