|
Keyboard Vector
KeyV changes for input debounce
Before key presses are inserted into the keyboard buffer by the Kernel a short delay (2 cs.) is enacted. This allows key debounce to be detected and ignored. However, certain input devices are not susceptible to such debounces and this additional delay can be ignored. Kernel versions from 10.23 can have this delay removed by passing a special value in R2 when the keyboard driver is declared present.
KeyV 0 (Keyboard present)
On entry
R0 = 0 (reason code)
R1 = keyboard ID
R2 = &4E6F4B64 to indicate that no delay should be applied other values
indicate that a delay should be applied
This reason code is issued by the keyboard driver once it has successfully initialised. The value is R2 will only be obeyed from Kernel 10.23 onward. See PRM 5a-238 for more details.
Augmentation of KeyV for modern keyboard systems
Introduction
KeyV was introduced with RISC OS 3.5 to provide a more generic mechanism for the system to report key events at a lower level. This allowed the abstraction of the Hardware keyboard driver from the Kernel - KeyV providing the communication between the Kernel key input tracking routines and the hardware driver. The key handler routines providing the communication between the Kernel and InternationalKeyboard were unaffected by this change.
The appearance of new keyboard styles providing many other controls through PS/2, and the huge selection of keyboard input operations possible with USB keyboards, has meant that this design is quite limited.
Because a large number of possible keys can now be generated these must be fitted into the current system. The following interfaces provide access to input information from the keyboard and mouse, at increasingly high levels :
- PS2Driver - (not compiled in, but available interface for modifying PS/2 to Low Level key code translations)
- KeyV - (low level key codes)
- EventV - (internal key codes, using Key_Transition and Mouse_Transition)
- OS_Byte &81 - (internal BBC key codes, as INKEY and range scanning operations)
- REMV - (read keyboard buffer directly)
- OS_Byte &81 - (read ASCII key within time limit)
- OS_ReadC - (read ASCII key)
Key transitions have always been expected to come from a simple input stream - the keyboard and mouse being the most common input mechanisms. The input system has never been extended to other input mechanisms such as joysticks or remote control devices. Joystick interfacing has followed its own, limited, SWI interface. Remote Control devices have invariably been provided through a keyboard driver, allowing an almost equivalent overlay to be provided for the development keyboard environment.
Requirements
This change has ensured the following :
- Support for larger numbers of inputs, primarily supporting PS/2 keyboards with specialised inputs, and focusing on the power controls and media controls initially
- Better 'source' support for multiple devices connected to the system, where such sources need to be differentiated.
- Compatibility with legacy APIs where ever possible, and additional APIs only where necessary.
The change does not intend to address :
- Unicode input issues
- Fully unified HID input mechanisms
- Key modifier support within buffered input
RISC OS 3.5 KeyV API
The RISC OS 3.5 KeyV API provides a mechanism for the keyboard driver to report keys to the system. The interface is as follows :
On entry
R0 = Reason code (1 or 2 for release or pressed respectively)
R1 = low-level key number
New KeyV interface
At present, KeyV provides all low-level key codes as numerically low values. This is important to earlier (pre-Select 1) RISC OS, because values above &A0 may generate aborts from the Kernel. This should be borne in mind when any of the following changes are considered.
The USB HID Usage Tables provide a large collection of defined usages of HID devices and will be the most commonly used feature set for manufacturers of keyboard (and other input devices). To simplify the design of such an interface, the spirit of the HID Usage will be followed rather than the full design. It is expected that clients wishing to obtain fully specified USB HID reports should use a dedicated API to do so.
The following features of the USB HID Usage Tables are provided by the proposed interface :
- HID Usage Page and HID Usage ID will be grouped together into a 32bit value. HID Usage Page 0 is guaranteed reserved by the specification and thus can be safely used for 'legacy' key operations.
- One-Shot-Controls (OSC), Momentary Controls (MC) and Retrigger Controls (RTC) are the only controls which are suitable for reporting through this mechanism. Other reports should use an alternative, more specific interface to read information. Linear Controls (LC) will be supported in a simplified form only. On-Off-Controls (OOC)
- The Usage will be reported raw, together with its source. It is expected that clients wishing to obtain more specific information should use alternative interfaces.
New KeyV API
The changes to the KeyV API are minimal, allowing the system to continue functioning with legacy drivers where necessary.
On entry
R0 = Reason code (15)
R1 = 32bit usage (HID Usage Page<<16 | HID Usage ID)
R2 = Effect:
0 for disabled, 1 for enabled or a scale for a linear control
R3 = Source type :
0 = Anonymous source (no additional information present,
such as might be provided by a simple forwarding tool)
1 = Simple source (internal device, such as PS/2)
2 = USB source (to be defined)
3 = Remote control (to be defined)
R4 = Source-specific information (none present for source type 0, 1)
The operation of USB HID devices is expected to be as follows :
- Examine the HID Usage for the components of a Report.
- If the Usage is determined to be Mouse, Keyboard or Keypad, it can be passed to this vector entry directly.
- Mouse button events should be passed through as raw 'Button' usages (ie Button usage page, button number in identifier)
- Where USB devices already provide direct support for conversion to the regular KeyV interface, this may be retained. Conversion of code to the proposed interface should take place in stages and may require staggering where legacy support (ie before this interface is in use) is available.
A new module, KeyInput performs the translation from this usage to key operations necessary under the legacy operating system interfaces. That is, the key events reported here are downgraded to KeyV reason code values, where appropriate, which will then be passed on to the remainder of the system. Legacy applications will thus be unaware of the additional layer above them, but more modern applications will be able to trap additional key codes in order to provide advanced functions.
In addition, the KeyInput module will provide an interface to read the state of Usages which it has observed. This will replace the INKEY method of key state checks.
It is expected that 'source types' would be registered values and the 'source-specific information' would be declared public information such that users could trap specific sources where necessary.
KeyInput_Check
On entry
R0 = flags (must be 0)
R1 = 32bit usage
On exit
R2 = current state (as last seen through KeyV)
R3 = time of last state change
This SWI is used to read the state of a particular key. It replaces OS_Byte &81 as a mechanism for reading internal BBC key code states.
KeyInput_CheckMultiple
On entry
R0 = flags :
bit 0 = return time of state change
R1 = pointer to buffer
R2 = number of entries to fill in
On exit
R2 = number of entries filled in
This SWI is used to read the state of a number of defined keys. The buffer will be filled in with the state of the currently depressed keys. The size of the records returned depends on the bits set in the flags on entry
+0 32bit usage (on input)
+4 current state (on output)
[+8] time of state change (on output)
KeyInput_Scan
On entry
R0 = flags (must be 0)
R1 = initial code, or 0 to start a scan
On exit
R1 = new key code, or 0 when no more keys are pressed
R2 = state of the new key code (will be 1 or some other value for linear controls)
R3 = time of last state change
This SWI is used to read the currently pressed key information. It replaces OS_Byte &81, &79 and &7A as a mechanism for scanning key codes.
Note: Key codes passed for the initial value must only be those codes returned by a previous call. The order in which keys are returned is not defined.
KeyInput_ScanMultiple
On entry
R0 = flags :
bit 0 = return time of state change
R1 = initial code, or 0 to start a scan
R2 = pointer to buffer to fill
R3 = number of entries to fill in
On exit
R1 = next key code to pass to SWI, or 0 when no move keys are pressed
R3 = number of entries filled in
This SWI is used to read the state of keys to a buffer. The buffer should be at least 8 bytes per key code (depends on the flags set) :
+0 32bit usage
+4 current state
[+8] time of last state change
Example operation (1)
Example operation (2)
Future extensions
The Keyboard module will be modified to take over from the Kernel all tasks relating to key generation and insertion into buffers.
Wimp and other interactive components will be modified to use this interface in preference to the INKEY interfaces.
INKEY operations will be declared legacy and moved to a separate component. Event_KeyTransition will be declared legacy.
KeyV support will be relegated to being a legacy component, reversing the above described backward compatible interface.
KeyInput may be extended to provide scripted, trigger actions for keys which are not presently supported.
KeyInput may be extended to provide typematic actions for keys which are not presently supported.
|
![[Select]](../imgs/seldoc.png)
