Re: [PATCH v6 17/18] docs: Add protvirt docs

[Janosch Frank]

On 3/4/20 8:09 PM, David Hildenbrand wrote:
> On 04.03.20 12:42, Janosch Frank wrote:
>> Lets add some documentation for the Protected VM functionality.
>>
>> Signed-off-by: Janosch Frank <address@hidden>
>> ---
>>  docs/system/index.rst    |  1 +
>>  docs/system/protvirt.rst | 57 ++++++++++++++++++++++++++++++++++++++++
>>  2 files changed, 58 insertions(+)
>>  create mode 100644 docs/system/protvirt.rst
>>
>> diff --git a/docs/system/index.rst b/docs/system/index.rst
>> index 1a4b2c82ac..d2dc63b973 100644
>> --- a/docs/system/index.rst
>> +++ b/docs/system/index.rst
>> @@ -16,3 +16,4 @@ Contents:
>>  
>>     qemu-block-drivers
>>     vfio-ap
>> +   protvirt
>> diff --git a/docs/system/protvirt.rst b/docs/system/protvirt.rst
>> new file mode 100644
>> index 0000000000..a1902cc47c
>> --- /dev/null
>> +++ b/docs/system/protvirt.rst
>> @@ -0,0 +1,57 @@
>> +Protected Virtualization on s390x
>> +=================================
>> +
>> +The memory and most of the register contents of Protected Virtual
> 
> s/register contents/registers/

Ack

> 
>> +Machines (PVMs) are inaccessible to the hypervisor, effectively
> 
> s/inaccessible/encrypted or even inaccessible/ ?
> 
>> +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.
> 
> maybe "(a.k.a. the Ultravisor)"

At rest, PVMs are
encrypted and can only be decrypted by the firmware, represented by an
entity called Ultravisor, of specific IBM Z machines.

> 
>> +
>> +
>> +Prerequisites
>> +-------------
>> +
>> +To run PVMs, you need to have a machine with the Protected
> 
> "a machine with the Protected Virtualization feature is required"

Ack

> 
>> +Virtualization feature, which is indicated by the Ultravisor Call
>> +facility (stfle bit 158). This is a KVM only feature, therefore you
> 
> ", therefore, "
> 
> I don't understand the "KVM only" feature part. Just say that an updated
> KVM + right HW is required and how it is to be updated.

The KVM only part is mostly messaging that this can't be run under TCG

> 
>> +need a KVM which is able to support PVMs and activate the Ultravisor
> 
> "a KVM version"
> 
>> +initialization by setting `prot_virt=1` on the kernel command line.

To run PVMs a machine with the Protected Virtualization feature
which is indicated by the Ultravisor Call facility (stfle bit
158) is required. The Ultravisor needs to be initialized at boot 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
> 
> s/move/transition/ ?

Ack
I also took most of the suggestions below with some forms of modification.

> 
>> +`Unpack facility` (stfle bit 161) needs to be part of the cpu model of
>> +the VM.
> 
> Maybe mention the CPU feature name here.
> 
>> +
>> +All I/O devices need to use the IOMMU.
>> +Passthrough (vfio) devices are currently not supported.
>> +
>> +Host huge page backings are not supported. The guest however can use
> 
> "However, the guest can ..."
> 
>> +huge pages as indicated by its facilities.
>> +
>> +
>> +Boot Process
>> +------------
>> +
>> +A secure guest image can be both booted from disk and using the QEMU
> 
> "either be loaded from disk or supplied on the QEMU command line" ?
> 
>> +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
> 
> "interpreted, multiple components are"
> 
>> +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
> 
> to many ", which". Better split that up for readability.
> 
>> +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
> 
> "from the image supplied on the QEMU command line" ?
> 
>> +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
> 
> s/of secure/of a PMV image/
> 
>> +program (name tbd) of the s390-tools package.
>>
> 
> 
> General: secure guest -> PMV
>

signature.asc
Description: OpenPGP digital signature