USBD Protocol Driver

Purpose

Supports the USB system driver (USBD) protocol.

Syntax

#include <sys/usb.h>
#include <sys/usbdi.h>
#include <sys/hubClass.h>
#include <sys/hidClass.h>

Description

The USBD protocol driver is the layer between the host controller the and client drivers. The /dev/usb0 special file provides interface to allow communication between the host controller and the client drivers. This driver is responsible for the device communication to appropriate host controller. The device connection, disconnection, and re-connection are performed at this level. There is no parent for this device and the device's CuDv entry is created by the /usr/lib/methods/startusb script that is invoked from the ConfigRules field.

The /usr/lib/drivers/usb/usbd driver implements the USB protocol and the /usr/lib/methods/cfgusb file is the usbd file's configuration method. The USB protocol driver updates the speed ODM attribute that is specific to each individual USB devices. The speed is updated when the USB devices are enumerated during the AIX® configuration.

Device-dependant subroutines

The USBD protocol driver supports only the open, close, and ioctl subroutines. The read and write subroutines are not supported.

open and close subroutines

The open subroutine associates a specific device number that is passed in as a parameter to the open system call with the internal adapter device structure. If it finds an adapter structure, it verifies that the corresponding adapter device is configured and sets the state as open. Otherwise, the subroutine returns an error.

ioctl subroutine

The ioctl operations for USBD protocol drivers are exposed to kernel and user environments.

USBD ioctl operations

The following USBD ioctl operations are exposed to kernel threads that are used to open a specific USB logical device:

  • USBD_OPEN_DEVICE
  • USBD_OPEN_DEVICE_EXT

The following USBD ioctl operations are exposed to user threads:

Operation Description
USBD_REGISTER_MULTI_HC Registers all the USB host controllers with USB system driver.
USBD_REGISTER_SINGLE_HC Registers only a single USB host controller with USB system driver.
USBD_ENUMERATE_DEVICE Gets a list of USB logical devices (excluding hubs) that are connected to a host controller.
USBD_ENUMERATE_ALL Gets a list of all the USB logical devices that are connected to a host controller. 
USBD_ENUMERATE_CFG Gets a list of USB logical devices that are connected to a host controller along with the client device selection information.
USBD_GET_DESCRIPTORS Gets standard USB descriptors for a logical device.
USBD_CFG_CLIENT_UPDATE Updates client connection information. 

Summary of USBD error conditions

Possible errno values for the adapter device driver are as follows:

Value Description
EACCES An openx subroutine was attempted to run while the adapter had one or more devices in use.
EEXIST The device is already configured.
EINVAL An invalid parameter or that the device is not opened.
EIO
  • The command failed due to an error detected.
  • 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 an insufficient amount of memory.
ENXIO The requested ioctl operation is not supported by this adapter.
EPERM The caller does not have the required authority.