Difference between revisions of "Unit Keyboard"

From Ultibo.org
Jump to: navigation, search
Line 4: Line 4:
 
=== Description ===
 
=== Description ===
 
----
 
----
 +
 +
'''Ultibo Keyboard interface unit'''
  
 
'''Keyboard Devices'''
 
'''Keyboard Devices'''

Revision as of 05:09, 19 December 2016

Return to Unit Reference


Description

Ultibo Keyboard interface unit

Keyboard Devices

This unit provides both the Keyboard device interface and the generic USB HID keyboard driver. The keyboard unit also provides the STDIN interface for the Run Time Library (RTL).

USB Keyboard Devices

This driver currently uses HID Boot Protocol only and could be redesigned in future to use the HID Report Protocol instead to allow for greater language support etc.

Constants


Keyboard specific constants KEYBOARD_NAME_*
KEYBOARD_NAME_PREFIX = 'Keyboard'; Name prefix for Keyboard Devices


Keyboard device type constants KEYBOARD_TYPE_*
KEYBOARD_TYPE_NONE = 0;  
KEYBOARD_TYPE_USB = 1;  
KEYBOARD_TYPE_PS2 = 2;  
KEYBOARD_TYPE_SERIAL = 3;  
 
KEYBOARD_TYPE_MAX = 3;  


Keyboard device state constants KEYBOARD_STATE_*
KEYBOARD_STATE_DETACHED = 0;  
KEYBOARD_STATE_DETACHING = 1;  
KEYBOARD_STATE_ATTACHING = 2;  
KEYBOARD_STATE_ATTACHED = 3;  
 
KEYBOARD_STATE_MAX = 3;  


Keyboard device flag constants KEYBOARD_FLAG_*
KEYBOARD_FLAG_NONE = $00000000;  
KEYBOARD_FLAG_NON_BLOCK = $00000001;  
KEYBOARD_FLAG_DIRECT_READ = $00000002;  
KEYBOARD_FLAG_PEEK_BUFFER = $00000004;  
 
KEYBOARD_FLAG_MASK = KEYBOARD_FLAG_NON_BLOCK or KEYBOARD_FLAG_DIRECT_READ or KEYBOARD_FLAG_PEEK_BUFFER;


Keyboard device control code constants KEYBOARD_CONTROL_*
KEYBOARD_CONTROL_GET_FLAG = 1; Get Flag
KEYBOARD_CONTROL_SET_FLAG = 2; Set Flag
KEYBOARD_CONTROL_CLEAR_FLAG = 3; Clear Flag
KEYBOARD_CONTROL_FLUSH_BUFFER = 4; Flush Buffer
KEYBOARD_CONTROL_GET_LED = 5; Get LED
KEYBOARD_CONTROL_SET_LED = 6; Set LED
KEYBOARD_CONTROL_CLEAR_LED = 7; Clear LED
KEYBOARD_CONTROL_GET_REPEAT_RATE = 8; Get Repeat Rate
KEYBOARD_CONTROL_SET_REPEAT_RATE = 9; Set Repeat Rate
KEYBOARD_CONTROL_GET_REPEAT_DELAY = 10; Get Repeat Delay
KEYBOARD_CONTROL_SET_REPEAT_DELAY = 11; Set Repeat Delay


Keyboard device LED constants KEYBOARD_LED_*
KEYBOARD_LED_NONE = $00000000;  
KEYBOARD_LED_NUMLOCK = $00000001;  
KEYBOARD_LED_CAPSLOCK = $00000002;  
KEYBOARD_LED_SCROLLLOCK = $00000004;  
KEYBOARD_LED_COMPOSE = $00000008;  
KEYBOARD_LED_KANA = $00000010;  
 
KEYBOARD_LED_MASK = KEYBOARD_LED_NUMLOCK or KEYBOARD_LED_CAPSLOCK or KEYBOARD_LED_SCROLLLOCK or KEYBOARD_LED_COMPOSE or KEYBOARD_LED_KANA;


Keyboard buffer size constants KEYBOARD_BUFFER_*
KEYBOARD_BUFFER_SIZE = 512;  


Keyboard sampling rate constants KEYBOARD_REPEAT_*
KEYBOARD_REPEAT_RATE = (40 div 4); 40msec -> 25cps
KEYBOARD_REPEAT_DELAY = 10; 10 x KEYBOARD_REPEAT_RATE = 400msec initial delay before repeat


Keyboard data definition constants KEYBOARD_*
Values for TKeyboardData.Modifiers
 
