Difference between revisions of "Unit USBKEYBOARD"

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...")
 
 
(2 intermediate revisions by the same user not shown)
Line 5: Line 5:
 
----
 
----
  
−
''To be documented''
+
'''Ultibo USB Keyboard Driver unit'''
 +
 
 +
'''USB Keyboard Devices'''
 +
 
 +
The USB keyboard driver in this unit uses HID Boot Protocol only and has been replaced by the HIDKeyboard unit which provides complete HID Report Protocol support for USB keyboards. It is retained here for legacy uses and backwards compatibility only.
 +
 
 +
To use this driver in place of the default HID Keyboard driver set the following configuration variables in your application during system initialization.
 +
HID_REGISTER_KEYBOARD := False;
 +
USB_KEYBOARD_REGISTER_DRIVER := True;
 +
This driver does not recognize devices that do not report themselves as boot keyboards.
  
 
=== 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 keyboard specific constants''' <code> NAME_* </code></div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
| <code>USBKEYBOARD_DRIVER_NAME = 'USB Keyboard Driver (HID boot protocol)';</code>
 +
| Name of USB keyboard driver
 +
|-
 +
| <code>USBKEYBOARD_KEYBOARD_DESCRIPTION = 'USB HID Keyboard';</code>
 +
| Description of USB keyboard device
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<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 interface subclass''' <code> USB_HID_SUBCLASS_* </code></div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
|colspan="2"|See USB HID v1.11 specification
 +
|-
 +
|colspan="2"|&nbsp;
 +
|-
 +
| <code>USB_HID_SUBCLASS_NONE = 0;</code>
 +
| Section 4.2
 +
|-
 +
| <code>USB_HID_SUBCLASS_BOOT = 1;</code>
 +
| Section 4.2
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<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 interface protocol''' <code> USB_HID_BOOT_PROTOCOL_* </code></div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
|colspan="2"|See USB HID v1.11 specification
 +
|-
 +
|colspan="2"|&nbsp;
 +
|-
 +
| <code>USB_HID_BOOT_PROTOCOL_NONE = 0;</code>
 +
| Section 4.3
 +
|-
 +
| <code>USB_HID_BOOT_PROTOCOL_KEYBOARD = 1;</code>
 +
| Section 4.3
 +
|-
 +
| <code>USB_HID_BOOT_PROTOCOL_MOUSE = 2;</code>
 +
| Section 4.3
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<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 class descriptor''' <code> USB_HID_DESCRIPTOR_* </code></div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
|colspan="2"|See USB HID v1.11 specification
 +
|-
 +
|colspan="2"|&nbsp;
 +
|-
 +
| <code>USB_HID_DESCRIPTOR_TYPE_HID = $21;</code>
 +
| Section 7.1
 +
|-
 +
| <code>USB_HID_DESCRIPTOR_TYPE_REPORT = $22;</code>
 +
| Section 7.1
 +
|-
 +
| <code>USB_HID_DESCRIPTOR_TYPE_PHYSICAL_DESCRIPTOR = $23;</code>
 +
| Section 7.1
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<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 request''' <code> USB_HID_REQUEST_* </code></div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
|colspan="2"|See USB HID v1.11 specification
 +
|-
 +
|colspan="2"|&nbsp;
 +
|-
 +
| <code>USB_HID_REQUEST_GET_REPORT = $01;</code>
 +
| Section 7.2
 +
|-
 +
| <code>USB_HID_REQUEST_GET_IDLE = $02;</code>
 +
| Section 7.2
 +
|-
 +
| <code>USB_HID_REQUEST_GET_PROTOCOL = $03;</code>
 +
| Section 7.2
 +
|-
 +
| <code>USB_HID_REQUEST_SET_REPORT = $09;</code>
 +
| Section 7.2
 +
|-
 +
| <code>USB_HID_REQUEST_SET_IDLE = $0A;</code>
 +
| Section 7.2
 +
|-
 +
| <code>USB_HID_REQUEST_SET_PROTOCOL = $0B;</code>
 +
| Section 7.2
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<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 protocol''' <code> USB_HID_PROTOCOL_* </code></div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
|colspan="2"|See USB HID v1.11 specification
 +
