Orange Pi5 kernel

^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  1) .. SPDX-License-Identifier: GPL-2.0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  2) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  3) ======================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  4) s390 (IBM Z) Boot/IPL of Protected VMs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  5) ======================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  6) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  7) Summary
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  8) -------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  9) The memory of Protected Virtual Machines (PVMs) is not accessible to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) I/O or the hypervisor. In those cases where the hypervisor needs to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) access the memory of a PVM, that memory must be made accessible.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) Memory made accessible to the hypervisor will be encrypted. See
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) :doc:`s390-pv` for details."
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) On IPL (boot) a small plaintext bootloader is started, which provides
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) information about the encrypted components and necessary metadata to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) KVM to decrypt the protected virtual machine.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) Based on this data, KVM will make the protected virtual machine known
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) to the Ultravisor (UV) and instruct it to secure the memory of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) PVM, decrypt the components and verify the data and address list
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) hashes, to ensure integrity. Afterwards KVM can run the PVM via the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) SIE instruction which the UV will intercept and execute on KVM's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) behalf.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) As the guest image is just like an opaque kernel image that does the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) switch into PV mode itself, the user can load encrypted guest
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) executables and data via every available method (network, dasd, scsi,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) direct kernel, ...) without the need to change the boot process.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) Diag308
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) -------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) This diagnose instruction is the basic mechanism to handle IPL and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) related operations for virtual machines. The VM can set and retrieve
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) IPL information blocks, that specify the IPL method/devices and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) request VM memory and subsystem resets, as well as IPLs.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) For PVMs this concept has been extended with new subcodes:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) Subcode 8: Set an IPL Information Block of type 5 (information block
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) for PVMs)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) Subcode 9: Store the saved block in guest memory
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) Subcode 10: Move into Protected Virtualization mode
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) The new PV load-device-specific-parameters field specifies all data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) that is necessary to move into PV mode.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) * PV Header origin
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) * PV Header length
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) * List of Components composed of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52)    * AES-XTS Tweak prefix
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53)    * Origin
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54)    * Size
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) The PV header contains the keys and hashes, which the UV will use to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) decrypt and verify the PV, as well as control flags and a start PSW.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) The components are for instance an encrypted kernel, kernel parameters
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) and initrd. The components are decrypted by the UV.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) After the initial import of the encrypted data, all defined pages will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) contain the guest content. All non-specified pages will start out as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) zero pages on first access.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) When running in protected virtualization mode, some subcodes will result in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) exceptions or return error codes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) Subcodes 4 and 7, which specify operations that do not clear the guest
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) memory, will result in specification exceptions. This is because the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) UV will clear all memory when a secure VM is removed, and therefore
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) non-clearing IPL subcodes are not allowed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) Subcodes 8, 9, 10 will result in specification exceptions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) Re-IPL into a protected mode is only possible via a detour into non
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) protected mode.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) Keys
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) ----
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) Every CEC will have a unique public key to enable tooling to build
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) encrypted images.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) See  `s390-tools <https://github.com/ibm-s390-tools/s390-tools/>`_
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) for the tooling.