Re: [PATCH v3 23/33] docs: Roll semihosting option information into qemu-options.hx

["Alex Bennée" <alex.bennee@linaro.org>]

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

> Currently the per-target documentation for those targets that
> implement semihosting includes a bit of text that goes into both the
> manual and the manpage about options specific to the target.  This
> text is redundant with the earlier generic option description of the
> semihosting option produced from qemu-options.hx. To avoid having
> to create a lot of stub include files to include into the rST
> generated qemu.1 manpage, roll target-specific bits of information
> into the qemu-options.hx text, so the user doesn't have to look
> in two places for this information.
>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

Reviewed-by: Alex Bennée <alex.bennee@linaro.org>

> ---
> Yes, it would in theory make sense to do this before generating
> the rst from the texi docs, but I didn't realize this was a
> good idea until well after Paolo had done that part.
> ---
>  docs/system/target-arm.rst     | 10 ----------
>  docs/system/target-arm.texi    | 18 ------------------
>  docs/system/target-m68k.rst    | 11 -----------
>  docs/system/target-m68k.texi   | 19 -------------------
>  docs/system/target-xtensa.rst  | 12 ------------
>  docs/system/target-xtensa.texi | 20 --------------------
>  qemu-options.hx                | 18 ++++++++++++++++++
>  7 files changed, 18 insertions(+), 90 deletions(-)
>
> diff --git a/docs/system/target-arm.rst b/docs/system/target-arm.rst
> index 0490be55871..d2a3b44ce88 100644
> --- a/docs/system/target-arm.rst
> +++ b/docs/system/target-arm.rst
> @@ -215,13 +215,3 @@ emulation includes the following elements:
>  
>  A Linux 2.6 test image is available on the QEMU web site. More
>  information is available in the QEMU mailing-list archive.
> -
> -The following options are specific to the ARM emulation:
> -
> -``-semihosting``
> -   Enable semihosting syscall emulation.
> -
> -   On ARM this implements the \"Angel\" interface.
> -
> -   Note that this allows guest direct access to the host filesystem, so
> -   should only be used with trusted guest OS.
> diff --git a/docs/system/target-arm.texi b/docs/system/target-arm.texi
> index c56b5f6ebfe..eb80dd35f0b 100644
> --- a/docs/system/target-arm.texi
> +++ b/docs/system/target-arm.texi
> @@ -243,21 +243,3 @@ Three on-chip UARTs
>  A Linux 2.6 test image is available on the QEMU web site. More
>  information is available in the QEMU mailing-list archive.
>  
> -@c man begin OPTIONS
> -
> -The following options are specific to the ARM emulation:
> -
> -@table @option
> -
> -@item -semihosting
> -Enable semihosting syscall emulation.
> -
> -On ARM this implements the "Angel" interface.
> -
> -Note that this allows guest direct access to the host filesystem,
> -so should only be used with trusted guest OS.
> -
> -@end table
> -
> -@c man end
> -
> diff --git a/docs/system/target-m68k.rst b/docs/system/target-m68k.rst
> index 50b7dd9d639..d28d3b92e5e 100644
> --- a/docs/system/target-m68k.rst
> +++ b/docs/system/target-m68k.rst
> @@ -19,14 +19,3 @@ The AN5206 emulation includes the following devices:
>  -  MCF5206 ColdFire V2 Microprocessor.
>  
>  -  Two on-chip UARTs.
> -
> -The following options are specific to the ColdFire emulation:
> -
> -``-semihosting``
> -   Enable semihosting syscall emulation.
> -
> -   On M68K this implements the \"ColdFire GDB\" interface used by
> -   libgloss.
> -
> -   Note that this allows guest direct access to the host filesystem, so
> -   should only be used with trusted guest OS.
> diff --git a/docs/system/target-m68k.texi b/docs/system/target-m68k.texi
> index a77b19ea0f1..dcce7bc8c56 100644
> --- a/docs/system/target-m68k.texi
> +++ b/docs/system/target-m68k.texi
> @@ -23,22 +23,3 @@ MCF5206 ColdFire V2 Microprocessor.
>  @item
>  Two on-chip UARTs.
>  @end itemize
> -
> -@c man begin OPTIONS
> -
> -The following options are specific to the ColdFire emulation:
> -
> -@table @option
> -
> -@item -semihosting
> -Enable semihosting syscall emulation.
> -
> -On M68K this implements the "ColdFire GDB" interface used by libgloss.
> -
> -Note that this allows guest direct access to the host filesystem,
> -so should only be used with trusted guest OS.
> -
> -@end table
> -
> -@c man end
> -
> diff --git a/docs/system/target-xtensa.rst b/docs/system/target-xtensa.rst
> index 43cab8dc4da..8d703ad769e 100644
> --- a/docs/system/target-xtensa.rst
> +++ b/docs/system/target-xtensa.rst
> @@ -25,15 +25,3 @@ The Avnet LX60/LX110/LX200 emulation supports:
>  -  16550 UART
>  
>  -  OpenCores 10/100 Mbps Ethernet MAC
> -
> -The following options are specific to the Xtensa emulation:
> -
> -``-semihosting``
> -   Enable semihosting syscall emulation.
> -
> -   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.
> -
> -   Note that this allows guest direct access to the host filesystem, so
> -   should only be used with trusted guest OS.
> diff --git a/docs/system/target-xtensa.texi b/docs/system/target-xtensa.texi
> index 40327de6fa7..1e6c04dccd6 100644
> --- a/docs/system/target-xtensa.texi
> +++ b/docs/system/target-xtensa.texi
> @@ -33,23 +33,3 @@ A range of Xtensa CPUs, default is the DC232B
>  @item
>  OpenCores 10/100 Mbps Ethernet MAC
>  @end itemize
> -
> -@c man begin OPTIONS
> -
> -The following options are specific to the Xtensa emulation:
> -
> -@table @option
> -
> -@item -semihosting
> -Enable semihosting syscall emulation.
> -
> -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.
> -
> -Note that this allows guest direct access to the host filesystem,
> -so should only be used with trusted guest OS.
> -
> -@end table
> -
> -@c man end
> -
> diff --git a/qemu-options.hx b/qemu-options.hx
> index 5fbfa2797cb..4bc8048f60b 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -4116,6 +4116,12 @@ STEXI
>  @item -semihosting
>  @findex -semihosting
>  Enable semihosting mode (ARM, M68K, Xtensa, MIPS, Nios II only).
> +
> +Note that this allows guest direct access to the host filesystem, so
> +should only be used with a trusted guest OS.
> +
> +See the -semihosting-config option documentation for further information
> +about the facilities this enables.
>  ETEXI
>  DEF("semihosting-config", HAS_ARG, QEMU_OPTION_semihosting_config,
>      "-semihosting-config [enable=on|off][,target=native|gdb|auto][,chardev=id][,arg=str[,...]]\n" \
> @@ -4126,6 +4132,18 @@ STEXI
>  @item -semihosting-config [enable=on|off][,target=native|gdb|auto][,chardev=id][,arg=str[,...]]
>  @findex -semihosting-config
>  Enable and configure semihosting (ARM, M68K, Xtensa, MIPS, Nios II 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.
> +
>  @table @option
>  @item target=@code{native|gdb|auto}
>  Defines where the semihosting calls will be addressed, to QEMU (@code{native})


-- 
Alex Bennée