|-
 +
|colspan="2"|&nbsp;
 +
|-
 +
| <code>USB_HID_PROTOCOL_BOOT = 0;</code>
 +
| Section 7.2.5
 +
|-
 +
| <code>USB_HID_PROTOCOL_REPORT = 1;</code>
 +
| Section 7.2.5
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<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 report''' <code> USB_HID_REPORT_* </code></div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
|colspan="2"|See USB HID v1.11 specification
 +
|-
 +
|colspan="2"|&nbsp;
 +
|-
 +
| <code>USB_HID_REPORT_INPUT = 1;</code>
 +
| Section 7.2.1
 +
|-
 +
| <code>USB_HID_REPORT_OUTPUT = 2;</code>
 +
| Section 7.2.1
 +
|-
 +
| <code>USB_HID_REPORT_FEATURE = 3;</code>
 +
| Section 7.2.1
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<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 report Ids''' <code> USB_HID_REPORTID_* </code></div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
|colspan="2"|See USB HID v1.11 specification
 +
|-
 +
|colspan="2"|&nbsp;
 +
|-
 +
| <code>USB_HID_REPORTID_NONE = 0;</code>
 +
| Section 7.2.1
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<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 boot protocol''' <code> USB_HID_BOOT_LEFT_*, USB_HID_BOOT_RIGHT_*  </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_BOOT_LEFT_CTRL = (1 shl 0);</code>
 +
| style="width: 50%;"|&nbsp;
 +
|-
 +
| <code>USB_HID_BOOT_LEFT_SHIFT = (1 shl 1);</code>
 +
| &nbsp;
 +
|-
 +
| <code>USB_HID_BOOT_LEFT_ALT = (1 shl 2);</code>
 +
| &nbsp;
 +
|-
 +
| <code>USB_HID_BOOT_LEFT_GUI = (1 shl 3);</code>
 +
| &nbsp;
 +
|-
 +
| <code>USB_HID_BOOT_RIGHT_CTRL = (1 shl 4);</code>
 +
| &nbsp;
 +
|-
 +
| <code>USB_HID_BOOT_RIGHT_SHIFT = (1 shl 5);</code>
 +
| &nbsp;
 +
|-
 +
| <code>USB_HID_BOOT_RIGHT_ALT = (1 shl 6);</code>
 +
| &nbsp;
 +
|-
 +
| <code>USB_HID_BOOT_RIGHT_GUI = (1 shl 7);</code>
 +
| &nbsp;
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<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 boot protocol report data''' <code> USB_HID_BOOT_REPORT_* </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_BOOT_REPORT_SIZE = 8;</code>
 +
| Appendix B of HID Device Class Definition 1.11
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<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 boot protocol output''' <code> USB_HID_BOOT_*_LED </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_BOOT_NUMLOCK_LED = (1 shl 0);</code>
 +
| style="width: 50%;"|&nbsp;
 +
|-
 +
| <code>USB_HID_BOOT_CAPSLOCK_LED = (1 shl 1);</code>
 +
| &nbsp;
 +
|-
 +
| <code>USB_HID_BOOT_SCROLLLOCK_LED = (1 shl 2);</code>
 +
| &nbsp;
 +
|-
 +
| <code>USB_HID_BOOT_COMPOSE_LED = (1 shl 3);</code>
 +
| &nbsp;
 +
|-
 +
| <code>USB_HID_BOOT_KANA_LED = (1 shl 4);</code>
 +
| &nbsp;
 +
|-
 +
|colspan="2"|&nbsp;
 +
|-
 +
| <code>USB_HID_BOOT_LEDMASK = USB_HID_BOOT_NUMLOCK_LED or USB_HID_BOOT_CAPSLOCK_LED or USB_HID_BOOT_SCROLLLOCK_LED or USB_HID_BOOT_COMPOSE_LED or USB_HID_BOOT_KANA_LED;</code>
 +
| &nbsp;
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<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 boot protocol output data''' <code> USB_HID_BOOT_OUTPUT_* </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_BOOT_OUTPUT_SIZE = 1;</code>
 +
