docs/specs/vmcoreinfo.rst

   1 =================
   2 VMCoreInfo device
   3 =================
   4
   5 The ``-device vmcoreinfo`` will create a ``fw_cfg`` entry for a guest to
   6 store dump details.
   7
   8 ``etc/vmcoreinfo``
   9 ==================
  10
  11 A guest may use this ``fw_cfg`` entry to add information details to QEMU
  12 dumps.
  13
  14 The entry of 16 bytes has the following layout, in little-endian::
  15
  16     #define VMCOREINFO_FORMAT_NONE 0x0
  17     #define VMCOREINFO_FORMAT_ELF 0x1
  18
  19     struct FWCfgVMCoreInfo {
  20         uint16_t host_format;  /* formats host supports */
  21         uint16_t guest_format; /* format guest supplies */
  22         uint32_t size;         /* size of vmcoreinfo region */
  23         uint64_t paddr;        /* physical address of vmcoreinfo region */
  24     };
  25
  26 Only full write (of 16 bytes) are considered valid for further
  27 processing of entry values.
  28
  29 A write of 0 in ``guest_format`` will disable further processing of
  30 vmcoreinfo entry values & content.
  31
  32 You may write a ``guest_format`` that is not supported by the host, in
  33 which case the entry data can be ignored by QEMU (but you may still
  34 access it through a debugger, via ``vmcoreinfo_realize::vmcoreinfo_state``).
  35
  36 Format & content
  37 ================
  38
  39 As of QEMU 2.11, only ``VMCOREINFO_FORMAT_ELF`` is supported.
  40
  41 The entry gives location and size of an ELF note that is appended in
  42 qemu dumps.
  43
  44 The note format/class must be of the target bitness and the size must
  45 be less than 1Mb.
  46
  47 If the ELF note name is ``VMCOREINFO``, it is expected to be the Linux
  48 vmcoreinfo note (see `the kernel documentation for its format
  49 <https://www.kernel.org/doc/Documentation/ABI/testing/sysfs-kernel-vmcoreinfo>`_).
  50 In this case, qemu dump code will read the content
  51 as a key=value text file, looking for ``NUMBER(phys_base)`` key
  52 value. The value is expected to be more accurate than architecture
  53 guess of the value. This is useful for KASLR-enabled guest with
  54 ancient tools not handling the ``VMCOREINFO`` note.