Extensible Host Controller Adapter Device Driver
Purpose
Supports the Universal Serial Bus (USB) 3.0 Extensible Host Controller Interface (xHCI) specification for adapter device drivers.
Syntax
#include <sys/hcdi.h>
#include <sys/usbdi.h>
#include <sys/usb.h>Description
The /dev/usbhcn special files provide interfaces that allow access to the USB host controller adapter devices. These files manage the adapter resources so that multiple USB client drivers and the USB system (or the protocol driver) can access the USB devices on the same USB host controller adapter simultaneously.
The AIX® operating system supports the USB host controllers with various interface architectures, such as the Open Host Controller Interface (OHCI) and the Enhanced Host Controller Interface (EHCI). The binary interface to the USB 3.0 adapters is called the Extensible Host Controller Interface (xHCI). The AIX operating system currently supports the 0.96 and 1.0 versions of the xHCI specification. The xHCI specification defines a new host controller architecture that replaces the existing OHCI or EHCI specification and also extends to new specifications, for example, USB Version 3.0, or later.
The /usr/lib/drivers/pci/xhcidd device driver handles the xHCI adapters and the /usr/lib/methods/cfgxhci device driver is the corresponding AIX configuration method.
The max_slots Object Data Manager (ODM)
attribute for the adapter driver specifies the maximum number of USB
devices that are supported by an xHCI adapter. The default value of
the attribute is 8. You can modify this value to a maximum value of
32 to support more devices.
max_slots values
is set to 8 and if you connect more than 8 USB devices to the USB
adapter, the adapter configures only 8 devices. The configuration
for the remaining device fails.Adapter device driver entry point subroutines
The
USB adapter device driver supports only the open, close, ioctl,
and config entry points. The read and write entry
points are not supported.
open and close subroutines
The open subroutine
associates the device number, which is specified as a parameter to
the open system call, with the internal adapter device
structure. If the open subroutine finds an adapter
structure, it verifies that the corresponding adapter device is configured
and is not marked inactive. If the open subroutine
does not find an adapter structure, it returns an error. If the Enhanced
Error Handling (EEH) feature is enabled, the open subroutine
prevents access to the device when an EEH event is being processed.
ioctl subroutine
ioctl suboperation:
| Operation | Description |
|---|---|
| HCD_REGISTER_HC | Registers the call vectors between the USB system (or the protocol driver) and the host controller driver. After the call vectors are registered, all further communication between the USB system (or protocol driver) and the host controller driver is handled by these vectors. |
Summary of error conditions returned by the xHCI adapter device driver
The following Transfer Request Block (TRB) completion status codes are returned by the xHCI during status update if the associated error condition is detected. The TRB status values are specified in the xHCI specification. These completion codes in turn are mapped to the following USBstatus values:
| TRB status | USBstatus value | Description |
|---|---|---|
| XHCI_TRB_STATUS_BAB_DET_ERR | USBD_STALL | Babbling during transaction |
| XHCI_TRB_STATUS_BW_ERR | USBD_ERROR | Bandwidth is not available for periodic endpoint connection |
| XHCI_TRB_STATUS_BW_OVERRUN_ERR | USBD_ERROR | Isochronous transfer descriptor (TD) exceeded bandwidth of the endpoints |
| XHCI_TRB_STATUS_CMDRING_ABORT_ERR | USBD_ERROR | Command abort operation |
| XHCI_TRB_STATUS_CMDRING_STOP_ERR | USBD_ERROR | Command ring stopped |
| XHCI_TRB_STATUS_CTXT_STATE_ERR | USBD_ERROR | Invalid context state change command |
| XHCI_TRB_STATUS_DATA_BUF_ERR | USBD_ERROR | Overrun or underrun |
| XHCI_TRB_STATUS_EP_NE_ERR | USBD_ERROR | Endpoint is in a disabled state |
| XHCI_TRB_STATUS_EVENT_LOST_ERR | USBD_ERROR | Internal event overrun |
| XHCI_TRB_STATUS_EVTRING_FULL_ERR | USBD_ERROR | Event ring is full |
| XHCI_TRB_STATUS_INCOMPAT_DEV_ERR | USBD_ERROR | Incompatible device |
| XHCI_TRB_STATUS_INVALID | USBD_ERROR | Completion update error |
| XHCI_TRB_STATUS_INVALID_SID_ERR | USBD_ERROR | Invalid stream ID |
| XHCI_TRB_STATUS_INVALID_STR_TYP_ERR | USBD_ERROR | Invalid stream of context (Ctxt)
type |
| XHCI_TRB_STATUS_ISOCH_BUF_OVR_ERR | USBD_ERROR | Isochronous buffer overrun |
| XHCI_TRB_STATUS_MAXEL_LARGE_ERR | USBD_ERROR | Maximum exit latency is too large |
| XHCI_TRB_STATUS_MIS_SERV_ERR | USBD_ERROR | Isochronous endpoint is not serviced |
| XHCI_TRB_STATUS_NOPING_RESP_ERR | USBD_ERROR | No ping response within endpoint service interval time (ESIT) |
| XHCI_TRB_STATUS_NOSLOTS_ERR | USBD_ERROR | Exceeded maximum slots |
| XHCI_TRB_STATUS_PARAM_ERR | USBD_ERROR | Context parameter is invalid |
| XHCI_TRB_STATUS_RESOURCE_ERR | USBD_ERROR | No adequate resources |
| XHCI_TRB_STATUS_RING_OVERRUN_ERR | USBD_ERROR | Ring overrun |
| XHCI_TRB_STATUS_RING_UNDERRUN_ERR | USBD_ERROR | Ring underrun |
| XHCI_TRB_STATUS_SEC_BW_ERR | USBD_ERROR | Secondary bandwidth error |
| XHCI_TRB_STATUS_SHORT_PKT_ERR | USBD_SUCCESSS | The packet size is lesser than the transfer descriptor size in the transfer request. |
| XHCI_TRB_STATUS_SLOT_DISABLED_ERR | USBD_ERROR | Slot is in a disabled state |
| XHCI_TRB_STATUS_SPLIT_TR_ERR | USBD_ERROR | Split transaction error |
| XHCI_TRB_STATUS_STALL_ERR | USBD_STALL | Delay detected on TRB |
| XHCI_TRB_STATUS_STOP_LEN_ERR | USBD_ERROR | Transfer event length is invalid |
| XHCI_TRB_STATUS_STOPPED_ERR | USBD_ERROR | Stop endpoint command is received |
| XHCI_TRB_STATUS_SUCCESS | USBD_SUCCESS | Command success |
| XHCI_TRB_STATUS_TRB_ERR | USBD_ERROR | TRB parameter error |
| XHCI_TRB_STATUS_UNDEFINED_ERR | USBD_ERROR | Undefined error condition |
| XHCI_TRB_STATUS_USB_TSX_ERR | USBD_ERROR | No valid response from the device |
| XHCI_TRB_STATUS_VF_EVTRING_FULL_ERR | USBD_ERROR | Virtual Function (VF) event ring is full |
Call vectors
Whenever the USB configuration
method is run, it opens the /dev/usb0 USB system
driver (USBD) special file and attempts to register each detected
and available USB host controller with the USBD by using a USBD_REGISTER_HC ioctl operation.
When the USBD_REGISTER_HC ioctl operation
is processed, the USBD opens the host controller driver and requests
for the registration of call vectors stored within the host controller
driver by using an HCD_REGISTER_HC ioctl operation.
After the call vectors are registered with the USBD, all further communication
between the USBD and the host controller driver is handled by the
call vectors. The summary of call vectors follows:
| Call vector | Description |
|---|---|
| hcdConfigPipes | This call vector is provided by the USBD during
the enumeration of USB logical device. This call vector supports the xHCD with USBD, however it does not support EHCI or OHCI drivers. It issues a configure endpoint command to the USB device to make the non-control endpoints on the device operational. This call vector is called by the USBD after the configuration selection is complete on the USB device. |
| hcdDevAlloc | Detects the attachment of a USB logical device.
This call vector is provided by the USBD. This call vector supports the Extensible Host Controller Driver (xHCD) with USBD, however it does not support EHCI or OHCI drivers. It enables the slot, sets the USB device address, and allocates the HCD driver resources to use the USB device. It returns the USB address value to the USBD. After this call, the default control endpoint on the USB device is enabled to query the USB protocol-specific data. |
| hcdDevFree | Detects the removal of a USB logical device.
This call vector is provided by the USBD. This call vector supports
the xHCD with USBD, however it does not support EHCI or OHCI drivers.
It disables the slot and also deallocates the resources that are allocated
by the |
| hcdGetFrame | Obtains the current frame number from the connected host controller. This call vector is provided by the USBD. |
| hcdPipeAbort | Cancels the processing of an I/O buffer. The
pipe that is specified by the I/O buffer is already halted before
the hcdPipeAbort call vector is called. This call
vector is provided by the USBD. |
| hcdPipeAddIOB | Increases the maximum number of outstanding I/O buffers. This call vector is provided by the USBD. |
| hcdPipeClear | Clears, unhalts, and restarts the I/O operations on a specific endpoint. When this call vector is called, the function checks whether the ring is in the halted state. |
| hcdPipeConnect | Creates a pipe connection to an endpoint on a specific USB device. |
| hcdPipeDisconnect | Removes the previously established pipe connection with the endpoint on a specific USB device. |
| hcdPipeHalt | Halts a pipe from the perspective of the host controller. All pending I/O operations remain in a pending state. This call vector is provided by the USBD. |
| hcdPipeIO | Performs the I/O operations on the USB device. The I/O operations can be of the following transfer types: control, bulk, isochronous, and interrupt. |
| hcdPipeResetToggle | Resets the data synchronization toggle bit to DATA0.
This call vector is provided by the USBD. |
| hcdPipeStatus | Obtains the status of the pipe from the host perspective. This call vector is provided by the USBD. |
| hcdShutdownComplete | Informs the host controller driver that the usbdReqHCshutdown request
is completed. This call vector is provided by the USBD. |
| hcdUnconfigPipes | Detects that a device is removed from the system.
This call vector is provided by the USBD. This call vector supports
the xHCD with USBD, however it does not support EHCI or OHCI drivers.
It issues a configure endpoint command with the |
| hcdUnregisterHC | Unregisters a host controller from the USBD. |
| usbdBusMap | Maps the memory for bus mastering. This call vector is provided by the xHCD. |
| usbdPostIOB | Retires an I/O buffer. This call vector is provided by the adapter driver. |
| usbdReqHCrestart | This call is provided when an error is detected with the adapter and the recovery of adapter driver from this error requires you to restart the adapter. |
| usbdReqHCshutdown | This call vector is provided during the removal of host controller. |
| usbdReqHCunregister | The CFG TERM function of the
adapter driver requests the USBD to unregister the host controller.
This call vector is provided during the removal of the host controller. |