12345678901234567890123456789012345678901234567890123456789012345678901234567890


                     TECHNICAL FUNCTIONAL SPECIFICATION
                     ==================================

                     Joystick Module for Risc OS Black
                     ---------------------------------

                             Issue:     1
                            Author:     W.Turner
                              Date:     31st March 1994

                        Last Issue:     n/a
________________________________________________________________________________

This document aims to set out the technical structure of the joystick module to
be developed for Kryten.

Note that this document only covers analogue joysticks, as the existing code is
sufficient to handle digital joysticks.

Due to the (comparatively) long length of time that an A->D conversion takes, it
is impractical to expect the SWI to wait for a complete conversion before
returning.

As a result, it is proposed that a periodic routine be used to update a 'magic'
memory location with the value of the last A->D conversion performed & then 
initiate the next conversion.

The SWI then need only look at the contents of this 'magic' location to find the
most recent A->D result, and can return almost instantaneously.

Also, to prevent the periodic routine from claiming processor time when the
joystick module is not in use, it is proposed that the first call to the SWI shall
return a 'centred' result, and start the periodic routine. As the joystick SWI is
likely to be called frequently, this erroneous result will be short-lived, and so
sohuld not adversely affect the calling application.


For the implementation of the periodic routine, there are two possibilities:

1) Interrupt-driven

  The joystick interface board has the capability to generate an interrupt when
some combination of A->D conversions have completed. The valid combinations are:
any channel (mask available), all of the channels, the joystick 1 pair, the
joystick 2 pair.

  Hence, depending on the IRQ type, any or all of the channels may be in a
readable state. An attempt must not be made to read a channel which does not have
it's 'conversion complete' line asserted, as the wrong value will be read.


2) Polled

  The interrupt line from each of the A->D convertors is available in a register,
and so can be read to see whether the conversion has finished. Thus, a periodic
routine could be attached to (say) the OS_CallEvery vector, to read the states.



The advantage of the polled routine is that it will be called at regular pre
-defined intervals, thus creating a constant load on the processor, which may be
important for games.
 The interrupt driven routine however, will be called more frequently as the
joystick position moves to the SW corner, as the conversion times will become
faster. This may lead to timing problems in games.

 Note also that should the Irq-driven route be taken, then an extra SWI would be
useful to set the irq conditions (ie which channels to monitor, and on what
condition to interrupt)                  



The second option (Polled) was taken, and the polling routine attached to the
VSync event.
