Difference between revisions of "Unit USB"

From Ultibo.org
Jump to: navigation, search
Line 990: Line 990:
 
! '''Request'''
 
! '''Request'''
 
| The USB request which has completed
 
| The USB request which has completed
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
 +
'''USB hub functions'''
 +
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">function USBHubCreatePorts(Hub:PUSBHub):LongWord;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Create and initialize the ports for a Hub</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! '''Hub'''
 +
| The hub to initialize ports for
 +
|-
 +
! '''Return'''
 +
| USB_STATUS_SUCCESS if completed or another error code on failure
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">function USBHubPowerOnPorts(Hub:PUSBHub):LongWord;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Power on all ports on a Hub</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! '''Hub'''
 +
| The hub to power on ports for
 +
|-
 +
! '''Return'''
 +
| USB_STATUS_SUCCESS if completed or another error code on failure
 
|-
 
|-
 
|}
 
|}

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;
Description: Performs basic initialization of the USB core driver, after this devices, hosts and drivers can be registered however nothing will work until USBStart is called
Note To be documented


function USBStart:LongWord;
Description: Starts all registered USB hosts, starts the USB hub thread and begins the USB enumeration process. USB enumeration will continue after this function returns as devices are discovered by changes in hub status.
Note To be documented


function USBStop:LongWord;
Description: To be documented
Note To be documented


procedure USBAsyncStart(Host:PUSBHost);
Description: To be documented
Note To be documented


USB device, driver and host functions

function USBDeviceGetAddress(Device:PUSBDevice):Byte;
Description: Get the bus address for the specified device
Device The USB device to get the address for
Return Device address or 0 on failure


function USBDeviceSetAddress(Device:PUSBDevice; Address:Byte):LongWord;
Description: Set the bus address for the specified device
Device The USB device to set the address for
Return USB_STATUS_SUCCESS if completed or another error code on failure


function USBDeviceCreateDeviceDescriptor(Device:PUSBDevice; Length:Word):LongWord;
Description: Allocate a device descriptor for the specified device
Device The USB device to create the device descriptor for
Length The length of the descriptor to create
Return USB_STATUS_SUCCESS if completed or another error code on failure


function USBDeviceCreateConfigurations(Device:PUSBDevice):LongWord;
Description: Allocate the available configurations for this device
Device The USB device to create the configurations for
Return USB_STATUS_SUCCESS if completed or another error code on failure


function USBDeviceReadConfigurations(Device:PUSBDevice):LongWord;
Description: Read and parse the available configurations for this device
Device The USB device to read the configurations for
Return USB_STATUS_SUCCESS if completed or another error code on failure


function USBDeviceCreateConfiguration(Device:PUSBDevice; Index:Byte; Size:Word):LongWord;
Description: Allocate the specified configuration for this device
Device The USB device to create the configuration for
Index The index of the configuration to create
Size The size of the configuration descriptor to create
Return USB_STATUS_SUCCESS if completed or another error code on failure


function USBDeviceReadConfiguration(Device:PUSBDevice; Index:Byte):LongWord;
Description: Read and parse the specified configuration for this device
Device The USB device to read the configuration for
Index The index of the configuration to read
Return USB_STATUS_SUCCESS if completed or another error code on failure


function USBDeviceReadStringDescriptor(Device:PUSBDevice; Index:Byte):String;
Description: To be documented
Note To be documented


function USBDeviceReadStringDescriptorW(Device:PUSBDevice; Index:Byte):UnicodeString;
Description: To be documented
Note To be documented


function USBDeviceGetConfiguration(Device:PUSBDevice; var ConfigurationValue:Byte):LongWord;
Description: Get the current configuration for the specified device
Device The USB device to get the current configuration for
ConfigurationValue The current configuration (As per bConfigurationValue in the configuration descriptor)
Return USB_STATUS_SUCCESS if completed or another error code on failure


function USBDeviceSetConfiguration(Device:PUSBDevice; ConfigurationValue:Byte):LongWord;
Description: Set the configuration for the specified device
Device The USB device to set the configuration for
ConfigurationValue The configuration to set (As per bConfigurationValue in the configuration descriptor)
Return USB_STATUS_SUCCESS if completed or another error code on failure


function USBDeviceFindConfigurationByValue(Device:PUSBDevice; ConfigurationValue:Byte):PUSBConfiguration;
Description: Find the configuration represented by configuration value for the specified device
Device The USB device to find the configuration for
ConfigurationValue The configuration value to find (As per bConfigurationValue in the configuration descriptor)
Return USB Configuration if completed or nil on failure


function USBDeviceGetInterface(Device:PUSBDevice; Index:Byte; var AlternateSetting:Byte):LongWord;
Description: Get the interface alternate setting for the specified device
Device The USB device to get the interface alternate setting for
Index The index of the interface to get (As per bInterfaceNumber in the interface descriptor)
AlternateSetting The current alternate setting of the specified interface (As per bAlternateSetting in the interface descriptor)
Return USB_STATUS_SUCCESS if completed or another error code on failure


