docs/specs/vmcoreinfo: Convert to rST

Convert docs/specs/vmcoreinfo.txt to rST format.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Message-id: 20230927151205.70930-8-peter.maydell@linaro.org
Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org>
Acked-by: Marc-André Lureau <marcandre.lureau@redhat.com>

MAINTAINERS

@@ -2884,6 +2884,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
 
 Error reporting
 M: Markus Armbruster <armbru@redhat.com>

docs/specs/index.rst

@@ -30,3 +30,4 @@ guest hardware that is specific to QEMU.
    pvpanic
    standard-vga
    virt-ctlr
+   vmcoreinfo

docs/specs/vmcoreinfo.txt → 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
-which case the entry data can be ignored by qemu (but you may still
-access it through a debugger, via vmcoreinfo_realize::vmcoreinfo_state).
+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``).
 
 Format & content
-****************
+================
 
-As of qemu 2.11, only VMCOREINFO_FORMAT_ELF is supported.
+As of QEMU 2.11, only ``VMCOREINFO_FORMAT_ELF`` is supported.
 
 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.