[3/4] semihosting: add semihosting section to the docs

The main reason to do this is to document our O_BINARY implementation
decision somewhere. However I've also moved some of the implementation
details out of qemu-options and added links between the two. As a
bonus I've highlighted the scary warnings about host access with the
appropriate RST tags.

Reviewed-by: Richard Henderson <richard.henderson@linaro.org>
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>

---
v2
  - moved inside the generic emulation section
---
 docs/about/emulation.rst | 80 ++++++++++++++++++++++++++++++++++++++++
 qemu-options.hx          | 27 +++++---------
 2 files changed, 90 insertions(+), 17 deletions(-)

On Fri, 13 Jan 2023 at 13:39, Alex Bennée <alex.bennee@linaro.org> wrote:
>
> The main reason to do this is to document our O_BINARY implementation
> decision somewhere. However I've also moved some of the implementation
> details out of qemu-options and added links between the two. As a
> bonus I've highlighted the scary warnings about host access with the
> appropriate RST tags.
>
> Reviewed-by: Richard Henderson <richard.henderson@linaro.org>
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
>
> ---
> v2
>   - moved inside the generic emulation section
> ---
>  docs/about/emulation.rst | 80 ++++++++++++++++++++++++++++++++++++++++
>  qemu-options.hx          | 27 +++++---------
>  2 files changed, 90 insertions(+), 17 deletions(-)
>
> diff --git a/docs/about/emulation.rst b/docs/about/emulation.rst
> index d919175b5e..4d978e697b 100644
> --- a/docs/about/emulation.rst
> +++ b/docs/about/emulation.rst
> @@ -101,3 +101,83 @@ depending on the guest architecture.
>
>  A number of features are are only available when running under
>  emulation including :ref:`Record/Replay<replay>` and :ref:`TCG Plugins`.
> +
> +.. _Semihosting:
> +
> +Semihosting
> +-----------
> +
> +Semihosting is a feature provided by a number of guests that allow the

It's not provided by the guest, it's provided by QEMU... The
important thing here is that semihosting is an API defined by
somebody else, eg the owner of the architecture, and QEMU
offers an implementation of it.

> +program running on the target to interact with the host system. On
> +real hardware this is usually provided by a debugger hooked directly
> +to the system.
> +
> +Generally semihosting makes it easier to bring up low level code before a
> +more fully functional operating system has been enabled. On QEMU it
> +also allows for embedded micro-controller code which typically doesn't
> +have a full libc to be run as "bare-metal" code under QEMU's user-mode
> +emulation. It is also useful for writing test cases and indeed a
> +number of compiler suites as well as QEMU itself use semihosting calls
> +to exit test code while reporting the success state.
> +
> +Semihosting is only available using TCG emulation. This is because the
> +instructions to trigger a semihosting call are typically reserved
> +causing most hypervisors to trap and fault on them.
> +
> +.. warning::
> +   Semihosting inherently bypasses any isolation there may be between
> +   the guest and the host. As a result a program using semihosting can
> +   happily trash your host system. You should only ever run trusted
> +   code with semihosting enabled.

(One of these days I might write the patch for 'safe semihosting'
which limits support to only non-harmful functions like console
output and makes all the file access stuff return an error...)

> +
> +Redirection
> +~~~~~~~~~~~
> +
> +Semihosting calls can be re-directed to a (potentially remote) gdb
> +during debugging via the :ref:`gdbstub<GDB usage>`. Output to the
> +semihosting console is configured as a ``chardev`` so can be
> +redirected to a file, pipe or socket like any other ``chardev``
> +device.
> +
> +See :ref:`Semihosting Options<Semihosting Options>` for details.
> +
> +Supported Targets
> +~~~~~~~~~~~~~~~~~
> +
> +Most targets offer a similar semihosting implementations with some

"offer similar"

> +minor changes to define the appropriate instruction to encode the
> +semihosting call and which registers hold the parameters. They tend to
> +presents a simple POSIX-like API which allows your program to read and
> +write files, access the console and some other basic interactions.

"For full details of the ABI for a particular target, and the
set of calls it provides, you should consult the semihosting
specification for that architecture."

> +
> +.. note::
> +   QEMU makes an implementation decision to implement all file access
> +   in ``O_BINARY`` mode regardless of the host operating system.

We should say what the user-visible effect of this is (i.e. that even
if the semihosting API the guest uses makes a distinction between
"text" and "binary" mode files, QEMU does not, and no line-terminator
conversion is performed for input or output).