| Appendix B of HID Device Class Definition 1.11
 +
|-
 +
|colspan="2"|&nbsp;
 +
|-
 +
| <code>USB_HID_BOOT_USAGE_NUMLOCK = SCAN_CODE_NUMLOCK;</code>
 +
| 83
 +
|-
 +
| <code>USB_HID_BOOT_USAGE_CAPSLOCK = SCAN_CODE_CAPSLOCK;</code>
 +
| 57
 +
|-
 +
| <code>USB_HID_BOOT_USAGE_SCROLLLOCK = SCAN_CODE_SCROLLLOCK;</code>
 +
| 71
 +
|-
 +
|}
 +
</div></div>
 +
<br />
  
 
=== Type definitions ===
 
=== Type definitions ===
 
----
 
----
  
−
''To be documented''
+
 
 +
'''USB HID descriptor'''
 +
 
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial;">
 +
<code>PUSBHIDDescriptor = ^TUSBHIDDescriptor;</code>
 +
 
 +
<code>TUSBHIDDescriptor = packed record</code>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
| <code>bLength:Byte;</code>
 +
| style="width: 50%;"|&nbsp;
 +
|-
 +
| <code>bDescriptorType:Byte;</code>
 +
| &nbsp;
 +
|-
 +
| <code>bcdHID:Word;</code>
 +
| &nbsp;
 +
|-
 +
| <code>bCountryCode:Byte;</code>
 +
| &nbsp;
 +
|-
 +
| <code>bNumDescriptors:Byte;</code>
 +
| &nbsp;
 +
|-
 +
| <code>bHIDDescriptorType:Byte;</code>
 +
| &nbsp;
 +
|-
 +
| <code>wHIDDescriptorLength:Word;</code>
 +
| &nbsp;
 +
|-
 +
|colspan="2"|Note: Up to two optional bHIDDescriptorType/wHIDDescriptorLength pairs after the Report descriptor details
 +
|-
 +
|}
 +
</div></div>
 +
 
 +
'''USB boot keyboard report'''
 +
 
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial;">
 +
<code>PUSBKeyboardReport = ^TUSBKeyboardReport;</code>
 +
 
 +
