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)
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
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 :
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.
This change has ensured the following :
The change does not intend to address :
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 :
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 :
New KeyV API
The changes to the KeyV API are minimal, allowing the system to continue functioning with legacy drivers where necessary.
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 :
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.
R0 = flags (must be 0) R1 = 32bit usage
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.
R0 = flags : bit 0 = return time of state change R1 = pointer to buffer R2 = number of entries to fill in
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)
[+8] time of state change (on output)
R0 = flags (must be 0) R1 = initial code, or 0 to start a scan
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.
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
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
[+8] time of last state change
Example operation (1)
Example operation (2)
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.
This documentation is copyright 3QD Developments Ltd 2013 and may not be reproduced or published in any form without the copyright holders permission. RISC OS is subject to continuous development and improvement as such all information is reproduced by 3QD Developments Ltd in good faith and is believed to be correct at the time of publication E&OE. 3QD Developments Ltd cannot accept any liability for any loss or damage arising from the use of any information provided as part of the RISC OS Documentation.
HTML document version 1.03 3rd November 2015