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

[Marc-André Lureau]

On Tue, Oct 31, 2023 at 7:43 PM Philippe Mathieu-Daudé
<philmd@linaro.org> wrote:
>
> 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>

Acked-by: Marc-André Lureau <marcandre.lureau@redhat.com>

> > ---
> >   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.
>