Contents


AHAFS events support for adding and removing USB devices in IBM AIX

USB hotplug support

Comments

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 cfgmgr command.

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 cfgmgr command to detect the USB device and run the rmdev command 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:

  1. Mount AHAFS to listen to the USB device events.
    #mount -v ahafs /aha /aha

    If /aha is not an existing directory, we can create one. This command can be run from any directory.

  2. 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

    usbEvProd is the event producer name which is already registered with the usbd kernel extension. monFactory is 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.

  3. 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 shown.
      • For example, portpath = 7 means that the device is connected to port 7 of the adapter (root hub) on the host.
      • For example, portpath = 7.2 means 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.
    • 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 CuDv class.

Note: If libusb is enabled, the remove_device() function also takes care of deleting the libusb devices. For more information on libusb support 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:

  1. Compile the program using the following flags.
     #cc hotplug_usb.c -o hotplug_usb -lodm -lcfg
  2. Mount AHAFS and run the hotplug_usb program.
    1. Mount AHAFS using the following command:
      #mount -v ahafs /aha /aha
    2. Run the binary in a separate shell window.
                          ./hotplug_usb /aha/usbdEvProd.monFactory/usbd.mon
                          "CHANGED=YES;INFO_LVL=3" 10 /tmp/nodestateevent
  3. 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

The 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.


Downloadable resources


Comments

Sign in or register to add and subscribe to comments.

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=AIX and UNIX
ArticleID=1043776
ArticleTitle=AHAFS events support for adding and removing USB devices in IBM AIX
publish-date=03142017