USBLIBDD Passthru Driver

Purpose

Supports the application drivers that are written by using the libusb APIs.

Syntax

#include <usbdi.h>
#include <usb.h>

Description

The libusb passthru driver is the layer between the user-level application driver and the USB protocol driver (USBD). The /dev/usblibdevX special file provides interface to libusb applications to communicate directly with the device through the passthru driver. The passthru driver converts the libusb APIs to the USBD function vectors that interact with the appropriate Universal Serial Bus (USB) host controllers such as Open Host Controller Interface (OHCI), Enhanced Host Controller Interface (EHCI), or eXtensible Host Controller Interface (xHCI).

The libusb devices are created in the /dev file system irrespective of the presence of built-in AIX® client USB drivers. The parent for this device is the usb0 and the libusb devices that are enumerated by the /usr/lib/methods/cfgusb file.

The /usr/lib/drivers/usb/usblibdd driver implements the libusb passthru driver. The passthru driver uses the /usr/lib/methods/cfgusblibke configuration method. These devices have two Object Data Manager (ODM) attributes called usbdevice and speed. If a device belongs to standard classes such as Mass Storage, Tape, human interface device (HID), these devices are claimed by the built-in USB client driver of the AIX operating system. In such case, a libusb device is created as a pseudo device. The usbdevice attribute identifies the device of the client driver that is associated with a pseudo device. If a device belongs to other classes and if client drivers are not associated with the device, the usbdevice attribute is not valid.

For every libusb device, which has an AIX operating system built-in client driver, a new attribute that is called usbdevice is created in the ODM to identify the client driver device that is associated with the libusb device. The following example shows how the device is displayed:
# lsattr -El usblibdev0

speed    highspeed  USB Protocol Speed of Device      False

usbdevice usbms0 Actual USB Device with Client Driver False

In this example, the USB device that is connected is a flash drive, which has the AIX operating system built-in /usr/lib/drivers/usb/usbcd Mass Storage Class client driver. The device of the client driver associated with the usblibdev0 device is usbms0.

By default, this device is claimed by the built-in client driver. The same device is also claimed by the libusb passthru driver. Therefore, for one physical USB device, you have two OS devices (usbms0 and usblibdev0) located in the /dev file system after you run the configuration method of the parent device, which is USBD protocol driver.

Note: Only the built-in client driver or the libusb passthru driver can use this device at a time. You cannot run simultaneous operations on both drivers.
Use the following command to display the USB devices in this scenario:
# lsdev -C | grep usb
An output similar to the following example is displayed: 

usb0       Available       USB System Software

usbhc0     Available 00-00 PCIe2 USB 3.0 xHCI 4-Port Adapter (4c10418214109e04)

usblibdev0 Available       USB Library Interface Device

usbms0     Available 0.3   USB Mass Storage
In the this example, a USB encryption device (vendor-defined class) is connected to the AIX system. The device does not have a built-in client driver. This device is only claimed by the libusb passthru driver and only a single device is displayed. Another example to display the USB devices follows:
# lsdev -C | grep usb
An output similar to the following example is displayed: 

usb0       Available       USB System Software

usbhc0     Available 00-00 PCIe2 USB 3.0 xHCI 4-Port Adapter (4c10418214109e04)

usblibdev1 Available 0.4   USB Library Interface Device
In this example, usblibdev1 device is the encryption device of the libusb driver.

Device-dependant subroutines

The libusb passthru driver supports the following subroutines:
  • open
  • close
  • ioctl
Note: The read and write subroutines are not supported.

open and close subroutines

The open and close subroutines are not directly supported on usblibdevX devices. You can open and close subroutines by using the libusb APIs.

ioctl subroutine

The libusb driver exposes the ioctl subroutine to the libusb user environments. The libusb implementation of operating system backend use these ioctl subroutines. The ioctl subroutine acts as a pass through between the application and the protocol driver.

The following USBD ioctl operations are supported by the libusb drivers:

Table 1. USBD ioctl operations
Operations Description
USBLIB_PIPE_IO Issues I/O on the wanted endpoint through the aix_pipeio structure.
USBLIB_HALT_CLEAR Issues a request to halt an endpoint.
USBLIB_GETIRP_STATUS Read the status of the I/O request packet (IRP) that was issued.
USBLIB_SET_CONFIGURATION Issues a set configuration on a device.
USBLIB_CLAIM_INTERFACE Ensures sure that the interface is being used by the libusb passthru driver.
USBLIB_RELEASE_INTERFACE Sets the interface to alternate setting value of zero.
USBLIB_SET_ALT_INTFC Sets the alternate setting on an interface.
USBLIB_RESET_DEVICE Resets on the device.
USBLIB_ABORT_IO Aborts or cancels to the submitted I/O.
USBLIB_GET_CONFIG_DESC Issues request to read the entire configuration descriptor. If a device has X configurations, X number of total configuration descriptor is read and stored in a single buffer.

