[RFC PATCH v1 01/17] docs/system/riscv/virt: document the cove-vm machine option

[Baolong Duan <blduan@linux.alibaba.com>]

Describe the cove-vm option of the virt machine and how a CoVE TEE VM
(TVM) differs from a regular KVM guest: its memory and vCPU state are
owned by the TEE Security Manager (TSM), the guest images are measured
before it starts, interrupts are delivered as MSIs only, there is no
virtio-mmio transport and vhost cannot be used.

The option itself is added by the following patches.

Signed-off-by: Baolong Duan <blduan@linux.alibaba.com>
---
 docs/system/riscv/virt.rst | 39 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/docs/system/riscv/virt.rst b/docs/system/riscv/virt.rst
index 60850970ce..d053dbc300 100644
--- a/docs/system/riscv/virt.rst
+++ b/docs/system/riscv/virt.rst
@@ -146,6 +146,45 @@ The following machine-specific options are supported:
 
   Enables the riscv-iommu-sys platform device. Defaults to 'off'.
 
+- cove-vm=[on|off]
+
+  When this option is "on" the guest is created as a RISC-V CoVE
+  (Confidential VM Extension) TEE VM, or TVM. Defaults to "off". See
+  `Running a confidential VM`_ below.
+
+Running a confidential VM
+-------------------------
+
+With "cove-vm=on" the ``virt`` machine creates a TEE VM (TVM) instead of a
+regular KVM guest. The memory and the vCPU state of a TVM are owned by the
+TEE Security Manager (TSM) running in M-mode and are not accessible to the
+host, which changes the machine in a few ways:
+
+- the kernel, the initrd and the device tree are added to the initial
+  measurement of the guest before it starts, so that the guest can be
+  attested later on;
+
+- interrupts are delivered as MSIs only. An IMSIC is therefore mandatory and
+  "aia=aplic-imsic" is selected automatically when no AIA mode is requested.
+  The APLIC is emulated by QEMU because KVM does not implement one for a TVM;
+
+- no virtio-mmio transport is created. Devices have to be attached to the
+  PCIe host bridge, and they always negotiate VIRTIO_F_ACCESS_PLATFORM so
+  that DMA is bounced through memory the guest shares explicitly;
+
+- vhost cannot be used, as the kernel datapath has no access to guest memory.
+
+This requires a host with CoVE support, both in the firmware and in KVM, and
+it only works with ``-accel kvm``. An example command line is:
+
+.. code-block:: bash
+
+  $ qemu-system-riscv64 -M virt,cove-vm=on -accel kvm \
+      -m 256M -smp 1 -nographic \
+      -kernel Image -append "console=ttyS0 root=/dev/vda" \
+      -drive file=rootfs.ext4,format=raw,id=hd0,if=none \
+      -device virtio-blk-pci,drive=hd0,disable-legacy=on
+
 Running Linux kernel
 --------------------
 
-- 
2.34.1