[RFC PATCH v3 0/1] VM introspection

[Adalbert Lazar <alazar@bitdefender.com>]

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