<code>TUSBKeyboardReport = array[0..7] of Byte;</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 keyboard device'''
 +
 
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial;">
 +
<code>PUSBKeyboardDevice = ^TUSBKeyboardDevice;</code>
 +
 
 +
<code>TUSBKeyboardDevice = record</code>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
|colspan="2"|''Keyboard Properties''
 +
|-
 +
| <code>Keyboard:TKeyboardDevice;</code>
 +
| &nbsp;
 +
|-
 +
|colspan="2"|''USB Properties''
 +
|-
 +
| <code>HIDInterface:PUSBInterface;</code>
 +
| USB HID Keyboard Interface
 +
|-
 +
| <code>ReportRequest:PUSBRequest;</code>
 +
| USB request for keyboard report data
 +
|-
 +
| <code>ReportEndpoint:PUSBEndpointDescriptor;</code>
 +
| USB Keyboard Interrupt IN Endpoint
 +
|-
 +
| <code>HIDDescriptor:PUSBHIDDescriptor;</code>
 +
| USB HID Descriptor for keyboard
 +
|-
 +
| <code>ReportDescriptor:Pointer;</code>
 +
| USB HID Report Descriptor for keyboard
 +
|-
 +
| <code>LastCode:Word;</code>
 +
| The scan code of the last key pressed
 +
|-
 +
| <code>LastCount:LongWord;</code>
 +
| The repeat count of the last key pressed
 +
|-
 +
| <code>LastReport:TUSBKeyboardReport;</code>
 +
| The last keyboard report received
 +
|-
 +
| <code>PendingCount:LongWord;</code>
 +
| Number of USB requests pending for this keyboard
 +
|-
 +
| <code>WaiterThread:TThreadId;</code>
 +
| Thread waiting for pending requests to complete (for keyboard detachment)
 +
|-
 +
|}
 +
</div></div>
 +
<br />
  
 
=== Public variables ===
 
=== Public variables ===
 
----
 
----
  
−
''To be documented''
+
''None defined''
  
 
=== Function declarations ===
 
=== Function declarations ===
 
----
 
----
  
−
''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 USBKeyboardInit;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Initialize the USB keyboard 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 keyboard 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 USBKeyboardDeviceRead(Keyboard:PKeyboardDevice; Buffer:Pointer; Size:LongWord; var Count:LongWord):LongWord;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Implementation of KeyboardDeviceRead API for USB Keyboard</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Note
 +
| Not intended to be called directly by applications, use KeyboardDeviceRead instead.
 +
|-
 +
|}
 +
</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 USBKeyboardDeviceControl(Keyboard:PKeyboardDevice; Request:Integer; Argument1:PtrUInt; var Argument2:PtrUInt):LongWord;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Implementation of KeyboardDeviceControl API for USB Keyboard</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Note
 +
| Not intended to be called directly by applications, use KeyboardDeviceControl instead.
 +
|-
 +
|}
 +
</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 USBKeyboardDriverBind(Device:PUSBDevice; Interrface:PUSBInterface):LongWord;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Bind the Keyboard driver to a USB device if it is suitable</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 attempt to bind to
 +
|-
 +
! Interrface
 +
| The USB interface to attempt to bind to (or nil for whole device)
 +
|-
 +
! Return
 +
| USB_STATUS_SUCCESS if completed, USB_STATUS_DEVICE_UNSUPPORTED if unsupported 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 USBKeyboardDriverUnbind(Device:PUSBDevice; Interrface:PUSBInterface):LongWord;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Unbind the Keyboard driver from a USB 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 unbind from
 +
|-
 +
! Interrface
 +
| The USB interface to unbind from (or nil for whole device)
 +
|-
 +
! 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;">procedure USBKeyboardReportWorker(Request:PUSBRequest);</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Called (by a Worker thread) to process a completed USB request from a USB keyboard IN interrupt endpoint</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Request
 +
| The USB request which has completed
 +
|-
 +
|}
 +
</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;">procedure USBKeyboardReportComplete(Request:PUSBRequest);</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Called when a USB request from a USB keyboard IN interrupt endpoint completes</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Request
 +
| The USB request which has completed
 +
|-
 +
! Note
 +
| Request is passed to worker thread for processing to prevent blocking the USB completion
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
 +
'''USB 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 USBKeyboardCheckDevice(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 HID Keyboard 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 USBKeyboardCheckPressed(Keyboard:PUSBKeyboardDevice; ScanCode:Byte):Boolean;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Check if the passed scan code has been pressed (True if not pressed in last report)</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Keyboard
 +
| The USB keyboard device to check for
 +
|-
 +
! ScanCode
 +
| The keyboard scan code to check
 +
|-
 +
! Note
 +
| Caller must hold the keyboard lock
 +
|-
 +
|}
 +
</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 USBKeyboardCheckRepeated(Keyboard:PUSBKeyboardDevice; ScanCode:Byte):Boolean;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Check if the passed scan code was the last key pressed and if the repeat delay has expired</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Keyboard
 +
| The USB keyboard device to check for
 +
|-
 +
! ScanCode
 +
| The keyboard scan code to check
 +
|-
 +
! Note
 +
| Caller must hold the keyboard lock
 +
|-
 +
|}
 +
