Open Host Controller Adapter Device Driver
Purpose
Supports the Open Host Controller Interface (OHCI) 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 low and full speed of the USB devices on the same USB host controller adapter simultaneously.
The OHCI adapter supports the USB devices (for example, keyboard and mouse) that operate at USB 1.0 and USB 1.1 speeds.
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 OHCI adapter device driver
The following error condition codes for OHCI are translated into a USBstatus value to inform the USB protocol driver and the client drivers about the error condition. Possible OHCI error conditions and the corresponding USBstatus values follow:
| OHCI error condition code | USBstatus value | Description |
|---|---|---|
| OHCI_CC_BitStuffing | USBD_ERROR | General error condition |
| OHCI_CC_BufferOverrun | USBD_ERROR | General error condition |
| OHCI_CC_BufferUnderrun | USBD_ERROR | General error condition |
| OHCI_CC_CRC | USBD_ERROR | General error condition |
| OHCI_CC_DataOverrun | USBD_ERROR | General error condition |
| OHCI_CC_DataToggleMismatch | USBD_ERROR | General error condition |
| OHCI_CC_DataUnderrun | USBD_ERROR | General error condition |
| OHCI_CC_DeviceNotResponding | USBD_ERROR | General error condition |
| OHCI_CC_NotAccessed_0 | USBD_ERROR | General error condition |
| OHCI_CC_NotAccessed_1 | USBD_ERROR | General error condition |
| OHCI_CC_NoError | USBD_SUCCESS | Completion of successful transaction |
| OHCI_CC_PIDCheckFailure | USBD_ERROR | General error condition |
| OHCI_CC_STALL | USBD_STALL | The logical pipe is delayed |
| OHCI_CC_UnexpectedPID | USBD_ERROR | General error condition |
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 the 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 halted state. This call vector is provided by the USBD. |
| 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 I/O operations on the USB device. The I/O operation 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. |
| hcdUnregisterHC | Unregisters a host controller from the USBD. |
| usbdBusMap | Maps memory for bus mastering by the host controller. 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 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. |