Re: [PATCH v9 14/15] docs: Add protvirt docs

[Janosch Frank]

On 3/13/20 2:00 PM, Claudio Imbrenda wrote:
> On Wed, 11 Mar 2020 09:21:50 -0400
> Janosch Frank <address@hidden> 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 | 56
>> ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 57
>> insertions(+) create mode 100644 docs/system/protvirt.rst
>>
>> diff --git a/docs/system/index.rst b/docs/system/index.rst
>> index 6e5f20fa1333ce23..74afbd7cc3fc0296 100644
>> --- a/docs/system/index.rst
>> +++ b/docs/system/index.rst
>> @@ -34,3 +34,4 @@ Contents:
>>     deprecated
>>     build-platforms
>>     license
>> +   protvirt
>> diff --git a/docs/system/protvirt.rst b/docs/system/protvirt.rst
>> new file mode 100644
>> index 0000000000000000..6c8cf0f7910eae86
>> --- /dev/null
>> +++ b/docs/system/protvirt.rst
>> @@ -0,0 +1,56 @@
>> +Protected Virtualization on s390x
>> +=================================
>> +
>> +The memory and most of the registers of Protected Virtual Machines
>> +(PVMs) are encrypted or 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, represented
>> by an +entity called Ultravisor, of specific IBM Z machines.
>> +
>> +
>> +Prerequisites
>> +-------------
>> +
>> +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.
> 
> I'd add "of the host" just to make it extra clear

How about:
...on the host 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 transition into protected mode, the
>> +`Unpack facility` (stfle bit 161 represented by the feature
>> +`S390_FEAT_UNPACK`) needs to be part of the cpu model of the VM.
>> +
>> +All I/O devices need to use the IOMMU.
>> +Passthrough (vfio) devices are currently not supported.
>> +
>> +Host huge page backings are not supported. However guests can use
>> huge +pages as indicated by its facilities.
>> +
>> +
>> +Boot Process
>> +------------
>> +
>> +A secure guest image can either be loaded from disk or supplied on
>> the +QEMU command line. Booting from disk is done by the unmodified
>> +s390-ccw BIOS. I.e., the bootmap is interpreted, multiple components
>> +are read into memory and control is transferred to one of the
>> +components (zipl stage3). Stag3 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) that uses the new diag308 subcodes 8 and 10 to trigger the
>> +transition into secure mode.
>> +
>> +Booting from the image supplied via the QEMU 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 a
>> PVM +image is done by genprotimg of the s390-tools package.
> 
> Reviewed-by: Claudio Imbrenda <address@hidden>

Thanks!

signature.asc
Description: OpenPGP digital signature