Convert docs/specs/vmcoreinfo.txt to rST format. Signed-off-by: Peter Maydell <[email protected]> --- 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 Error reporting M: Markus Armbruster <[email protected]> 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. 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. -- 2.34.1
