[PULL 14/33] docs/specs/vmcoreinfo: Convert to rST

From: Peter Maydell <peter.maydell@linaro.org>
To: qemu-devel@nongnu.org
Subject: [PULL 14/33] docs/specs/vmcoreinfo: Convert to rST
Date: Thu,  2 Nov 2023 17:38:16 +0000	[thread overview]
Message-ID: <20231102173835.609985-15-peter.maydell@linaro.org> (raw)
In-Reply-To: <20231102173835.609985-1-peter.maydell@linaro.org>

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               |  1 +
 docs/specs/index.rst      |  1 +
 docs/specs/vmcoreinfo.rst | 54 +++++++++++++++++++++++++++++++++++++++
 docs/specs/vmcoreinfo.txt | 53 --------------------------------------
 4 files changed, 56 insertions(+), 53 deletions(-)
 create mode 100644 docs/specs/vmcoreinfo.rst
 delete mode 100644 docs/specs/vmcoreinfo.txt

diff --git a/MAINTAINERS b/MAINTAINERS
index 11f3bdbfa78..6d654cc1277 100644
--- a/MAINTAINERS
+++ b/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>
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.rst b/docs/specs/vmcoreinfo.rst
new file mode 100644
index 00000000000..6541aa116f7
--- /dev/null
+++ b/docs/specs/vmcoreinfo.rst
@@ -0,0 +1,54 @@
+=================
+VMCoreInfo device
+=================
+
+The ``-device vmcoreinfo`` will create a ``fw_cfg`` entry for a guest to
+store dump details.
+
+``etc/vmcoreinfo``
+==================
+
+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
+
+    struct FWCfgVMCoreInfo {
+        uint16_t host_format;  /* formats host supports */
+        uint16_t guest_format; /* format guest supplies */
+        uint32_t size;         /* size of vmcoreinfo region */
+        uint64_t paddr;        /* physical address of vmcoreinfo region */
+    };
+
+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
+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``).
+
+Format & content
+================
+
+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.
+
+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 `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.
diff --git a/docs/specs/vmcoreinfo.txt b/docs/specs/vmcoreinfo.txt
deleted file mode 100644
index bcbca6fe47c..00000000000
--- a/docs/specs/vmcoreinfo.txt
+++ /dev/null
@@ -1,53 +0,0 @@
-=================
-VMCoreInfo device
-=================
-
-The `-device vmcoreinfo` will create a fw_cfg entry for a guest to
-store dump details.
-
-etc/vmcoreinfo
-**************
-
-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
-
-    struct FWCfgVMCoreInfo {
-        uint16_t host_format;  /* formats host supports */
-        uint16_t guest_format; /* format guest supplies */
-        uint32_t size;         /* size of vmcoreinfo region */
-        uint64_t paddr;        /* physical address of vmcoreinfo region */
-    };
-
-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
-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).
-
-Format & content
-****************
-
-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.
-
-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
-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.
-- 
2.34.1