function USBDeviceSetInterface(Device:PUSBDevice; Index,AlternateSetting:Byte):LongWord;
Description: Set the interface alternate setting for the specified device
Device The USB device to set the interface alternate setting for
Index The index of the interface to set (As per bInterfaceNumber in the interface descriptor)
AlternateSetting The alternate setting to set on the specified interface (As per bAlternateSetting in the interface descriptor)
Return USB_STATUS_SUCCESS if completed or another error code on failure


function USBDeviceSetFeature(Device:PUSBDevice; Endpoint:PUSBEndpointDescriptor; Feature,Index:Word):LongWord;
Description: Enable a feature on the specified endpoint on the specified device
Device The USB device to enable the feature for
Endpoint The endpoint to enable the feature on
Feature The feature to enable
Index To be documented
Return USB_STATUS_SUCCESS if completed or another error code on failure


function USBDeviceClearFeature(Device:PUSBDevice; Endpoint:PUSBEndpointDescriptor; Feature:Word):LongWord;
Description: Disable a feature on the specified endpoint on the specified device
Device The USB device to disable the feature for
Endpoint The endpoint to disable the feature on
Feature The feature to disable
Index To be documented
Return USB_STATUS_SUCCESS if completed or another error code on failure


function USBDeviceSetState(Device:PUSBDevice; State:LongWord):LongWord;
Description: Set the state of the specified device and send a notification
Device The USB device to set the state for
Status The new state to set and notify
Return USB_STATUS_SUCCESS if completed or another error code on failure


function USBDeviceSetStatus(Device:PUSBDevice; Status:LongWord):LongWord;
Description: Set the status of the specified device and send a notification
Device The USB device to set the status for
Status The new status to set and notify
Return USB_STATUS_SUCCESS if completed or another error code on failure


function USBDeviceBind(Device:PUSBDevice):LongWord;
Description: Attempt to bind a device to one of the registers drivers
Device The device to attempt to bind a driver to
Return USB_STATUS_SUCCESS if completed or another error code on failure


function USBDeviceAttach(Device:PUSBDevice):LongWord;
Description: Configure and initialize a newly attached USB device
Device New USB device to configure and initialize
Return USB_STATUS_SUCCESS if completed or another error code on failure


function USBDeviceDetach(Device:PUSBDevice):LongWord;
Description: Shutdown and detach a USB device
Device The USB device to shutdown and detach
Return USB_STATUS_SUCCESS if completed or another error code on failure


function USBDeviceAllocate(Host:PUSBHost; Parent:PUSBDevice):PUSBDevice;
Description: Create and Register a new Device entry in the Device table}
Host The Host this device is attached to
Parent The Parent device (Hub) this device is attached to (nil if this device is a root hub)
Return Pointer to new Device entry or nil if device could not be created


function USBDeviceFind(USBId:LongWord):PUSBDevice;
Description: To be documented
Note To be documented


function USBDeviceFindByName(const Name:String):PUSBDevice; inline;
Description: To be documented
Note To be documented


function USBDeviceFindByDescription(const Description:String):PUSBDevice; inline;
Description: To be documented
Note To be documented


function USBDeviceEnumerate(Callback:TUSBDeviceEnumerate; Data:Pointer):LongWord;
Description: To be documented
Note To be documented


function USBDeviceNotification(Device:PUSBDevice; Callback:TUSBDeviceNotification; Data:Pointer; Notification,Flags:LongWord):LongWord;
Description: To be documented
Note To be documented


function USBDriverCreate:PUSBDriver;
Description: Create a new Driver entry
Return Pointer to new Driver entry or nil if driver could not be created


function USBDriverCreateEx(Size:LongWord):PUSBDriver;
Description: Create a new Driver entry}
Size Size in bytes to allocate for new driver (Including the driver entry)
Return Pointer to new Driver entry or nil if driver could not be created


function USBDriverDestroy(Driver:PUSBDriver):LongWord;
Description: Destroy an existing Driver entry
Note To be documented


function USBDriverRegister(Driver:PUSBDriver):LongWord;
Description: Register a new Driver in the Driver table
Note To be documented


function USBDriverFind(DriverId:LongWord):PUSBDriver;
Description: To be documented
Note To be documented


function USBDriverFindByName(const Name:String):PUSBDriver; inline;
Description: To be documented
Note To be documented


function USBDriverEnumerate(Callback:TUSBDriverEnumerate; Data:Pointer):LongWord;
Description: To be documented
Note To be documented


function USBHostSetState(Host:PUSBHost; State:LongWord):LongWord;
Description: Set the state of the specified host and send a notification}
Host The USB host to set the state for
State The new state to set and notify
Return USB_STATUS_SUCCESS if completed or another error code on failure


function USBHostCreate:PUSBHost;
Description: Create a new Host entry
Return Pointer to new Host entry or nil if host could not be created


function USBHostCreateEx(Size:LongWord):PUSBHost;
Description: Create a new Host entry
Size Size in bytes to allocate for new host (Including the host entry)
Return Pointer to new Host entry or nil if host could not be created


