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

The OHCI adapter device driver supports the following 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.