


                     SOFTWARE FUNCTIONAL SPECIFICATION
                     =================================

                     PS/2 Driver Module for Risc OS Black
                     ------------------------------------

                        Drawing No:     1303,003/FS
                             Issue:     0.04
                            Author:     R.C.Manby
                              Date:     16th June 1994

                        Last Issue:     0.03
________________________________________________________________________________


1. History
----------

Version   Date       Notes
 0.01      12-04-94   Initial draft
 0.02       5-05-94   Added reference to trackerball in section 3.
                      Added module size target to section 11.
 0.03      16-05-94   Changes prompted by FS review:
                        Added outstanding issues:
                          2.1 Check trackerball and mouse data formats are
                              identical.
                          2.2 Check mouse/keyboard plug use on Kryten.
                        Added 12. Development Test Strategy
                        Added 13. Product Organisation
 0.04      16-06-94   Added keyboard driver to allow device swapping for Stork
                      and allow Kryten user to plug mouse & keyboard into wrong
                      sockets.



2. Outstanding Issues
---------------------

2.1 Check that the proposed trackerball returns data in the same format as the
    PS/2 mouse.



3. Product Overview
-------------------

The PS/2 driver module for RISC OS Black is to provide support for an IBM PS/2
mouse, trackerball and keyboard on an IOMD or MORRIS based platform (eg Medusa,
Kryton or Stork).



4. Concepts & Definitions
-------------------------

A PS/2 port is a bi-directional serial interface. It allows commands to be sent
to a device such as a keyboard or mouse and allows the device to return data.
The commands sent include RESET and SET SAMPLING RATE. The returned data
includes key codes (keyboard) or position reports (mouse).

The IOMD chip contains one PS/2 bi-directional serial interface intended for
use as a keyboard port.

The MORRIS chip contains two identical PS/2 bi-directional serial interfaces,
one intended for use as a keyboard port, the other for use as a mouse port.

Medusa uses the IOMD chip and uses its PS/2 interface for the keyboard.

Kryten uses the MORRIS chip. Although its PS/2 ports are labelled, the fact
that the connectors are identical will mean that some users will swap mouse and
keyboard plugs either by accident or on purpose. It is a requirement of the
Kryten project that this should work.

Stork uses the MORRIS chip. Stork uses the MORRIS 'mouse' port for connection
to an internal trackerball. The 'keyboard' port goes to an external connector
intended for use by either a keyboard or a mouse. Storks internal keyboard is
handled by the keyboard/battery-manager microcontroller. This microcontroller
communicates battery status and keyboard codes via a memory mapped parallel
interface into the Portable module. The keyboard protocol is the same as a
normal PS/2 keyboard and is routed by the portable module into the PS/2 driver.


The existing Medusa OS has a mechanism for installing mouse drivers (drivers
for quadrature and two types of serial mouse already exist) and keyboard
drivers, into which this combined keyboard/mouse driver must fit
(see 0197,257/FS Jordan  Keyboard/Mouse/Serial Mouse Software Functional
Specification).
     


5. User Interface
-----------------

The type of device connected to each port will be determined at module start
time and the appropriate driver code selected then. A hot key will be provided
on the Stork internal keyboard to allow the 'external port' to be reset when
an external keyboard is replaced by an external mouse or vice-versa.


The PS/2 mouse can be selected from the command line by typing
  *configure MouseType 3

or from the desktop using !Configure.

When !Configure's Mouse configuration window is opened, all the mouse drivers
are asked to return type and name information for the mice that they support.
This enables !Configure to construct a menu of all the available mouse drivers,
from which the user can select.



6. Programmer Interface
-----------------------

A new module, PS2Driver, will be developed which will drive PS/2 keyboards or
PS/2 mice/trackerballs connected to the interfaces provided by IOMD and MORRIS.

The module will adhere to the same interfaces as the PS/2 keyboard, quadrature
mouse and serial mouse modules written for Medusa (see 0197,257/FS Jordan
Keyboard/Mouse/Serial Mouse Software Functional Specification).

On initialisation this module will claim vector KEYV and PointerV and then
reset all available PS/2 ports. As each device responds (under interrupt), the
driver will determine its type and hence select the appropriate internal
driver code. 


The keyboard.

Once the keyboard has completed its self-test, the driver calls KEYV with reason
code 0 (keyboard present), passing a keyboard id of 2 (PC-AT keyboard).
The driver does not pass key events to the Kernel until explicitly enabled
by being sent (via KVEC) reason code 4 (keyboard enable).

For a fuller description of KEYV reason codes, see 0197,257/FS Jordan Keyboard/
Mouse/Serial Mouse Software Functional Specification. 


The mouse.

This code will intercept PointerV and respond to requests for device type 3
(PS/2 mouse).
 
Mouse movements, received as 3 byte packets, under interrupt, will be
amalgamated until PointerV is called with reason code 0 (request pointer
device state) at which time a report will be returned to the kernel.

The device driver will call KEYV to notify the system of changes in button
state.
    


7. Standards
------------

The code is assembled with !ObjAsm.



8. Data Interchange
-------------------

There are no data interchange formats defined by this project.



9. Data Formats
---------------

A PS/2 mouse sends position and mouse button data as 3 byte packets, in the
following format.

Byte 1  b0  Left button status    1 = button down
        b1  Right button status   1 = button down
        b2  Middle button status  1 = button down
        b3  always 1
        b4  X data sign           1 = negative
        b5  Y data sign           1 = negative
        b6  X data overflow       1 = overflow
        b7  Y data overflow       1 = overflow

Byte 2  b0  LSB of X data         combine with sign bit
        ~                         to give a nine bit
        b7  MSB of X data         2's complement number

Byte 3  b0  LSB of Y data         combine with sign bit
        ~                         to give a nine bit
        b7  MSB of Y data         2's complement number



10. External Dependencies
-------------------------

Medusa hardware
MORRIS
Kryten hardware
Stork hardware

Initial development and testing of the module can be done using a PS/2 mouse or
keyboard connected to the PS/2 keyboard port of a Medusa. Final testing must be
performed using a MORRIS chip on Stork or Kryten hardware.



11. Acceptance Test
-------------------

Must function on Medusa, Kryten and Stork hardware.

Servicing the interrupts caused by mouse movements should not cause any
noticable machine slowdown.

The driver should be no larger than 3.5Kbytes (expected to be 3Kbytes).



12. Development Test Strategy
-----------------------------

Testing will take place using samples of all PS2 keyboards and mice that are
likely to be shipped with Medusa, Kryten or Stork machines and with the Stork
trackerball.

Testing will be performed to ensure that the mouse pointer accuratly and
quickly tracks the physical mouse movements and that all keys respond correctly.

Normally the mouse and keyboard will be plugged in when the machine is switched
on, but testing will be performed to show that they can be plugged in after
machine switch on, and unpluged then re-plugged (into the same sockets) at
anytime.

Testing will take place to ensure that on Stork, an external keyboard can be
swapped for an external mouse or vice versa using the 'device reset' hot key.



13. Product Organisation
------------------------

The module will form part of the RISC OS Black OS ROM image.



14. Future Enhancements
-----------------------