Difference between revisions of "Unit USBHID"

From Ultibo.org
Jump to: navigation, search
(Created page with "Return to Unit Reference === Description === ---- ''To be documented'' === Constants === ---- ''To be documented'' === Type definitions === ---- ''To...")
 
 
(3 intermediate revisions by the same user not shown)
Line 5: Line 5:
 
----
 
----
  
−
''To be documented''
+
'''Ultibo USB Human Interface Device (HID) Driver unit'''
 +
 
 +
The USB Human Interface Device (HID) class is one of the most widely used classes of USB devices. HID devices can appear as keyboard, mice, touch devices, gamepads, joysticks and many more.
 +
 +
Importantly HID devices can appear as controls within other devices, for example a USB headset can describe the volume and mute buttons as a HID device and a generic driver can recognize it without the need for a custom driver.
 +
 +
Unlike other USB devices where either an entire device or an interface on a device is used to provide a specific function, the HID standard allows multiple devices to coexist on the same interface. So a mouse and keyboard could be defined on a single USB interface and the HID implementation is able to route the reports they generate to the correct consumer.
 +
 +
Some HID devices (such as proprietary game devices) may require more specific handling than can be provided by the generic device infrastructure included in this unit.
 +
 +
In those cases a standard USB driver can be developed which claims the entire device by vendor and product (as USB offers the complete device to all drivers first). The driver can then configure the device as required and is able to use some of the services of both this unit and the HID unit to parse and examine the HID report descriptors.
 +
 +
Alternatively a HID consumer can be developed that claims the HID device during the optional HID DeviceBind callback which prevents other consumers from binding to the HID collections it contains. The consumer can then use some or all of the services of this unit and the HID unit to handle the HID report descriptors when dealing with reports received from the device.
  
 
=== Constants ===
 
=== Constants ===
 
----
 
----
  
−
''To be documented''
+
 
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 20px; padding-bottom: 15px;">
 +
<div style="font-size: 14px; padding-left: 12px;">'''USB HID specific constants''' <code> USB_HID_* </code></div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
| <code>USB_HID_DRIVER_NAME = 'USB HID Driver';</code>
 +
| Name of USB HID driver
 +
|-
 +
|}
 +
</div></div>
 +
<br />
  
 
=== Type definitions ===
 
=== Type definitions ===
 
----
 
----
  
−
''To be documented''
+
 
 +
'''USB HID request'''
 +
 
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial;">
 +
<code>PUSBHIDRequest = ^TUSBHIDRequest;</code>
 +
 
 +
<code>TUSBHIDRequest = record</code>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
| <code>Collection:PHIDCollection;</code>
 +
| The collection this request corresponds to
 +
|-
 +
|}
 +
</div></div>
 +
 
 +
'''USB HID requests'''
 +
 
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial;">
 +
<code>PUSBHIDRequests = ^TUSBHIDRequests;</code>
 +
 
 +
<code>TUSBHIDRequests = array[0..0] of PUSBHIDRequest;</code>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
| &nbsp;
 +
| style="width: 50%;"|&nbsp;
 +
|-
 +
|}
 +
</div></div>
 +
 
 +
'''USB HID device'''
 +
 
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial;">
 +
<code>PUSBHIDDevice = ^TUSBHIDDevice;</code>
 +
 
 +
<code>TUSBHIDDevice = record</code>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
|colspan="2"|''HID Properties''
 +
|-
 +
| <code>HID:THIDDevice;</code>
 +
| The HID entry for this USB Device
 +
|-
 +
|colspan="2"|''USB Properties''
 +
|-
 +
| <code>USBDevice:PUSBDevice;</code>
 +
| The USB device
 +
|-
 +
| <code>USBInterface:PUSBInterface;</code>
 +
| The USB interface
 +
|-
 +
| <code>HIDDescriptor:PHIDDescriptor;</code>
 +
| The USB HID descriptor from the interface
 +
|-
 +
|colspan="2"|''Driver Properties''
 +
|-
 +
| <code>ReportActive:LongWord;</code>
 +
| The number of currently active report requests
 +
|-
 +
| <code>ReportMaxId:LongWord;</code>
 +
| The maximum report id number this device supports
 +
|-
 +
| <code>ReportMaxSize:LongWord;</code>
 +
| The maximum report size in bytes this device sends
 +
|-
 +
| <code>ReportRequests:PUSBHIDRequests;</code>
 +
| Active input report requests from consumers
 +
|-
 +
| <code>ReportEndpoint:PUSBEndpointDescriptor;</code>
 +
| The USB endpoint for receiving input reports
 +
|-
 +
| <code>OutputEndpoint:PUSBEndpointDescriptor;</code>
 +
| The USB endpoint for receiving ouput reports
 +
|-
 +
| <code>PendingCount:LongWord;</code>
 +
| Number of USB requests pending for this HID device
 +
|-
 +
| <code>WaiterThread:TThreadId;</code>
 +
| Thread waiting for pending requests to complete (for device detachment)
 +
|-
 +
|}
 +
</div></div>
 +
<br />
  
 
=== Public variables ===
 
=== Public variables ===
Line 25: Line 132:
 
----
 
----
  
−
''To be documented''
 
  
 +
'''Initialization 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;">procedure USBHIDInit;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Initialize the USB HID unit and USB HID driver</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Note
 +
| Called only during system startup
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
 +
'''USB HID helper 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 USBHIDCheckDevice(Device:PUSBDevice):Boolean;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Check if the supplied USB device is suitable for detection as a USB HID Device</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Device
 +
| The USB device to check
 +
|-
 +
! Return
 +
| True if the device is suitable or False if it is not
 +
|-
 +
|}
 +
