Lines Matching full:ap
2 Adjunct Processor (AP) facility
8 The Adjunct Processor (AP) facility is an IBM Z cryptographic facility comprised
9 of three AP instructions and from 1 up to 256 PCIe cryptographic adapter cards.
10 The AP devices provide cryptographic functions to all CPUs assigned to a
13 The AP adapter cards are exposed via the AP bus. The motivation for vfio-ap
14 is to make AP cards available to KVM guests using the VFIO mediated device
16 facilities which do most of the hard work of providing direct access to AP
19 AP Architectural Overview
24 * AP adapter
26 An AP adapter is an IBM Z adapter card that can perform cryptographic
31 When installed, an AP adapter is accessed by AP instructions executed by any
34 The AP adapter cards are assigned to a given LPAR via the system's Activation
36 in the LPAR, the AP bus detects the AP adapter cards assigned to the LPAR and
37 creates a sysfs device for each assigned adapter. For example, if AP adapters
38 4 and 10 (0x0a) are assigned to the LPAR, the AP bus will create the following
41 /sys/devices/ap/card04
42 /sys/devices/ap/card0a
44 Symbolic links to these devices will also be created in the AP bus devices
47 /sys/bus/ap/devices/[card04]
48 /sys/bus/ap/devices/[card04]
50 * AP domain
56 as a set of hardware registers and memory used for processing AP commands. A
61 * Usage domains are domains that are targeted by an AP instruction to
62 process an AP command.
64 * Control domains are domains that are changed by an AP command sent to a
68 The AP usage and control domains are assigned to a given LPAR via the system's
70 is IPL'd in the LPAR, the AP bus module detects the AP usage and control
72 adapter number of each AP adapter are combined to create AP queue devices
73 (see AP Queue section below). The domain number of each control domain will be
75 /sys/bus/ap/ap_control_domain_mask. The bits in the mask, from most to least
78 * AP Queue
80 An AP queue is the means by which an AP command is sent to a usage domain
81 inside a specific adapter. An AP queue is identified by a tuple
82 comprised of an AP adapter ID (APID) and an AP queue index (APQI). The
84 forms an AP Queue Number (APQN) uniquely identifying an AP queue. AP
85 instructions include a field containing the APQN to identify the AP queue to
86 which the AP command is to be sent for processing.
88 The AP bus will create a sysfs device for each APQN that can be derived from
89 the cross product of the AP adapter and usage domain numbers detected when the
90 AP bus module is loaded. For example, if adapters 4 and 10 (0x0a) and usage
91 domains 6 and 71 (0x47) are assigned to the LPAR, the AP bus will create the
94 /sys/devices/ap/card04/04.0006
95 /sys/devices/ap/card04/04.0047
96 /sys/devices/ap/card0a/0a.0006
97 /sys/devices/ap/card0a/0a.0047
99 The following symbolic links to these devices will be created in the AP bus
102 /sys/bus/ap/devices/[04.0006]
103 /sys/bus/ap/devices/[04.0047]
104 /sys/bus/ap/devices/[0a.0006]
105 /sys/bus/ap/devices/[0a.0047]
107 * AP Instructions:
109 There are three AP instructions:
111 * NQAP: to enqueue an AP command-request message to a queue
112 * DQAP: to dequeue an AP command-reply message from a queue
115 AP instructions identify the domain that is targeted to process the AP
116 command; this must be one of the usage domains. An AP command may modify a
120 AP and SIE
122 Let's now take a look at how AP instructions executed on a guest are interpreted
130 * The AP Mask (APM) field is a bit mask that identifies the AP adapters assigned
136 * The AP Queue Mask (AQM) field is a bit mask identifying the AP usage domains
139 an AP queue index (APQI) from 0-255. If a bit is set, the corresponding queue
142 * The AP Domain Mask field is a bit mask that identifies the AP control domains
144 changed by an AP command-request message sent to a usage domain from the
147 0-255. If a bit is set, the corresponding domain can be modified by an AP
150 If you recall from the description of an AP Queue, AP instructions include
151 an APQN to identify the AP queue to which an AP command-request message is to be
193 1. AP matrix device
194 2. VFIO AP device driver (vfio_ap.ko)
195 3. VFIO AP mediated matrix pass-through device
197 The VFIO AP device driver
199 The VFIO AP (vfio_ap) device driver serves the following purposes:
208 SIE state description to grant the guest access to a matrix of AP devices
230 | | | 4 register AP driver | | 2 register device
251 The process for reserving an AP queue for use by a KVM guest is:
254 2. The vfio-ap driver during its initialization will register a single 'matrix'
256 all mediated matrix devices used to configure an AP matrix for a guest.
258 4. The vfio_ap device driver will register with the AP bus for AP queue devices
265 5. The AP bus registers the vfio_ap device driver with the device core
266 6. The administrator edits the AP adapter and queue masks to reserve AP queues
268 7. The AP bus removes the AP queues reserved for the vfio_ap driver from the
270 8. The AP bus probes the vfio_ap device driver to bind the queues reserved for
279 The VFIO AP device driver utilizes the common interface of the VFIO mediated
282 * Register an AP mediated bus driver to add a mediated matrix device to and
285 * Add a mediated matrix device to and remove it from the AP mediated bus driver
289 of the VFIO AP mediated matrix device driver::
326 The VFIO AP device driver will register one mediated device type for
358 Write-only attributes for assigning/unassigning an AP adapter to/from the
362 Write-only attributes for assigning/unassigning an AP usage domain to/from
370 Write-only attributes for assigning/unassigning an AP control domain
384 * Store the AP matrix configuration for the adapters, domains, and control
399 is used to configure the guest's access to the AP matrix defined via the
403 mdev matrix device and deconfigures the guest's AP matrix.
407 Configuring the AP matrix for a KVM guest will be performed when the
409 function is called when QEMU connects to KVM. The guest's AP matrix is
419 The CPU model features for AP
421 The AP stack relies on the presence of the AP instructions as well as two
422 facilities: The AP Facilities Test (APFT) facility; and the AP Query
426 1. ap: Indicates whether the AP instructions are installed on the guest. This
427 feature will be enabled by KVM only if the AP instructions are installed
434 3. apqci: Indicates the AP QCI facility is available on the guest. This facility
442 /usr/bin/qemu-system-s390x ... -cpu z13,ap=on,apqci=on,apft=on
444 A guest can be precluded from using AP features/facilities by turning them off
447 /usr/bin/qemu-system-s390x ... -cpu host,ap=off,apqci=off,apft=off
450 will not see any AP devices. The zcrypt device drivers that register for type 10
451 and newer AP devices - i.e., the cex4card and cex4queue device drivers - need
452 the APFT facility to ascertain the facilities installed on a given AP device. If
460 access to AP facilities. For this example, we will show how to configure
524 select S390 AP IOMMU Support
529 -> VFIO support for AP devices
531 2. Secure the AP queues to be used by the three guests so that the host can not
533 bitmasks marking a subset of the APQN range as 'usable by the default AP
538 /sys/bus/ap/apmask
539 /sys/bus/ap/aqmask
541 The 'apmask' is a 256-bit mask that identifies a set of AP adapter IDs
544 0-255. If a bit is set, the APID is marked as usable only by the default AP
548 The 'aqmask' is a 256-bit mask that identifies a set of AP queue indexes
551 0-255. If a bit is set, the APQI is marked as usable only by the default AP
564 The APQN of each AP queue device assigned to the linux host is checked by the
565 AP bus against the set of APQNs derived from the cross product of APIDs
566 and APQIs marked as usable only by the default AP queue device drivers. If a
567 match is detected, only the default AP queue device drivers will be probed;
571 AP queue device drivers. There are two ways the default masks can be changed:
615 ap.apmask=0xffff ap.aqmask=0x40
632 To secure the AP queues 05.0004, 05.0047, 05.00ab, 05.00ff, 06.0004, 06.0047,
636 echo -5,-6 > /sys/bus/ap/apmask
638 echo -4,-0x47,-0xab,-0xff > /sys/bus/ap/aqmask
648 This will result in AP queues 05.0004, 05.0047, 05.00ab, 05.00ff, 06.0004,
651 to the AP queue devices bound to it::
653 /sys/bus/ap
671 The administrator, therefore, must take care to secure only AP queues that
672 can be bound to the vfio_ap device driver. The device type for a given AP
676 cat /sys/bus/ap/devices/card05/hwtype
681 3. Create the mediated devices needed to configure the AP matrixes for the
816 /usr/bin/qemu-system-s390x ... -cpu host,ap=on,apqci=on,apft=on \
817 -device vfio-ap,sysfsdev=/sys/devices/vfio_ap/matrix/$uuid1 ...
821 /usr/bin/qemu-system-s390x ... -cpu host,ap=on,apqci=on,apft=on \
822 -device vfio-ap,sysfsdev=/sys/devices/vfio_ap/matrix/$uuid2 ...
826 /usr/bin/qemu-system-s390x ... -cpu host,ap=on,apqci=on,apft=on \
827 -device vfio-ap,sysfsdev=/sys/devices/vfio_ap/matrix/$uuid3 ...
860 assigned lest the host be given access to the private data of the AP queue
863 * Dynamically modifying the AP matrix for a running guest (which would amount to
864 hot(un)plug of AP devices for the guest) is currently not supported
866 * Live guest migration is not supported for guests using AP devices.