The following patch adds the documentation for an introspection subsystem for KVM (KVMI). It details the purpose and the use case that has shaped the proposed API/ABI, as well as the wire protocol. The previous RFC can be read here: https://marc.info/?l=kvm&m=149943806203155 In this iteration we consolidated the feedback received from Paolo and others. More discussion is needed on the topic of pausing the VM. For now we settled on a vCPU pause function that should be used to implement the former. This requires a bit of finesse in userspace but keeps a potentially complicated logic out of the kernel. One other topic that we would like to bring again into discussion is that of page sharing between guests (the VM on which the introspection tool runs and the VM being introspected, provided they are on the same host). This iteration of the document also tries to integrate #VE and multiple EPT views (VMFUNC). It does so simply by copying the ideas that have been discussed on xen-devel (see KVMI_CONTROL_VE and KVMI_{GET,SET}_PAGE_ACCESS). Please note that some slight adjustments might still appear as we progress with the qemu side of things. We have not included anything about IOMMU groups as we feel we don't yet have all the details to begin working on an API that deals with DMA attacks. Changes since v2: - make small changes to the wire protocol (eg. use kvmi_error_code with every command reply, a few renames, etc.) - removed '_x86' from x86 specific structure names. Architecture specific structures will have the same name. - drop KVMI_GET_MTRR_TYPE and KVMI_GET_MTRRS (use KVMI_SET_REGISTERS) - drop KVMI_EVENT_ACTION_SET_REGS (use KVMI_SET_REGISTERS) - remove KVMI_MAP_PHYSICAL_PAGE_TO_GUEST and KVMI_UNMAP_PHYSICAL_PAGE_FROM_GUEST (to be replaced by a token+hypercall pair) - extend KVMI_GET_VERSION with allowed commnd/event masks - replace KVMI_PAUSE_GUEST/KVMI_UNPAUSE_GUEST with KVMI_PAUSE_VCPU - replace KVMI_SHUTDOWN_GUEST with KVMI_EVENT_ACTION_CRASH - replace KVMI_GET_XSAVE_INFO with KVMI_GET_CPUID - merge KVMI_INJECT_PAGE_FAULT and KVMI_INJECT_BREAKPOINT in KVMI_INJECT_EXCEPTION - replace event reply flags with ALLOW/SKIP/RETRY/CRASH actions - make KVMI_SET_REGISTERS work with vCPU events only - add EPT view support in KVMI_GET_PAGE_ACCESS/KVMI_SET_PAGE_ACCESS - add support for multiple pages in KVMI_GET_PAGE_ACCESS/KVMI_SET_PAGE_ACCESS - add (back) KVMI_READ_PHYSICAL/KVMI_WRITE_PHYSICAL - add KVMI_CONTROL_VE - add cstar to KVMI_EVENT - add new events: KVMI_EVENT_VCPU_PAUSED, KVMI_EVENT_CREATE_VCPU, KVMI_EVENT_DESCRIPTOR_ACCESS, KVMI_EVENT_SINGLESTEP - add new sections: "Introspection capabilities", "Live migrations", "Guest snapshots with memory", "Memory access safety" - document the hypercall used by the KVMI_EVENT_HYPERCALL command (was KVMI_EVENT_USER_CALL) Changes since v1: - add documentation and ABI [Paolo, Jan] - drop all the other patches for now [Paolo] - remove KVMI_GET_GUESTS, KVMI_EVENT_GUEST_ON, KVMI_EVENT_GUEST_OFF, and let libvirt/qemu handle this [Stefan, Paolo] - change the license from LGPL to GPL [Jan] - remove KVMI_READ_PHYSICAL and KVMI_WRITE_PHYSICAL (not used anymore) - make the interface a little more consistent Adalbert Lazar (1): kvm: add documentation for the VM introspection subsystem Documentation/virtual/kvm/hypercalls.txt | 32 + Documentation/virtual/kvm/kvmi.rst | 1275 ++++++++++++++++++++++++++++++ 2 files changed, 1307 insertions(+) create mode 100644 Documentation/virtual/kvm/kvmi.rst
