34fd8d0049
Replace dead link in semihosting documentation. Fix #88206 Signed-off-by: Gaetan Perrot <gaetan.perrot@spacecubics.com>
73 lines
2.4 KiB
ReStructuredText
73 lines
2.4 KiB
ReStructuredText
.. _semihost_guide:
|
|
|
|
Semihosting Guide
|
|
#################
|
|
|
|
Overview
|
|
********
|
|
|
|
Semihosting is a mechanism that enables code running on ARM, RISC-V and Xtensa
|
|
targets to communicate and use the Input/Output facilities on a host computer
|
|
that is running a debugger or emulator.
|
|
|
|
More complete documentation on the available functionality is available at the
|
|
`ARM Github documentation`_.
|
|
|
|
The RISC-V functionality borrows from the ARM definitions, as described at the
|
|
`RISC-V Github documentation`_.
|
|
|
|
Semihosting implementation on Xtensa supports GDB File-I/O extension, which is
|
|
explained in `GDB File-I/O Remote Protocol`_.
|
|
|
|
File Operations
|
|
***************
|
|
|
|
Semihosting enables files on the host computer to be opened, read, and modified
|
|
by an application. This can be useful when attempting to validate the behaviour
|
|
of code across datasets that are larger than what can fit into ROM of an
|
|
emulated platform. File paths can be either absolute, or relative to the
|
|
directory of the running process.
|
|
|
|
.. code-block:: c
|
|
|
|
const char *path = "./data.bin";
|
|
long file_len, bytes_read, fd;
|
|
uint8_t buffer[16];
|
|
|
|
/* Open the data file for reading */
|
|
fd = semihost_open(path, SEMIHOST_OPEN_RB);
|
|
if (fd < 0) {
|
|
return -ENOENT;
|
|
}
|
|
/* Read all data from the file */
|
|
file_len = semihost_flen(fd);
|
|
while(file_len > 0) {
|
|
bytes_read = semihost_read(fd, buffer, MIN(file_len, sizeof(buffer)));
|
|
if (bytes_read < 0) {
|
|
break;
|
|
}
|
|
/* Process read data */
|
|
do_data_processing(buffer, bytes_read);
|
|
/* Update remaining length */
|
|
file_len -= bytes_read;
|
|
}
|
|
/* Close the file */
|
|
semihost_close(fd);
|
|
|
|
Additional Functionality
|
|
************************
|
|
|
|
Additional functionality is available by running semihosting instructions
|
|
directly with :c:func:`semihost_exec` with one of the instructions defined
|
|
in :c:enum:`semihost_instr`. For complete documentation on the required
|
|
arguments and return codes, see the `ARM Github documentation`_.
|
|
|
|
API Reference
|
|
*************
|
|
|
|
.. doxygengroup:: semihost
|
|
|
|
.. _ARM Github documentation: https://github.com/ARM-software/abi-aa/blob/main/semihosting/semihosting.rst
|
|
.. _RISC-V Github documentation: https://github.com/riscv-non-isa/riscv-semihosting/blob/main/riscv-semihosting.adoc
|
|
.. _GDB File-I/O Remote Protocol: https://sourceware.org/gdb/current/onlinedocs/gdb.html/File_002dI_002fO-Remote-Protocol-Extension.html
|