docs/vfio-ap.txt

   1 Adjunct Processor (AP) Device
   2 =============================
   3
   4 Contents:
   5 =========
   6 * Introduction
   7 * AP Architectural Overview
   8 * Start Interpretive Execution (SIE) Instruction
   9 * AP Matrix Configuration on Linux Host
  10 * Starting a Linux Guest Configured with an AP Matrix
  11 * Example: Configure AP Matrices for Three Linux Guests
  12
  13 Introduction:
  14 ============
  15 The IBM Adjunct Processor (AP) Cryptographic Facility is comprised
  16 of three AP instructions and from 1 to 256 PCIe cryptographic adapter cards.
  17 These AP devices provide cryptographic functions to all CPUs assigned to a
  18 linux system running in an IBM Z system LPAR.
  19
  20 On s390x, AP adapter cards are exposed via the AP bus. This document
  21 describes how those cards may be made available to KVM guests using the
  22 VFIO mediated device framework.
  23
  24 AP Architectural Overview:
  25 =========================
  26 In order understand the terminology used in the rest of this document, let's
  27 start with some definitions:
  28
  29 * AP adapter
  30
  31   An AP adapter is an IBM Z adapter card that can perform cryptographic
  32   functions. There can be from 0 to 256 adapters assigned to an LPAR depending
  33   on the machine model. Adapters assigned to the LPAR in which a linux host is
  34   running will be available to the linux host. Each adapter is identified by a
  35   number from 0 to 255; however, the maximum adapter number allowed is
  36   determined by machine model. When installed, an AP adapter is accessed by
  37   AP instructions executed by any CPU.
  38
  39 * AP domain
  40
  41   An adapter is partitioned into domains. Each domain can be thought of as
  42   a set of hardware registers for processing AP instructions. An adapter can
  43   hold up to 256 domains; however, the maximum domain number allowed is
  44   determined by machine model. Each domain is identified by a number from 0 to
  45   255. Domains can be further classified into two types:
  46
  47     * Usage domains are domains that can be accessed directly to process AP
  48       commands
  49
  50     * Control domains are domains that are accessed indirectly by AP
  51       commands sent to a usage domain to control or change the domain; for
  52       example, to set a secure private key for the domain.
  53
  54 * AP Queue
  55
  56   An AP queue is the means by which an AP command-request message is sent to an
  57   AP usage domain inside a specific AP. An AP queue is identified by a tuple
  58   comprised of an AP adapter ID (APID) and an AP queue index (APQI). The
  59   APQI corresponds to a given usage domain number within the adapter. This tuple
  60   forms an AP Queue Number (APQN) uniquely identifying an AP queue. AP
  61   instructions include a field containing the APQN to identify the AP queue to
  62   which the AP command-request message is to be sent for processing.
  63
  64 * AP Instructions:
  65
  66   There are three AP instructions:
  67
  68   * NQAP: to enqueue an AP command-request message to a queue
  69   * DQAP: to dequeue an AP command-reply message from a queue
  70   * PQAP: to administer the queues
  71
  72   AP instructions identify the domain that is targeted to process the AP
  73   command; this must be one of the usage domains. An AP command may modify a
  74   domain that is not one of the usage domains, but the modified domain
  75   must be one of the control domains.
  76
  77 Start Interpretive Execution (SIE) Instruction
  78 ==============================================
  79 A KVM guest is started by executing the Start Interpretive Execution (SIE)
  80 instruction. The SIE state description is a control block that contains the
  81 state information for a KVM guest and is supplied as input to the SIE
  82 instruction. The SIE state description contains a satellite control block called
  83 the Crypto Control Block (CRYCB). The CRYCB contains three fields to identify
  84 the adapters, usage domains and control domains assigned to the KVM guest:
  85
  86 * The AP Mask (APM) field is a bit mask that identifies the AP adapters assigned
  87   to the KVM guest. Each bit in the mask, from left to right, corresponds to
  88   an APID from 0-255. If a bit is set, the corresponding adapter is valid for
  89   use by the KVM guest.
  90
  91 * The AP Queue Mask (AQM) field is a bit mask identifying the AP usage domains
  92   assigned to the KVM guest. Each bit in the mask, from left to right,
  93   corresponds to  an AP queue index (APQI) from 0-255. If a bit is set, the
  94   corresponding queue is valid for use by the KVM guest.
  95
  96 * The AP Domain Mask field is a bit mask that identifies the AP control domains
  97   assigned to the KVM guest. The ADM bit mask controls which domains can be
  98   changed by an AP command-request message sent to a usage domain from the
  99   guest. Each bit in the mask, from left to right, corresponds to a domain from
 100   0-255. If a bit is set, the corresponding domain can be modified by an AP
 101   command-request message sent to a usage domain.
 102
 103 If you recall from the description of an AP Queue, AP instructions include
 104 an APQN to identify the AP adapter and AP queue to which an AP command-request
 105 message is to be sent (NQAP and PQAP instructions), or from which a
 106 command-reply message is to be received (DQAP instruction). The validity of an
 107 APQN is defined by the matrix calculated from the APM and AQM; it is the
 108 cross product of all assigned adapter numbers (APM) with all assigned queue
 109 indexes (AQM). For example, if adapters 1 and 2 and usage domains 5 and 6 are
 110 assigned to a guest, the APQNs (1,5), (1,6), (2,5) and (2,6) will be valid for
 111 the guest.
 112
 113 The APQNs can provide secure key functionality - i.e., a private key is stored
 114 on the adapter card for each of its domains - so each APQN must be assigned to
 115 at most one guest or the linux host.
 116
 117    Example 1: Valid configuration:
 118    ------------------------------
 119    Guest1: adapters 1,2  domains 5,6
 120    Guest2: adapter  1,2  domain 7
 121
 122    This is valid because both guests have a unique set of APQNs: Guest1 has
 123    APQNs (1,5), (1,6), (2,5) and (2,6); Guest2 has APQNs (1,7) and (2,7).
 124
 125    Example 2: Valid configuration:
 126    ------------------------------
 127    Guest1: adapters 1,2 domains 5,6
 128    Guest2: adapters 3,4 domains 5,6
 129
 130    This is also valid because both guests have a unique set of APQNs:
 131       Guest1 has APQNs (1,5), (1,6), (2,5), (2,6);
 132       Guest2 has APQNs (3,5), (3,6), (4,5), (4,6)
 133
 134    Example 3: Invalid configuration:
 135    --------------------------------
 136    Guest1: adapters 1,2  domains 5,6
 137    Guest2: adapter  1    domains 6,7
 138
 139    This is an invalid configuration because both guests have access to
 140    APQN (1,6).
 141
 142 AP Matrix Configuration on Linux Host:
 143 =====================================
 144 A linux system is a guest of the LPAR in which it is running and has access to
 145 the AP resources configured for the LPAR. The LPAR's AP matrix is
 146 configured via its Activation Profile which can be edited on the HMC. When the
 147 linux system is started, the AP bus will detect the AP devices assigned to the
 148 LPAR and create the following in sysfs:
 149
 150 /sys/bus/ap
 151 ... [devices]
 152 ...... xx.yyyy
 153 ...... ...
 154 ...... cardxx
 155 ...... ...
 156
 157 Where:
 158     cardxx     is AP adapter number xx (in hex)
 159 ....xx.yyyy    is an APQN with xx specifying the APID and yyyy specifying the
 160                APQI
 161
 162 For example, if AP adapters 5 and 6 and domains 4, 71 (0x47), 171 (0xab) and
 163 255 (0xff) are configured for the LPAR, the sysfs representation on the linux
 164 host system would look like this:
 165
 166 /sys/bus/ap
 167 ... [devices]
 168 ...... 05.0004
 169 ...... 05.0047
 170 ...... 05.00ab
 171 ...... 05.00ff
 172 ...... 06.0004
 173 ...... 06.0047
 174 ...... 06.00ab
 175 ...... 06.00ff
 176 ...... card05
 177 ...... card06
 178
 179 A set of default device drivers are also created to control each type of AP
 180 device that can be assigned to the LPAR on which a linux host is running:
 181
 182 /sys/bus/ap
 183 ... [drivers]
 184 ...... [cex2acard]        for Crypto Express 2/3 accelerator cards
 185 ...... [cex2aqueue]       for AP queues served by Crypto Express 2/3
 186                           accelerator cards
 187 ...... [cex4card]         for Crypto Express 4/5/6 accelerator and coprocessor
 188                           cards
 189 ...... [cex4queue]        for AP queues served by Crypto Express 4/5/6
 190                           accelerator and coprocessor cards
 191 ...... [pcixcccard]       for Crypto Express 2/3 coprocessor cards
 192 ...... [pcixccqueue]      for AP queues served by Crypto Express 2/3
 193                           coprocessor cards
 194
 195 Binding AP devices to device drivers
 196 ------------------------------------
 197 There are two sysfs files that specify bitmasks marking a subset of the APQN
 198 range as 'usable by the default AP queue device drivers' or 'not usable by the
 199 default device drivers' and thus available for use by the alternate device
 200 driver(s). The sysfs locations of the masks are:
 201
 202    /sys/bus/ap/apmask
 203    /sys/bus/ap/aqmask
 204
 205    The 'apmask' is a 256-bit mask that identifies a set of AP adapter IDs
 206    (APID). Each bit in the mask, from left to right (i.e., from most significant
 207    to least significant bit in big endian order), corresponds to an APID from
 208    0-255. If a bit is set, the APID is marked as usable only by the default AP
 209    queue device drivers; otherwise, the APID is usable by the vfio_ap
 210    device driver.
 211
 212    The 'aqmask' is a 256-bit mask that identifies a set of AP queue indexes
 213    (APQI). Each bit in the mask, from left to right (i.e., from most significant
 214    to least significant bit in big endian order), corresponds to an APQI from
 215    0-255. If a bit is set, the APQI is marked as usable only by the default AP
 216    queue device drivers; otherwise, the APQI is usable by the vfio_ap device
 217    driver.
 218
 219    Take, for example, the following mask:
 220
 221       0x7dffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
 222
 223     It indicates:
 224
 225       1, 2, 3, 4, 5, and 7-255 belong to the default drivers' pool, and 0 and 6
 226       belong to the vfio_ap device driver's pool.
 227
 228    The APQN of each AP queue device assigned to the linux host is checked by the
 229    AP bus against the set of APQNs derived from the cross product of APIDs
 230    and APQIs marked as usable only by the default AP queue device drivers. If a
 231    match is detected,  only the default AP queue device drivers will be probed;
 232    otherwise, the vfio_ap device driver will be probed.
 233
 234    By default, the two masks are set to reserve all APQNs for use by the default
 235    AP queue device drivers. There are two ways the default masks can be changed:
 236
 237    1. The sysfs mask files can be edited by echoing a string into the
 238       respective sysfs mask file in one of two formats:
 239
 240       * An absolute hex string starting with 0x - like "0x12345678" - sets
 241         the mask. If the given string is shorter than the mask, it is padded
 242         with 0s on the right; for example, specifying a mask value of 0x41 is
 243         the same as specifying:
 244
 245            0x4100000000000000000000000000000000000000000000000000000000000000
 246
 247         Keep in mind that the mask reads from left to right (i.e., most
 248         significant to least significant bit in big endian order), so the mask
 249         above identifies device numbers 1 and 7 (01000001).
 250
 251         If the string is longer than the mask, the operation is terminated with
 252         an error (EINVAL).
 253
 254       * Individual bits in the mask can be switched on and off by specifying
 255         each bit number to be switched in a comma separated list. Each bit
 256         number string must be prepended with a ('+') or minus ('-') to indicate
 257         the corresponding bit is to be switched on ('+') or off ('-'). Some
 258         valid values are:
 259
 260            "+0"    switches bit 0 on
 261            "-13"   switches bit 13 off
 262            "+0x41" switches bit 65 on
 263            "-0xff" switches bit 255 off
 264
 265            The following example:
 266               +0,-6,+0x47,-0xf0
 267
 268               Switches bits 0 and 71 (0x47) on
 269               Switches bits 6 and 240 (0xf0) off
 270
 271         Note that the bits not specified in the list remain as they were before
 272         the operation.
 273
 274    2. The masks can also be changed at boot time via parameters on the kernel
 275       command line like this:
 276
 277          ap.apmask=0xffff ap.aqmask=0x40
 278
 279          This would create the following masks:
 280
 281             apmask:
 282             0xffff000000000000000000000000000000000000000000000000000000000000
 283
 284             aqmask:
 285             0x4000000000000000000000000000000000000000000000000000000000000000
 286
 287          Resulting in these two pools:
 288
 289             default drivers pool:    adapter 0-15, domain 1
 290             alternate drivers pool:  adapter 16-255, domains 0, 2-255
 291
 292 Configuring an AP matrix for a linux guest.
 293 ------------------------------------------
 294 The sysfs interfaces for configuring an AP matrix for a guest are built on the
 295 VFIO mediated device framework. To configure an AP matrix for a guest, a
 296 mediated matrix device must first be created for the /sys/devices/vfio_ap/matrix
 297 device. When the vfio_ap device driver is loaded, it registers with the VFIO
 298 mediated device framework. When the driver registers, the sysfs interfaces for
 299 creating mediated matrix devices is created:
 300
 301 /sys/devices
 302 ... [vfio_ap]
 303 ......[matrix]
 304 ......... [mdev_supported_types]
 305 ............ [vfio_ap-passthrough]
 306 ............... create
 307 ............... [devices]
 308
 309 A mediated AP matrix device is created by writing a UUID to the attribute file
 310 named 'create', for example:
 311
 312    uuidgen > create
 313
 314    or
 315
 316    echo $uuid > create
 317
 318 When a mediated AP matrix device is created, a sysfs directory named after
 319 the UUID is created in the 'devices' subdirectory:
 320
 321 /sys/devices
 322 ... [vfio_ap]
 323 ......[matrix]
 324 ......... [mdev_supported_types]
 325 ............ [vfio_ap-passthrough]
 326 ............... create
 327 ............... [devices]
 328 .................. [$uuid]
 329
 330 There will also be three sets of attribute files created in the mediated
 331 matrix device's sysfs directory to configure an AP matrix for the
 332 KVM guest:
 333
 334 /sys/devices
 335 ... [vfio_ap]
 336 ......[matrix]
 337 ......... [mdev_supported_types]
 338 ............ [vfio_ap-passthrough]
 339 ............... create
 340 ............... [devices]
 341 .................. [$uuid]
 342 ..................... assign_adapter
 343 ..................... assign_control_domain
 344 ..................... assign_domain
 345 ..................... matrix
 346 ..................... unassign_adapter
 347 ..................... unassign_control_domain
 348 ..................... unassign_domain
 349
 350 assign_adapter
 351    To assign an AP adapter to the mediated matrix device, its APID is written
 352    to the 'assign_adapter' file. This may be done multiple times to assign more
 353    than one adapter. The APID may be specified using conventional semantics
 354    as a decimal, hexadecimal, or octal number. For example, to assign adapters
 355    4, 5 and 16 to a mediated matrix device in decimal, hexadecimal and octal
 356    respectively:
 357
 358        echo 4 > assign_adapter
 359        echo 0x5 > assign_adapter
 360        echo 020 > assign_adapter
 361
 362    In order to successfully assign an adapter:
 363
 364    * The adapter number specified must represent a value from 0 up to the
 365      maximum adapter number allowed by the machine model. If an adapter number
 366      higher than the maximum is specified, the operation will terminate with
 367      an error (ENODEV).
 368
 369    * All APQNs that can be derived from the adapter ID being assigned and the
 370      IDs of the previously assigned domains must be bound to the vfio_ap device
 371      driver. If no domains have yet been assigned, then there must be at least
 372      one APQN with the specified APID bound to the vfio_ap driver. If no such
 373      APQNs are bound to the driver, the operation will terminate with an
 374      error (EADDRNOTAVAIL).
 375
 376      No APQN that can be derived from the adapter ID and the IDs of the
 377      previously assigned domains can be assigned to another mediated matrix
 378      device. If an APQN is assigned to another mediated matrix device, the
 379      operation will terminate with an error (EADDRINUSE).
 380
 381 unassign_adapter
 382    To unassign an AP adapter, its APID is written to the 'unassign_adapter'
 383    file. This may also be done multiple times to unassign more than one adapter.
 384
 385 assign_domain
 386    To assign a usage domain, the domain number is written into the
 387    'assign_domain' file. This may be done multiple times to assign more than one
 388    usage domain. The domain number is specified using conventional semantics as
 389    a decimal, hexadecimal, or octal number. For example, to assign usage domains
 390    4, 8, and 71 to a mediated matrix device in decimal, hexadecimal and octal
 391    respectively:
 392
 393       echo 4 > assign_domain
 394       echo 0x8 > assign_domain
 395       echo 0107 > assign_domain
 396
 397    In order to successfully assign a domain:
 398
 399    * The domain number specified must represent a value from 0 up to the
 400      maximum domain number allowed by the machine model. If a domain number
 401      higher than the maximum is specified, the operation will terminate with
 402      an error (ENODEV).
 403
 404    * All APQNs that can be derived from the domain ID being assigned and the IDs
 405      of the previously assigned adapters must be bound to the vfio_ap device
 406      driver. If no domains have yet been assigned, then there must be at least
 407      one APQN with the specified APQI bound to the vfio_ap driver. If no such
 408      APQNs are bound to the driver, the operation will terminate with an
 409      error (EADDRNOTAVAIL).
 410
 411      No APQN that can be derived from the domain ID being assigned and the IDs
 412      of the previously assigned adapters can be assigned to another mediated
 413      matrix device. If an APQN is assigned to another mediated matrix device,
 414      the operation will terminate with an error (EADDRINUSE).
 415
 416 unassign_domain
 417    To unassign a usage domain, the domain number is written into the
 418    'unassign_domain' file. This may be done multiple times to unassign more than
 419    one usage domain.
 420
 421 assign_control_domain
 422    To assign a control domain, the domain number is written into the
 423    'assign_control_domain' file. This may be done multiple times to
 424    assign more than one control domain. The domain number may be specified using
 425    conventional semantics as a decimal, hexadecimal, or octal number. For
 426    example, to assign  control domains 4, 8, and 71 to  a mediated matrix device
 427    in decimal, hexadecimal and octal respectively:
 428
 429       echo 4 > assign_domain
 430       echo 0x8 > assign_domain
 431       echo 0107 > assign_domain
 432
 433    In order to successfully assign a control domain, the domain number
 434    specified must represent a value from 0 up to the maximum domain number
 435    allowed by the machine model. If a control domain number higher than the
 436    maximum is specified, the operation will terminate with an error (ENODEV).
 437
 438 unassign_control_domain
 439    To unassign a control domain, the domain number is written into the
 440    'unassign_domain' file. This may be done multiple times to unassign more than
 441    one control domain.
 442
 443 Notes: Hot plug/unplug is not currently supported for mediated AP matrix
 444 devices, so no changes to the AP matrix will be allowed while a guest using
 445 the mediated matrix device is running. Attempts to assign an adapter,
 446 domain or control domain will be rejected and an error (EBUSY) returned.
 447
 448 Starting a Linux Guest Configured with an AP Matrix:
 449 ===================================================
 450 To provide a mediated matrix device for use by a guest, the following option
 451 must be specified on the QEMU command line:
 452
 453    -device vfio_ap,sysfsdev=$path-to-mdev
 454
 455 The sysfsdev parameter specifies the path to the mediated matrix device.
 456 There are a number of ways to specify this path:
 457
 458 /sys/devices/vfio_ap/matrix/$uuid
 459 /sys/bus/mdev/devices/$uuid
 460 /sys/bus/mdev/drivers/vfio_mdev/$uuid
 461 /sys/devices/vfio_ap/matrix/mdev_supported_types/vfio_ap-passthrough/devices/$uuid
 462
 463 When the linux guest is started, the guest will open the mediated
 464 matrix device's file descriptor to get information about the mediated matrix
 465 device. The vfio_ap device driver will update the APM, AQM, and ADM fields in
 466 the guest's CRYCB with the adapter, usage domain and control domains assigned
 467 via the mediated matrix device's sysfs attribute files. Programs running on the
 468 linux guest will then:
 469
 470 1. Have direct access to the APQNs derived from the cross product of the AP
 471    adapter numbers (APID) and queue indexes (APQI) specified in the APM and AQM
 472    fields of the guests's CRYCB respectively. These APQNs identify the AP queues
 473    that are valid for use by the guest; meaning, AP commands can be sent by the
 474    guest to any of these queues for processing.
 475
 476 2. Have authorization to process AP commands to change a control domain
 477    identified in the ADM field of the guest's CRYCB. The AP command must be sent
 478    to a valid APQN (see 1 above).
 479
 480 CPU model features:
 481
 482 Three CPU model features are available for controlling guest access to AP
 483 facilities:
 484
 485 1. AP facilities feature
 486
 487    The AP facilities feature indicates that AP facilities are installed on the
 488    guest. This feature will be exposed for use only if the AP facilities
 489    are installed on the host system. The feature is s390-specific and is
 490    represented as a parameter of the -cpu option on the QEMU command line:
 491
 492       qemu-system-s390x -cpu $model,ap=on|off
 493
 494       Where:
 495
 496          $model is the CPU model defined for the guest (defaults to the model of
 497                 the host system if not specified).
 498
 499          ap=on|off indicates whether AP facilities are installed (on) or not
 500                    (off). The default for CPU models zEC12 or newer
 501                    is ap=on. AP facilities must be installed on the guest if a
 502                    vfio-ap device (-device vfio-ap,sysfsdev=$path) is configured
 503                    for the guest, or the guest will fail to start.
 504
 505 2. Query Configuration Information (QCI) facility
 506
 507    The QCI facility is used by the AP bus running on the guest to query the
 508    configuration of the AP facilities. This facility will be available
 509    only if the QCI facility is installed on the host system. The feature is
 510    s390-specific and is represented as a parameter of the -cpu option on the
 511    QEMU command line:
 512
 513       qemu-system-s390x -cpu $model,apqci=on|off
 514
 515       Where:
 516
 517          $model is the CPU model defined for the guest
 518
 519          apqci=on|off indicates whether the QCI facility is installed (on) or
 520                       not (off). The default for CPU models zEC12 or newer
 521                       is apqci=on; for older models, QCI will not be installed.
 522
 523                       If QCI is installed (apqci=on) but AP facilities are not
 524                       (ap=off), an error message will be logged, but the guest
 525                       will be allowed to start. It makes no sense to have QCI
 526                       installed if the AP facilities are not; this is considered
 527                       an invalid configuration.
 528
 529                       If the QCI facility is not installed, APQNs with an APQI
 530                       greater than 15 will not be detected by the AP bus
 531                       running on the guest.
 532
 533 3. Adjunct Process Facility Test (APFT) facility
 534
 535    The APFT facility is used by the AP bus running on the guest to test the
 536    AP facilities available for a given AP queue. This facility will be available
 537    only if the APFT facility is installed on the host system. The feature is
 538    s390-specific and is represented as a parameter of the -cpu option on the
 539    QEMU command line:
 540
 541       qemu-system-s390x -cpu $model,apft=on|off
 542
 543       Where:
 544
 545          $model is the CPU model defined for the guest (defaults to the model of
 546                 the host system if not specified).
 547
 548          apft=on|off indicates whether the APFT facility is installed (on) or
 549                      not (off). The default for CPU models zEC12 and
 550                      newer is apft=on for older models, APFT will not be
 551                      installed.
 552
 553                      If APFT is installed (apft=on) but AP facilities are not
 554                      (ap=off), an error message will be logged, but the guest
 555                      will be allowed to start. It makes no sense to have APFT
 556                      installed if the AP facilities are not; this is considered
 557                      an invalid configuration.
 558
 559                      It also makes no sense to turn APFT off because the AP bus
 560                      running on the guest will not detect CEX4 and newer devices
 561                      without it. Since only CEX4 and newer devices are supported
 562                      for guest usage, no AP devices can be made accessible to a
 563                      guest started without APFT installed.
 564
 565 Example: Configure AP Matrixes for Three Linux Guests:
 566 =====================================================
 567 Let's now provide an example to illustrate how KVM guests may be given
 568 access to AP facilities. For this example, we will show how to configure
 569 three guests such that executing the lszcrypt command on the guests would
 570 look like this:
 571
 572 Guest1
 573 ------
 574 CARD.DOMAIN TYPE  MODE
 575 ------------------------------
 576 05          CEX5C CCA-Coproc
 577 05.0004     CEX5C CCA-Coproc
 578 05.00ab     CEX5C CCA-Coproc
 579 06          CEX5A Accelerator
 580 06.0004     CEX5A Accelerator
 581 06.00ab     CEX5C CCA-Coproc
 582
 583 Guest2
 584 ------
 585 CARD.DOMAIN TYPE  MODE
 586 ------------------------------
 587 05          CEX5A Accelerator
 588 05.0047     CEX5A Accelerator
 589 05.00ff     CEX5A Accelerator (5,4), (5,171), (6,4), (6,171),
 590
 591 Guest3
 592 ------
 593 CARD.DOMAIN TYPE  MODE
 594 ------------------------------
 595 06          CEX5A Accelerator
 596 06.0047     CEX5A Accelerator
 597 06.00ff     CEX5A Accelerator
 598
 599 These are the steps:
 600
 601 1. Install the vfio_ap module on the linux host. The dependency chain for the
 602    vfio_ap module is:
 603    * iommu
 604    * s390
 605    * zcrypt
 606    * vfio
 607    * vfio_mdev
 608    * vfio_mdev_device
 609    * KVM
 610
 611    To build the vfio_ap module, the kernel build must be configured with the
 612    following Kconfig elements selected:
 613    * IOMMU_SUPPORT
 614    * S390
 615    * ZCRYPT
 616    * S390_AP_IOMMU
 617    * VFIO
 618    * VFIO_MDEV
 619    * VFIO_MDEV_DEVICE
 620    * KVM
 621
 622    If using make menuconfig select the following to build the vfio_ap module:
 623    -> Device Drivers
 624       -> IOMMU Hardware Support
 625          select S390 AP IOMMU Support
 626       -> VFIO Non-Privileged userspace driver framework
 627          -> Mediated device driver frramework
 628             -> VFIO driver for Mediated devices
 629    -> I/O subsystem
 630       -> VFIO support for AP devices
 631
 632 2. Secure the AP queues to be used by the three guests so that the host can not
 633    access them. To secure the AP queues 05.0004, 05.0047, 05.00ab, 05.00ff,
 634    06.0004, 06.0047, 06.00ab, and 06.00ff for use by the vfio_ap device driver,
 635    the corresponding APQNs must be removed from the default queue drivers pool
 636    as follows:
 637
 638       echo -5,-6 > /sys/bus/ap/apmask
 639
 640       echo -4,-0x47,-0xab,-0xff > /sys/bus/ap/aqmask
 641
 642    This will result in AP queues 05.0004, 05.0047, 05.00ab, 05.00ff, 06.0004,
 643    06.0047, 06.00ab, and 06.00ff getting bound to the vfio_ap device driver. The
 644    sysfs directory for the vfio_ap device driver will now contain symbolic links
 645    to the AP queue devices bound to it:
 646
 647    /sys/bus/ap
 648    ... [drivers]
 649    ...... [vfio_ap]
 650    ......... [05.0004]
 651    ......... [05.0047]
 652    ......... [05.00ab]
 653    ......... [05.00ff]
 654    ......... [06.0004]
 655    ......... [06.0047]
 656    ......... [06.00ab]
 657    ......... [06.00ff]
 658
 659    Keep in mind that only type 10 and newer adapters (i.e., CEX4 and later)
 660    can be bound to the vfio_ap device driver. The reason for this is to
 661    simplify the implementation by not needlessly complicating the design by
 662    supporting older devices that will go out of service in the relatively near
 663    future, and for which there are few older systems on which to test.
 664
 665    The administrator, therefore, must take care to secure only AP queues that
 666    can be bound to the vfio_ap device driver. The device type for a given AP
 667    queue device can be read from the parent card's sysfs directory. For example,
 668    to see the hardware type of the queue 05.0004:
 669
 670    cat /sys/bus/ap/devices/card05/hwtype
 671
 672    The hwtype must be 10 or higher (CEX4 or newer) in order to be bound to the
 673    vfio_ap device driver.
 674
 675 3. Create the mediated devices needed to configure the AP matrixes for the
 676    three guests and to provide an interface to the vfio_ap driver for
 677    use by the guests:
 678
 679    /sys/devices/vfio_ap/matrix/
 680    --- [mdev_supported_types]
 681    ------ [vfio_ap-passthrough] (passthrough mediated matrix device type)
 682    --------- create
 683    --------- [devices]
 684
 685    To create the mediated devices for the three guests:
 686
 687        uuidgen > create
 688        uuidgen > create
 689        uuidgen > create
 690
 691         or
 692
 693         echo $uuid1 > create
 694         echo $uuid2 > create
 695         echo $uuid3 > create
 696
 697    This will create three mediated devices in the [devices] subdirectory named
 698    after the UUID used to create the mediated device. We'll call them $uuid1,
 699    $uuid2 and $uuid3 and this is the sysfs directory structure after creation:
 700
 701    /sys/devices/vfio_ap/matrix/
 702    --- [mdev_supported_types]
 703    ------ [vfio_ap-passthrough]
 704    --------- [devices]
 705    ------------ [$uuid1]
 706    --------------- assign_adapter
 707    --------------- assign_control_domain
 708    --------------- assign_domain
 709    --------------- matrix
 710    --------------- unassign_adapter
 711    --------------- unassign_control_domain
 712    --------------- unassign_domain
 713
 714    ------------ [$uuid2]
 715    --------------- assign_adapter
 716    --------------- assign_control_domain
 717    --------------- assign_domain
 718    --------------- matrix
 719    --------------- unassign_adapter
 720    ----------------unassign_control_domain
 721    ----------------unassign_domain
 722
 723    ------------ [$uuid3]
 724    --------------- assign_adapter
 725    --------------- assign_control_domain
 726    --------------- assign_domain
 727    --------------- matrix
 728    --------------- unassign_adapter
 729    ----------------unassign_control_domain
 730    ----------------unassign_domain
 731
 732 4. The administrator now needs to configure the matrixes for the mediated
 733    devices $uuid1 (for Guest1), $uuid2 (for Guest2) and $uuid3 (for Guest3).
 734
 735    This is how the matrix is configured for Guest1:
 736
 737       echo 5 > assign_adapter
 738       echo 6 > assign_adapter
 739       echo 4 > assign_domain
 740       echo 0xab > assign_domain
 741
 742       Control domains can similarly be assigned using the assign_control_domain
 743       sysfs file.
 744
 745       If a mistake is made configuring an adapter, domain or control domain,
 746       you can use the unassign_xxx interfaces to unassign the adapter, domain or
 747       control domain.
 748
 749       To display the matrix configuration for Guest1:
 750
 751          cat matrix
 752
 753          The output will display the APQNs in the format xx.yyyy, where xx is
 754          the adapter number and yyyy is the domain number. The output for Guest1
 755          will look like this:
 756
 757          05.0004
 758          05.00ab
 759          06.0004
 760          06.00ab
 761
 762    This is how the matrix is configured for Guest2:
 763
 764       echo 5 > assign_adapter
 765       echo 0x47 > assign_domain
 766       echo 0xff > assign_domain
 767
 768    This is how the matrix is configured for Guest3:
 769
 770       echo 6 > assign_adapter
 771       echo 0x47 > assign_domain
 772       echo 0xff > assign_domain
 773
 774 5. Start Guest1:
 775
 776    /usr/bin/qemu-system-s390x ... -cpu host,ap=on,apqci=on,apft=on \
 777       -device vfio-ap,sysfsdev=/sys/devices/vfio_ap/matrix/$uuid1 ...
 778
 779 7. Start Guest2:
 780
 781    /usr/bin/qemu-system-s390x ... -cpu host,ap=on,apqci=on,apft=on \
 782       -device vfio-ap,sysfsdev=/sys/devices/vfio_ap/matrix/$uuid2 ...
 783
 784 7. Start Guest3:
 785
 786    /usr/bin/qemu-system-s390x ... -cpu host,ap=on,apqci=on,apft=on \
 787       -device vfio-ap,sysfsdev=/sys/devices/vfio_ap/matrix/$uuid3 ...
 788
 789 When the guest is shut down, the mediated matrix devices may be removed.
 790
 791 Using our example again, to remove the mediated matrix device $uuid1:
 792
 793    /sys/devices/vfio_ap/matrix/
 794       --- [mdev_supported_types]
 795       ------ [vfio_ap-passthrough]
 796       --------- [devices]
 797       ------------ [$uuid1]
 798       --------------- remove
 799
 800
 801    echo 1 > remove
 802
 803    This will remove all of the mdev matrix device's sysfs structures including
 804    the mdev device itself. To recreate and reconfigure the mdev matrix device,
 805    all of the steps starting with step 3 will have to be performed again. Note
 806    that the remove will fail if a guest using the mdev is still running.
 807
 808    It is not necessary to remove an mdev matrix device, but one may want to
 809    remove it if no guest will use it during the remaining lifetime of the linux
 810    host. If the mdev matrix device is removed, one may want to also reconfigure
 811    the pool of adapters and queues reserved for use by the default drivers.
 812
 813 Limitations
 814 ===========
 815 * The KVM/kernel interfaces do not provide a way to prevent restoring an APQN
 816   to the default drivers pool of a queue that is still assigned to a mediated
 817   device in use by a guest. It is incumbent upon the administrator to
 818   ensure there is no mediated device in use by a guest to which the APQN is
 819   assigned lest the host be given access to the private data of the AP queue
 820   device, such as a private key configured specifically for the guest.
 821
 822 * Dynamically modifying the AP matrix for a running guest (which would amount to
 823   hot(un)plug of AP devices for the guest) is currently not supported
 824
 825 * Live guest migration is not supported for guests using AP devices.