</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 USBHIDCheckInterface(Device:PUSBDevice; Interrface:PUSBInterface):Boolean;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Check if the supplied USB device and interface are a USB HID Device</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Device
 +
| The USB device to check
 +
|-
 +
! Interrface
 +
| The USB interface to check
 +
|-
 +
! Return
 +
| True if the device and interface are a USB HID or False if not
 +
|-
 +
|}
 +
</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 USBHIDGetHIDDescriptor(Device:PUSBDevice; Interrface:PUSBInterface; Descriptor:PHIDDescriptor):LongWord;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Get the HID Descriptor for a USB device and interface</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Device
 +
| The USB device to get the descriptor for
 +
|-
 +
! Descriptor
 +
| Pointer to a USB HID Descriptor structure for the returned data
 +
|-
 +
! Return
 +
| USB_STATUS_SUCCESS if completed or another USB 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 USBHIDStatusToErrorCode(Status:LongWord):LongWord;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Convert a USB_STATUS_* code to an ERROR_* code</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Note
 +
| None documented
 +
|-
 +
|}
 +
</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 USBHIDErrorCodeToUSBStatus(Error:LongWord):LongWord;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Convert an ERROR_* code to a USB_STATUS_* code</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Note
 +
| None documented
 +
|-
 +
|}
 +
</div></div>
 +
<br />
  
 
Return to [[Unit_Reference|Unit Reference]]
 
Return to [[Unit_Reference|Unit Reference]]

Latest revision as of 04:23, 31 January 2024

Return to Unit Reference


Description

Ultibo USB Human Interface Device (HID) Driver unit

The USB Human Interface Device (HID) class is one of the most widely used classes of USB devices. HID devices can appear as keyboard, mice, touch devices, gamepads, joysticks and many more.

Importantly HID devices can appear as controls within other devices, for example a USB headset can describe the volume and mute buttons as a HID device and a generic driver can recognize it without the need for a custom driver.

Unlike other USB devices where either an entire device or an interface on a device is used to provide a specific function, the HID standard allows multiple devices to coexist on the same interface. So a mouse and keyboard could be defined on a single USB interface and the HID implementation is able to route the reports they generate to the correct consumer.

Some HID devices (such as proprietary game devices) may require more specific handling than can be provided by the generic device infrastructure included in this unit.

In those cases a standard USB driver can be developed which claims the entire device by vendor and product (as USB offers the complete device to all drivers first). The driver can then configure the device as required and is able to use some of the services of both this unit and the HID unit to parse and examine the HID report descriptors.

Alternatively a HID consumer can be developed that claims the HID device during the optional HID DeviceBind callback which prevents other consumers from binding to the HID collections it contains. The consumer can then use some or all of the services of this unit and the HID unit to handle the HID report descriptors when dealing with reports received from the device.

Constants


USB HID specific constants USB_HID_*
USB_HID_DRIVER_NAME = 'USB HID Driver'; Name of USB HID driver


Type definitions


USB HID request

PUSBHIDRequest = ^TUSBHIDRequest;

TUSBHIDRequest = record

Collection:PHIDCollection; The collection this request corresponds to

USB HID requests

PUSBHIDRequests = ^TUSBHIDRequests;

TUSBHIDRequests = array[0..0] of PUSBHIDRequest;

   

USB HID device

PUSBHIDDevice = ^TUSBHIDDevice;

TUSBHIDDevice = record

HID Properties
HID:THIDDevice; The HID entry for this USB Device
USB Properties
USBDevice:PUSBDevice; The USB device
USBInterface:PUSBInterface; The USB interface
HIDDescriptor:PHIDDescriptor; The USB HID descriptor from the interface
Driver Properties
ReportActive:LongWord; The number of currently active report requests
ReportMaxId:LongWord; The maximum report id number this device supports
ReportMaxSize:LongWord; The maximum report size in bytes this device sends
ReportRequests:PUSBHIDRequests; Active input report requests from consumers
ReportEndpoint:PUSBEndpointDescriptor; The USB endpoint for receiving input reports
OutputEndpoint:PUSBEndpointDescriptor; The USB endpoint for receiving ouput reports
PendingCount:LongWord; Number of USB requests pending for this HID device
WaiterThread:TThreadId; Thread waiting for pending requests to complete (for device detachment)


Public variables

None defined

Function declarations


Initialization functions 

procedure USBHIDInit;
Description: Initialize the USB HID unit and USB HID driver
Note Called only during system startup


USB HID helper functions 

function USBHIDCheckDevice(Device:PUSBDevice):Boolean;
Description: Check if the supplied USB device is suitable for detection as a USB HID Device
Device The USB device to check
Return True if the device is suitable or False if it is not 


function USBHIDCheckInterface(Device:PUSBDevice; Interrface:PUSBInterface):Boolean;
Description: Check if the supplied USB device and interface are a USB HID Device
Device The USB device to check
Interrface The USB interface to check
Return True if the device and interface are a USB HID or False if not 


function USBHIDGetHIDDescriptor(Device:PUSBDevice; Interrface:PUSBInterface; Descriptor:PHIDDescriptor):LongWord;
Description: Get the HID Descriptor for a USB device and interface
Device The USB device to get the descriptor for
Descriptor Pointer to a USB HID Descriptor structure for the returned data
Return USB_STATUS_SUCCESS if completed or another USB error code on failure 


function USBHIDStatusToErrorCode(Status:LongWord):LongWord;
Description: Convert a USB_STATUS_* code to an ERROR_* code
Note None documented 


function USBHIDErrorCodeToUSBStatus(Error:LongWord):LongWord;
Description: Convert an ERROR_* code to a USB_STATUS_* code
Note None documented


Return to Unit Reference

Retrieved from "https://ultibo.org/mediawiki_ultibo_org/index.php?title=Unit_USBHID&oldid=5846"