diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/papr-pef.txt | 30 | ||||
| -rw-r--r-- | docs/specs/ppc-spapr-hcalls.rst | 21 | ||||
| -rw-r--r-- | docs/system/ppc/pseries.rst | 75 | ||||
| -rw-r--r-- | docs/tools/qemu-storage-daemon.rst | 2 |
4 files changed, 65 insertions, 63 deletions
diff --git a/docs/papr-pef.txt b/docs/papr-pef.txt deleted file mode 100644 index 72550e9bf8..0000000000 --- a/docs/papr-pef.txt +++ /dev/null @@ -1,30 +0,0 @@ -POWER (PAPR) Protected Execution Facility (PEF) -=============================================== - -Protected Execution Facility (PEF), also known as Secure Guest support -is a feature found on IBM POWER9 and POWER10 processors. - -If a suitable firmware including an Ultravisor is installed, it adds -an extra memory protection mode to the CPU. The ultravisor manages a -pool of secure memory which cannot be accessed by the hypervisor. - -When this feature is enabled in QEMU, a guest can use ultracalls to -enter "secure mode". This transfers most of its memory to secure -memory, where it cannot be eavesdropped by a compromised hypervisor. - -Launching ---------- - -To launch a guest which will be permitted to enter PEF secure mode: - -# ${QEMU} \ - -object pef-guest,id=pef0 \ - -machine confidential-guest-support=pef0 \ - ... - -Live Migration ----------------- - -Live migration is not yet implemented for PEF guests. For -consistency, we currently prevent migration if the PEF feature is -enabled, whether or not the guest has actually entered secure mode. diff --git a/docs/specs/ppc-spapr-hcalls.rst b/docs/specs/ppc-spapr-hcalls.rst index 28daf9734a..6cdcef2026 100644 --- a/docs/specs/ppc-spapr-hcalls.rst +++ b/docs/specs/ppc-spapr-hcalls.rst @@ -1,13 +1,12 @@ +====================== sPAPR hypervisor calls ----------------------- +====================== When used with the ``pseries`` machine type, ``qemu-system-ppc64`` implements -a set of hypervisor calls (a.k.a. hcalls) defined in the `Linux on Power -Architecture Reference document (LoPAR) -<https://cdn.openpowerfoundation.org/wp-content/uploads/2020/07/LoPAR-20200812.pdf>`_. -This document is a subset of the Power Architecture Platform Reference (PAPR+) -specification (IBM internal only), which is what PowerVM, the IBM proprietary -hypervisor, adheres to. +a set of hypervisor calls (a.k.a. hcalls) defined in the Linux on Power +Architecture Reference ([LoPAR]_) document. This document is a subset of the +Power Architecture Platform Reference (PAPR+) specification (IBM internal only), +which is what PowerVM, the IBM proprietary hypervisor, adheres to. The subset in LoPAR is selected based on the requirements of Linux as a guest. @@ -18,8 +17,8 @@ running in the guest and QEMU. All those hypercalls start at hcall number 0xf000 which correspond to an implementation specific range in PAPR. -H_RTAS (0xf000) -^^^^^^^^^^^^^^^ +``H_RTAS (0xf000)`` +=================== RTAS stands for Run-Time Abstraction Sercies and is a set of runtime services generally provided by the firmware inside the guest to the operating system. It @@ -44,8 +43,8 @@ Returns: ``H_PARAMETER``: Unknown token. -H_LOGICAL_MEMOP (0xf001) -^^^^^^^^^^^^^^^^^^^^^^^^ +``H_LOGICAL_MEMOP (0xf001)`` +============================ When the guest runs in "real mode" (in powerpc terminology this means with MMU disabled, i.e. guest effective address equals to guest physical address), it diff --git a/docs/system/ppc/pseries.rst b/docs/system/ppc/pseries.rst index 72e315eff6..1689324815 100644 --- a/docs/system/ppc/pseries.rst +++ b/docs/system/ppc/pseries.rst @@ -1,19 +1,18 @@ +=================================== pSeries family boards (``pseries``) =================================== -The Power machine para-virtualized environment described by the `Linux on Power -Architecture Reference document (LoPAR) -<https://openpowerfoundation.org/wp-content/uploads/2020/07/LoPAR-20200812.pdf>`_ -is called pSeries. This environment is also known as sPAPR, System p guests, or -simply Power Linux guests (although it is capable of running other operating -systems, such as AIX). +The Power machine para-virtualized environment described by the Linux on Power +Architecture Reference ([LoPAR]_) document is called pSeries. This environment +is also known as sPAPR, System p guests, or simply Power Linux guests (although +it is capable of running other operating systems, such as AIX). Even though pSeries is designed to behave as a guest environment, it is also capable of acting as a hypervisor OS, providing, on that role, nested virtualization capabilities. Supported devices ------------------ +================= * Multi processor support for many Power processors generations: POWER7, POWER7+, POWER8, POWER8NVL, POWER9, and Power10. Support for POWER5+ exists, @@ -26,12 +25,12 @@ Supported devices * PCIe device pass through. Missing devices ---------------- +=============== * SPICE support. Firmware --------- +======== `SLOF <https://github.com/aik/SLOF>`_ (Slimline Open Firmware) is an implementation of the `IEEE 1275-1994, Standard for Boot (Initialization @@ -42,14 +41,14 @@ QEMU includes a prebuilt image of SLOF which is updated when a more recent version is required. Build directions ----------------- +================ .. code-block:: bash ./configure --target-list=ppc64-softmmu && make Running instructions --------------------- +==================== Someone can select the pSeries machine type by running QEMU with the following options: @@ -59,7 +58,7 @@ options: qemu-system-ppc64 -M pseries <other QEMU arguments> sPAPR devices -------------- +============= The sPAPR specification defines a set of para-virtualized devices, which are also supported by the pSeries machine in QEMU and can be instantiated with the @@ -102,11 +101,9 @@ device, or specify one with an ID NVRAM device with ``-global spapr-nvram.drive=pfid``. sPAPR specification -^^^^^^^^^^^^^^^^^^^ +------------------- -The main source of documentation on the sPAPR standard is the `Linux on Power -Architecture Reference document (LoPAR) -<https://openpowerfoundation.org/wp-content/uploads/2020/07/LoPAR-20200812.pdf>`_. +The main source of documentation on the sPAPR standard is the [LoPAR]_ document. However, documentation specific to QEMU's implementation of the specification can also be found in QEMU documentation: @@ -124,7 +121,7 @@ Other documentation available in QEMU docs directory: (``/docs/specs/ppc-spapr-uv-hcalls.txt``). Switching between the KVM-PR and KVM-HV kernel module ------------------------------------------------------ +===================================================== Currently, there are two implementations of KVM on Power, ``kvm_hv.ko`` and ``kvm_pr.ko``. @@ -139,7 +136,7 @@ possible to switch between the two modes with the ``kvm-type`` parameter: instead. KVM-PR -^^^^^^ +------ KVM-PR uses the so-called **PR**\ oblem state of the PPC CPUs to run the guests, i.e. the virtual machine is run in user mode and all privileged instructions @@ -166,7 +163,7 @@ In order to run KVM-PR guests with POWER9 processors, someone will need to start QEMU with ``kernel_irqchip=off`` command line option. KVM-HV -^^^^^^ +------ KVM-HV uses the hypervisor mode of more recent Power processors, that allow access to the bare metal hardware directly. Although POWER7 had this capability, @@ -188,7 +185,7 @@ CPUs generations, e.g. you can run a POWER7 guest on a POWER8 host by using ``-cpu POWER8,compat=power7`` as parameter to QEMU. Modules support ---------------- +=============== As noticed in the sections above, each module can run in a different environment. The following table shows with which environment each module can @@ -230,9 +227,45 @@ nested. Combinations not shown in the table are not available. .. [3] Introduced on Power10 machines. + +POWER (PAPR) Protected Execution Facility (PEF) +----------------------------------------------- + +Protected Execution Facility (PEF), also known as Secure Guest support +is a feature found on IBM POWER9 and POWER10 processors. + +If a suitable firmware including an Ultravisor is installed, it adds +an extra memory protection mode to the CPU. The ultravisor manages a +pool of secure memory which cannot be accessed by the hypervisor. + +When this feature is enabled in QEMU, a guest can use ultracalls to +enter "secure mode". This transfers most of its memory to secure +memory, where it cannot be eavesdropped by a compromised hypervisor. + +Launching +^^^^^^^^^ + +To launch a guest which will be permitted to enter PEF secure mode:: + + $ qemu-system-ppc64 \ + -object pef-guest,id=pef0 \ + -machine confidential-guest-support=pef0 \ + ... + +Live Migration +^^^^^^^^^^^^^^ + +Live migration is not yet implemented for PEF guests. For +consistency, QEMU currently prevents migration if the PEF feature is +enabled, whether or not the guest has actually entered secure mode. + + Maintainer contact information ------------------------------- +============================== Cédric Le Goater <clg@kaod.org> Daniel Henrique Barboza <danielhb413@gmail.com> + +.. [LoPAR] `Linux on Power Architecture Reference document (LoPAR) revision + 2.9 <https://openpowerfoundation.org/wp-content/uploads/2020/07/LoPAR-20200812.pdf>`_. diff --git a/docs/tools/qemu-storage-daemon.rst b/docs/tools/qemu-storage-daemon.rst index 3e5a9dc032..9b0eaba6e5 100644 --- a/docs/tools/qemu-storage-daemon.rst +++ b/docs/tools/qemu-storage-daemon.rst @@ -201,7 +201,7 @@ Export raw image file ``disk.img`` over NBD UNIX domain socket ``nbd.sock``:: --nbd-server addr.type=unix,addr.path=nbd.sock \ --export type=nbd,id=export,node-name=disk,writable=on -Export a qcow2 image file ``disk.qcow2`` as a vhosts-user-blk device over UNIX +Export a qcow2 image file ``disk.qcow2`` as a vhost-user-blk device over UNIX domain socket ``vhost-user-blk.sock``:: $ qemu-storage-daemon \ |