Difference between revisions of "Unit USB"

Revision as of 06:23, 15 September 2016

Return to Unit Reference

Description

USB

This unit implements the USB core software that does not depend on the specific host controller hardware and is not specific to any single USB device or platform.

Features and limitations:

• This driver is written to be compatible with USB 2.0. USB 3.0 devices work correctly when operating in USB 2.0 compatible mode, actual support for USB 3.0 host controllers and native super speed modes will require some modification to this driver.

• Not all USB transfer types and speeds are supported yet. This depends on the Host Controller Driver, see USBRequestSubmit.

• This driver does not attempt to do any intelligent power management, bandwidth allocation, or transfer scheduling. Devices are always set to their first listed configuration regardless of power requirements. Requests are simply passed to the Host Controller Driver in the order submitted, the Host Controller Driver is responsible for doing any more intelligent scheduling if desired.

• This driver does not support multiple configurations per USB device. If a device happens to have multiple configurations, the first one will be assigned (see devices below for more information).

• By design, it is possible to implement a host controller driver for different host controller hardware without changing any of this code, as long as the host controller driver provides the functions declared in TUSBHost (Start, Stop, Reset, Submit and Cancel).

• By design, this driver has a hard-coded dependency on the USB hub driver because USB is useless without hubs.

To initialize this core USB driver, USBInit must be called by the system startup code. See that function for details.

If the flag USB_AUTOSTART is not set then USBStart must be called to start the USB core. See that function for details.

The other functions exported by this core USB driver are mostly intended to be used by USB device drivers.

Debugging messages in this driver can be enabled by changing the value of USB_DEFAULT_LOG_LEVEL and by enabling the USB_DEBUG define in GlobalDefines.

Be careful when enabling USB debugging as the USB core can generate a lot of messages due to constant polling of interrupt endpoints on devices such as hubs, keyboards and mice.

USB Device

USB devices are the generic implementation of anything that can be connected to the USB bus. All USB devices require a driver to implement the specific behaviour of the device but at the generic level each device will have:

• One or more configurations available. The USB core will first offer the device to drivers without a configuration being selected, the driver may choose a specific configuration if required otherwise the core will simply select the first available configuration.

• One or more interfaces available. On devices with multiple interfaces, the USB core supports different drivers binding to different interfaces. This way combination devices are supported.

• One or more endpoints available. All devices must have a control endpoint and most devices will have one or more bulk, interrupt or isochronous endpoints as well. The USB core will only communicate with the control endpoint to perform generic operations like reading the desriptors and assigning a device addresss.

Drivers are expected to understand which endpoints they need to communicate with to provide the device specific functionality.

Devices are considered dynamic by the USB core and can be connected or disconnected at any time. The hub driver is responsible for attaching and detaching devices in response to hub status change events and for binding or unbinding drivers as devices are added or removed.

USB Host

USB hosts implement the hardware level interface that supports sending USB requests to the hardware and receiving responses. All handling of interrupts, DMA, transaction sequence, errors and resubmitting/retrying requests is done by the USB host driver. All host drivers must implement the functions defined in TUSBHost (Start, Stop, Reset, Submit and Cancel) and must register themselves with the USB core by calling USBHostRegister. When the USB core is started each registered host driver will be called via the Start function so it can initialize itself and allocate locks, buffers and other resources required to interact with the hardware.

A host driver can also be registered after the USB core has been started and it will be given the opportunity to start itself immediately. In this way USB hosts can potentially be hot pluggable.

Each host driver must also implement a root hub which respresents the port or ports that are directly connected to the controller hardware. In many cases this will not be a real hub but will be simulated in the host driver so that the hub driver can interact with it as though it was a standard hub device.

Constants

To be documented

Type definitions

To be documented

Public variables

To be documented

Function declarations

Initialization functions

procedure USBInit;

function USBStart:LongWord;

function USBStop:LongWord;

procedure USBAsyncStart(Host:PUSBHost);

USB device, driver and host functions

function USBDeviceGetAddress(Device:PUSBDevice):Byte;

function USBDeviceSetAddress(Device:PUSBDevice; Address:Byte):LongWord;

function USBDeviceCreateDeviceDescriptor(Device:PUSBDevice; Length:Word):LongWord;

function USBDeviceCreateConfigurations(Device:PUSBDevice):LongWord;

function USBDeviceReadConfigurations(Device:PUSBDevice):LongWord;

function USBDeviceCreateConfiguration(Device:PUSBDevice; Index:Byte; Size:Word):LongWord;

function USBDeviceReadConfiguration(Device:PUSBDevice; Index:Byte):LongWord;

function USBDeviceReadStringDescriptor(Device:PUSBDevice; Index:Byte):String;