</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 USBKeyboardCheckReleased(Keyboard:PUSBKeyboardDevice; Report:PUSBKeyboardReport; ScanCode:Byte):Boolean;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Check if the passed scan code has been released (True if not pressed in current report)</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Keyboard
 +
| The USB keyboard device to check for
 +
|-
 +
! Report
 +
| The USB keyboard report to compare against (Current)
 +
|-
 +
! ScanCode
 +
| The keyboard scan code to check
 +
|-
 +
! Note
 +
| Caller must hold the keyboard lock
 +
|-
 +
|}
 +
</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 USBKeyboardDeviceSetLEDs(Keyboard:PUSBKeyboardDevice; LEDs:Byte):LongWord;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Set the state of the LEDs for a USB keyboard device</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Keyboard
 +
| The USB keyboard device to set the LEDs for
 +
|-
 +
! LEDs
 +
| The LED state to set (eg KEYBOARD_LED_NUMLOCK)
 +
|-
 +
! 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 USBKeyboardDeviceSetIdle(Keyboard:PUSBKeyboardDevice; Duration,ReportId:Byte):LongWord;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Set the idle duration (Time between reports when no changes) for a USB keyboard device</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Keyboard
 +
| The USB keyboard device to set the idle duration for
 +
|-
 +
! Duration
 +
| The idle duration to set (Milliseconds divided by 4)
 +
|-
 +
! ReportId
 +
| The report Id to set the idle duration for (eg USB_HID_REPORTID_NONE)
 +
|-
 +
! 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 USBKeyboardDeviceSetProtocol(Keyboard:PUSBKeyboardDevice; Protocol:Byte):LongWord;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Set the report protocol for a USB keyboard device</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Keyboard
 +
| The USB keyboard device to set the report protocol for
 +
|-
 +
! Protocol
 +
| The report protocol to set (eg USB_HID_PROTOCOL_BOOT)
 +
|-
 +
! 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 USBKeyboardDeviceGetHIDDescriptor(Keyboard:PUSBKeyboardDevice; Descriptor:PUSBHIDDescriptor):LongWord;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Get the HID Descriptor for a USB keyboard device</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Keyboard
 +
| The USB keyboard device to get the descriptor for
 +
|-
 +
! Descriptor
 +
| Pointer to a USB HID Descriptor structure for the returned data
 +
|-
 +
! Descriptor
 +
| 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 USBKeyboardDeviceGetReportDescriptor(Keyboard:PUSBKeyboardDevice; Descriptor:Pointer; Size:LongWord):LongWord;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Get the Report Descriptor for a USB keyboard device</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Keyboard
 +
| The USB keyboard device to get the descriptor for
 +
|-
 +
! Descriptor
 +
| Pointer to a buffer to return the USB Report Descriptor
 +
|-
 +
! Size
 +
| The size in bytes of the buffer pointed to by Descriptor
 +
|-
 +
! Return
 +
| USB_STATUS_SUCCESS if completed or another USB error code on failure
 +
|-
 +
|}
 +
</div></div>
 +
<br />
  
 
Return to [[Unit_Reference|Unit Reference]]
 
Return to [[Unit_Reference|Unit Reference]]

Latest revision as of 03:17, 17 November 2022

Return to Unit Reference


Description

Ultibo USB Keyboard Driver unit

USB Keyboard Devices

The USB keyboard driver in this unit uses HID Boot Protocol only and has been replaced by the HIDKeyboard unit which provides complete HID Report Protocol support for USB keyboards. It is retained here for legacy uses and backwards compatibility only.

To use this driver in place of the default HID Keyboard driver set the following configuration variables in your application during system initialization. 

HID_REGISTER_KEYBOARD := False;
USB_KEYBOARD_REGISTER_DRIVER := True;

This driver does not recognize devices that do not report themselves as boot keyboards.

Constants


