AHAFS events support for adding and removing USB devices in IBM AIX
USB hotplug support
The Autonomic Health Advisor File System (AHAFS) provides event monitoring framework in IBM® AIX®. Users can monitor predefined system events and get notified about them. Each event is represented as a file in a pseudo file system (called AHAFS). The standard file APIs such as open, read, write, close, and select can be used by applications to monitor the files and retrieve the event data. The instance of the event infrastructure filesystem must be mounted to monitor the events. You can find more information about using AHAFS in the An introduction to event monitoring using the AIX Event Infrastructure article.
Hotplug and current limitation in AIX
Hotplug is the ability to detect the device dynamically as soon as it is plugged to the system. This feature is quite common in consumer systems to make it easily discoverable and usable to the user. This feature is forbidden in AIX server systems due to security reasons and the system administrator must run cfgmgr command to discover the new devices. Due to this limitation, USB devices are also not discovered and configured dynamically.
This article provides detailed steps on how to use the hotplug (plug-and-play)
feature for USB devices. By using the hotplug functionality with USB devices,
applications can use the dynamic discovery of the USB devices connected to the AIX
system without depending on the administrator to run the
Installation and configuration
The minimum AIX versions that support USB hotplug are 7.2 TL1 and 7.1 TL4 SP3.
A USB stack in AIX makes use of AHAFS (event infrastructure in AIX). The bos.ahafs file set is a prerequisite for the hotplug to work.
There are two ways to use the USB hotplug feature in AIX.
- USB device attach and detach events on an AIX system can be monitored from a MON file output. You can direct this output to a file and write your own programs to trigger the actions based on device attach and detach events.
- Poll the MON file for events and run the
cfgmgrcommand to detect the USB device and run the
rmdevcommand to remove the device on a detach event.
These two ways are explained in detail in the subsequent sections.
Method 1: Capturing USB device attach/detach events
Perform the following steps to capture the events:
- Mount AHAFS to listen to the USB device events.
#mount -v ahafs /aha /aha
/ahais not an existing directory, we can create one. This command can be run from any directory.
- Start a separate AIX shell and run following command to monitor the
attach/detach events of the USB device.
#/usr/samples/ahafs/bin/aha.pl -m /aha/usbdEvProd.monFactory/usbd.mon "CHANGED=YES;INFO_LVL=3"
A Kingston USB flash drive is disconnected from the AIX system and reconnected back while the above command was waiting for the events. It gives the following event data output:
Monitoring the AHAFS event "/aha/usbdEvProd.monFactory/usbd.mon". AHAFS event: /aha/usbdEvProd.monFactory/usbd.mon --------------------------------------------------- BEGIN_EVENT_INFO Time : Thu Oct 13 14:33:47 2016 Sequence Num : 1 RC_FROM_EVPROD=0 BEGIN_EVPROD_INFO USBDevice Disconnected VendorID=2385 ProductID=5718 PortNumber=5 DeviceAddress=1 Class=8 SubClass=6 Protocol=80 PortPath=5 HCDevno=8000000D00000000 connwhere=1.1.0 END_EVPROD_INFO END_EVENT_INFO AHAFS event: /aha/usbdEvProd.monFactory/usbd.mon --------------------------------------------------- BEGIN_EVENT_INFO Time : Thu Oct 13 14:33:52 2016 Sequence Num : 2 RC_FROM_EVPROD=0 BEGIN_EVPROD_INFO USBDevice Connected VendorID=2385 ProductID=5718 PortNumber=5 DeviceAddress=1 Class=8 SubClass=6 Protocol=80 PortPath=5 HCDevno=8000000D00000000 connwhere=1.1.0 END_EVPROD_INFO END_EVENT_INFO
usbEvProdis the event producer name which is already registered with the
monFactoryis a common extension to all the event producer names. usbd.mon is the AHAFS monitor file that subscribes to events from the kernel extension. The name of the AHAFS monitor file is user-defined.
aha.pl is the sample script to monitor a set of events listed in a file. It is installed from the bos.ahafs file set. It has multiple options to listen and subscribe to events. In this article, we are explaining only one case of printing event data to the standard output.
Refer to AIX Event Infrastructure components to find more information about AHAFS.
- Understand the event data output
The first 5 lines of the event are for informational purposes.
The USB related events start from the 6th line of an event. For example, if you unplug a USB device, the event will be shown as, Device Disconnected. If you plug a USB device, the event will be show as Device Connected.
In addition to that, the following information is displayed:
- Vendor ID: The manufacturer of the device. (see https://www.usb.org/developers/tools/comp_dump for mapping vendor ID to manufacturer).
- Product ID: The product code for the device given by the manufacturer.
- Port number: The parent device's port number to which this device is connected. The device may be connected to the system through root hub (USB adapter on the host) or external hub.
- Device Address: The address of the device assigned by the host controller.
- Class, Subclass, protocol: Information that is used to identify a device's functionality. (see https://www.usb.org/developers/defined_class to know the meaning of the class codes).
- Port Path: The
path to identify the topology of the device. If a device is connected
directly to the root hub (adapter on the host), only the port number is
- For example,
portpath = 7means that the device is connected to port 7 of the adapter (root hub) on the host.
- For example,
portpath = 7.2means that the device is connected to port 2 of an intermediate hub which in turn is connected to port 7 of the adapter (root hub) on the host.
- For example,
- HCDevno: The device number of the host controller device to which this device is connected.
- Connwhere: A combination of device address, configuration number, and interface number of the device.
In this method, the program displays only events related to USB attach and detach along with device information but does not configure or initialize the device. Users can direct this output to a file and take actions accordingly.
The subsequent example gives details about capturing the event and taking necessary action to configure and initialize the device or remove the device.
Method 2: Example to detect and configure the hotplug device
Refer to the hotplug_usb.c program (available in the Downloadable resources section) to detect the USB attach/detach events and trigger the appropriate action.
read_data(): This function reads the event data and triggers an
appropriate action based on the event. If it is an attach event, it runs the
cfgmgr command to configure and initialize the device. If it is a
detach event, it runs the
rmdev command to uninitialize and delete that
device from the system.
remove_device(): This function deletes the device by running the
rmdev command. Device name needs to be retrieved to run the
rmdev command on a device. Hence this function is called with
connwhere of the device and it gets the device name from the
libusb is enabled, the
remove_device() function also takes care of deleting the
libusb devices. For more information on
in AIX and enable/disable it, see https://www.ibm.com/support/knowledgecenter/ssw_aix_72/com.ibm.aix.files/usblibdev.htm
Perform the following steps to compile and run the program:
- Compile the program using the following flags.
#cc hotplug_usb.c -o hotplug_usb -lodm -lcfg
- Mount AHAFS and run the hotplug_usb program.
- Mount AHAFS using
the following command:
#mount -v ahafs /aha /aha
the binary in a separate shell window.
./hotplug_usb /aha/usbdEvProd.monFactory/usbd.mon "CHANGED=YES;INFO_LVL=3" 10 /tmp/nodestateevent
- Mount AHAFS using the following command:
- Plug the USB device and then unplug it to check for events. You will get events
in a new window. The output of the above command (in step 2b) is given below:
Entering select() to wait till the event corresponding to the AHA node /aha/usbdEvProd.monFactory/usbd.mon occurs. The select() completed. The event corresponding to the AHA node /aha/usbdEvProd.monFactory/usbd.mon has occurred. TIME_tvsec=1461163157 TIME_tvnsec=694334371 SEQUENCE_NUM=2 RC_FROM_EVPROD=0 BEGIN_EVPROD_INFO USBDevice Disconnected VendorID=2385 ProductID=5718 PortNumber=3 DeviceAddress=2 Class=8 SubClass=6 Protocol=80 PortPath=3 HCDevno=8000002700000000 connwhere=2.1.0 END_EVPROD_INFO END_EVENT_INFO device to be deleted: usbms0 usbms0 deleted device to be deleted : usblibdev1 usblibdev1 deleted Entering select() to wait till the event corresponding to the AHA node /aha/usbdEvProd.monFactory/usbd.mon occurs. The select() completed. The event corresponding to the AHA node /aha/usbdEvProd.monFactory/phani.mon has occurred. TIME_tvsec=1461163226 TIME_tvnsec=908116599 SEQUENCE_NUM=3 RC_FROM_EVPROD=0 BEGIN_EVPROD_INFO USBDevice Connected VendorID=1137 ProductID=18526 PortNumber=3 DeviceAddress=2 Class=3 SubClass=0 Protocol=0 PortPath=3 HCDevno=8000002600000000 connwhere=2.1.0 END_EVPROD_INFO END_EVENT_INFO New Devices configured and initialized
hotplug_usb program continuously monitors the attach/detach events.
Based on the event, it takes an appropriate action to configure the device or delete
it. The number of events that this program can take is given as input. In the above
example, the event count is 10. The even output can be redirected to a file to know
more details about the device being discovered and deleted.
/tmp/nodetstatevent is given as input to store the event data in
the above example.