|
www.riscos.com Technical Support: |
One of the main changes in RISC OS 3.5 was the removal of the Acorn keyboard interface from the kernel and its replacement with a standard IBM PS/2 compatible keyboard device driver, held in the separate 'Keyboard' module. For a description, see The keyboard interface.
The standard quadrature mouse driver was also removed form the kernel and is now a separate driver, held in the 'Mouse' module. There is also a serial mouse driver that can be used if you connect a standard PC-type (Microsoft or Mouse Systems) mouse to the serial port; this is held in the 'SerialMouse' module.
In RISC OS 3.6 the PS/2 keyboard module was renamed 'PS2Driver', and extended to support an IBM PS/2 compatible mouse.
For more details of mouse drivers see The pointer interface.
The keyboard interface has been changed to remove hardware dependent code from the kernel to separate keyboard device driver modules. This makes it easier to support different keyboard devices, and hence open up the choice of keyboards that can be connected. RISC OS 3.5 and 3.6 both supply one keyboard device driver, suitable for IBM PS/2 compatible keyboards.
The interface allows more than one keyboard device to provide input at any one time. Input from multiple devices is merged into one stream as if coming from one device.
The keyboard device driver and kernel communicate with each other through the KeyV software vector. The communication is two-way, so both the driver and the kernel need to claim the vector using OS_Claim, and install a routine to handle the calls that the other may make.
(KeyV is a software vector that was used in 8 bit Acorn machines, but has not been used since, and has now been redefined.)
The keyboard is connected to the new IOMD chip, or to the I/O circuitry integrated into an ARM 7500 or similar, rather than to the IOC chip used in earlier versions of RISC OS. The PS/2 compatible interface provided is similar to that provided by IOC, and includes:
status and control line registers, capable of driving the keyboard Clock and Data lines.
The keyboard device driver
The keyboard device driver claims the keyboard device interrupts that IOMD generates by calling OS_ClaimDeviceVector. It assumes that the keyboard sends scan codes from IBM-MF compatible code set 2 (standard PS/2 code set); if the keyboard does not, then you may get unexpected results.
The keyboard device driver converts the scan codes to the low level key numbers expected by the RISC OS kernel. It then passes these to the kernel by calling the KeyV software vector whenever a key is pressed or released; a reason code indicates which has occurred. The keyboard device driver keeps a table of flags for key states, and only calls KeyV when the state changes.
The keyboard firmware's own auto-repeat capability is not used. Keys are instead repeated by the kernel - just as in earlier versions of RISC OS - hence keeping the same scheme for configuring auto-repeat delay and repeat rate.
The supplied keyboard device driver(s) can be replaced by a custom version if required (eg for a special needs input device). If you wish to use some other device with this vector, contact Acorn Technical Support for a keyboard ID allocation.
The keyboard handler
The keyboard handler is similar to that in earlier versions of RISC OS. It consists of a look up table and a small amount of code. It converts low-level key numbers provided by the keyboard device driver into an ASCII form, with extensions for special characters.
The keyboard handler can be replaced by a custom version if required (eg to support a foreign keyboard).
The kernel keyboard driver is a part of the RISC OS kernel, and binds together the keyboard device driver and keyboard handler. The kernel keyboard driver uses the keyboard handler to convert the low-level key numbers into a recognisable form. The kernel keyboard driver also debounces key presses, keeps track of keys down, and generates auto-repeats of keys at the configured rate.
The kernel keyboard driver also tracks the state of the keyboard's LEDs, and calls KeyV to inform the keyboard device driver when it needs to change the state of an LED.
Now that different versions of RISC OS support different keyboards, you will find that the labels on key tops differ for certain key codes sent to applications. The RISC OS 3 Style Guide specifies applications' behaviour in terms of these labels, rather than key codes. Consequently, your application's behaviour (and possibly its help text and keyboard shortcuts) will have to change depending on which keyboard is in use. You can find this out by calling OS_InstallKeyHandler with R0 = 1.
Just as for the keyboard interface, all hardware dependent code has been removed from the kernel and placed in separate pointer device driver modules. Multiple pointing devices can exist on the computer, but only one can be active at any one time.
RISC OS 3.5 supplies two pointer device drivers:
These two drivers are held in separate modules.
RISC OS 3.6 adds a further pointer device driver:
This driver is held in the same module as the PS/2 keyboard device driver
Again a vector is used to communicate between the kernel and the device driver; both need to claim the vector and install a routine to handle the calls the other may make. The vector is a new one, named PointerV. The interface it provides is common to all pointer device drivers. However, the drivers obviously differ in the way that they access the pointer device's hardware.
The kernel requests pointer device movements every VSync by calling PointerV with reason code 0; the pointer device driver returns the movements. The kernel then scales the pointer device movements depending on the configured mouse step, and updates the pointer position on the display.
The kernel is also responsible for:
When any buttons on the pointer device change state, the pointer device driver passes this to the kernel by calling KeyV, just as for a keyboard. The kernel treats these in the same way as any other key, including debouncing them.
Most calls use a pointer device type to differentiate between the supported pointer devices. Currently defined devices are:
| Type | Device |
|---|---|
| 0 | Quadrature mouse |
| 1 | Microsoft mouse |
| 2 | Mouse Systems mouse |
| 3 | PS/2 mouse (RISC OS 3.6 onwards) |
If you wish to use some other device with this vector, contact Acorn Technical Support for a pointer device type allocation.
The new command *Configure MouseType configures the pointer device type to use thereafter. A new SWI, OS_Pointer, sets or gets the currently selected pointer device type. If a new type is selected, the kernel calls PointerV with reason code 2 so that pointer device drivers can enable or disable.
A further PointerV reason code of 1 can be used to enumerate the available pointer devices as text. This has been incorporated in the Configure application, so users can configure pointing devices from a menu.
When a pointer device driver initialises it must check the current pointer device type using OS_Pointer; should the driver understand the type, it must enable itself.
A quadrature mouse is connected to IOMD, which does not provide interrupt support for mouse input. Instead it provides two 16-bit registers (for x and y directions) which increment, decrement and wrap when the mouse is moved. The state of the mouse buttons is stored in a specific memory location.
The quadrature mouse driver responds to requests for pointer device type 0. It polls the mouse position registers in IOMD, and calculates the mouse movements to return to the kernel by comparing the previous values of these registers with the new ones. Like wise, it regularly reads the state of the buttons.
The Microsoft / Mouse Systems serial mouse driver responds to requests for pointer device type 1 (Microsoft) or 2 (Mouse Systems). When it is selected (see Configuring and selecting the pointer device type and PointerV), it configures the serial device using OS_SerialOp and opens the serial: device for input.
The driver also claims TickerV, and processes any data received by the serial device on centisecond clock ticks. The code re-enables interrupts to avoid any adverse effects on interrupt latency, and sets a flag to prevent re-entrancy while it is being executed. All mouse movements are amalgamated until the kernel calls PointerV to request they be sent.
The driver does not prevent the reconfiguration of the serial port while it is active itself; however it ensures that the serial: device is reopened if it is closed by an external source. If another pointer device becomes selected, the driver releases TickerV and closes the serial: device.
The PS/2 serial mouse driver calls PointerV in a similar way to the Microsoft / Mouse Systems serial mouse driver; see The Microsoft / Mouse Systems serial mouse driver above.
However, since it uses its own dedicated interface, it does not claim TickerV, nor does it configure and use the serial device.
The various serial mouse drivers communicate with serial mice which transmit data in one of these formats:
The first class of mice are Microsoft compatible, and are supported from RISC OS 3.5 onwards. They send data reports in the following format:
| Bit 6 | 5 | 4 | 3 | 2 | 1 | 0 | |
|---|---|---|---|---|---|---|---|
| Byte 1 | 1 | L | R | Y7 | Y6 | X7 | X6 |
| 2 | 0 | X5 | X4 | X3 | X2 | X1 | X0 |
| 3 | 0 | Y5 | Y4 | Y3 | Y2 | Y1 | Y0 |
| 4 | 0 | M | DT4 | DT3 | DT2 | DT1 | DT0 |
| L, R, M | bit flags for left, right and middle buttons: 1  button down
|
| X7 - X0 | signed x distance, in range -128 (left) to +127 (right) |
| Y7 - Y0 | signed y distance, in range -128 (up) to +127 (down) |
| DT4 - DT0 | device type: 0 mouse, all others reserved
|
Some three button mice omit the 4th byte in the report, and set both the L and R bits when the middle button is pressed. The driver can cope with this, and still detects the state of the middle button. This feature is not intended to support 2 button mice.
The second class of mice are Mouse Systems Corporation compatible, and are supported from RISC OS 3.5 onwards. They send their data reports in this format.
| Bit 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | |
|---|---|---|---|---|---|---|---|---|
| Byte 1 | 1 | 0 | 0 | 0 | 0 | L | M | R |
| 2 | X7 | X6 | X5 | X4 | X3 | X2 | X1 | X0 |
| 3 | Y7 | Y6 | Y5 | Y4 | Y3 | Y2 | Y1 | Y0 |
| 4 | X7 | X6 | X5 | X4 | X3 | X2 | X1 | X0 |
| 5 | Y7 | Y6 | Y5 | Y4 | Y3 | Y2 | Y2 | Y0 |
| L, R, M | bit flags for left, right and middle buttons: 0 button down
|
| X7 - X0 | signed x distance, in range -128 (left) to +127 (right) |
| Y7 - Y0 | signed y distance, in range -128 (down) to +127 (up) |
The second set of X, Y data (bytes 4 and 5) is not a duplicate of the first, but the movement of the mouse during transmission of the first report. It cannot be discarded.
The third class of mice are PS/2 compatible, and are supported from RISC OS 3.6 onwards. They send their data reports in this format.
| Bit 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | |
|---|---|---|---|---|---|---|---|---|
| Byte 1 | Yv | Xv | Y8 | X8 | 1 | M | R | L |
| 2 | X7 | X6 | X5 | X4 | X3 | X2 | X1 | X0 |
| 3 | Y7 | Y6 | Y5 | Y4 | Y3 | Y2 | Y1 | Y0 |
| L, R, M | bit flags for left, right and middle buttons: 1 button down
|
| X8 - X0 | signed x distance, in range -256 (left) to +255 (right) |
| Y8 - Y0 | signed y distance, in range -256 (down) to +255 (up) |
| Xv | x data overflow: 1 overflow
|
| Yv | y data overflow: 1 overflow
|
This driver only accepts data from mice communicating in a stream mode operating at 1200 baud. It does not support the higher baud rates that some mice allow you to select by sending them a command.
In Microsoft compatible format data is transferred in 7-bit bytes framed with 1 start bit and 2 stop bits with no parity.
In Mouse Systems Corporation compatible format data is transferred in 8-bit bytes framed with 1 start bit and 2 stop bits with no parity.
The PS/2 serial device driver uses an asynchronous serial port.
In PS/2 compatible format data is transferred in 8-bit bytes, preceded by 1 start bit, and followed by an odd parity bit and a stop bit.
Used to communicate between the kernel and a keyboard device driver
Register usage is dependent on a reason code held in R0:
R0 = 0 (reason code)
R1 = keyboard ID: 1 ARCHIMEDES KEYBOARD_ 2 PC-AT keyboard
R0 = 1 (reason code)
R1 = Low-level internal key number
R0 = 2 (reason code)
R1 = Low-level internal key number
R0 = 3 (reason code)
R1 = LED status flags:
| Bit | Meaning when set |
|---|---|
| 0 | Scroll Lock on |
| 1 | Num Lock on |
| 2 | Caps Lock on |
| 3 - 31 | reserved (should be ignored) |
R0 = 4 (reason code)
R0 = 5 - 10 (reason codes)
All registers preserved
All of these calls should be passed on; none of them should normally be intercepted.
When a keyboard device driver has successfully initialised, it must notify the kernel that the keyboard is present by calling KeyV with this reason code.
When a key is released or pressed, a keyboard device driver must inform the kernel by calling KeyV with these reason codes. It must not do so until it is enabled by the kernel; see Enable keyboard device drivers below.
The key numbers are the same as those used by the key up/down event; see Low-level internal key numbers.
When the state of the keyboard LEDs changes, the kernel calls KeyV with this reason code. A keyboard device driver must claim KeyV, and install a routine to handle such calls by setting the keyboard's LEDs as requested.
The kernel calls KeyV with this reason code to enable keyboard device drivers. A keyboard device driver must not use the Key released and key pressed reason codes until it has received this call; any attempt to do so will be ignored.
This is not a reset call, and keyboard device drivers may see this call many times while they are active. However, it does mean that the kernel has flushed its table of keys that are held down, so the device driver should do the same if appropriate.
Reason codes 5 - 10 are reserved for Acorn use.
Used to communicate between the kernel and a pointer device driver
Register usage is dependent on a reason code held in R0:
R0 = 0 (reason code)
R1 = device type - see Pointer device types
R0 = 1 (reason code)
R1 = pointer to previously found driver's device type record list, or 0 if none
R0 = 2 (reason code)
R1 = device type
All registers preserved except:
R2 = signed 32-bit x movement since last call
R3 = signed 32-bit y movement since last call
R1 = pointer to driver's device type record list
The kernel calls PointerV with this reason code every VSync, to obtain the latest movement of the pointer device. A pointer device driver that supports the specified device type should intercept the call, returning the movement of the pointing device since the last time this reason code was called. Otherwise it should pass the call on.
The kernel uses the returned values to update the pointer position.
The kernel calls PointerV with this reason code to enumerate the available pointer device types. A pointer device driver must claim PointerV, and install a routine that adds to a linked list of pointer devices. It must add one record for each device type it supports:
| Offset | Meaning |
|---|---|
| 0 | next pointer, giving address of next record |
| 4 | flags: bits 0 to 31 reserved (must be 0) |
| 8 | device type - see Pointer device types |
| 9 | name of pointer device, no more than 30 characters, null terminated |
| (for use in menus) |
The pointer device driver must claim the space for the records from RMA. It must set the next pointer field of the last record it added to the value that R1 had on entry, and pass on the call with R1 pointing to the first record it added.
The caller must later free the memory claimed from RMA, usually as it reads the returned list.
This call must not be intercepted.
The kernel calls PointerV with this reason code when a device type is selected by OS_Pointer. A pointer device driver should enable itself if it supports the specified device type; otherwise it should disable itself.
R0 = reason code: 0 GET POINTER TYPE_ 1 set pointer type
R1 = pointer device type (if R1 = 1 on entry) - see Pointer device types
R0 = pointer device type (if R1 = 0 on entry) - see Pointer device types
Interrupt status is not altered
Fast interrupts are enabled
Processor is in SVC mode
Not defined
This call gets or sets the currently selected pointer device type. This is used to ensure that the correct pointer device driver responds to certain PointerV calls.
Selecting a new device type causes PointerV to be called with reason code 2 (Pointer device type selected), so that drivers can enable or disable.
None
*Configure MouseType device_type
device_type - a number giving the pointer device type.
*Configure MouseType sets the configured pointer device to be used thereafter.