AP bus and zcrypt uevents

SUSE Linux Enterprise Server 15 SP5 LPAR mode z/VM guest KVM guest

The AP bus and the zcrypt device driver generate uevents.

Application programmers: This information is intended for programmers or system administrators who want to act on changes related to the cryptographic adapters. For example, this information is helpful when writing a udev rule to unlock an encrypted device with a key that depends on a specific cryptographic resource.

Table 1 summarizes the uevents that are generated by the AP bus, and Table 2 those that are generated by the zcrypt device driver. The uevents include one or more zcrypt-specific properties, see Properties.

Table 1. AP bus uevents
Uevent Example
An ADD uevent is generated for each cryptographic adapter when the AP card device struct is registered at the Linux® device model. 
KERNEL[133.856730] add          /devices/ap/card00 (ap)
ACTION=add
DEVPATH=/devices/ap/card00
SUBSYSTEM=ap
DEVTYPE=ap_card
DEV_TYPE=000C
MODALIAS=ap:t0C
MODE=accel
SEQNUM=14752
An ADD uevent is generated for each AP queue when the AP queue device struct is registered at the Linux device model. 
KERNEL[133.856916] add          /devices/ap/card00/00.0011 (ap)
ACTION=add
DEVPATH=/devices/ap/card00/00.0011
SUBSYSTEM=ap
DEVTYPE=ap_queue
MODE=accel
SEQNUM=14753
A BIND uevent is generated for each cryptographic adapter when the AP card device is bound to a device driver. 
KERNEL[133.889983] bind        /devices/ap/card00 (ap)
ACTION=bind
DEVPATH=/devices/ap/card00
SUBSYSTEM=ap
DEVTYPE=ap_card
DRIVER=cex4card
DEV_TYPE=000C
MODALIAS=ap:t0C
MODE=accel
SEQNUM=14801
A BIND uevent is generated for each AP queue when the AP queue device is bound to a device driver. 
KERNEL[133.894060] bind         /devices/ap/card00/00.0011 (ap)
ACTION=bind
DEVPATH=/devices/ap/card00/00.0011
SUBSYSTEM=ap
DEVTYPE=ap_queue
DRIVER=cex4queue
MODE=accel
SEQNUM=14818
A CHANGE uevent is generated when the first AP bus scan is complete. This uevent indicates that all AP devices have been detected and are represented in sysfs.

The AP devices might still require bindings to the appropriate zcrypt device drivers to become usable to user space.

 
KERNEL[133.888562] change        /devices/ap (ap)
ACTION=change
DEVPATH=/devices/ap
SUBSYSTEM=ap
INITSCAN=done
SEQNUM=14800
A CHANGE uevent is generated when all AP devices are bound to device drivers.

This event can recur, for example, in response to user space actions that change driver bindings through unbind or rebind. The uevent is then generated when all device driver bindings are, again, complete.

The COMPLETECOUNT property shows how often this uevent has occurred.

 
KERNEL[133.899708] change        /devices/ap (ap)
ACTION=change
DEVPATH=/devices/ap
SUBSYSTEM=ap
BINDINGS=complete
COMPLETECOUNT=1
SEQNUM=14849
An UNBIND uevent is generated for each cryptographic adapter when the AP card device is unbound from its device driver. 
KERNEL[1915.351494] unbind        /devices/ap/card00 (ap)
ACTION=unbind
DEVPATH=/devices/ap/card00
SUBSYSTEM=ap
DEVTYPE=ap_card
DEV_TYPE=000C
MODE=accel
SEQNUM=14930
An UNBIND uevent is generated for each AP queue when the AP queue device is unbound from its device driver. 
KERNEL[11648.474687] unbind        /devices/ap/card0a/0a.0036 (ap)
ACTION=unbind
DEVPATH=/devices/ap/card0a/0a.0036
SUBSYSTEM=ap
DEVTYPE=ap_queue
MODE=ep11
SEQNUM=14865
A REMOVE uevent is generated for each cryptographic adapter when the AP card device struct is unregistered at the Linux device model. 
KERNEL[3193.308746] remove         /devices/ap/card02 (ap)
ACTION=remove
DEVPATH=/devices/ap/card02
SUBSYSTEM=ap
DEVTYPE=ap_card
DEV_TYPE=000C
MODALIAS=ap:t0C
MODE=cca
SEQNUM=14936
A REMOVE uevent is generated for each AP queue when the AP queue device struct is unregistered at the Linux device model. 
KERNEL[3193.308372] remove         /devices/ap/card02/02.0036 (ap)
ACTION=remove
DEVPATH=/devices/ap/card02/02.0036
SUBSYSTEM=ap
DEVTYPE=ap_queue
DEV_TYPE=000C
MODALIAS=ap:t0C
MODE=ep11
SEQNUM=14934
A CHANGE uevent is generated for each cryptographic adapter when the configuration state of the adapter changes.