function USBDeviceReadStringDescriptorW(Device:PUSBDevice; Index:Byte):UnicodeString;

function USBDeviceGetConfiguration(Device:PUSBDevice; var ConfigurationValue:Byte):LongWord;

function USBDeviceSetConfiguration(Device:PUSBDevice; ConfigurationValue:Byte):LongWord;

function USBDeviceFindConfigurationByValue(Device:PUSBDevice; ConfigurationValue:Byte):PUSBConfiguration;

function USBDeviceGetInterface(Device:PUSBDevice; Index:Byte; var AlternateSetting:Byte):LongWord;

function USBDeviceSetInterface(Device:PUSBDevice; Index,AlternateSetting:Byte):LongWord;

function USBDeviceSetFeature(Device:PUSBDevice; Endpoint:PUSBEndpointDescriptor; Feature,Index:Word):LongWord;

function USBDeviceClearFeature(Device:PUSBDevice; Endpoint:PUSBEndpointDescriptor; Feature:Word):LongWord;

function USBDeviceSetState(Device:PUSBDevice; State:LongWord):LongWord;

function USBDeviceSetStatus(Device:PUSBDevice; Status:LongWord):LongWord;

function USBDeviceBind(Device:PUSBDevice):LongWord;

function USBDeviceAttach(Device:PUSBDevice):LongWord;

function USBDeviceDetach(Device:PUSBDevice):LongWord;

function USBDeviceAllocate(Host:PUSBHost; Parent:PUSBDevice):PUSBDevice;

function USBDeviceFind(USBId:LongWord):PUSBDevice;

function USBDeviceFindByName(const Name:String):PUSBDevice; inline;

function USBDeviceFindByDescription(const Description:String):PUSBDevice; inline;

function USBDeviceEnumerate(Callback:TUSBDeviceEnumerate; Data:Pointer):LongWord;

function USBDeviceNotification(Device:PUSBDevice; Callback:TUSBDeviceNotification; Data:Pointer; Notification,Flags:LongWord):LongWord;

function USBDriverCreate:PUSBDriver;

function USBDriverCreateEx(Size:LongWord):PUSBDriver;

function USBDriverDestroy(Driver:PUSBDriver):LongWord;

function USBDriverRegister(Driver:PUSBDriver):LongWord;

function USBDriverFind(DriverId:LongWord):PUSBDriver;

function USBDriverFindByName(const Name:String):PUSBDriver; inline;

function USBDriverEnumerate(Callback:TUSBDriverEnumerate; Data:Pointer):LongWord;

function USBHostSetState(Host:PUSBHost; State:LongWord):LongWord;

function USBHostCreate:PUSBHost;

function USBHostCreateEx(Size:LongWord):PUSBHost;

function USBHostDestroy(Host:PUSBHost):LongWord;

function USBHostRegister(Host:PUSBHost):LongWord;

function USBHostFind(HostId:LongWord):PUSBHost;

function USBHostFindByName(const Name:String):PUSBHost; inline;

function USBHostFindByDescription(const Description:String):PUSBHost; inline;

function USBHostEnumerate(Callback:TUSBHostEnumerate; Data:Pointer):LongWord;

function USBHostNotification(Host:PUSBHost; Callback:TUSBHostNotification; Data:Pointer; Notification,Flags:LongWord):LongWord;

function USBBufferAllocate(Device:PUSBDevice; Size:LongWord):Pointer; inline;

function USBBufferAllocateEx(Device:PUSBDevice; Size:LongWord; var Flags:LongWord):Pointer;

function USBBufferValidate(Device:PUSBDevice; Buffer:Pointer; Size:LongWord; var Flags:LongWord):LongWord;

function USBRequestAllocate(Device:PUSBDevice; Endpoint:PUSBEndpointDescriptor; Callback:TUSBRequestCompleted; Size:LongWord; DriverData:Pointer):PUSBRequest; inline;

function USBRequestAllocateEx(Device:PUSBDevice; Endpoint:PUSBEndpointDescriptor; Callback:TUSBRequestCompleted; var Data:Pointer; Size:LongWord; DriverData:Pointer):PUSBRequest;

function USBRequestRelease(Request:PUSBRequest):LongWord;

function USBRequestInitialize(Request:PUSBRequest; Callback:TUSBRequestCompleted; Data:Pointer; Size:LongWord; DriverData:Pointer):LongWord;

function USBRequestSubmit(Request:PUSBRequest):LongWord;

function USBRequestCancel(Request:PUSBRequest):LongWord;

procedure USBRequestComplete(Request:PUSBRequest);

function USBHubCreatePorts(Hub:PUSBHub):LongWord;

function USBHubPowerOnPorts(Hub:PUSBHub):LongWord;