Enhanced Host Controller Adapter Device Driver
Purpose
Supports the Enhanced Host Controller Interface (EHCI) 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 Universal Serial Bus (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.
In the USB
2.0 design, the USB Implementers Forum (USB-IF) implemented single
specification, which is known as EHCI, that supports only high-speed
data transfers. EHCI-based adapters are multi-function Peripheral
Component Interconnect (PCI) devices that consist of virtual host
controller functions that are called companion controllers to support
Open Host Controller Interface (OHCI) connectivity to USB 1.0 and
1.1 devices. The Object Data Manager (ODM) alt_usb_ctrl attribute
of the EHCI adapter provides the location values for the companion
OHCI controllers.
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
does not access the device when an EEH event is being processed.
ioctl subroutine
ioctl suboperations:
| 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 the protocol driver) and the host controller driver is handled by these vectors. |
| HCD_REQUEST_COMPANIONS | Requests port routing information about the companion OHCI host controllers. |
Summary of error conditions returned by the EHCI adapter device driver
Possible values of the USBstatus return value for the EHCI adapter device driver are as follows:
| Error code | Description |
|---|---|
| USBD_ABORTED | The associated IRP has ended. |
| USBD_ABORTING | The associated I/O request packet (IRP) is failing. |
| USBD_ACTIVE | The logical pipe is in operation and is not halted. |
| USBD_BADHANDLE | The handle that is passed as parameter through the call vector interface is invalid. |
| USBD_BANDWIDTH | The logical pipe connection has failed because of bandwidth requirements. |
| USBD_CONNECT | The logical pipe is already connected. |
| USBD_DATA | Invalid response from the device. |
| USBD_DISCONNECT | The device that is associated with the transaction is disconnected or removed. |
| USBD_ERROR | General error condition. |
| USBD_HALTED | The logical pipe that is associated with the transaction is halted. |
| USBD_POWER | The device exceeded power budget. |
| USBD_SPEED | The port reset operation has failed because of device speed mismatch. |
| USBD_STALL | The logical pipe that is associated with the transaction is delayed. |
| USBD_TIMEOUT | The I/O operation has timed out. |
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 that are 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 |
|---|---|
| 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 the 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 perspective of the host controller. 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. |
| hcdUnregisterHC | Unregisters a host controller from the USBD. |
| usbdBusMap | Maps the memory for bus-mastering. This call vector is provided by the Extensible Host Controller Driver (xHCD). |
| usbdPostIOB | Retires an I/O buffer. This call vector is provided by the adapter driver. |
| usbdReqHCrestart | This call vector is provided when an error is detected in 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 the 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. |