Displaying information about cryptographic devices and AP queues

6.10 LPAR mode z/VM guest KVM guest

Use the lszcrypt command to display status information about your cryptographic devices and AP queues; alternatively, you can use sysfs.

About this task

For information about lszcrypt, see lszcrypt - Display cryptographic devices.

Each cryptographic adapter is represented in sysfs as a device with a directory of the form

/sys/bus/ap/devices/card<XX>

where <XX> is the two-digit hexadecimal device index for each device. For example, device 0x1a can be found under /sys/bus/ap/devices/card1a. The sysfs directory contains a number of attributes with information about the AP queue.

Table 1. Cryptographic adapter attributes
Attribute	Explanation
ap_functions	Read-only attribute that represents the function facilities that are installed on this adapter.
API_ordinalnr	EP11 coprocessors only: Read-only attribute that displays the EP11 adapter's firmware API ordinal number.
chkstop	Read-only attribute that is 1 if the adapter is in checkstop state and 0 otherwise. In checkstop state, the adapter is not available for processing cryptographic requests.
config	Read-write attribute that represents the LPAR configuration status for this adapter, see Setting the LPAR configuration status.
depth	Read-only attribute that represents the input queue length for this adapter.
FW_version	EP11 coprocessors only: Read-only attribute that shows the major and minor firmware version in the format: `<major_version>.<minor_version>`
hwtype	Read-only attribute the represents the numeric hardware type as interpreted by the device driver. The following values are defined: 10 CEX4A, CEX4C, or CEX4P adapters. 11 CEX5A, CEX5C, or CEX5P adapters. 12 CEX6A, CEX6C, or CEX6P adapters. 13 CEX7A, CEX7C, or CEX7P adapters. 14 CEX8A, CEX8C, or CEX8P adapters. The `hwtype` attribute shows the hardware type as interpreted by the device driver. See also the raw_hwtype attribute.
raw_hwtype	Read-only attribute that represents the actual hardware type of the cryptographic adapter.
max_msg_size	Read-only attribute that shows the upper limit, in bytes, for requests and replies that are send to and received from this adapter. The AP bus and zcrypt device driver assign a request to an AP queue only if the request is within the upper limit of the queue's adapter. A request fails with ENODEV if no suitable adapter is available. A request fails with EMSGSIZE if the request size is within the limit, but the response exceeds it. The upper limit for CEX7A, CEX7C, CEX7P, and earlier adapters is 12288 bytes (12 KB).
modalias	Read-only attribute that represents an internally used device bus-ID.
online	Read-write attribute that shows whether the device is online (1) or offline (0).
op_modes	EP11 coprocessors only: Read-only attribute that shows the adapter's enabled modes of operation. Enabled modes are always listed on a single line, with multiple modes separated by spaces. The line is empty if no known mode is enabled.
pendingq_count	Read-only attribute that represents the number of requests in the hardware queue.
request_count	Read-only attribute that represents the number of requests that are already processed by this device.
requestq_count	Read-only attribute that represents the number of outstanding requests (not including the requests in the hardware queue).
serialnr	For CCA and EP11 coprocessors only: Read-only attribute that shows the adapter serial number. The serial number is a unique ASCII string of 8 characters for CCA coprocessors and 16-characters for EP11 coprocessors.
type	Read-only attribute with a name for the device type. The following types are defined: CEX4A, CEX4C, CEX4P CEX5A, CEX5C, CEX5P CEX6A, CEX6C, CEX6P CEX7A, CEX7C, CEX7P CEX8A, CEX8C, CEX8P

Each AP queue is independently configurable and represented in a subdirectory of the cryptographic device it belongs to:

/sys/bus/ap/devices/card<XX>/<XX>.<YYYY>

where <XX> is the adapter ID of the cryptographic device and <YYYY> is the domain. For example, a cryptographic device with adapter ID 1a might have domains 5 (0005), 31 (001f), and 77 (004d) configured. The cryptographic device together with its AP queues would be represented in sysfs as:

/sys/devices/ap/card1a   
/sys/devices/ap/card1a/1a.0005
/sys/devices/ap/card1a/1a.001f
/sys/devices/ap/card1a/1a.004d

Actions that you take on the cryptographic device also apply to its associated AP queues. Attributes like type and hwtype are inherited by the AP queues. The sysfs directory contains a number of attributes with information about the AP queues.

Table 2. Attributes of the AP queues
Attribute	Explanation
ap_functions	Read-only attribute that represents the function facilities that are available on this AP queue. Bits 16 and 17 describe the binding and association state of the queue inside a KVM guest that is running in secure-execution mode.
chkstop	Read-only attribute that is 1 if the queue is in checkstop state and 0 otherwise. In checkstop state, no requests are sent to the AP queue. The queue is reset when it exits the checkstop state.
config	Read-only attribute that shows the LPAR configuration status of the AP queue, as configured (1) or not configured (0). The configuration status of an AP queue matches the configuration status of its cryptographic adapter.
online	Read-write attribute that shows whether the AP queue is online (1) or offline (0).
interrupt	Read-only attribute that represents the interrupt state (enabled or disabled) of the AP queue, and hence the request queue.
mkvps	Read-only attribute with multiple lines of information about the master key states and verification patterns for CCA or EP11 coprocessors. See Investigating master key states and verification patterns.
op_modes	EP11 coprocessors only: Read-only attribute that shows the adapter's enabled modes of operation. Enabled modes are always listed on a single line, with multiple modes separated by spaces. The line is empty if no known mode is enabled.
reset	Read-only attribute that indicate the state of pending resets of the AP queues, and hence the request queue.
pendingq_count	Read-only attribute that represents the number of requests in the hardware queue.
request_count	Read-only attribute that represents the number of requests that are already processed by this AP queue.
requestq_count	Read-only attribute that represents the number of outstanding requests (not including the requests in the hardware queue).
se_associate	Read-write attribute that is available for KVM guests running in secure-execution mode only: Reading from this attribute gives the association state of this AP queue. Writing an integer to this attribute triggers an asynchronous operation to associate this AP queue with the secret referred to by the given index. For more details about associating an AP queue, see Introducing IBM® Secure Execution for Linux, SC34-7721.
se_bind	Read-write attribute that is available for KVM guests running in secure-execution mode only: Reading from this attribute gives the state of the binding of this AP queue. Writing 1 to this attribute triggers a synchronous operation to bind this AP queue to this guest. Writing 0 to this attribute initiates an unbind of the AP queue for this guest. For more details about binding an AP queue, see Introducing IBM Secure Execution for Linux, SC34-7721.

To display status information about your cryptographic devices and AP queues, you can also use the lszcrypt command (see lszcrypt - Display cryptographic devices).