On Tue, Oct 31, 2023 at 7:43 PM Philippe Mathieu-Daudé
<phi...@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.mayd...@linaro.org>
Acked-by: Marc-André Lureau <marcandre.lur...@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 <arm...@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é <phi...@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.
>
