| 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. |