In the hardware configuration, adapter and domain specifications assign a matrix of AP queues to
the LPAR or DPM partition on which the KVM host runs. By
default, the zcrypt device driver controls all AP queues that are available to a
KVM host and so makes them unavailable to KVM guests.
Use the chzdev and lszdev commands to manage host
control of AP queues. With chzdev, you can persistently free AP queues, across
reboots of the KVM host.
Before you begin
Issue the lszdev --list-types command to confirm that your version of the
chzdev and lszdev commands support AP queues.
# lszdev --list-types
TYPE DESCRIPTION
ap Cryptographic Adjunct Processor (AP) device
...
If your version of the chzdev command does not support AP queues, you can use
the /sys/bus/ap/apmask and /sys/bus/ap/aqmask bit masks in
sysfs as a fallback method. In contrast to chzdev, you cannot persistently free
AP queues by directly using this sysfs interface, and no consistency checks are performed for your
configuration.
The steps that follow use the chzdev command, as the preferred method. For
information about the fallback method of directly using the sysfs interface, see Device Drivers, Features, and
Commands.
About this task
The examples in the steps that follow assume that the following cryptographic resources are
configured for the host partition:
Three adapters, with IDs 00, 01, and 0a.
Four domains, with IDs 0000, 0001, 0002, and
001b.
This configuration corresponds to a matrix of 12 AP queues, as illustrated in Figure 1.
Figure 1. Example matrix of AP queues that are assigned to the host
partition
All AP queues are to be freed, except 01.001b, which is to remain available for
host use. This goal can be achieved by freeing adapters 00 and 0a
and domains 0001, 0002, and 0004 as illustrated
in the following graphic.Figure 2. AP queues freed for KVM guests
For AP queue 01.001b to be exempt, neither its adapter, 01, nor
its domain, 001b, must be freed.
Procedure
Load the vfio-ap device driver.
# modprobe vfio_ap
Optional: Issue lszcrypt -V to list the cryptographic
resources that are configured for the partition in which the KVM host runs.
AP queues that are controlled by the
zcrypt device driver on the host show cex4queue in the DRIVER
column of the output table. These AP queues cannot be used by KVM guests.
Bring AP queues under control of the vfio-ap device driver by issuing a
command of this form:
# chzdev --type ap apmask=<ap_specification> aqmask=<aq_specification><scope>
Where:
<ap_specification>
Specifies one or more adapter IDs. Plain numbers are interpreted as decimal, numbers with a 0x
prefix are interpreted as hexadecimal.
Multiple adapters
Specify multiple adapters as a comma-separated list of adapter IDs and ranges of adapter
IDs.
Ranges
Ranges begin with the lowest ID, followed by a hyphen (-), followed by the highest ID.
Sign prefix
All IDs and ranges to be freed must have a minus sign (-) prefix. A plus (+) prefix returns
adapters to host control.
A specification without sign prefixes overwrites the entire adapter
mask. The plus (+) prefix is implied for all specified adapter IDs. The minus (-) prefix is assumed
for all other IDs.
<aq_specification>
Specifies one or more domain IDs. Plain numbers are interpreted as decimal, numbers with a 0x
prefix are interpreted as hexadecimal.
Multiple domains
Specify multiple domains as a comma-separated list of domain IDs and ranges of domain IDs.
Ranges
Ranges begin with the lowest ID, followed by a hyphen (-), followed by the highest ID.
Sign prefix
All IDs and ranges to be freed must have a minus sign (-) prefix. A plus (+) prefix returns
domains to host control.
A specification without sign prefixes overwrites the entire domain mask.
The plus (+) prefix is implied for all specified domain IDs. The minus (-) prefix is assumed for all
other IDs.
<scope>
The scope can be -a for changing the active configuration or
-p for changing the persistent configuration. Omitting the scope applies the change
to both the active and the persistent configuration.
Example:
To free queues according to Figure 2, issue the
following
command:
# chzdev --type ap apmask=-0x0,-0xa aqmask=-0x0001,-0x0002,-0x0004
The equivalent command variant with the more compact decimal notation
is:
# chzdev --type ap apmask=-0,-10 aqmask=-1,-2,-4
This equivalent command variant specifies domains 1 and 2 as a
range:
# chzdev --type ap apmask=-0,-10 aqmask=-1-2,-4
This equivalent command variant overwrites the entire masks. Note the similarity of the
specifications with the output of the lszdev command in step 4.
# chzdev --type ap apmask=1-9,11-255 aqmask=0,3,5-255
Optional: Confirm your results with lszdev --type
ap and lszcrypt -V.
Example: The summary of the adapter and domain masks as shown by
lszdev --type ap now excludes the adapters with decimal IDs 0 and 10 and the
queues with decimal IDs 1-2 and 4.
# lszdev --type ap
DEVICE TYPE ap
Description : Cryptographic Adjunct Processor (AP) device
Modules : ap
Active : yes
Persistent : yes
ATTRIBUTE ACTIVE PERSISTENT
apmask "1-9,11-255" "1-9,11-255"
aqmask "0,3,5-255" "0,3,5-255"
The lszcrypt -V command shows
the effect of the masks on the available cryptographic resources.
With
the verbose option, the lszcrypt command shows the AP queues that are controlled
by the vfio-ap device driver. The output of lszcrypt without the
verbose option omits AP queues that are not controlled by zcrypt. The adapters
themselves always remain under control of cex4card, which is a submodule of
zcrypt.
What to do next
You can now assign AP queues that are controlled by the vfio-ap device
driver to VFIO AP mediated devices.
