SYS-OSS/FRET-qemu
4
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

docs: rstfy vfio-ap documentation

Browse Source 
Move to system/, as this is mostly about configuring vfio-ap.

Message-Id: <20200213162942.14177-3-cohuck@redhat.com>
Reviewed-by: Pierre Morel <pmorel@linux.ibm.com>
Signed-off-by: Cornelia Huck <cohuck@redhat.com>
This commit is contained in:
Cornelia Huck 2020-01-28 18:37:27 +01:00
parent cc3d15a5ea
commit 8f4335242a
3 changed files with 409 additions and 368 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
MAINTAINERS
View File

@ -1570,7 +1570,7 @@ F: hw/s390x/ap-bridge.c
F: include/hw/s390x/ap-device.h F: include/hw/s390x/ap-device.h
F: include/hw/s390x/ap-bridge.h F: include/hw/s390x/ap-bridge.h
F: hw/vfio/ap.c F: hw/vfio/ap.c
F: docs/vfio-ap.txt F: docs/system/vfio-ap.rst
L: qemu-s390x@nongnu.org L: qemu-s390x@nongnu.org
vhost vhost

1
docs/system/index.rst
View File

@ -15,3 +15,4 @@ Contents:
:maxdepth: 2 :maxdepth: 2
qemu-block-drivers qemu-block-drivers
vfio-ap

404
docs/vfio-ap.txt → docs/system/vfio-ap.rst
View File

