Kernel parameters

6.10 LPAR mode z/VM guest KVM guest

You configure the cryptographic device driver, zcrypt, by adding parameters to the kernel parameter line.

zcrypt kernel parameter syntax

mask_specification

where

<domain_id>: is an integer that identifies the default cryptographic domain for the Linux® instance. You define cryptographic domains in the LPAR activation profile on the HMC or SE.
The default value (ap.domain=autoselect) causes the device driver to choose one of the available domains automatically.

Important: Be sure to enter an existing domain. The Trusted Key Entry (TKE) workstation does not find the cryptographic adapters if a non-existing domain is entered here. All CCA applications use the default domain, and do not work correctly if the specified domain does not exist.
ap.poll_thread=: is an integer argument and enables a polling thread to tune cryptographic performance. Valid values are 1 (enabled) or 0 (disabled, this value is the default).
Note: Regardless of this setting, the polling thread is disabled in environments where AP adapter interrupts are available.

ap.apmask= and ap.aqmask=

are two 256-bit masks that specify which AP queues are controlled by the zcrypt device driver and which are available to alternative device drivers, like vfio_ap.

If your Linux instance is a KVM host, the vfio_ap device driver controls AP queues on behalf of KVM guests. While vfio_ap is the only eligible alternative device driver, freeing an AP queue from zcrypt makes it available to vfio_ap.

Each bit of the ap.apmask= mask addresses a cryptographic adapter. The leftmost bit corresponds to the adapter with ID 0x00. Generally, the bit number in the mask corresponds to the decimal value of the adapter ID. If an adapter bit is set to 0, all AP queues for this adapter are available to alternative device drivers, across all domains.

Each bit of the ap.aqmask= mask addresses a cryptographic domain. The leftmost bit corresponds to domain 0x0000. Generally, the bit number in the mask corresponds to the decimal value of the domain ID. If a domain bit is set to 0, all AP queues with this domain are available to alternative device drivers, across all adapters.

AP queues are controlled by the zcrypt device driver if both the bit for its adapter and for its domain are set to 1. An AP queue is available to alternative device drivers if the bit for its adapter, or its domain, or both are set to 0.

By default, all bits in both masks are 1. Therefore, zcrypt is the default device driver for all AP queues.

<hex_mask>: specifies a replacement for the default mask. Valid values are 0x followed by 1 - 64 hexadecimal digits. If fewer than 64 digits are specified, the specification is padded with 0s on the right. The value is big-endian. The hexadecimal representation is mapped to the 256-digit binary mask.
<bit>: specifies an individual bit number. 0 specifies the leftmost bit. With the plus sign (+) prefix, the bit is set to 1. With the minus sign (-) prefix, the bit is set to 0.
<from_bit>-<to_bit>: specifies the range of bits from bit number <from_bit> to bit number <to_bit>. With the plus sign (+) prefix, all bits in the range are set to 1. With the minus sign (-) prefix, all bits in the range are set to 0.

Bit numbers can be in decimal or hexadecimal notation. Hexadecimal numbers must be prefixed with 0x. You can specify a comma-separated list of bits and ranges. Such lists are processed left to right.

The hexadecimal representations of the masks are available in sysfs. Using sysfs, you can change the masks on a running Linux instance, see Freeing AP queues for KVM guests.

Examples

The following kernel parameter line specification makes the zcrypt device driver operate within the default cryptographic domain 7 with ap.poll_thread= enabled:
```
ap.domain=7 ap.poll_thread=1
```
The following specification makes all AP queues on adapter 0x00 and any adapters with IDs greater than 0x07 and all AP queues with domain ID, 0x0007, 0x0008, 0x0009, 0x000a, and 0x000b available to the vfio_ap device driver.
```
ap.apmask=0x7F ap.aqmask=-7-11
```
The following specification with hexadecimal notation for the queue range is equivalent:
```
ap.apmask=0x7F ap.aqmask=-0x7-0xb
```