KEYBOARD_LEFT_CTRL = $00000001; The Left Control key is pressed
KEYBOARD_LEFT_SHIFT = $00000002; The Left Shift key is pressed
KEYBOARD_LEFT_ALT = $00000004; The Left Alt key is pressed
KEYBOARD_LEFT_GUI = $00000008; The Left GUI (or Windows) key is pressed
KEYBOARD_RIGHT_CTRL = $00000010; The Right Control key is pressed
KEYBOARD_RIGHT_SHIFT = $00000020; The Right Shift key is pressed
KEYBOARD_RIGHT_ALT = $00000040; The Right Alt key is pressed
KEYBOARD_RIGHT_GUI = $00000080; The Right GUI (or Windows) key is pressed
KEYBOARD_NUM_LOCK = $00000100; Num Lock is currently on
KEYBOARD_CAPS_LOCK = $00000200; Caps Lock is currently on
KEYBOARD_SCROLL_LOCK = $00000400; Scroll Lock is currently on
KEYBOARD_COMPOSE = $00000800; Compose is currently on
KEYBOARD_KANA = $00001000; Kana is currently on
KEYBOARD_KEYUP = $00002000; The key state changed to up
KEYBOARD_KEYDOWN = $00004000; The key state changed to down
KEYBOARD_KEYREPEAT = $00008000; The key is being repeated
KEYBOARD_DEADKEY = $00010000; The key is a being handled as a deadkey}
KEYBOARD_ALTGR = $00020000; The AltGr key is pressed (Normally also Right Alt but may be Ctrl-Alt)


Keyboard logging constants KEYBOARD_LOG_*
KEYBOARD_LOG_LEVEL_DEBUG = LOG_LEVEL_DEBUG; Keyboard debugging messages
KEYBOARD_LOG_LEVEL_INFO = LOG_LEVEL_INFO; Keyboard informational messages, such as a device being attached or detached
KEYBOARD_LOG_LEVEL_ERROR = LOG_LEVEL_ERROR; Keyboard error messages
KEYBOARD_LOG_LEVEL_NONE = LOG_LEVEL_NONE; No Keyboard messages


Type definitions

To be documented

Public variables

To be documented

Function declarations


Initialization functions 

procedure KeyboardInit;
Description: Initialize the keyboard unit, device table and USB keyboard driver
Note Called only during system startup


Keyboard functions 

function KeyboardGet(var KeyCode:Word):LongWord;
Description: Get the first key code from the global keyboard buffer
KeyCode The returned key code read from the buffer (eg KEY_CODE_A)
Return ERROR_SUCCESS if completed or another error code on failure
Note Key code is the value translated from the scan code using the current keymap it may not be a character code and it may include non printable characters. To translate a key code to a character call KeymapGetCharCode() 


function KeyboardPeek:LongWord;
Description: Peek at the global keyboard buffer to see if any data packets are ready
Return ERROR_SUCCESS if packets are ready, ERROR_NO_MORE_ITEMS if not or another error code on failure 


function KeyboardRead(Buffer:Pointer; Size:LongWord; var Count:LongWord):LongWord; inline;
Description: Read keyboard data packets from the global keyboard buffer
Buffer Pointer to a buffer to copy the keyboard data packets to
Size The size of the buffer in bytes (Must be at least TKeyboardData or greater)
Count The number of keyboard data packets copied to the buffer
Return ERROR_SUCCESS if completed or another error code on failure 


function KeyboardReadEx(Buffer:Pointer; Size,Flags:LongWord; var Count:LongWord):LongWord;
Description: Read keyboard data packets from the global keyboard buffer
Buffer Pointer to a buffer to copy the keyboard data packets to
Size TThe size of the buffer in bytes (Must be at least TKeyboardData or greater)
Flags The flags to use for the read (eg KEYBOARD_FLAG_NON_BLOCK)
Count The number of keyboard data packets copied to the buffer
Return ERROR_SUCCESS if completed or another error code on failure 


function KeyboardPut(ScanCode,KeyCode:Word; Modifiers:LongWord):LongWord;
Description: Put a scan code and key code in the global keyboard buffer
ScanCode The scan code to write to the buffer (eg SCAN_CODE_A)
KeyCode The key code to write to the buffer (eg KEY_CODE_A)
Modifiers The modifier keys to write to the buffer (eg KEYBOARD_LEFT_CTRL)
Return ERROR_SUCCESS if completed or another error code on failure 


function KeyboardWrite(Buffer:Pointer; Size,Count:LongWord):LongWord;
Description: Write keyboard data packets to the global keyboard buffer
Buffer Pointer to a buffer to copy the keyboard data packets from
Size The size of the buffer in bytes (Must be at least TKeyboardData or greater)
Count The number of keyboard data packets to copy from the buffer
Return ERROR_SUCCESS if completed or another error code on failure 


