Enchanced Joystick support for OS/2
-----------------------------------

This proposal is written by:
Vesa Jskelinen (jaaskela@tietomyrsky.fi)

dated: 19/12/1999


Table of Contents
-----------------

1.   Introduction
2.   Compatibility
3.   In general
4.   IOCtl commands
4.1. Get driver version (0x01)
4.2. Get extended driver version (0x21)
4.3. Driver specific (0x22)
4.4. Get joystick capabilities (0x23)
4.5. Get joystick axis and button statuses (0x24)
4.6. Set calibration information (0x25)
4.7. Get calibration information (0x26)
4.8. Set deadzone information (0x27)
4.9. Get deadzone information (0x28)
5.   Final words

1. Introduction
---------------

Before if you wanted to use joysticks you were basicly limited 
to IBM's generic joystick driver which supported maximium of 
4 axis and 4 buttons. So only two player games could be played 
if game didn't require more buttons than two.

There was need to support multiple joysticks with multiple axis 
and buttons. So I decided to make this proposal and also driver
which supports this proposal. This specification is little 
compatible with Windows one so it wouldn't be so hard to make
joystick support to project Odin. 

Examples which is included in this package was compiled using 
Watcom C/C++ v11.0b but should be easily converted to other 
compilers.


2. Compatibility
----------------

I have tried to desing proposal in way that it won't brake other
joystick implementations. Only thing that differs from orginal
IBM specification (v2.0) is version number. I changed it to from
2.0 to 2.1 and it is used to detect newer interface.


3. In general
-------------

Joystick driver is accessed by device GAME$ which is called by using
filesystem commands OPEN, IOCTL and CLOSE. Device is opended with
DosOpen and all communication happens with DosDevIOCtl and finally 
when joystick is not needed device is closed with DosClose.

IOCtl command uses category 0x80 and specification defines command
entries between 0x21 to 0x28. There is also way to add driver specific
operations to allow flexibility. Before using this interface you should
verify that you really have correct driver (checking strings /versions).

Specification supports up to 6 axis and 32 buttons per joystick. There
could be up to 2G of joysticks but maybe there is no need for more.
Interface support deadzones when reporting digital statuses of axis.
It's up to app writer to use it for different tasks. Deadzones and
calibration information can be written by anyone but it is suggested
that only configuration tool may change these values. It is also
suggested that support for older interface (v2.0) is also included to
maintain larger compatibility with older software and why not to add
support for newer apps to read older interface if newer can't be
located. But since all joysticks that was supported with older 
interface is now supported with newer one you could just say that 
download newest drivers from somewhere.

As mentioned before communication happens using IOCtl commands. To also
add support for DOS session you can make interface you like. Also try
to make enchanced support there too. Example emululate 8 button
joystick or something. One solution could be emulating GrIP to allow
many joysticks with many buttons. It's your call.


4. IOCtl commands
-----------------

Following sub sections describes IOCtl commands specified in this
specification. I have created include file EJOYOS2.H and it should
be included to application which uses enchanced interface. Also
orignal IBM header file JOYOS2.H should be included (not in this
package)

All specified IOCtl commands:
- Get driver version (0x01)
- Get extended driver version (0x21)
- Driver specific (0x22)
- Get joystick capabilities (0x23)
- Get joystick axis and button statuses (0x24)
- Set calibration information (0x25)
- Get calibration information (0x26)
- Set deadzone information (0x27)
- Get deadzone information (0x28)


4.1. Get driver version (0x01)
------------------------------

This command is from IBM specification (v2.0) and it is used to
query version of drivers. Since IBM haven't made any more drivers
it have been stuck to v2.0 (0x20). When driver supporting newer
specification is called with command 0x01 it should respond with
value 0x21 as being version 2.1. 


Parameter packet:

No parameter packet


Data packet: (Read/Write access needed)

Offset    Size      Type      Description
0         4         ULONG     version number


Example call:

ULONG data;
ULONG data_len;

data_len = sizeof(ULONG);