USBD error conditions

Possible errno values for the adapter device driver follow:

Table 2. USBD error conditions
Value Description
EAGAIN Indicates that the operation has been to retried.
EEXIST The device is already configured.
EINVAL An invalid parameter or the device is not opened.
EIO
  • The command failed due to an error.
  • The device driver was unable to pin code.
  • A kernel service failed or an unrecoverable I/O error occurred.
ENOCONNECT A USB bus fault occurred.
ENODEV The target device cannot be selected or is not responding.
ENOMEM The command cannot be completed because of insufficient memory.
ENXIO The requested ioctl operation is not supported by this adapter.
EPERM The caller does not have the required authority.

Non-responsive USB devices

USB devices that are associated to libusb applications on the AIX operating system might not respond on non-control endpoints. This condition might be because of default behavior of AIX USB protocol driver to send the CLEAR_FEATURE request when the USB devices are opened.
Note: The CLEAR_FEATURE request is a standard USB command to remove the halt condition on the device.
To resolve the issues associated with the non-responsive USB devices, the following attributes must be set:
PdAt class object
The Predefined Attribute (PdAt), object class contains an entry for each existing attribute for each USB device. This includes information such as interrupt levels, bus I/O address ranges, baud rates, parity settings, block sizes, and microcode file names. To initialize the PdAt class object set the following values:

            uniquetype = "generic/usbif/usblibke"
            attribute = "<vendorid>_<productid>"     
            deflt = "toggle_no"            
            values = "toggle_yes,toggle_no"        
            width = ""
            type = "R"
            generic = "U"
            rep = "sl"
            nls_index = 0
VendorId
Vendor ID of the USB device that can be obtained from the descriptor data of the USB device. VendorID must be a hexadecimal number.
ProductID
Product ID of the USB device that can be obtained from the descriptor data of the USB device. ProductID must be a hexadecimal number.
toggle_no
Indicates that the CLEAR_FEATURE request is not sent to the device during pipe initialization.
toggle_yes
Indicates the default behavior of the USB device to send the CLEAR_FEATURE request.
Note: The ODM entry must be added to each device that does not respond on non-control endpoints.
An example ODM attribute follows. This example considers the Kingston USB flash drive (DataTraveler Ultimate G2). The vendor ID of Kingston USB flash drive is 0951 and Product ID is 1656.
PdAt:
        uniquetype = "generic/usbif/usblibke"
        attribute = "0951_1656"
        deflt = "toggle_no"
        values = "toggle_yes,toggle_no"
        width = ""
        type = "R"
        generic = "U"
        rep = "sl"
        nls_index = 0

To add predefined attributes to the PdAt object class complete the following steps:

  1. Run the following command to remove a non-responsive USB device from the ODM entries.
    rmdev -Rl usb0
    The output might be similar to the following example:
    
usbms0 Defined
usblibdev0 Defined
usblibdev1 Defined
usb0 Defined
  2. Add the odm PdAt entry in to a file by using any standard file edit command such as vi.
  3. Run the following command.
    odmadd entry
    The output is not displayed.
  4. Run the following command.
    cfgmgr -l usb0
    The output is not displayed.
  5. Run the libusb application. Following example shows the execution of a USB application.
    
# ./xusb -k XXXX:YYYY
Opening device XXXX:YYYY...
found /dev/usbhc0
found 1 devices
found /dev/usbhc1
found 0 devices
found /dev/usbhc2
found 1 devices

Reading device descriptor:
            length: 18
      device class: 0
               S/N: 0
           VID:PID: XXXX:YYYY
         bcdDevice: 0303
   iMan:iProd:iSer: 1:2:0
          nb confs: 1

Reading BOS descriptor: no descriptor

Reading first configuration descriptor:
             nb interfaces: 1
              interface[0]: id = 0
interface[0].altsetting[0]: num endpoints = 1
   Class.SubClass.Protocol: 03.00.00
       endpoint[0].address: 81
           max packet size: 0008
          polling interval: 0A

Claiming interface 0...

 in aix_claim_interface

Reading string descriptors:
   String (0x01): "DeviceName"
   String (0x02): "Elitename"

Releasing interface 0...
Closing device...
  6. Run the following command to delete the PdAt entry of the non-responsive USB device: 
    odmdelete -o PdAt -q 'attribute=0951_1656 and uniquetype="generic/usbif/usblibke"'
    The output might be similar to the following example:
    0518-307 odmdelete: 1 object deleted