1 |
3 |
xianfeng |
$Id: gameport-programming.txt,v 1.3 2001/04/24 13:51:37 vojtech Exp $
|
2 |
|
|
|
3 |
|
|
Programming gameport drivers
|
4 |
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
5 |
|
|
|
6 |
|
|
1. A basic classic gameport
|
7 |
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
8 |
|
|
|
9 |
|
|
If the gameport doesn't provide more than the inb()/outb() functionality,
|
10 |
|
|
the code needed to register it with the joystick drivers is simple:
|
11 |
|
|
|
12 |
|
|
struct gameport gameport;
|
13 |
|
|
|
14 |
|
|
gameport.io = MY_IO_ADDRESS;
|
15 |
|
|
gameport_register_port(&gameport);
|
16 |
|
|
|
17 |
|
|
Make sure struct gameport is initialized to 0 in all other fields. The
|
18 |
|
|
gameport generic code will take care of the rest.
|
19 |
|
|
|
20 |
|
|
If your hardware supports more than one io address, and your driver can
|
21 |
|
|
choose which one to program the hardware to, starting from the more exotic
|
22 |
|
|
addresses is preferred, because the likelihood of clashing with the standard
|
23 |
|
|
0x201 address is smaller.
|
24 |
|
|
|
25 |
|
|
Eg. if your driver supports addresses 0x200, 0x208, 0x210 and 0x218, then
|
26 |
|
|
0x218 would be the address of first choice.
|
27 |
|
|
|
28 |
|
|
If your hardware supports a gameport address that is not mapped to ISA io
|
29 |
|
|
space (is above 0x1000), use that one, and don't map the ISA mirror.
|
30 |
|
|
|
31 |
|
|
Also, always request_region() on the whole io space occupied by the
|
32 |
|
|
gameport. Although only one ioport is really used, the gameport usually
|
33 |
|
|
occupies from one to sixteen addresses in the io space.
|
34 |
|
|
|
35 |
|
|
Please also consider enabling the gameport on the card in the ->open()
|
36 |
|
|
callback if the io is mapped to ISA space - this way it'll occupy the io
|
37 |
|
|
space only when something really is using it. Disable it again in the
|
38 |
|
|
->close() callback. You also can select the io address in the ->open()
|
39 |
|
|
callback, so that it doesn't fail if some of the possible addresses are
|
40 |
|
|
already occupied by other gameports.
|
41 |
|
|
|
42 |
|
|
2. Memory mapped gameport
|
43 |
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~
|
44 |
|
|
|
45 |
|
|
When a gameport can be accessed through MMIO, this way is preferred, because
|
46 |
|
|
it is faster, allowing more reads per second. Registering such a gameport
|
47 |
|
|
isn't as easy as a basic IO one, but not so much complex:
|
48 |
|
|
|
49 |
|
|
struct gameport gameport;
|
50 |
|
|
|
51 |
|
|
void my_trigger(struct gameport *gameport)
|
52 |
|
|
{
|
53 |
|
|
my_mmio = 0xff;
|
54 |
|
|
}
|
55 |
|
|
|
56 |
|
|
unsigned char my_read(struct gameport *gameport)
|
57 |
|
|
{
|
58 |
|
|
return my_mmio;
|
59 |
|
|
}
|
60 |
|
|
|
61 |
|
|
gameport.read = my_read;
|
62 |
|
|
gameport.trigger = my_trigger;
|
63 |
|
|
gameport_register_port(&gameport);
|
64 |
|
|
|
65 |
|
|
3. Cooked mode gameport
|
66 |
|
|
~~~~~~~~~~~~~~~~~~~~~~~
|
67 |
|
|
|
68 |
|
|
There are gameports that can report the axis values as numbers, that means
|
69 |
|
|
the driver doesn't have to measure them the old way - an ADC is built into
|
70 |
|
|
the gameport. To register a cooked gameport:
|
71 |
|
|
|
72 |
|
|
struct gameport gameport;
|
73 |
|
|
|
74 |
|
|
int my_cooked_read(struct gameport *gameport, int *axes, int *buttons)
|
75 |
|
|
{
|
76 |
|
|
int i;
|
77 |
|
|
|
78 |
|
|
for (i = 0; i < 4; i++)
|
79 |
|
|
axes[i] = my_mmio[i];
|
80 |
|
|
buttons[i] = my_mmio[4];
|
81 |
|
|
}
|
82 |
|
|
|
83 |
|
|
int my_open(struct gameport *gameport, int mode)
|
84 |
|
|
{
|
85 |
|
|
return -(mode != GAMEPORT_MODE_COOKED);
|
86 |
|
|
}
|
87 |
|
|
|
88 |
|
|
gameport.cooked_read = my_cooked_read;
|
89 |
|
|
gameport.open = my_open;
|
90 |
|
|
gameport.fuzz = 8;
|
91 |
|
|
gameport_register_port(&gameport);
|
92 |
|
|
|
93 |
|
|
The only confusing thing here is the fuzz value. Best determined by
|
94 |
|
|
experimentation, it is the amount of noise in the ADC data. Perfect
|
95 |
|
|
gameports can set this to zero, most common have fuzz between 8 and 32.
|
96 |
|
|
See analog.c and input.c for handling of fuzz - the fuzz value determines
|
97 |
|
|
the size of a gaussian filter window that is used to eliminate the noise
|
98 |
|
|
in the data.
|
99 |
|
|
|
100 |
|
|
4. More complex gameports
|
101 |
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~
|
102 |
|
|
|
103 |
|
|
Gameports can support both raw and cooked modes. In that case combine either
|
104 |
|
|
examples 1+2 or 1+3. Gameports can support internal calibration - see below,
|
105 |
|
|
and also lightning.c and analog.c on how that works. If your driver supports
|
106 |
|
|
more than one gameport instance simultaneously, use the ->private member of
|
107 |
|
|
the gameport struct to point to your data.
|
108 |
|
|
|
109 |
|
|
5. Unregistering a gameport
|
110 |
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
111 |
|
|
|
112 |
|
|
Simple:
|
113 |
|
|
|
114 |
|
|
gameport_unregister_port(&gameport);
|
115 |
|
|
|
116 |
|
|
6. The gameport structure
|
117 |
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~
|
118 |
|
|
|
119 |
|
|
struct gameport {
|
120 |
|
|
|
121 |
|
|
void *private;
|
122 |
|
|
|
123 |
|
|
A private pointer for free use in the gameport driver. (Not the joystick
|
124 |
|
|
driver!)
|
125 |
|
|
|
126 |
|
|
int number;
|
127 |
|
|
|
128 |
|
|
Number assigned to the gameport when registered. Informational purpose only.
|
129 |
|
|
|
130 |
|
|
int io;
|
131 |
|
|
|
132 |
|
|
I/O address for use with raw mode. You have to either set this, or ->read()
|
133 |
|
|
to some value if your gameport supports raw mode.
|
134 |
|
|
|
135 |
|
|
int speed;
|
136 |
|
|
|
137 |
|
|
Raw mode speed of the gameport reads in thousands of reads per second.
|
138 |
|
|
|
139 |
|
|
int fuzz;
|
140 |
|
|
|
141 |
|
|
If the gameport supports cooked mode, this should be set to a value that
|
142 |
|
|
represents the amount of noise in the data. See section 3.
|
143 |
|
|
|
144 |
|
|
void (*trigger)(struct gameport *);
|
145 |
|
|
|
146 |
|
|
Trigger. This function should trigger the ns558 oneshots. If set to NULL,
|
147 |
|
|
outb(0xff, io) will be used.
|
148 |
|
|
|
149 |
|
|
unsigned char (*read)(struct gameport *);
|
150 |
|
|
|
151 |
|
|
Read the buttons and ns558 oneshot bits. If set to NULL, inb(io) will be
|
152 |
|
|
used instead.
|
153 |
|
|
|
154 |
|
|
int (*cooked_read)(struct gameport *, int *axes, int *buttons);
|
155 |
|
|
|
156 |
|
|
If the gameport supports cooked mode, it should point this to its cooked
|
157 |
|
|
read function. It should fill axes[0..3] with four values of the joystick axes
|
158 |
|
|
and buttons[0] with four bits representing the buttons.
|
159 |
|
|
|
160 |
|
|
int (*calibrate)(struct gameport *, int *axes, int *max);
|
161 |
|
|
|
162 |
|
|
Function for calibrating the ADC hardware. When called, axes[0..3] should be
|
163 |
|
|
pre-filled by cooked data by the caller, max[0..3] should be pre-filled with
|
164 |
|
|
expected maximums for each axis. The calibrate() function should set the
|
165 |
|
|
sensitivity of the ADC hardware so that the maximums fit in its range and
|
166 |
|
|
recompute the axes[] values to match the new sensitivity or re-read them from
|
167 |
|
|
the hardware so that they give valid values.
|
168 |
|
|
|
169 |
|
|
int (*open)(struct gameport *, int mode);
|
170 |
|
|
|
171 |
|
|
Open() serves two purposes. First a driver either opens the port in raw or
|
172 |
|
|
in cooked mode, the open() callback can decide which modes are supported.
|
173 |
|
|
Second, resource allocation can happen here. The port can also be enabled
|
174 |
|
|
here. Prior to this call, other fields of the gameport struct (namely the io
|
175 |
|
|
member) need not to be valid.
|
176 |
|
|
|
177 |
|
|
void (*close)(struct gameport *);
|
178 |
|
|
|
179 |
|
|
Close() should free the resources allocated by open, possibly disabling the
|
180 |
|
|
gameport.
|
181 |
|
|
|
182 |
|
|
struct gameport_dev *dev;
|
183 |
|
|
struct gameport *next;
|
184 |
|
|
|
185 |
|
|
For internal use by the gameport layer.
|
186 |
|
|
|
187 |
|
|
};
|
188 |
|
|
|
189 |
|
|
Enjoy!
|