> This
> +   is because gdb semihosting support doesn't make the distinction
> +   between the modes and magically processing line endings can be confusing.
> +
> +.. list-table:: Guest Architectures supporting Semihosting
> +  :widths: 10 10 80
> +  :header-rows: 1
> +
> +  * - Architecture
> +    - Modes
> +    - Specification
> +  * - Arm
> +    - System and User-mode
> +    - https://github.com/ARM-software/abi-aa/blob/main/semihosting/semihosting.rst
> +  * - m68k
> +    - System
> +    - https://sourceware.org/git/?p=newlib-cygwin.git;a=blob;f=libgloss/m68k/m68k-semi.txt;hb=HEAD
> +  * - mips
> +    - System
> +    - Unified Hosting Interface (MD01069)
> +  * - Nios II
> +    - System
> +    - https://sourceware.org/git/gitweb.cgi?p=newlib-cygwin.git;a=blob;f=libgloss/nios2/nios2-semi.txt;hb=HEAD
> +  * - RISC-V
> +    - System and User-mode
> +    - https://github.com/riscv/riscv-semihosting-spec/blob/main/riscv-semihosting-spec.adoc
> +  * - Xtensa
> +    - System
> +    - Tensilica ISS SIMCALL

We should be consistent in this table whether we're naming the
architectures by their official names (eg "RISC-V"), or by the
QEMU lowercase names for them (eg "mips").

> diff --git a/qemu-options.hx b/qemu-options.hx
> index 3aa3a2f5a3..de3a368f58 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -4633,10 +4633,13 @@ DEF("semihosting", 0, QEMU_OPTION_semihosting,
>      QEMU_ARCH_MIPS | QEMU_ARCH_NIOS2 | QEMU_ARCH_RISCV)
>  SRST
>  ``-semihosting``
> -    Enable semihosting mode (ARM, M68K, Xtensa, MIPS, Nios II, RISC-V only).
> +    Enable :ref:`Semihosting` mode (ARM, M68K, Xtensa, MIPS, Nios II, RISC-V only).
>
> -    Note that this allows guest direct access to the host filesystem, so
> -    should only be used with a trusted guest OS.
> +    .. warning::
> +      Note that this allows guest direct access to the host filesystem, so
> +      should only be used with a trusted guest OS.
> +
> +    .. _Semihosting Options:

Does this render OK in the manpage version of this text ?

>      See the -semihosting-config option documentation for further
>      information about the facilities this enables.
> @@ -4648,22 +4651,12 @@ QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA |
>  QEMU_ARCH_MIPS | QEMU_ARCH_NIOS2 | QEMU_ARCH_RISCV)
>  SRST
>  ``-semihosting-config [enable=on|off][,target=native|gdb|auto][,chardev=id][,userspace=on|off][,arg=str[,...]]``
> -    Enable and configure semihosting (ARM, M68K, Xtensa, MIPS, Nios II, RISC-V
> +    Enable and configure :ref:`Semihosting` (ARM, M68K, Xtensa, MIPS, Nios II, RISC-V
>      only).
>
> -    Note that this allows guest direct access to the host filesystem, so
> -    should only be used with a trusted guest OS.
> -
> -    On Arm this implements the standard semihosting API, version 2.0.
> -
> -    On M68K this implements the "ColdFire GDB" interface used by
> -    libgloss.
> -
> -    Xtensa semihosting provides basic file IO calls, such as
> -    open/read/write/seek/select. Tensilica baremetal libc for ISS and
> -    linux platform "sim" use this interface.
> -
> -    On RISC-V this implements the standard semihosting API, version 0.2.
> +    .. warning::
> +      Note that this allows guest direct access to the host filesystem, so
> +      should only be used with a trusted guest OS.
>
>      ``target=native|gdb|auto``
>          Defines where the semihosting calls will be addressed, to QEMU
> --
> 2.34.1
>



-- PMM

Peter Maydell <peter.maydell@linaro.org> writes:

> On Fri, 13 Jan 2023 at 13:39, Alex Bennée <alex.bennee@linaro.org> wrote:
>>
<snip>
>> diff --git a/qemu-options.hx b/qemu-options.hx
>> index 3aa3a2f5a3..de3a368f58 100644
>> --- a/qemu-options.hx
>> +++ b/qemu-options.hx
>> @@ -4633,10 +4633,13 @@ DEF("semihosting", 0, QEMU_OPTION_semihosting,
>>      QEMU_ARCH_MIPS | QEMU_ARCH_NIOS2 | QEMU_ARCH_RISCV)
>>  SRST
>>  ``-semihosting``
>> -    Enable semihosting mode (ARM, M68K, Xtensa, MIPS, Nios II, RISC-V only).
>> +    Enable :ref:`Semihosting` mode (ARM, M68K, Xtensa, MIPS, Nios II, RISC-V only).
>>
>> -    Note that this allows guest direct access to the host filesystem, so
>> -    should only be used with a trusted guest OS.
>> +    .. warning::
>> +      Note that this allows guest direct access to the host filesystem, so
>> +      should only be used with a trusted guest OS.
>> +
>> +    .. _Semihosting Options:
>
> Does this render OK in the manpage version of this text ?

Seems to yes.