18.8. Attaching cryptographic coprocessors to virtual machines on IBM Z

Procédure

1. Obtain the decimal values for the devices that you want to assign to the VM. For example, for the devices 05.0004 and 05.00ab:

   # echo "obase=10; ibase=16; 04" | bc
   4
   # echo "obase=10; ibase=16; AB" | bc
   171

2. On the host, reassign the devices to the vfio-ap drivers:

   # chzdev -t ap apmask=-5 aqmask=-4,-171

   Note

   To assign the devices persistently, use the -p flag.

3. Verify that the cryptographic devices have been reassigned correctly.

   # lszcrypt -V
   
   CARD.DOMAIN TYPE  MODE        STATUS  REQUESTS  PENDING HWTYPE QDEPTH FUNCTIONS  DRIVER
   --------------------------------------------------------------------------------------------
   05          CEX5C CCA-Coproc  -              1        0     11     08 S--D--N--  cex4card
   05.0004     CEX5C CCA-Coproc  -              1        0     11     08 S--D--N--  vfio_ap
   05.00ab     CEX5C CCA-Coproc  -              1        0     11     08 S--D--N--  vfio_ap

   If the DRIVER values of the domain queues changed to vfio_ap, the reassignment succeeded.

4. Generate a device UUID.

   # uuidgen
   669d9b23-fe1b-4ecb-be08-a2fabca99b71

   In the following steps of this procedure, replace 669d9b23-fe1b-4ecb-be08-a2fabca99b71 with your generated UUID.

5. Using the UUID, create a new vfio_ap device.

   The following example shows creating a persistent mediated device and assigning queues to it. For example, the following commands assign domain adapter 0x05 and domain queues 0x0004 and 0x00ab to device 669d9b23-fe1b-4ecb-be08-a2fabca99b71.

   # mdevctl define --uuid 669d9b23-fe1b-4ecb-be08-a2fabca99b71 --parent matrix --type vfio_ap-passthrough
   # mdevctl modify --uuid 669d9b23-fe1b-4ecb-be08-a2fabca99b71 --addattr=assign_adapter --value=0x05
   # mdevctl modify --uuid 669d9b23-fe1b-4ecb-be08-a2fabca99b71 --addattr=assign_domain --value=0x0004
   # mdevctl modify --uuid 669d9b23-fe1b-4ecb-be08-a2fabca99b71 --addattr=assign_domain --value=0x00ab

6. Start the mediated device.

   # mdevctl start --uuid 669d9b23-fe1b-4ecb-be08-a2fabca99b71

7. Check that the configuration has been applied correctly

   # cat /sys/devices/vfio_ap/matrix/mdev_supported_types/vfio_ap-passthrough/devices/669d9b23-fe1b-4ecb-be08-a2fabca99b71/matrix
   05.0004
   05.00ab

   If the output contains the numerical values of queues that you have previously assigned to vfio-ap, the process was successful.

8. Attach the mediated device to the VM.

   1. Create and open an XML file for the cryptographic card mediated device. For example:

      # vim crypto-dev.xml

   2. Add the following lines to the file and save it:

      <hostdev mode='subsystem' type='mdev' managed='no' model='vfio-ap'>
        <source>
          <address uuid='669d9b23-fe1b-4ecb-be08-a2fabca99b71'/>
        </source>
      </hostdev>

   3. Use the XML file to attach the mediated device to the VM. For example, to permanently attach a device defined in the crypto-dev.xml file to the running testguest1 VM:

      # virsh attach-device testguest1 crypto-dev.xml --live --config

      The --live option attaches the device to a running VM only, without persistence between boots. The --config option makes the configuration changes persistent. You can use the --config option alone to attach the device to a shut-down VM.

      Note that each UUID can only be assigned to one VM at a time.

9. Assign the required control domains to the mediated device.

   # mdevctl modify --uuid 669d9b23-fe1b-4ecb-be08-a2fabca99b71 --addattr=assign_control_domain --value=0x00ab
   # mdevctl modify --uuid 669d9b23-fe1b-4ecb-be08-a2fabca99b71 --addattr=assign_control_domain --value=0x0004

Vérification

1. Ensure that the guest operating system detects the assigned cryptographic devices.

   # lszcrypt -V
   
   CARD.DOMAIN TYPE  MODE        STATUS  REQUESTS  PENDING HWTYPE QDEPTH FUNCTIONS  DRIVER
   --------------------------------------------------------------------------------------------
   05          CEX5C CCA-Coproc  online         1        0     11     08 S--D--N--  cex4card
   05.0004     CEX5C CCA-Coproc  online         1        0     11     08 S--D--N--  cex4queue
   05.00ab     CEX5C CCA-Coproc  online         1        0     11     08 S--D--N--  cex4queue

   The output of this command in the guest operating system will be identical to that on a host logical partition with the same cryptographic coprocessor devices available.

2. In the guest operating system, confirm that a control domain has been successfully assigned to the cryptographic devices.

   # lszcrypt -d C
   
   DOMAIN 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f
   ------------------------------------------------------
       00  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
       10  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
       20  .  .  .  .  .  .  .  .  .  .  .  B  .  .  .  .
       30  .  .  B  B  .  .  .  .  .  .  .  .  .  .  .  .
       40  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
       50  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
       60  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
       70  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
       80  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
       90  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
       a0  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
       b0  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
       c0  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
       d0  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
       e0  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
       f0  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
   ------------------------------------------------------

   If lszcrypt -d C displays B intersections in the cryptographic device matrix, the control domain assignment was successful.