[v4,16/16] docs: Add protvirt docs

Commit Message

Janosch Frank Feb. 20, 2020, 12:56 p.m. UTC

Lets add some documentation for the Protected VM functionality.

Signed-off-by: Janosch Frank <[e-mail]>
---
 docs/protvirt.rst | 53 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)
 create mode 100644 docs/protvirt.rst

2.20.1

Comments

Cornelia Huck Feb. 21, 2020, 10 a.m. UTC | #1

On Thu, 20 Feb 2020 07:56:38 -0500
Janosch Frank <[e-mail]> wrote:

> Lets add some documentation for the Protected VM functionality.
> 
> Signed-off-by: Janosch Frank <[e-mail]>
> ---
>  docs/protvirt.rst | 53 +++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 53 insertions(+)
>  create mode 100644 docs/protvirt.rst

You'll probably want to add that file to an index as well, so that it
gets built properly.

> 
> diff --git a/docs/protvirt.rst b/docs/protvirt.rst
> new file mode 100644
> index 0000000000..8bfa72be01
> --- /dev/null
> +++ b/docs/protvirt.rst
> @@ -0,1 +1,53 @@
> +Protected Virtualization on s390x
> +========================

Please lengthen the underlining :)

Also, it might improve readability of the text doc if you added an
empty line beneath the headers.

> +The memory and most of the register contents of Protected Virtual
> +Machines (PVMs) are inaccessible to the hypervisor, effectively
> +prohibiting VM introspection when the VM is running. At rest, PVMs are
> +encrypted and can only be decrypted by the firmware of specific IBM Z
> +machines.
> +
> +
> +Prerequisites
> +-------------
> +To run PVMs, you need to have a machine with the Protected
> +Virtualization feature, which is indicated by the Ultravisor Call
> +facility (stfle bit 158). This is a KVM only feature, therefore you
> +need a KVM which is able to support PVMs and activate the Ultravisor
> +initialization by setting "prot_virt=1" on the kernel command line.

`prot_virt=1`, so that it gets rendered as a literal in html?

> +
> +If those requirements are met, the capability "KVM_CAP_S390_PROTECTED"

`KVM_CAP_S390_PROTECTED`

> +will indicate that KVM can support PVMs on that LPAR.
> +
> +
> +QEMU Settings
> +-------------
> +To indicate to the VM that it can move into protected mode, the
> +"Unpack facility" (stfle bit 161) needs to be part of the cpu model of
> +the VM.

Add an example invocation here?

> +
> +All I/O devices need to use the IOMMU.
> +Passthrough devices are currently not supported.

s/Passthrough devices/Passthrough (vfio) devices/ ?

> +
> +Host huge page backings are not supported. The guest however can use
> +huge pages as indicated by its facilities.
> +
> +
> +Boot Process
> +-----------------

Underlining too long :)

> +A secure guest image can be booted from disk and using the QEMU

"can be both booted from..." ?

> +command line. Booting from disk is done by the unmodified s390-ccw
> +BIOS. I.e., the bootmap is interpreted and a number of components is
> +read into memory and control is transferred to one of the components
> +(zipl stage3), which does some fixups and then transfers control to
> +some program residing in guest memory, which is normally the OS
> +kernel. The secure image has another component prepended (stage3a)
> +which uses the new diag308 subcodes 8 and 10 to trigger the transition
> +into secure mode.
> +
> +Booting from the command line requires that the file passed
> +via -kernel has the same memory layout as would result from the disk
> +boot. This memory layout includes the encrypted components (kernel,
> +initrd, cmdline), the stage3a loader and metadata. In case this boot
> +method is used, the command line options -initrd and -cmdline are
> +ineffective.  The preparation of secure guest image is done by a
> +program (name tbd) of the s390-tools package.

Hm... do you have an ETA for that tbd program?

Patch

diff --git a/docs/protvirt.rst b/docs/protvirt.rst
new file mode 100644
index 0000000000..8bfa72be01
--- /dev/null
+++ b/docs/protvirt.rst
@@ -0,1 +1,53 @@ 
+Protected Virtualization on s390x
+========================
+The memory and most of the register contents of Protected Virtual
+Machines (PVMs) are inaccessible to the hypervisor, effectively
+prohibiting VM introspection when the VM is running. At rest, PVMs are
+encrypted and can only be decrypted by the firmware of specific IBM Z
+machines.
+
+
+Prerequisites
+-------------
+To run PVMs, you need to have a machine with the Protected
+Virtualization feature, which is indicated by the Ultravisor Call
+facility (stfle bit 158). This is a KVM only feature, therefore you
+need a KVM which is able to support PVMs and activate the Ultravisor
+initialization by setting "prot_virt=1" on the kernel command line.
+
+If those requirements are met, the capability "KVM_CAP_S390_PROTECTED"
+will indicate that KVM can support PVMs on that LPAR.
+
+
+QEMU Settings
+-------------
+To indicate to the VM that it can move into protected mode, the
+"Unpack facility" (stfle bit 161) needs to be part of the cpu model of
+the VM.
+
+All I/O devices need to use the IOMMU.
+Passthrough devices are currently not supported.
+
+Host huge page backings are not supported. The guest however can use
+huge pages as indicated by its facilities.
+
+
+Boot Process
+-----------------
+A secure guest image can be booted from disk and using the QEMU
+command line. Booting from disk is done by the unmodified s390-ccw
+BIOS. I.e., the bootmap is interpreted and a number of components is
+read into memory and control is transferred to one of the components
+(zipl stage3), which does some fixups and then transfers control to
+some program residing in guest memory, which is normally the OS
+kernel. The secure image has another component prepended (stage3a)
+which uses the new diag308 subcodes 8 and 10 to trigger the transition
+into secure mode.
+
+Booting from the command line requires that the file passed
+via -kernel has the same memory layout as would result from the disk
+boot. This memory layout includes the encrypted components (kernel,
+initrd, cmdline), the stage3a loader and metadata. In case this boot
+method is used, the command line options -initrd and -cmdline are
+ineffective.  The preparation of secure guest image is done by a
+program (name tbd) of the s390-tools package.
--