function USBHostDestroy(Host:PUSBHost):LongWord;
Description: Destroy an existing Host entry
Note To be documented


function USBHostRegister(Host:PUSBHost):LongWord;
Description: Register a new Host in the Host table
Note To be documented


function USBHostFind(HostId:LongWord):PUSBHost;
Description: To be documented
Note To be documented


function USBHostFindByName(const Name:String):PUSBHost; inline;
Description: To be documented
Note To be documented


function USBHostFindByDescription(const Description:String):PUSBHost; inline;
Description: To be documented
Note To be documented


function USBHostEnumerate(Callback:TUSBHostEnumerate; Data:Pointer):LongWord;
Description: To be documented
Note To be documented


function USBHostNotification(Host:PUSBHost; Callback:TUSBHostNotification; Data:Pointer; Notification,Flags:LongWord):LongWord;
Description: To be documented
Note To be documented


function USBBufferAllocate(Device:PUSBDevice; Size:LongWord):Pointer; inline;
Description: Allocate a data buffer for a USB request
Device The device that the request will be sent to
Size The size of the data buffer to allocate
Return The newly allocated buffer or nil on failure


function USBBufferAllocateEx(Device:PUSBDevice; Size:LongWord; var Flags:LongWord):Pointer;
Description: Allocate a data buffer for a USB request
Device The device that the request will be sent to
Size The size of the data buffer to allocate
Flags The returned flags for the allocated buffer (eg USB_REQUEST_FLAG_SHARED)
Return The newly allocated buffer or nil on failure


function USBBufferValidate(Device:PUSBDevice; Buffer:Pointer; Size:LongWord; var Flags:LongWord):LongWord;
Description: Validate a data buffer for a USB request against the USB host requirements
Device The device that the request will be sent to
Buffer The data buffer to validate
Size The size of the data buffer
Flags The returned flags for the validated buffer (eg USB_REQUEST_FLAG_SHARED)
Return USB_STATUS_SUCCESS on success or another error code on failure


function USBRequestAllocate(Device:PUSBDevice; Endpoint:PUSBEndpointDescriptor; Callback:TUSBRequestCompleted; Size:LongWord; DriverData:Pointer):PUSBRequest; inline;
Description: Allocate a new USB request
Device The USB device this request will be sent to
Endpoint The Endpoint descriptor this request will be sent to (Or nil for the default control endpoint)
Callback The callback function to be called on completion of the request
Size The size of the data buffer for the request
DriverData Device driver private data for the callback (Optional)
Return The newly allocated request or nil on failure


function USBRequestAllocateEx(Device:PUSBDevice; Endpoint:PUSBEndpointDescriptor; Callback:TUSBRequestCompleted; var Data:Pointer; Size:LongWord; DriverData:Pointer):PUSBRequest;
Description: Allocate a new USB request
Device The USB device this request will be sent to
Endpoint The Endpoint descriptor this request will be sent to (Or nil for the default control endpoint)
Callback The callback function to be called on completion of the request
Data The returned data buffer allocated for the request (Or nil if size is zero)(Pass an existing buffer to prevent allocation)
Size The size of the data buffer for the request
DriverData Device driver private data for the callback (Optional)
Return The newly allocated request or nil on failure


function USBRequestRelease(Request:PUSBRequest):LongWord;
Description: Release and destroy a USB request
Request The request to be released
Return USB_STATUS_SUCCESS on success or another error code on failure


function USBRequestInitialize(Request:PUSBRequest; Callback:TUSBRequestCompleted; Data:Pointer; Size:LongWord; DriverData:Pointer):LongWord;
Description: Initialize or Reinitialize an existing USB request/div>
Request The request to be initialized
Callback The callback function to be called on completion of the request
Data The returned data buffer allocated for the request (Or nil if size is zero)
Size The size of the data buffer for the request
DriverData Device driver private data for the callback (Optional)
Return USB_STATUS_SUCCESS on success or another error code on failure


function USBRequestSubmit(Request:PUSBRequest):LongWord;
Description: Submit a USB request to a host controller for execution
Request The request to be submitted
Return USB_STATUS_SUCCESS if completed or another error code on failure
Note The request will be completed asynchronously by the host controller and the completion callback will be called when the request has either succeeded or failed


function USBRequestCancel(Request:PUSBRequest):LongWord;
Description: Cancel a USB request previously submitted to a host controller
Request The request to be cancelled
Return USB_STATUS_SUCCESS if completed or another error code on failure


procedure USBRequestComplete(Request:PUSBRequest);
Description: Called by a host controller when a USB request completes
Request The USB request which has completed


USB hub functions

function USBHubCreatePorts(Hub:PUSBHub):LongWord;
Description: Create and initialize the ports for a Hub
Hub The hub to initialize ports for
Return USB_STATUS_SUCCESS if completed or another error code on failure


function USBHubPowerOnPorts(Hub:PUSBHub):LongWord;
Description: Power on all ports on a Hub
Hub The hub to power on ports for
Return USB_STATUS_SUCCESS if completed or another error code on failure


Return to Unit Reference