rc = DosDevIOCtl(hGame,
                 IOCTL_CAT_USER, GAME_GET_VERSION,
                 NULL, 0, NULL,
                 &data, data_len, &data_len);

if (rc!=0)
{
    printf("can't read version information!\n");
    exit(1);
}

if (data>=GAME_EXTVERSION)
{
    printf("Enchanced joystick driver is present!\n");
} else 
if (data==GAME_VERSION)
{
    printf("Joystick interface 2.0 is present!\n");
} else
{
    printf("Very old interface is present!\n");
}


4.2. Get extended driver version (0x21)
---------------------------------------

Command is used to retrive information about driver version to
be used on identification purposes for configuration tool.


Parameter packet:

No parameter packet


Data packet: (Read/Write access needed)

Offset    Size      Type      Description
0         256       CHAR      Driver name
256       256       CHAR      Driver author name
512       20        CHAR      Driver version string
532       4         ULONG     Driver versio number (HI WORD major, LOWORD minor)


4.3. Driver specific (0x22)
---------------------------

This command is freely used by driver writer and documentation is not
needed to be public. Command is included to make configuration progress
little easier.


4.4. Get joystick capabilities (0x23)
-------------------------------------

Command returns information about joystick capabilities. Structure
includes total number of joysticks which could be used to query
all joysticks in system. Information for as which axis are connected,
does joystick support POV (Point of View, in helmets?) or is joystick
even connected to this entry.


Parameter packet: (Read access needed)

Offset    Size      Type      Description
0         4         LONG      Joystick number to query (0 is first one)


Data packet: (Read/Write access needed)

Offset    Size      Type      Description
0         256       CHAR      Joystick name (allows easier joystick
                              indentification to user choose which one
                              he/she wants)
256       4         LONG      Number of joystick in system
260       4	    LONG      This joystick number (-1 if out of range)
264       4         ULONG     Capability flags (see EJOYOS2.H for more)
268       4         LONG      Number of axis in joystick (0-6)
272       4         LONG      Number of buttons in joystick (0-32)


4.5. Get joystick axis and button statuses (0x24)
-------------------------------------------------

Command is used to read axis and buttons statuses. Structure contains
digital axis information (generated using deadzone information) and
normal analog axis information. On pads analog axis information should 
follow calibration information set with command (0x25). Deadzone
information even effects to pad digital axis information. When using
analog statuses remember to use deadzones or your own similar interface
to make it little easier user to example control character in game.


Parameter packet: (Read access needed)

Offset    Size      Type      Description
0         4         LONG      Joystick number to query (0 is first one)


Data packet: (Read/Write access needed)

Offset    Size      Type      Description
0         4	    LONG      This joystick number (-1 if out of range)
4         4         ULONG     Analog X axis information
8         4         ULONG     Analog Y axis information
12        4         ULONG     Analog Z axis information
16        4         ULONG     Analog Rudder/4th axis information
20        4         ULONG     Analog 5th axis information
24        4         ULONG     Analog 6th axis information
28        4         ULONG     Bitmapped button statuses (bit set when pressed)
32	  4         ULONG     Point of View direction (set to -1 when no 
                              support found for POV)
36        4         ULONG     Bitmapped digital axis information (see
                              EJOYOS2.H for more details)


4.6. Set calibration information (0x25)
---------------------------------------

Function to set calibration information for axis. It includeds
minium/maxium and also center value. Center values is about value
usually between minium and maxium ((max-min)/2+min). To support
non linear pad or construct faults center value is stored and
it should be used when reading analog statuses. 


Parameter packet: (Read access needed)

Offset    Size      Type      Description
0         4	    LONG      Joystick number
4         4         ULONG     Analog X axis min
8         4         ULONG     Analog X axis center
12        4         ULONG     Analog X axis max
16        4         ULONG     Analog Y axis min
20        4         ULONG     Analog Y axis center
24        4         ULONG     Analog Y axis max
28        4         ULONG     Analog Z axis min
32        4         ULONG     Analog Z axis center
36        4         ULONG     Analog Z axis max
40        4         ULONG     Analog Rudder/4th axis min
44        4         ULONG     Analog Rudder/4th axis center
48        4         ULONG     Analog Rudder/4th axis max
52        4         ULONG     Analog 5th axis min
56        4         ULONG     Analog 5th axis center
60        4         ULONG     Analog 5th axis max
64        4         ULONG     Analog 6th axis min
68        4         ULONG     Analog 6th axis center
72        4         ULONG     Analog 6th axis max