function KeyboardFlush:LongWord;
Description: Flush the contents of the global keyboard buffer
Return ERROR_SUCCESS if completed or another error code on failure 


function KeyboardDeviceGet(Keyboard:PKeyboardDevice; var KeyCode:Word):LongWord;
Description: Get the first key code from the buffer of the specified keyboard
Keyboard The keyboard device to get from
Keycode The returned key code read from the buffer (eg KEY_CODE_A)
Return ERROR_SUCCESS if completed or another error code on failure
Note Key code is the value translated from the scan code using the current keymap it may not be a character code and it may include non printable characters. To translate a key code to a character call KeymapGetCharCode() 


function KeyboardDeviceRead(Keyboard:PKeyboardDevice; Buffer:Pointer; Size:LongWord; var Count:LongWord):LongWord;
Description: Read keyboard data packets from the buffer of the specified keyboard
Keyboard The keyboard device to read from
Buffer Pointer to a buffer to copy the keyboard data packets to
Size The size of the buffer in bytes (Must be at least TKeyboardData or greater)
Count The number of keyboard data packets copied to the buffer
Return ERROR_SUCCESS if completed or another error code on failure 


function KeyboardDeviceControl(Keyboard:PKeyboardDevice; Request:Integer; Argument1:LongWord; var Argument2:LongWord):LongWord;
Description: Perform a control request on the specified keyboard device
Keyboard The keyboard device to control
Request The request code for the operation (eg KEYBOARD_CONTROL_GET_FLAG)
Argument1 The first argument for the operation (Dependent on request code)
Argument2 The second argument for the operation (Dependent on request code)
Return ERROR_SUCCESS if completed or another error code on failure 


function KeyboardDeviceSetState(Keyboard:PKeyboardDevice; State:LongWord):LongWord;
Description: Set the state of the specified keyboard and send a notification
Keyboard The keyboard to set the state for
State The new state to set and notify
Return ERROR_SUCCESS if completed or another error code on failure 


function KeyboardDeviceCreate:PKeyboardDevice;
Description: Create a new Keyboard device entry
Return Pointer to new Keyboard device entry or nil if keyboard could not be created 


function KeyboardDeviceCreateEx(Size:LongWord):PKeyboardDevice;
Description: Create a new Keyboard device entry
Size Size in bytes to allocate for new keyboard (Including the keyboard device entry)
Return Pointer to new Keyboard device entry or nil if keyboard could not be created 


function KeyboardDeviceDestroy(Keyboard:PKeyboardDevice):LongWord;
Description: Destroy an existing Keyboard device entry
Keyboard The keyboard device to destroy
Return ERROR_SUCCESS if completed or another error code on failure 


function KeyboardDeviceRegister(Keyboard:PKeyboardDevice):LongWord;
Description: Register a new Keyboard device in the Keyboard table
Keyboard The keyboard device to register
Return ERROR_SUCCESS if completed or another error code on failure 


function KeyboardDeviceDeregister(Keyboard:PKeyboardDevice):LongWord;
Description: Deregister a Keyboard device from the Keyboard table
Keyboard The keyboard device to deregister
Return ERROR_SUCCESS if completed or another error code on failure 


function KeyboardDeviceFind(KeyboardId:LongWord):PKeyboardDevice;
Description: Find a keyboard device by ID in the keyboard table
KeyboardId The ID number of the keyboard to find
Return Pointer to keyboard device entry or nil if not found 


function KeyboardDeviceFindByName(const Name:String):PKeyboardDevice; inline;
Description: Find a keyboard device by name in the keyboard table
Name The name of the keyboard to find (eg Keyboard0)
Return Pointer to keyboard device entry or nil if not found 


function KeyboardDeviceFindByDescription(const Description:String):PKeyboardDevice; inline;
Description: Find a keyboard device by description in the keyboard table
Description The description of the keyboard to find (eg USB HID Keyboard)
Return Pointer to keyboard device entry or nil if not found 


function KeyboardDeviceEnumerate(Callback:TKeyboardEnumerate; Data:Pointer):LongWord;
Description: Enumerate all keyboard devices in the keyboard table
Callback The callback function to call for each keyboard in the table
Data A private data pointer to pass to callback for each keyboard in the table
Return ERROR_SUCCESS if completed or another error code on failure 