@ -1,17 +1,11 @@
Adjunct Processor (AP) Device Adjunct Processor (AP) Device
============================= =============================
Contents: .. contents::
=========
* Introduction Introduction
* AP Architectural Overview ------------
* Start Interpretive Execution (SIE) Instruction
* AP Matrix Configuration on Linux Host
* Starting a Linux Guest Configured with an AP Matrix
* Example: Configure AP Matrices for Three Linux Guests
Introduction:
============
The IBM Adjunct Processor (AP) Cryptographic Facility is comprised The IBM Adjunct Processor (AP) Cryptographic Facility is comprised
of three AP instructions and from 1 to 256 PCIe cryptographic adapter cards. of three AP instructions and from 1 to 256 PCIe cryptographic adapter cards.
These AP devices provide cryptographic functions to all CPUs assigned to a These AP devices provide cryptographic functions to all CPUs assigned to a
@ -21,8 +15,9 @@ On s390x, AP adapter cards are exposed via the AP bus. This document
describes how those cards may be made available to KVM guests using the describes how those cards may be made available to KVM guests using the
VFIO mediated device framework. VFIO mediated device framework.
AP Architectural Overview: AP Architectural Overview
========================= -------------------------
In order understand the terminology used in the rest of this document, let's In order understand the terminology used in the rest of this document, let's
start with some definitions: start with some definitions:
@ -75,7 +70,8 @@ start with some definitions:
must be one of the control domains. must be one of the control domains.
Start Interpretive Execution (SIE) Instruction Start Interpretive Execution (SIE) Instruction
============================================== ----------------------------------------------
A KVM guest is started by executing the Start Interpretive Execution (SIE) A KVM guest is started by executing the Start Interpretive Execution (SIE)
instruction. The SIE state description is a control block that contains the instruction. The SIE state description is a control block that contains the
state information for a KVM guest and is supplied as input to the SIE state information for a KVM guest and is supplied as input to the SIE
@ -114,38 +110,60 @@ The APQNs can provide secure key functionality - i.e., a private key is stored
on the adapter card for each of its domains - so each APQN must be assigned to on the adapter card for each of its domains - so each APQN must be assigned to
at most one guest or the linux host. at most one guest or the linux host.
Example 1: Valid configuration: Example 1: Valid configuration
------------------------------ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Guest1: adapters 1,2 domains 5,6
Guest2: adapter 1,2 domain 7
This is valid because both guests have a unique set of APQNs: Guest1 has +----------+--------+--------+
APQNs (1,5), (1,6), (2,5) and (2,6); Guest2 has APQNs (1,7) and (2,7). | | Guest1 | Guest2 |
+==========+========+========+
| adapters | 1, 2 | 1, 2 |
+----------+--------+--------+
| domains | 5, 6 | 7 |
+----------+--------+--------+
Example 2: Valid configuration: This is valid because both guests have a unique set of APQNs:
------------------------------
Guest1: adapters 1,2 domains 5,6 * Guest1 has APQNs (1,5), (1,6), (2,5) and (2,6);
Guest2: adapters 3,4 domains 5,6 * Guest2 has APQNs (1,7) and (2,7).
Example 2: Valid configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------+--------+--------+
| | Guest1 | Guest2 |
+==========+========+========+
| adapters | 1, 2 | 3, 4 |
+----------+--------+--------+
| domains | 5, 6 | 5, 6 |
+----------+--------+--------+
This is also valid because both guests have a unique set of APQNs: This is also valid because both guests have a unique set of APQNs:
Guest1 has APQNs (1,5), (1,6), (2,5), (2,6);
Guest2 has APQNs (3,5), (3,6), (4,5), (4,6)
Example 3: Invalid configuration: * Guest1 has APQNs (1,5), (1,6), (2,5), (2,6);
-------------------------------- * Guest2 has APQNs (3,5), (3,6), (4,5), (4,6)
Guest1: adapters 1,2 domains 5,6
Guest2: adapter 1 domains 6,7 Example 3: Invalid configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------+--------+--------+
| | Guest1 | Guest2 |
+==========+========+========+
| adapters | 1, 2 | 1 |
+----------+--------+--------+
| domains | 5, 6 | 6, 7 |
+----------+--------+--------+
This is an invalid configuration because both guests have access to This is an invalid configuration because both guests have access to
APQN (1,6). APQN (1,6).
AP Matrix Configuration on Linux Host: AP Matrix Configuration on Linux Host
===================================== -------------------------------------
A linux system is a guest of the LPAR in which it is running and has access to A linux system is a guest of the LPAR in which it is running and has access to
the AP resources configured for the LPAR. The LPAR's AP matrix is the AP resources configured for the LPAR. The LPAR's AP matrix is
configured via its Activation Profile which can be edited on the HMC. When the configured via its Activation Profile which can be edited on the HMC. When the
linux system is started, the AP bus will detect the AP devices assigned to the linux system is started, the AP bus will detect the AP devices assigned to the
LPAR and create the following in sysfs: LPAR and create the following in sysfs::
/sys/bus/ap /sys/bus/ap
... [devices] ... [devices]
@ -155,13 +173,16 @@ LPAR and create the following in sysfs:
...... ... ...... ...
Where: Where:
cardxx is AP adapter number xx (in hex)
....xx.yyyy is an APQN with xx specifying the APID and yyyy specifying the ``cardxx``
APQI is AP adapter number xx (in hex)
``xx.yyyy``
is an APQN with xx specifying the APID and yyyy specifying the APQI
For example, if AP adapters 5 and 6 and domains 4, 71 (0x47), 171 (0xab) and For example, if AP adapters 5 and 6 and domains 4, 71 (0x47), 171 (0xab) and
255 (0xff) are configured for the LPAR, the sysfs representation on the linux 255 (0xff) are configured for the LPAR, the sysfs representation on the linux
host system would look like this: host system would look like this::
/sys/bus/ap /sys/bus/ap
... [devices] ... [devices]
@ -177,7 +198,7 @@ host system would look like this:
...... card06 ...... card06
A set of default device drivers are also created to control each type of AP A set of default device drivers are also created to control each type of AP
device that can be assigned to the LPAR on which a linux host is running: device that can be assigned to the LPAR on which a linux host is running::
/sys/bus/ap /sys/bus/ap
... [drivers] ... [drivers]
@ -193,30 +214,31 @@ device that can be assigned to the LPAR on which a linux host is running:
coprocessor cards coprocessor cards
Binding AP devices to device drivers Binding AP devices to device drivers
------------------------------------ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
There are two sysfs files that specify bitmasks marking a subset of the APQN There are two sysfs files that specify bitmasks marking a subset of the APQN
range as 'usable by the default AP queue device drivers' or 'not usable by the range as 'usable by the default AP queue device drivers' or 'not usable by the
default device drivers' and thus available for use by the alternate device default device drivers' and thus available for use by the alternate device
driver(s). The sysfs locations of the masks are: driver(s). The sysfs locations of the masks are::
/sys/bus/ap/apmask /sys/bus/ap/apmask
/sys/bus/ap/aqmask /sys/bus/ap/aqmask
The 'apmask' is a 256-bit mask that identifies a set of AP adapter IDs The ``apmask`` is a 256-bit mask that identifies a set of AP adapter IDs
(APID). Each bit in the mask, from left to right (i.e., from most significant (APID). Each bit in the mask, from left to right (i.e., from most significant
to least significant bit in big endian order), corresponds to an APID from to least significant bit in big endian order), corresponds to an APID from
0-255. If a bit is set, the APID is marked as usable only by the default AP 0-255. If a bit is set, the APID is marked as usable only by the default AP
queue device drivers; otherwise, the APID is usable by the vfio_ap queue device drivers; otherwise, the APID is usable by the vfio_ap
device driver. device driver.
The 'aqmask' is a 256-bit mask that identifies a set of AP queue indexes The ``aqmask`` is a 256-bit mask that identifies a set of AP queue indexes
(APQI). Each bit in the mask, from left to right (i.e., from most significant (APQI). Each bit in the mask, from left to right (i.e., from most significant
to least significant bit in big endian order), corresponds to an APQI from to least significant bit in big endian order), corresponds to an APQI from
0-255. If a bit is set, the APQI is marked as usable only by the default AP 0-255. If a bit is set, the APQI is marked as usable only by the default AP
queue device drivers; otherwise, the APQI is usable by the vfio_ap device queue device drivers; otherwise, the APQI is usable by the vfio_ap device
driver. driver.
Take, for example, the following mask: Take, for example, the following mask::
0x7dffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff 0x7dffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
@ -240,29 +262,30 @@ driver(s). The sysfs locations of the masks are:
* An absolute hex string starting with 0x - like "0x12345678" - sets * An absolute hex string starting with 0x - like "0x12345678" - sets
the mask. If the given string is shorter than the mask, it is padded the mask. If the given string is shorter than the mask, it is padded
with 0s on the right; for example, specifying a mask value of 0x41 is with 0s on the right; for example, specifying a mask value of 0x41 is
the same as specifying: the same as specifying::
0x4100000000000000000000000000000000000000000000000000000000000000 0x4100000000000000000000000000000000000000000000000000000000000000
Keep in mind that the mask reads from left to right (i.e., most Keep in mind that the mask reads from left to right (i.e., most
significant to least significant bit in big endian order), so the mask significant to least significant bit in big endian order), so the mask
above identifies device numbers 1 and 7 (01000001). above identifies device numbers 1 and 7 (``01000001``).
If the string is longer than the mask, the operation is terminated with If the string is longer than the mask, the operation is terminated with
an error (EINVAL). an error (EINVAL).
* Individual bits in the mask can be switched on and off by specifying * Individual bits in the mask can be switched on and off by specifying
each bit number to be switched in a comma separated list. Each bit each bit number to be switched in a comma separated list. Each bit
number string must be prepended with a ('+') or minus ('-') to indicate number string must be prepended with a (``+``) or minus (``-``) to indicate
the corresponding bit is to be switched on ('+') or off ('-'). Some the corresponding bit is to be switched on (``+``) or off (``-``). Some
valid values are: valid values are::
"+0" switches bit 0 on "+0" switches bit 0 on
"-13" switches bit 13 off "-13" switches bit 13 off
"+0x41" switches bit 65 on "+0x41" switches bit 65 on
"-0xff" switches bit 255 off "-0xff" switches bit 255 off
The following example: The following example::
+0,-6,+0x47,-0xf0 +0,-6,+0x47,-0xf0
Switches bits 0 and 71 (0x47) on Switches bits 0 and 71 (0x47) on
@ -272,31 +295,34 @@ driver(s). The sysfs locations of the masks are:
the operation. the operation.
2. The masks can also be changed at boot time via parameters on the kernel 2. The masks can also be changed at boot time via parameters on the kernel
command line like this: command line like this::
ap.apmask=0xffff ap.aqmask=0x40 ap.apmask=0xffff ap.aqmask=0x40
This would create the following masks: This would create the following masks:
apmask: apmask::
0xffff000000000000000000000000000000000000000000000000000000000000 0xffff000000000000000000000000000000000000000000000000000000000000
aqmask: aqmask::
0x4000000000000000000000000000000000000000000000000000000000000000 0x4000000000000000000000000000000000000000000000000000000000000000
Resulting in these two pools: Resulting in these two pools::
default drivers pool: adapter 0-15, domain 1 default drivers pool: adapter 0-15, domain 1
alternate drivers pool: adapter 16-255, domains 0, 2-255 alternate drivers pool: adapter 16-255, domains 0, 2-255
Configuring an AP matrix for a linux guest. Configuring an AP matrix for a linux guest
------------------------------------------ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The sysfs interfaces for configuring an AP matrix for a guest are built on the The sysfs interfaces for configuring an AP matrix for a guest are built on the
VFIO mediated device framework. To configure an AP matrix for a guest, a VFIO mediated device framework. To configure an AP matrix for a guest, a
mediated matrix device must first be created for the /sys/devices/vfio_ap/matrix mediated matrix device must first be created for the ``/sys/devices/vfio_ap/matrix``
device. When the vfio_ap device driver is loaded, it registers with the VFIO device. When the vfio_ap device driver is loaded, it registers with the VFIO
mediated device framework. When the driver registers, the sysfs interfaces for mediated device framework. When the driver registers, the sysfs interfaces for
creating mediated matrix devices is created: creating mediated matrix devices is created::
/sys/devices /sys/devices
... [vfio_ap] ... [vfio_ap]
@ -307,16 +333,18 @@ creating mediated matrix devices is created:
............... [devices] ............... [devices]
A mediated AP matrix device is created by writing a UUID to the attribute file A mediated AP matrix device is created by writing a UUID to the attribute file
named 'create', for example: named ``create``, for example::
uuidgen > create uuidgen > create
or or
::
echo $uuid > create echo $uuid > create
When a mediated AP matrix device is created, a sysfs directory named after When a mediated AP matrix device is created, a sysfs directory named after
the UUID is created in the 'devices' subdirectory: the UUID is created in the ``devices`` subdirectory::
/sys/devices /sys/devices
... [vfio_ap] ... [vfio_ap]
@ -329,7 +357,7 @@ the UUID is created in the 'devices' subdirectory:
There will also be three sets of attribute files created in the mediated There will also be three sets of attribute files created in the mediated
matrix device's sysfs directory to configure an AP matrix for the matrix device's sysfs directory to configure an AP matrix for the
KVM guest: KVM guest::
/sys/devices /sys/devices
... [vfio_ap] ... [vfio_ap]
@ -347,13 +375,13 @@ KVM guest:
..................... unassign_control_domain ..................... unassign_control_domain
..................... unassign_domain ..................... unassign_domain
assign_adapter ``assign_adapter``
To assign an AP adapter to the mediated matrix device, its APID is written To assign an AP adapter to the mediated matrix device, its APID is written
to the 'assign_adapter' file. This may be done multiple times to assign more to the ``assign_adapter`` file. This may be done multiple times to assign more
than one adapter. The APID may be specified using conventional semantics than one adapter. The APID may be specified using conventional semantics
as a decimal, hexadecimal, or octal number. For example, to assign adapters as a decimal, hexadecimal, or octal number. For example, to assign adapters
4, 5 and 16 to a mediated matrix device in decimal, hexadecimal and octal 4, 5 and 16 to a mediated matrix device in decimal, hexadecimal and octal
respectively: respectively::
echo 4 > assign_adapter echo 4 > assign_adapter
echo 0x5 > assign_adapter echo 0x5 > assign_adapter
@ -373,22 +401,22 @@ assign_adapter
APQNs are bound to the driver, the operation will terminate with an APQNs are bound to the driver, the operation will terminate with an
error (EADDRNOTAVAIL). error (EADDRNOTAVAIL).
No APQN that can be derived from the adapter ID and the IDs of the * No APQN that can be derived from the adapter ID and the IDs of the
previously assigned domains can be assigned to another mediated matrix previously assigned domains can be assigned to another mediated matrix
device. If an APQN is assigned to another mediated matrix device, the device. If an APQN is assigned to another mediated matrix device, the
operation will terminate with an error (EADDRINUSE). operation will terminate with an error (EADDRINUSE).
unassign_adapter ``unassign_adapter``
To unassign an AP adapter, its APID is written to the 'unassign_adapter' To unassign an AP adapter, its APID is written to the ``unassign_adapter``
file. This may also be done multiple times to unassign more than one adapter. file. This may also be done multiple times to unassign more than one adapter.
assign_domain ``assign_domain``
To assign a usage domain, the domain number is written into the To assign a usage domain, the domain number is written into the
'assign_domain' file. This may be done multiple times to assign more than one ``assign_domain`` file. This may be done multiple times to assign more than one
usage domain. The domain number is specified using conventional semantics as usage domain. The domain number is specified using conventional semantics as
a decimal, hexadecimal, or octal number. For example, to assign usage domains a decimal, hexadecimal, or octal number. For example, to assign usage domains
4, 8, and 71 to a mediated matrix device in decimal, hexadecimal and octal 4, 8, and 71 to a mediated matrix device in decimal, hexadecimal and octal
respectively: respectively::
echo 4 > assign_domain echo 4 > assign_domain
echo 0x8 > assign_domain echo 0x8 > assign_domain
@ -408,23 +436,23 @@ assign_domain
APQNs are bound to the driver, the operation will terminate with an APQNs are bound to the driver, the operation will terminate with an
error (EADDRNOTAVAIL). error (EADDRNOTAVAIL).
No APQN that can be derived from the domain ID being assigned and the IDs * No APQN that can be derived from the domain ID being assigned and the IDs
of the previously assigned adapters can be assigned to another mediated of the previously assigned adapters can be assigned to another mediated
matrix device. If an APQN is assigned to another mediated matrix device, matrix device. If an APQN is assigned to another mediated matrix device,
the operation will terminate with an error (EADDRINUSE). the operation will terminate with an error (EADDRINUSE).
unassign_domain ``unassign_domain``
To unassign a usage domain, the domain number is written into the To unassign a usage domain, the domain number is written into the
'unassign_domain' file. This may be done multiple times to unassign more than ``unassign_domain`` file. This may be done multiple times to unassign more than
one usage domain. one usage domain.
assign_control_domain ``assign_control_domain``
To assign a control domain, the domain number is written into the To assign a control domain, the domain number is written into the
'assign_control_domain' file. This may be done multiple times to ``assign_control_domain`` file. This may be done multiple times to
assign more than one control domain. The domain number may be specified using assign more than one control domain. The domain number may be specified using
conventional semantics as a decimal, hexadecimal, or octal number. For conventional semantics as a decimal, hexadecimal, or octal number. For
example, to assign control domains 4, 8, and 71 to a mediated matrix device example, to assign control domains 4, 8, and 71 to a mediated matrix device
in decimal, hexadecimal and octal respectively: in decimal, hexadecimal and octal respectively::
echo 4 > assign_domain echo 4 > assign_domain
echo 0x8 > assign_domain echo 0x8 > assign_domain
@ -435,24 +463,25 @@ assign_control_domain
allowed by the machine model. If a control domain number higher than the allowed by the machine model. If a control domain number higher than the
maximum is specified, the operation will terminate with an error (ENODEV). maximum is specified, the operation will terminate with an error (ENODEV).
unassign_control_domain ``unassign_control_domain``
To unassign a control domain, the domain number is written into the To unassign a control domain, the domain number is written into the
'unassign_domain' file. This may be done multiple times to unassign more than ``unassign_domain`` file. This may be done multiple times to unassign more than
one control domain. one control domain.
Notes: No changes to the AP matrix will be allowed while a guest using Notes: No changes to the AP matrix will be allowed while a guest using
the mediated matrix device is running. Attempts to assign an adapter, the mediated matrix device is running. Attempts to assign an adapter,
domain or control domain will be rejected and an error (EBUSY) returned. domain or control domain will be rejected and an error (EBUSY) returned.
Starting a Linux Guest Configured with an AP Matrix: Starting a Linux Guest Configured with an AP Matrix
=================================================== ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To provide a mediated matrix device for use by a guest, the following option To provide a mediated matrix device for use by a guest, the following option
must be specified on the QEMU command line: must be specified on the QEMU command line::
-device vfio_ap,sysfsdev=$path-to-mdev -device vfio_ap,sysfsdev=$path-to-mdev
The sysfsdev parameter specifies the path to the mediated matrix device. The sysfsdev parameter specifies the path to the mediated matrix device.
There are a number of ways to specify this path: There are a number of ways to specify this path::
/sys/devices/vfio_ap/matrix/$uuid /sys/devices/vfio_ap/matrix/$uuid
/sys/bus/mdev/devices/$uuid /sys/bus/mdev/devices/$uuid
@ -461,7 +490,7 @@ There are a number of ways to specify this path:
When the linux guest is started, the guest will open the mediated When the linux guest is started, the guest will open the mediated
matrix device's file descriptor to get information about the mediated matrix matrix device's file descriptor to get information about the mediated matrix
device. The vfio_ap device driver will update the APM, AQM, and ADM fields in device. The ``vfio_ap`` device driver will update the APM, AQM, and ADM fields in
the guest's CRYCB with the adapter, usage domain and control domains assigned the guest's CRYCB with the adapter, usage domain and control domains assigned
via the mediated matrix device's sysfs attribute files. Programs running on the via the mediated matrix device's sysfs attribute files. Programs running on the
linux guest will then: linux guest will then:
@ -486,19 +515,21 @@ facilities:
The AP facilities feature indicates that AP facilities are installed on the The AP facilities feature indicates that AP facilities are installed on the
guest. This feature will be exposed for use only if the AP facilities guest. This feature will be exposed for use only if the AP facilities
are installed on the host system. The feature is s390-specific and is are installed on the host system. The feature is s390-specific and is
represented as a parameter of the -cpu option on the QEMU command line: represented as a parameter of the -cpu option on the QEMU command line::
qemu-system-s390x -cpu $model,ap=on|off qemu-system-s390x -cpu $model,ap=on|off
Where: Where:
$model is the CPU model defined for the guest (defaults to the model of ``$model``
is the CPU model defined for the guest (defaults to the model of
the host system if not specified). the host system if not specified).
ap=on|off indicates whether AP facilities are installed (on) or not ``ap=on|off``
indicates whether AP facilities are installed (on) or not
(off). The default for CPU models zEC12 or newer (off). The default for CPU models zEC12 or newer
is ap=on. AP facilities must be installed on the guest if a is ``ap=on``. AP facilities must be installed on the guest if a
vfio-ap device (-device vfio-ap,sysfsdev=$path) is configured vfio-ap device (``-device vfio-ap,sysfsdev=$path``) is configured
for the guest, or the guest will fail to start. for the guest, or the guest will fail to start.
2. Query Configuration Information (QCI) facility 2. Query Configuration Information (QCI) facility
@ -507,20 +538,22 @@ facilities:
configuration of the AP facilities. This facility will be available configuration of the AP facilities. This facility will be available
only if the QCI facility is installed on the host system. The feature is only if the QCI facility is installed on the host system. The feature is
s390-specific and is represented as a parameter of the -cpu option on the s390-specific and is represented as a parameter of the -cpu option on the
QEMU command line: QEMU command line::
qemu-system-s390x -cpu $model,apqci=on|off qemu-system-s390x -cpu $model,apqci=on|off
Where: Where:
$model is the CPU model defined for the guest ``$model``
is the CPU model defined for the guest
apqci=on|off indicates whether the QCI facility is installed (on) or ``apqci=on|off``
indicates whether the QCI facility is installed (on) or
not (off). The default for CPU models zEC12 or newer not (off). The default for CPU models zEC12 or newer
is apqci=on; for older models, QCI will not be installed. is ``apqci=on``; for older models, QCI will not be installed.
If QCI is installed (apqci=on) but AP facilities are not If QCI is installed (``apqci=on``) but AP facilities are not
(ap=off), an error message will be logged, but the guest (``ap=off``), an error message will be logged, but the guest
will be allowed to start. It makes no sense to have QCI will be allowed to start. It makes no sense to have QCI
installed if the AP facilities are not; this is considered installed if the AP facilities are not; this is considered
an invalid configuration. an invalid configuration.
@ -535,22 +568,24 @@ facilities:
AP facilities available for a given AP queue. This facility will be available AP facilities available for a given AP queue. This facility will be available
only if the APFT facility is installed on the host system. The feature is only if the APFT facility is installed on the host system. The feature is
s390-specific and is represented as a parameter of the -cpu option on the s390-specific and is represented as a parameter of the -cpu option on the
QEMU command line: QEMU command line::
qemu-system-s390x -cpu $model,apft=on|off qemu-system-s390x -cpu $model,apft=on|off
Where: Where:
$model is the CPU model defined for the guest (defaults to the model of ``$model``
is the CPU model defined for the guest (defaults to the model of
the host system if not specified). the host system if not specified).
apft=on|off indicates whether the APFT facility is installed (on) or ``apft=on|off``
indicates whether the APFT facility is installed (on) or
not (off). The default for CPU models zEC12 and not (off). The default for CPU models zEC12 and
newer is apft=on for older models, APFT will not be newer is ``apft=on`` for older models, APFT will not be
installed. installed.
If APFT is installed (apft=on) but AP facilities are not If APFT is installed (``apft=on``) but AP facilities are not
(ap=off), an error message will be logged, but the guest (``ap=off``), an error message will be logged, but the guest
will be allowed to start. It makes no sense to have APFT will be allowed to start. It makes no sense to have APFT
installed if the AP facilities are not; this is considered installed if the AP facilities are not; this is considered
an invalid configuration. an invalid configuration.
@ -561,22 +596,23 @@ facilities:
for guest usage, no AP devices can be made accessible to a for guest usage, no AP devices can be made accessible to a
guest started without APFT installed. guest started without APFT installed.
Hot plug a vfio-ap device into a running guest: Hot plug a vfio-ap device into a running guest
============================================== ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Only one vfio-ap device can be attached to the virtual machine's ap-bus, so a Only one vfio-ap device can be attached to the virtual machine's ap-bus, so a
vfio-ap device can be hot plugged if and only if no vfio-ap device is attached vfio-ap device can be hot plugged if and only if no vfio-ap device is attached
to the bus already, whether via the QEMU command line or a prior hot plug to the bus already, whether via the QEMU command line or a prior hot plug
action. action.
To hot plug a vfio-ap device, use the QEMU device_add command: To hot plug a vfio-ap device, use the QEMU ``device_add`` command::
(qemu) device_add vfio-ap,sysfsdev="$path-to-mdev" (qemu) device_add vfio-ap,sysfsdev="$path-to-mdev"
Where the '$path-to-mdev' value specifies the absolute path to a mediated Where the ``$path-to-mdev`` value specifies the absolute path to a mediated
device to which AP resources to be used by the guest have been assigned. device to which AP resources to be used by the guest have been assigned.
Note that on Linux guests, the AP devices will be created in the Note that on Linux guests, the AP devices will be created in the
/sys/bus/ap/devices directory when the AP bus subsequently performs its periodic ``/sys/bus/ap/devices`` directory when the AP bus subsequently performs its periodic
scan, so there may be a short delay before the AP devices are accessible on the scan, so there may be a short delay before the AP devices are accessible on the
guest. guest.
@ -587,37 +623,39 @@ The command will fail if:
* The CPU model features for controlling guest access to AP facilities are not * The CPU model features for controlling guest access to AP facilities are not
enabled (see 'CPU model features' subsection in the previous section). enabled (see 'CPU model features' subsection in the previous section).
Hot unplug a vfio-ap device from a running guest: Hot unplug a vfio-ap device from a running guest
================================================ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A vfio-ap device can be unplugged from a running KVM guest if a vfio-ap device A vfio-ap device can be unplugged from a running KVM guest if a vfio-ap device
has been attached to the virtual machine's ap-bus via the QEMU command line has been attached to the virtual machine's ap-bus via the QEMU command line
or a prior hot plug action. or a prior hot plug action.
To hot unplug a vfio-ap device, use the QEMU device_del command: To hot unplug a vfio-ap device, use the QEMU ``device_del`` command::
(qemu) device_del vfio-ap,sysfsdev="$path-to-mdev" (qemu) device_del vfio-ap,sysfsdev="$path-to-mdev"
Where $path-to-mdev is the same as the path specified when the vfio-ap Where ``$path-to-mdev`` is the same as the path specified when the vfio-ap
device was attached to the virtual machine's ap-bus. device was attached to the virtual machine's ap-bus.
On a Linux guest, the AP devices will be removed from the /sys/bus/ap/devices On a Linux guest, the AP devices will be removed from the ``/sys/bus/ap/devices``
directory on the guest when the AP bus subsequently performs its periodic scan, directory on the guest when the AP bus subsequently performs its periodic scan,
so there may be a short delay before the AP devices are no longer accessible by so there may be a short delay before the AP devices are no longer accessible by
the guest. the guest.
The command will fail if the $path-to-mdev specified on the device_del command The command will fail if the ``$path-to-mdev`` specified on the ``device_del`` command
does not match the value specified when the vfio-ap device was attached to does not match the value specified when the vfio-ap device was attached to
the virtual machine's ap-bus. the virtual machine's ap-bus.
Example: Configure AP Matrixes for Three Linux Guests: Example: Configure AP Matrices for Three Linux Guests
===================================================== -----------------------------------------------------
Let's now provide an example to illustrate how KVM guests may be given Let's now provide an example to illustrate how KVM guests may be given
access to AP facilities. For this example, we will show how to configure access to AP facilities. For this example, we will show how to configure
three guests such that executing the lszcrypt command on the guests would three guests such that executing the lszcrypt command on the guests would
look like this: look like this:
Guest1 Guest1::
------
CARD.DOMAIN TYPE MODE CARD.DOMAIN TYPE MODE
------------------------------ ------------------------------
05 CEX5C CCA-Coproc 05 CEX5C CCA-Coproc
@ -627,16 +665,16 @@ CARD.DOMAIN TYPE MODE
06.0004 CEX5A Accelerator 06.0004 CEX5A Accelerator
06.00ab CEX5C CCA-Coproc 06.00ab CEX5C CCA-Coproc
Guest2 Guest2::
------
CARD.DOMAIN TYPE MODE CARD.DOMAIN TYPE MODE
------------------------------ ------------------------------
05 CEX5A Accelerator 05 CEX5A Accelerator
05.0047 CEX5A Accelerator 05.0047 CEX5A Accelerator
05.00ff CEX5A Accelerator (5,4), (5,171), (6,4), (6,171), 05.00ff CEX5A Accelerator
Guest3::
Guest3
------
CARD.DOMAIN TYPE MODE CARD.DOMAIN TYPE MODE
------------------------------ ------------------------------
06 CEX5A Accelerator 06 CEX5A Accelerator
@ -647,6 +685,7 @@ These are the steps:
1. Install the vfio_ap module on the linux host. The dependency chain for the 1. Install the vfio_ap module on the linux host. The dependency chain for the
vfio_ap module is: vfio_ap module is:
* iommu * iommu
* s390 * s390
* zcrypt * zcrypt
@ -657,6 +696,7 @@ These are the steps:
To build the vfio_ap module, the kernel build must be configured with the To build the vfio_ap module, the kernel build must be configured with the
following Kconfig elements selected: following Kconfig elements selected:
* IOMMU_SUPPORT * IOMMU_SUPPORT
* S390 * S390
* ZCRYPT * ZCRYPT
@ -666,7 +706,7 @@ These are the steps:
* VFIO_MDEV_DEVICE * VFIO_MDEV_DEVICE
* KVM * KVM
If using make menuconfig select the following to build the vfio_ap module: If using make menuconfig select the following to build the vfio_ap module::
-> Device Drivers -> Device Drivers
-> IOMMU Hardware Support -> IOMMU Hardware Support
select S390 AP IOMMU Support select S390 AP IOMMU Support
@ -680,7 +720,7 @@ These are the steps:
access them. To secure the AP queues 05.0004, 05.0047, 05.00ab, 05.00ff, access them. To secure the AP queues 05.0004, 05.0047, 05.00ab, 05.00ff,
06.0004, 06.0047, 06.00ab, and 06.00ff for use by the vfio_ap device driver, 06.0004, 06.0047, 06.00ab, and 06.00ff for use by the vfio_ap device driver,
the corresponding APQNs must be removed from the default queue drivers pool the corresponding APQNs must be removed from the default queue drivers pool
as follows: as follows::
echo -5,-6 > /sys/bus/ap/apmask echo -5,-6 > /sys/bus/ap/apmask
@ -689,7 +729,7 @@ These are the steps:
This will result in AP queues 05.0004, 05.0047, 05.00ab, 05.00ff, 06.0004, This will result in AP queues 05.0004, 05.0047, 05.00ab, 05.00ff, 06.0004,
06.0047, 06.00ab, and 06.00ff getting bound to the vfio_ap device driver. The 06.0047, 06.00ab, and 06.00ff getting bound to the vfio_ap device driver. The
sysfs directory for the vfio_ap device driver will now contain symbolic links sysfs directory for the vfio_ap device driver will now contain symbolic links
to the AP queue devices bound to it: to the AP queue devices bound to it::
/sys/bus/ap /sys/bus/ap
... [drivers] ... [drivers]
@ -712,7 +752,7 @@ These are the steps:
The administrator, therefore, must take care to secure only AP queues that The administrator, therefore, must take care to secure only AP queues that
can be bound to the vfio_ap device driver. The device type for a given AP can be bound to the vfio_ap device driver. The device type for a given AP
queue device can be read from the parent card's sysfs directory. For example, queue device can be read from the parent card's sysfs directory. For example,
to see the hardware type of the queue 05.0004: to see the hardware type of the queue 05.0004::
cat /sys/bus/ap/devices/card05/hwtype cat /sys/bus/ap/devices/card05/hwtype
@ -721,15 +761,15 @@ These are the steps:
3. Create the mediated devices needed to configure the AP matrixes for the 3. Create the mediated devices needed to configure the AP matrixes for the
three guests and to provide an interface to the vfio_ap driver for three guests and to provide an interface to the vfio_ap driver for
use by the guests: use by the guests::
/sys/devices/vfio_ap/matrix/ /sys/devices/vfio_ap/matrix/
--- [mdev_supported_types] ... [mdev_supported_types]
------ [vfio_ap-passthrough] (passthrough mediated matrix device type) ...... [vfio_ap-passthrough] (passthrough mediated matrix device type)
--------- create ......... create
--------- [devices] ......... [devices]
To create the mediated devices for the three guests: To create the mediated devices for the three guests::
uuidgen > create uuidgen > create
uuidgen > create uuidgen > create
@ -737,49 +777,51 @@ These are the steps:
or or
::
echo $uuid1 > create echo $uuid1 > create
echo $uuid2 > create echo $uuid2 > create
echo $uuid3 > create echo $uuid3 > create
This will create three mediated devices in the [devices] subdirectory named This will create three mediated devices in the [devices] subdirectory named
after the UUID used to create the mediated device. We'll call them $uuid1, after the UUID used to create the mediated device. We'll call them $uuid1,
$uuid2 and $uuid3 and this is the sysfs directory structure after creation: $uuid2 and $uuid3 and this is the sysfs directory structure after creation::
/sys/devices/vfio_ap/matrix/ /sys/devices/vfio_ap/matrix/
--- [mdev_supported_types] ... [mdev_supported_types]
------ [vfio_ap-passthrough] ...... [vfio_ap-passthrough]
--------- [devices] ......... [devices]
------------ [$uuid1] ............ [$uuid1]
--------------- assign_adapter ............... assign_adapter
--------------- assign_control_domain ............... assign_control_domain
--------------- assign_domain ............... assign_domain
--------------- matrix ............... matrix
--------------- unassign_adapter ............... unassign_adapter
--------------- unassign_control_domain ............... unassign_control_domain
--------------- unassign_domain ............... unassign_domain
------------ [$uuid2] ............ [$uuid2]
--------------- assign_adapter ............... assign_adapter
--------------- assign_control_domain ............... assign_control_domain
--------------- assign_domain ............... assign_domain
--------------- matrix ............... matrix
--------------- unassign_adapter ............... unassign_adapter
----------------unassign_control_domain ............... unassign_control_domain
----------------unassign_domain ............... unassign_domain
------------ [$uuid3] ............ [$uuid3]
--------------- assign_adapter ............... assign_adapter
--------------- assign_control_domain ............... assign_control_domain
--------------- assign_domain ............... assign_domain
--------------- matrix ............... matrix
--------------- unassign_adapter ............... unassign_adapter
----------------unassign_control_domain ............... unassign_control_domain
----------------unassign_domain ............... unassign_domain
4. The administrator now needs to configure the matrixes for the mediated 4. The administrator now needs to configure the matrixes for the mediated
devices $uuid1 (for Guest1), $uuid2 (for Guest2) and $uuid3 (for Guest3). devices $uuid1 (for Guest1), $uuid2 (for Guest2) and $uuid3 (for Guest3).
This is how the matrix is configured for Guest1: This is how the matrix is configured for Guest1::
echo 5 > assign_adapter echo 5 > assign_adapter
echo 6 > assign_adapter echo 6 > assign_adapter
@ -790,59 +832,56 @@ These are the steps:
sysfs file. sysfs file.
If a mistake is made configuring an adapter, domain or control domain, If a mistake is made configuring an adapter, domain or control domain,
you can use the unassign_xxx interfaces to unassign the adapter, domain or you can use the ``unassign_xxx`` interfaces to unassign the adapter, domain or
control domain. control domain.
To display the matrix configuration for Guest1: To display the matrix configuration for Guest1::
cat matrix cat matrix
The output will display the APQNs in the format xx.yyyy, where xx is The output will display the APQNs in the format ``xx.yyyy``, where xx is
the adapter number and yyyy is the domain number. The output for Guest1 the adapter number and yyyy is the domain number. The output for Guest1
will look like this: will look like this::
05.0004 05.0004
05.00ab 05.00ab
06.0004 06.0004
06.00ab 06.00ab
This is how the matrix is configured for Guest2: This is how the matrix is configured for Guest2::
echo 5 > assign_adapter echo 5 > assign_adapter
echo 0x47 > assign_domain echo 0x47 > assign_domain
echo 0xff > assign_domain echo 0xff > assign_domain
This is how the matrix is configured for Guest3: This is how the matrix is configured for Guest3::
echo 6 > assign_adapter echo 6 > assign_adapter
echo 0x47 > assign_domain echo 0x47 > assign_domain
echo 0xff > assign_domain echo 0xff > assign_domain
5. Start Guest1: 5. Start Guest1::
/usr/bin/qemu-system-s390x ... -cpu host,ap=on,apqci=on,apft=on \ /usr/bin/qemu-system-s390x ... -cpu host,ap=on,apqci=on,apft=on -device vfio-ap,sysfsdev=/sys/devices/vfio_ap/matrix/$uuid1 ...
-device vfio-ap,sysfsdev=/sys/devices/vfio_ap/matrix/$uuid1 ...
7. Start Guest2: 7. Start Guest2::
/usr/bin/qemu-system-s390x ... -cpu host,ap=on,apqci=on,apft=on \ /usr/bin/qemu-system-s390x ... -cpu host,ap=on,apqci=on,apft=on -device vfio-ap,sysfsdev=/sys/devices/vfio_ap/matrix/$uuid2 ...
-device vfio-ap,sysfsdev=/sys/devices/vfio_ap/matrix/$uuid2 ...
7. Start Guest3: 7. Start Guest3::
/usr/bin/qemu-system-s390x ... -cpu host,ap=on,apqci=on,apft=on \ /usr/bin/qemu-system-s390x ... -cpu host,ap=on,apqci=on,apft=on -device vfio-ap,sysfsdev=/sys/devices/vfio_ap/matrix/$uuid3 ...
-device vfio-ap,sysfsdev=/sys/devices/vfio_ap/matrix/$uuid3 ...
When the guest is shut down, the mediated matrix devices may be removed. When the guest is shut down, the mediated matrix devices may be removed.
Using our example again, to remove the mediated matrix device $uuid1: Using our example again, to remove the mediated matrix device $uuid1::
/sys/devices/vfio_ap/matrix/ /sys/devices/vfio_ap/matrix/
--- [mdev_supported_types] ... [mdev_supported_types]
------ [vfio_ap-passthrough] ...... [vfio_ap-passthrough]
--------- [devices] ......... [devices]
------------ [$uuid1] ............ [$uuid1]
--------------- remove ............... remove
echo 1 > remove echo 1 > remove
@ -858,7 +897,8 @@ Using our example again, to remove the mediated matrix device $uuid1:
the pool of adapters and queues reserved for use by the default drivers. the pool of adapters and queues reserved for use by the default drivers.
Limitations Limitations
=========== -----------
* The KVM/kernel interfaces do not provide a way to prevent restoring an APQN * The KVM/kernel interfaces do not provide a way to prevent restoring an APQN
to the default drivers pool of a queue that is still assigned to a mediated to the default drivers pool of a queue that is still assigned to a mediated
device in use by a guest. It is incumbent upon the administrator to device in use by a guest. It is incumbent upon the administrator to
@ -867,10 +907,10 @@ Limitations
device, such as a private key configured specifically for the guest. device, such as a private key configured specifically for the guest.
* Dynamically assigning AP resources to or unassigning AP resources from a * Dynamically assigning AP resources to or unassigning AP resources from a
mediated matrix device - see 'Configuring an AP matrix for a linux guest' mediated matrix device - see `Configuring an AP matrix for a linux guest`_
section above - while a running guest is using it is currently not supported. section above - while a running guest is using it is currently not supported.
* Live guest migration is not supported for guests using AP devices. If a guest * Live guest migration is not supported for guests using AP devices. If a guest
is using AP devices, the vfio-ap device configured for the guest must be is using AP devices, the vfio-ap device configured for the guest must be
unplugged before migrating the guest (see 'Hot unplug a vfio-ap device from a unplugged before migrating the guest (see `Hot unplug a vfio-ap device from a
running guest' section above. running guest`_ section above.)