1.. _semihost_guide:
2
3Semihosting Guide
4#################
5
6Overview
7********
8
9Semihosting is a mechanism that enables code running on ARM and RISC-V targets
10to communicate and use the Input/Output facilities on a host computer that is
11running a debugger or emulator.
12
13More complete documentation on the available functionality is available at the
14`ARM Github documentation`_.
15
16The RISC-V functionality borrows from the ARM definitions, as described at the
17`RISC-V Github documentation`_.
18
19File Operations
20***************
21
22Semihosting enables files on the host computer to be opened, read, and modified
23by an application. This can be useful when attempting to validate the behaviour
24of code across datasets that are larger than what can fit into ROM of an
25emulated platform. File paths can be either absolute, or relative to the
26directory of the running process.
27
28.. code-block:: c
29
30   const char *path = "./data.bin";
31   long file_len, bytes_read, fd;
32   uint8_t buffer[16];
33
34   /* Open the data file for reading */
35   fd = semihost_open(path, SEMIHOST_OPEN_RB);
36   if (fd < 0) {
37      return -ENOENT;
38   }
39   /* Read all data from the file */
40   file_len = semihost_flen(fd);
41   while(file_len > 0) {
42      bytes_read = semihost_read(fd, buffer, MIN(file_len, sizeof(buffer)));
43      if (bytes_read < 0) {
44         break;
45      }
46      /* Process read data */
47      do_data_processing(buffer, bytes_read);
48      /* Update remaining length */
49      file_len -= bytes_read;
50   }
51   /* Close the file */
52   semihost_close(fd);
53
54Additional Functionality
55########################
56
57Additional functionality is available by running semihosting instructions
58directly with :c:func:`semihost_exec` with one of the instructions defined
59in :c:enum:`semihost_instr`. For complete documentation on the required
60arguments and return codes, see the `ARM Github documentation`_.
61
62API Reference
63*************
64
65.. doxygengroup:: semihost
66
67.. _ARM Github documentation: https://github.com/ARM-software/abi-aa/blob/main/semihosting/semihosting.rst
68.. _RISC-V Github documentation: https://github.com/riscv/riscv-semihosting-spec/blob/main/riscv-semihosting-spec.adoc
69