function KeyboardDeviceNotification(Keyboard:PKeyboardDevice; Callback:TKeyboardNotification; Data:Pointer; Notification,Flags:LongWord):LongWord;
Description: Register a notification for keyboard device changes
Keyboard The keyboard device to notify changes for (Optional, pass nil for all keyboards)
Callback The function to call when a notification event occurs
Data A private data pointer to pass to callback when a notification event occurs
Notification The events to register for notification of (eg DEVICE_NOTIFICATION_REGISTER)
Flags The flags to control the notification (eg NOTIFIER_FLAG_WORKER)


RTL console functions 

function SysConsoleGetKey(var ACh:Char; AUserData:Pointer):Boolean;
Description: Handler for Platform ConsoleGetKey function
Note None documented 


function SysConsolePeekKey(var ACh:Char; AUserData:Pointer):Boolean;
Description: Handler for Platform ConsolePeekKey function
Note None documented 


function SysConsoleReadChar(var ACh:Char; AUserData:Pointer):Boolean;
Description: Handler for Platform ConsoleReadChar function
Note None documented 


function SysConsoleReadWideChar(var ACh:WideChar; AUserData:Pointer):Boolean;
Description: Handler for Platform ConsoleReadWideChar function
Note None documented


USB keyboard functions 

function USBKeyboardDeviceRead(Keyboard:PKeyboardDevice; Buffer:Pointer; Size:LongWord; var Count:LongWord):LongWord;
Description: Implementation of KeyboardDeviceRead API for USB Keyboard
Note None documented 


function USBKeyboardDeviceControl(Keyboard:PKeyboardDevice; Request:Integer; Argument1:LongWord; var Argument2:LongWord):LongWord;
Description: Implementation of KeyboardDeviceControl API for USB Keyboard
Note None documented 


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
Interface 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
Interface 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


Keyboard helper functions 

function KeyboardGetCount:LongWord; inline;
Description: Get the current keyboard count
Note None documented 


function KeyboardDeviceCheck(Keyboard:PKeyboardDevice):PKeyboardDevice;
Description: Check if the supplied Keyboard is in the keyboard table
Note None documented 


function KeyboardDeviceTypeToString(KeyboardType:LongWord):String;
Description: To be documented
Note None documented 


function KeyboardDeviceStateToString(KeyboardState:LongWord):String;
Description: To be documented
Note None documented 


function KeyboardDeviceStateToNotification(State:LongWord):LongWord;
Description: Convert a Keyboard state value into the notification code for device notifications
Note None documented 


function KeyboardRemapCtrlCode(KeyCode,CharCode:Word):Word;
Description: Remap Ctrl-<Key> combinations to ASCII control codes
Note Caller must check for Left-Ctrl or Right-Ctrl modifiers 


function KeyboardRemapKeyCode(ScanCode,KeyCode:Word; var CharCode:Byte; Modifiers:LongWord):Boolean;
Description: Remap the SCAN_CODE_* and KEY_CODE_* values to DOS compatible scan codes
Return Returns True if the key was remapped, False if it was not
See http://www.freepascal.org/docs-html/rtl/keyboard/kbdscancode.html See also: \source\packages\rtl-console\src\inc\keyscan.inc
Note See below for a version that uses SCAN_CODE_* values instead of translated KEY_CODE_* values 


function KeyboardRemapScanCode(ScanCode,KeyCode:Word; var CharCode:Byte; Modifiers:LongWord):Boolean;
Description: Remap the SCAN_CODE_* and KEY_CODE_* values to DOS compatible scan codes
Return Returns True if the key was remapped, False if it was not
See http://www.freepascal.org/docs-html/rtl/keyboard/kbdscancode.html See also: \source\packages\rtl-console\src\inc\keyscan.inc
Note Same as above except using SCAN_CODE_* values instead of translated KEY_CODE_* values 


procedure KeyboardLog(Level:LongWord; Keyboard:PKeyboardDevice; const AText:String);
Description: To be documented
Note None documented 


procedure KeyboardLogInfo(Keyboard:PKeyboardDevice; const AText:String);
Description: To be documented
Note None documented 


procedure KeyboardLogError(Keyboard:PKeyboardDevice; const AText:String);
Description: To be documented
Note None documented 


procedure KeyboardLogDebug(Keyboard:PKeyboardDevice; const AText:String);
Description: To be documented
Note None documented


USB keyboard helper functions 

function USBKeyboardInsertData(Keyboard:PUSBKeyboardDevice; Data:PKeyboardData):LongWord;
Description: Insert a TKeyboardData entry into the keyboard buffer (Direct or Global)
Keyboard The USB keyboard device to insert data for
Data The TKeyboardData entry to insert
Return ERROR_SUCCESS if completed or another error code on failure
Note Caller must hold the keyboard lock 


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


Return to Unit Reference

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