Re: [PATCH 7/8] docs/specs/vmcoreinfo: Convert to rST

[Philippe Mathieu-Daudé]

On 27/9/23 17:12, Peter Maydell wrote:
> Convert docs/specs/vmcoreinfo.txt to rST format.
>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
>   MAINTAINERS                                   |  1 +
>   docs/specs/index.rst                          |  1 +
>   docs/specs/{vmcoreinfo.txt => vmcoreinfo.rst} | 33 ++++++++++---------
>   3 files changed, 19 insertions(+), 16 deletions(-)
>   rename docs/specs/{vmcoreinfo.txt => vmcoreinfo.rst} (50%)
>
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 9e27cad11c3..23ee617acaf 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -2805,6 +2805,7 @@ F: include/sysemu/dump.h
>   F: qapi/dump.json
>   F: scripts/dump-guest-memory.py
>   F: stubs/dump.c
> +F: docs/specs/vmcoreinfo.rst

Good :)

Cc'ing Marc-André.

>   Error reporting
>   M: Markus Armbruster <armbru@redhat.com>
> diff --git a/docs/specs/index.rst b/docs/specs/index.rst
> index 8d30968650b..7a56ccb2155 100644
> --- a/docs/specs/index.rst
> +++ b/docs/specs/index.rst
> @@ -30,3 +30,4 @@ guest hardware that is specific to QEMU.
>      pvpanic
>      standard-vga
>      virt-ctlr
> +   vmcoreinfo
> diff --git a/docs/specs/vmcoreinfo.txt b/docs/specs/vmcoreinfo.rst
> similarity index 50%
> rename from docs/specs/vmcoreinfo.txt
> rename to docs/specs/vmcoreinfo.rst
> index bcbca6fe47c..462b04474d3 100644
> --- a/docs/specs/vmcoreinfo.txt
> +++ b/docs/specs/vmcoreinfo.rst
> @@ -2,19 +2,19 @@
>   VMCoreInfo device
>   =================
>   
> -The `-device vmcoreinfo` will create a fw_cfg entry for a guest to
> +The ``-device vmcoreinfo`` will create a ``fw_cfg`` entry for a guest to
>   store dump details.
>   
> -etc/vmcoreinfo
> -**************
> +``etc/vmcoreinfo``
> +==================
>   
> -A guest may use this fw_cfg entry to add information details to qemu
> +A guest may use this ``fw_cfg`` entry to add information details to qemu
>   dumps.
>   
>   The entry of 16 bytes has the following layout, in little-endian::
>   
> -#define VMCOREINFO_FORMAT_NONE 0x0
> -#define VMCOREINFO_FORMAT_ELF 0x1
> +    #define VMCOREINFO_FORMAT_NONE 0x0
> +    #define VMCOREINFO_FORMAT_ELF 0x1
>   
>       struct FWCfgVMCoreInfo {
>           uint16_t host_format;  /* formats host supports */
> @@ -26,17 +26,17 @@ The entry of 16 bytes has the following layout, in 
> little-endian::
>   Only full write (of 16 bytes) are considered valid for further
>   processing of entry values.
>   
> -A write of 0 in guest_format will disable further processing of
> +A write of 0 in ``guest_format`` will disable further processing of
>   vmcoreinfo entry values & content.
>   
> -You may write a guest_format that is not supported by the host, in
> +You may write a ``guest_format`` that is not supported by the host, in
>   which case the entry data can be ignored by qemu (but you may still
> -access it through a debugger, via vmcoreinfo_realize::vmcoreinfo_state).
> +access it through a debugger, via ``vmcoreinfo_realize::vmcoreinfo_state``).
>   
>   Format & content
> -****************
> +================
>   
> -As of qemu 2.11, only VMCOREINFO_FORMAT_ELF is supported.
> +As of qemu 2.11, only ``VMCOREINFO_FORMAT_ELF`` is supported.

Maybe s/qemu/QEMU/, otherwise:

Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org>

>   The entry gives location and size of an ELF note that is appended in
>   qemu dumps.
> @@ -44,10 +44,11 @@ qemu dumps.
>   The note format/class must be of the target bitness and the size must
>   be less than 1Mb.
>   
> -If the ELF note name is "VMCOREINFO", it is expected to be the Linux
> -vmcoreinfo note (see Documentation/ABI/testing/sysfs-kernel-vmcoreinfo
> -in Linux source). In this case, qemu dump code will read the content
> -as a key=value text file, looking for "NUMBER(phys_base)" key
> +If the ELF note name is ``VMCOREINFO``, it is expected to be the Linux
> +vmcoreinfo note (see `the kernel documentation for its format
> +<https://www.kernel.org/doc/Documentation/ABI/testing/sysfs-kernel-vmcoreinfo>`_).
> +In this case, qemu dump code will read the content
> +as a key=value text file, looking for ``NUMBER(phys_base)`` key
>   value. The value is expected to be more accurate than architecture
>   guess of the value. This is useful for KASLR-enabled guest with
> -ancient tools not handling the VMCOREINFO note.
> +ancient tools not handling the ``VMCOREINFO`` note.