USB keyboard specific constants NAME_*
USBKEYBOARD_DRIVER_NAME = 'USB Keyboard Driver (HID boot protocol)'; Name of USB keyboard driver
USBKEYBOARD_KEYBOARD_DESCRIPTION = 'USB HID Keyboard'; Description of USB keyboard device


USB HID interface subclass USB_HID_SUBCLASS_*
See USB HID v1.11 specification
 
USB_HID_SUBCLASS_NONE = 0; Section 4.2
USB_HID_SUBCLASS_BOOT = 1; Section 4.2


USB HID interface protocol USB_HID_BOOT_PROTOCOL_*
See USB HID v1.11 specification
 
USB_HID_BOOT_PROTOCOL_NONE = 0; Section 4.3
USB_HID_BOOT_PROTOCOL_KEYBOARD = 1; Section 4.3
USB_HID_BOOT_PROTOCOL_MOUSE = 2; Section 4.3


USB HID class descriptor USB_HID_DESCRIPTOR_*
See USB HID v1.11 specification
 
USB_HID_DESCRIPTOR_TYPE_HID = $21; Section 7.1
USB_HID_DESCRIPTOR_TYPE_REPORT = $22; Section 7.1
USB_HID_DESCRIPTOR_TYPE_PHYSICAL_DESCRIPTOR = $23; Section 7.1


USB HID request USB_HID_REQUEST_*
See USB HID v1.11 specification
 
USB_HID_REQUEST_GET_REPORT = $01; Section 7.2
USB_HID_REQUEST_GET_IDLE = $02; Section 7.2
USB_HID_REQUEST_GET_PROTOCOL = $03; Section 7.2
USB_HID_REQUEST_SET_REPORT = $09; Section 7.2
USB_HID_REQUEST_SET_IDLE = $0A; Section 7.2
USB_HID_REQUEST_SET_PROTOCOL = $0B; Section 7.2


USB HID protocol USB_HID_PROTOCOL_*
See USB HID v1.11 specification
 
USB_HID_PROTOCOL_BOOT = 0; Section 7.2.5
USB_HID_PROTOCOL_REPORT = 1; Section 7.2.5


USB HID report USB_HID_REPORT_*
See USB HID v1.11 specification
 
USB_HID_REPORT_INPUT = 1; Section 7.2.1
USB_HID_REPORT_OUTPUT = 2; Section 7.2.1
USB_HID_REPORT_FEATURE = 3; Section 7.2.1


USB HID report Ids USB_HID_REPORTID_*
See USB HID v1.11 specification
 
USB_HID_REPORTID_NONE = 0; Section 7.2.1


USB HID boot protocol USB_HID_BOOT_LEFT_*, USB_HID_BOOT_RIGHT_*
USB_HID_BOOT_LEFT_CTRL = (1 shl 0);  
USB_HID_BOOT_LEFT_SHIFT = (1 shl 1);  
USB_HID_BOOT_LEFT_ALT = (1 shl 2);  
USB_HID_BOOT_LEFT_GUI = (1 shl 3);  
USB_HID_BOOT_RIGHT_CTRL = (1 shl 4);  
USB_HID_BOOT_RIGHT_SHIFT = (1 shl 5);  
USB_HID_BOOT_RIGHT_ALT = (1 shl 6);  
USB_HID_BOOT_RIGHT_GUI = (1 shl 7);  


USB HID boot protocol report data USB_HID_BOOT_REPORT_*
USB_HID_BOOT_REPORT_SIZE = 8; Appendix B of HID Device Class Definition 1.11


USB HID boot protocol output USB_HID_BOOT_*_LED
USB_HID_BOOT_NUMLOCK_LED = (1 shl 0);  
USB_HID_BOOT_CAPSLOCK_LED = (1 shl 1);  
USB_HID_BOOT_SCROLLLOCK_LED = (1 shl 2);  
USB_HID_BOOT_COMPOSE_LED = (1 shl 3);  
USB_HID_BOOT_KANA_LED = (1 shl 4);  
 