The configuration state can change when the adapter is switched between Candidate and Candidate and Online on the SE panel that shows the cryptographic resources of an LPAR.

The configuration state can also be changed from Linux, see AP queue status overview.

The property field CONFIG shows the new configuration state of the adapter (0 or 1).

 
KERNEL[89.321715] change         /devices/ap/card0f (ap)
ACTION=change
DEVPATH=/devices/ap/card0f
SUBSYSTEM=ap
CONFIG=1
DEVTYPE=ap_card
DRIVER=cex4card
DEV_TYPE=000D
MODALIAS=ap:t0D
MODE=cca
SEQNUM=14949
A CHANGE uevent is generated for each AP queue when the configuration state of the adapter changes. The property field CONFIG shows the new configuration state of the queue (0 or 1). 
KERNEL[89.358270] change          /devices/ap/card0f/0f.0011 (ap)
ACTION=change
DEVPATH=/devices/ap/card0f/0f.0011
SUBSYSTEM=ap
CONFIG=0
DEVTYPE=ap_queue
DRIVER=cex4queue
MODE=cca
SEQNUM=14950
Table 2. zcrypt device driver uevents
Uevent Example
A CHANGE uevent is generated when the online state, within Linux, of a cryptographic adapter changes.

The online state can be changed through the online sysfs attribute of the card device.

An adapter can also be set offline in response to failures being detected within the zcrypt device driver.

The property field ONLINE shows the new online state of the adapter (0 or 1).

 
KERNEL[1463.711604] change         /devices/ap/card0f (ap)
ACTION=change
DEVPATH=/devices/ap/card0f
SUBSYSTEM=ap
ONLINE=0
DEVTYPE=ap_card
DRIVER=cex4card
DEV_TYPE=000D
MODALIAS=ap:t0D
MODE=cca
SEQNUM=14955
A CHANGE uevent is generated when the online state, within Linux, of an AP queue changes.

The online state can be changed through the online sysfs attribute of the AP queue device.

An AP queue can also be set offline in response to failures being detected within the zcrypt device driver.

The property field ONLINE shows the new online state of the AP queue (0 or 1).

 
KERNEL[1463.712387] change         /devices/ap/card0f/0f.0036 (ap)
ACTION=change
DEVPATH=/devices/ap/card0f/0f.0036
SUBSYSTEM=ap
ONLINE=1
DEVTYPE=ap_queue
DRIVER=cex4queue
MODE=cca
SEQNUM=14957

Properties

The following properties are specific to zcrypt:
COMPLETECOUNT
The bindings complete counter. For the first bindings complete uevent its value is 1. The value is then incremented with each subsequent bindings complete uevent.
CONFIG
The new configuration state, 0 or 1, for an adapter or AP queue.
DEVPATH
The path to the device representation in sysfs. This path does not include the sysfs mount point, which is usually /sys.
DEVTYPE
Indicates whether the uevent is for an adapter (ap_card) or for an AP queue (ap_queue).
DEV_TYPE
The device type as a 4-digit hexadecimal value.
DRIVER
The device driver module that is bound to or unbound from the AP device, for example, cex4card, cex4queue, or vfio_ap.
INITSCAN
Indication that the initial AP bus scan is complete. The value is always done.
MODALIAS: ap:t<xx>
The module alias of the AP device, where <xx> is a two-digit hexadecimal value for the mapped device type.
MODE
The mode of operation of the adapter or AP queue:
accel
for cryptographic accelerator mode.
ep11
for EP11 coprocessor mode.
cca
for CCA coprocessor mode.
ONLINE
The online state, within Linux, of the adapter or AP queue.
SUBSYSTEM
Identifier for the AP subsystem. The value is always ap.