Data packet:

No data packet


4.7. Get calibration information (0x26)
---------------------------------------

Funtion is basicly same as set calibration (0x25) but it returns
calibration information.


Parameter packet: (Read access needed)

Offset    Size      Type      Description
0         4	    LONG      Joystick number


Data packet: (Read/Write access needed)

Offset    Size      Type      Description
0         4	    LONG      This joystick number (-1 if out of range)
4         4         ULONG     Analog X axis min
8         4         ULONG     Analog X axis center
12        4         ULONG     Analog X axis max
16        4         ULONG     Analog Y axis min
20        4         ULONG     Analog Y axis center
24        4         ULONG     Analog Y axis max
28        4         ULONG     Analog Z axis min
32        4         ULONG     Analog Z axis center
36        4         ULONG     Analog Z axis max
40        4         ULONG     Analog Rudder/4th axis min
44        4         ULONG     Analog Rudder/4th axis center
48        4         ULONG     Analog Rudder/4th axis max
52        4         ULONG     Analog 5th axis min
56        4         ULONG     Analog 5th axis center
60        4         ULONG     Analog 5th axis max
64        4         ULONG     Analog 6th axis min
68        4         ULONG     Analog 6th axis center
72        4         ULONG     Analog 6th axis max


4.8. Set deadzone information (0x27)
------------------------------------

Funtion is used to set deadzone information which will be used for
generating digital statuses of axis. App writers can use these values
to create better control of joystick when analog axis status is needed.


Parameter packet: (Read access needed)

Offset    Size      Type      Description
0         4	    LONG      Joystick number
4         4         ULONG     Analog X axis lower deadzone value
8         4         ULONG     Analog X axis upper deadzone value
12        4         ULONG     Analog Y axis lower deadzone value
16        4         ULONG     Analog Y axis upper deadzone value
20        4         ULONG     Analog Z axis lower deadzone value
24        4         ULONG     Analog Z axis upper deadzone value
28        4         ULONG     Analog Rudder/4th axis lower deadzone value
32        4         ULONG     Analog Rudder/4th axis upper deadzone value
36        4         ULONG     Analog 5th axis lower deadzone value
40        4         ULONG     Analog 5th axis upper deadzone value
44        4         ULONG     Analog 6th axis lower deadzone value
48        4         ULONG     Analog 6th axis upper deadzone value


Data packet:

No data packet


4.9. Get deadzone information (0x28)
------------------------------------

Funtion is basicly same as set deadzone (0x27) but it returns
deadzone information.


Parameter packet: (Read access needed)

Offset    Size      Type      Description
0         4	    LONG      Joystick number


Data packet: (Read/Write access needed)

Offset    Size      Type      Description
0         4	    LONG      This joystick number (-1 if out of range)
4         4         ULONG     Analog X axis lower deadzone value
8         4         ULONG     Analog X axis upper deadzone value
12        4         ULONG     Analog Y axis lower deadzone value
16        4         ULONG     Analog Y axis upper deadzone value
20        4         ULONG     Analog Z axis lower deadzone value
24        4         ULONG     Analog Z axis upper deadzone value
28        4         ULONG     Analog Rudder/4th axis lower deadzone value
32        4         ULONG     Analog Rudder/4th axis upper deadzone value
36        4         ULONG     Analog 5th axis lower deadzone value
40        4         ULONG     Analog 5th axis upper deadzone value
44        4         ULONG     Analog 6th axis lower deadzone value
48        4         ULONG     Analog 6th axis upper deadzone value


5. Final words
--------------

I wrote this text file in little hurry so there may be some errors
but see EJOYOS2.H and included examples to get proper description
about interface. If you have questions or suggestions please send
them to me by email (see address at top).