USB_HID_BOOT_LEDMASK = USB_HID_BOOT_NUMLOCK_LED or USB_HID_BOOT_CAPSLOCK_LED or USB_HID_BOOT_SCROLLLOCK_LED or USB_HID_BOOT_COMPOSE_LED or USB_HID_BOOT_KANA_LED;  


USB HID boot protocol output data USB_HID_BOOT_OUTPUT_*
USB_HID_BOOT_OUTPUT_SIZE = 1; Appendix B of HID Device Class Definition 1.11
 
USB_HID_BOOT_USAGE_NUMLOCK = SCAN_CODE_NUMLOCK; 83
USB_HID_BOOT_USAGE_CAPSLOCK = SCAN_CODE_CAPSLOCK; 57
USB_HID_BOOT_USAGE_SCROLLLOCK = SCAN_CODE_SCROLLLOCK; 71


Type definitions


USB HID descriptor

PUSBHIDDescriptor = ^TUSBHIDDescriptor;

TUSBHIDDescriptor = packed record

bLength:Byte;  
bDescriptorType:Byte;  
bcdHID:Word;  
bCountryCode:Byte;  
bNumDescriptors:Byte;  
bHIDDescriptorType:Byte;  
wHIDDescriptorLength:Word;  
Note: Up to two optional bHIDDescriptorType/wHIDDescriptorLength pairs after the Report descriptor details

USB boot keyboard report

PUSBKeyboardReport = ^TUSBKeyboardReport;

TUSBKeyboardReport = array[0..7] of Byte;

   

USB keyboard device

PUSBKeyboardDevice = ^TUSBKeyboardDevice;

TUSBKeyboardDevice = record

Keyboard Properties
Keyboard:TKeyboardDevice;  
USB Properties
HIDInterface:PUSBInterface; USB HID Keyboard Interface
ReportRequest:PUSBRequest; USB request for keyboard report data
ReportEndpoint:PUSBEndpointDescriptor; USB Keyboard Interrupt IN Endpoint
HIDDescriptor:PUSBHIDDescriptor; USB HID Descriptor for keyboard
ReportDescriptor:Pointer; USB HID Report Descriptor for keyboard
LastCode:Word; The scan code of the last key pressed
LastCount:LongWord; The repeat count of the last key pressed
LastReport:TUSBKeyboardReport; The last keyboard report received
PendingCount:LongWord; Number of USB requests pending for this keyboard
WaiterThread:TThreadId; Thread waiting for pending requests to complete (for keyboard detachment)


Public variables

None defined

Function declarations


Initialization functions 

procedure USBKeyboardInit;
Description: Initialize the USB keyboard driver
Note Called only during system startup


USB keyboard functions 

function USBKeyboardDeviceRead(Keyboard:PKeyboardDevice; Buffer:Pointer; Size:LongWord; var Count:LongWord):LongWord;
Description: Implementation of KeyboardDeviceRead API for USB Keyboard
Note Not intended to be called directly by applications, use KeyboardDeviceRead instead. 


function USBKeyboardDeviceControl(Keyboard:PKeyboardDevice; Request:Integer; Argument1:PtrUInt; var Argument2:PtrUInt):LongWord;
Description: Implementation of KeyboardDeviceControl API for USB Keyboard
Note Not intended to be called directly by applications, use KeyboardDeviceControl instead. 


function USBKeyboardDriverBind(Device:PUSBDevice; Interrface:PUSBInterface):LongWord;
Description: Bind the Keyboard driver to a USB device if it is suitable
Device The USB device to attempt to bind to
Interrface The USB interface to attempt to bind to (or nil for whole device)
Return USB_STATUS_SUCCESS if completed, USB_STATUS_DEVICE_UNSUPPORTED if unsupported or another error code on failure 


function USBKeyboardDriverUnbind(Device:PUSBDevice; Interrface:PUSBInterface):LongWord;
Description: Unbind the Keyboard driver from a USB device
Device The USB device to unbind from
Interrface The USB interface to unbind from (or nil for whole device)
Return USB_STATUS_SUCCESS if completed or another error code on failure 


