[RFC PATCH v1 08/26] kvm: add VM introspection usage documentation

[Adalbert Lazăr]

From: Marian Rotariu <address@hidden>

Signed-off-by: Marian Rotariu <address@hidden>
Signed-off-by: Adalbert Lazăr <address@hidden>
---
 qemu-options.hx | 76 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 76 insertions(+)

diff --git a/qemu-options.hx b/qemu-options.hx
index 16debd03cb..6c5618e310 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -5005,6 +5005,82 @@ SRST
         ::
 
             (qemu) qom-set /objects/iothread1 poll-max-ns 100000
+
+    ``-object 
introspection,id=id,chardev=id[,key=id][,handshake_timeout=seconds][,unhook_timeout=seconds][,command=id[,...]][,event=id[,...]]``
+        Defines a VM Introspection (VMI) object that will connect to
+        an introspection tool, initiate the handshake and hand over the 
connection
+        file descriptor to KVM. The introspection channel will be used by
+        the introspection tool to talk directly with KVM. If the VM is paused
+        or migrated, QEMU will delay the action, signal KVM, which in turn will
+        signal the introspection tool to remove its hooks (e.g. breakpoints
+        placed inside the guest).
+
+        The ``chardev`` parameter provides the introspection channel.
+        This is the id of a previously created chardev socket,
+        with a non-zero reconnect parameter.
+
+        The ``key`` parameter is an optional secret object used to
+        authenticate the instrospection tool.
+
+        The ``handshake_timeout`` parameter specify how long will QEMU
+        wait for the introspection tool during handshake (default is
+        10 seconds).
+
+        The ``unhook_timeout` parameter specify how long will QEMU
+        wait for the introspection tool on pause/migrate (default is
+        60 seconds).
+
+        The ``command`` parameter specify an allowed introspection command.
+        It can be used multiple times. If omitted, all commands are
+        allowed. For example, ``command=10,command=8`` will allow the
+        introspection tool to use two commands, KVMI_VCPU_PAUSE(10) and
+        KVMI_VM_WRITE_PHYSICAL(8), in addition to those that are used
+        to query the API, which are always allowed (KVMI_GET_VERSION,
+        KVMI_VM_CHECK_COMMAND and KVMI_VM_CHECK_EVENT).
+
+        The ``event` parameter specify an allowed introspection event.
+        It can be used multiple times. If omitted, all events
+        are allowed. For example, ``event=1,event=3`` will
+        allow the introspection tool to receive only two events,
+        KVMI_EVENT_PAUSE_VCPU(1) and KVMI_EVENT_BREAKPOINT(3).
+
+        VM introspected through a unix socket:
+
+        .. parsed-literal::
+
+             # |qemu_system_x86| \
+                 ......
+                 -chardev 
socket,id=vmi_chardev,type=unix,path=/tmp/vmi-guest1.sock,reconnect=10 \
+                 -object introspection,id=vmi,chardev=vmi_chardev
+
+        VM introspected by an authenticated introspection tool:
+
+        .. parsed-literal::
+
+             # |qemu_system_x86| \
+                 ......
+                 -chardev 
socket,id=vmi_chardev,type=unix,path=/tmp/vmi-guest1.sock,reconnect=10 \
+                 -object secret,id=vmi_key,file=/etc/secret \
+                 -object introspection,id=vmi,chardev=vmi_chardev,key=vmi_key
+
+        VM introspected through a virtual socket, with the introspection tool
+        listening on port 4321 from another VM started with cid=1234:
+
+        .. parsed-literal::
+
+             # |qemu_system_x86| \
+                 ......
+                 -chardev 
socket,id=vmi_chardev,type=vsock,cid=1234,port=4321,reconnect=10 \
+                 -object introspection,id=vmi,chardev=vmi_chardev
+
+        VM running the introspection tool:
+
+        .. parsed-literal::
+
+             # |qemu_system_x86| \
+                 ......
+                 -device vhost-vsock-pci,id=vhost-vsock-pci0,guest-cid=1234
+
 ERST