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