procedure USBKeyboardReportWorker(Request:PUSBRequest);
Description: Called (by a Worker thread) to process a completed USB request from a USB keyboard IN interrupt endpoint
Request The USB request which has completed 


procedure USBKeyboardReportComplete(Request:PUSBRequest);
Description: Called when a USB request from a USB keyboard IN interrupt endpoint completes
Request The USB request which has completed
Note Request is passed to worker thread for processing to prevent blocking the USB completion


USB helper functions 

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


function USBKeyboardCheckPressed(Keyboard:PUSBKeyboardDevice; ScanCode:Byte):Boolean;
Description: Check if the passed scan code has been pressed (True if not pressed in last report)
Keyboard The USB keyboard device to check for
ScanCode The keyboard scan code to check
Note Caller must hold the keyboard lock 


function USBKeyboardCheckRepeated(Keyboard:PUSBKeyboardDevice; ScanCode:Byte):Boolean;
Description: Check if the passed scan code was the last key pressed and if the repeat delay has expired
Keyboard The USB keyboard device to check for
ScanCode The keyboard scan code to check
Note Caller must hold the keyboard lock 


function USBKeyboardCheckReleased(Keyboard:PUSBKeyboardDevice; Report:PUSBKeyboardReport; ScanCode:Byte):Boolean;
Description: Check if the passed scan code has been released (True if not pressed in current report)
Keyboard The USB keyboard device to check for
Report The USB keyboard report to compare against (Current)
ScanCode The keyboard scan code to check
Note Caller must hold the keyboard lock 


function USBKeyboardDeviceSetLEDs(Keyboard:PUSBKeyboardDevice; LEDs:Byte):LongWord;
Description: Set the state of the LEDs for a USB keyboard device
Keyboard The USB keyboard device to set the LEDs for
LEDs The LED state to set (eg KEYBOARD_LED_NUMLOCK)
Return USB_STATUS_SUCCESS if completed or another USB error code on failure 


function USBKeyboardDeviceSetIdle(Keyboard:PUSBKeyboardDevice; Duration,ReportId:Byte):LongWord;
Description: Set the idle duration (Time between reports when no changes) for a USB keyboard device
Keyboard The USB keyboard device to set the idle duration for
Duration The idle duration to set (Milliseconds divided by 4)
ReportId The report Id to set the idle duration for (eg USB_HID_REPORTID_NONE)
Return USB_STATUS_SUCCESS if completed or another USB error code on failure 


function USBKeyboardDeviceSetProtocol(Keyboard:PUSBKeyboardDevice; Protocol:Byte):LongWord;
Description: Set the report protocol for a USB keyboard device
Keyboard The USB keyboard device to set the report protocol for
Protocol The report protocol to set (eg USB_HID_PROTOCOL_BOOT)
Return USB_STATUS_SUCCESS if completed or another USB error code on failure 


function USBKeyboardDeviceGetHIDDescriptor(Keyboard:PUSBKeyboardDevice; Descriptor:PUSBHIDDescriptor):LongWord;
Description: Get the HID Descriptor for a USB keyboard device
Keyboard The USB keyboard device to get the descriptor for
Descriptor Pointer to a USB HID Descriptor structure for the returned data
Descriptor USB_STATUS_SUCCESS if completed or another USB error code on failure 


function USBKeyboardDeviceGetReportDescriptor(Keyboard:PUSBKeyboardDevice; Descriptor:Pointer; Size:LongWord):LongWord;
Description: Get the Report Descriptor for a USB keyboard device
Keyboard The USB keyboard device to get the descriptor for
Descriptor Pointer to a buffer to return the USB Report Descriptor
Size The size in bytes of the buffer pointed to by Descriptor
Return USB_STATUS_SUCCESS if completed or another USB error code on failure


Return to Unit Reference

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