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 | ||
ebe14885 | 24 | E.g. if your driver supports addresses 0x200, 0x208, 0x210 and 0x218, then |
1da177e4 LT |
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]; | |
ebe14885 | 81 | buttons[0] = my_mmio[4]; |
1da177e4 LT |
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 | :: |
1da177e4 | 121 | |
9b0ce690 | 122 | struct gameport { |
1da177e4 | 123 | |
ebe14885 | 124 | void *port_data; |
1da177e4 LT |
125 | |
126 | A private pointer for free use in the gameport driver. (Not the joystick | |
127 | driver!) | |
128 | ||
9b0ce690 MCC |
129 | :: |
130 | ||
ebe14885 RD |
131 | char name[32]; |
132 | ||
133 | Driver's name as set by driver calling gameport_set_name(). Informational | |
134 | purpose only. | |
135 | ||
136 | :: | |
137 | ||
138 | char phys[32]; | |
1da177e4 | 139 | |
ebe14885 RD |
140 | gameport's physical name/description as set by driver calling gameport_set_phys(). |
141 | Informational purpose only. | |
1da177e4 | 142 | |
9b0ce690 MCC |
143 | :: |
144 | ||
1da177e4 LT |
145 | int io; |
146 | ||
147 | I/O address for use with raw mode. You have to either set this, or ->read() | |
148 | to some value if your gameport supports raw mode. | |
149 | ||
9b0ce690 MCC |
150 | :: |
151 | ||
1da177e4 LT |
152 | int speed; |
153 | ||
154 | Raw mode speed of the gameport reads in thousands of reads per second. | |
155 | ||
9b0ce690 MCC |
156 | :: |
157 | ||
1da177e4 LT |
158 | int fuzz; |
159 | ||
160 | If the gameport supports cooked mode, this should be set to a value that | |
9b0ce690 MCC |
161 | represents the amount of noise in the data. See |
162 | :ref:`gameport_pgm_cooked_mode`. | |
163 | ||
164 | :: | |
1da177e4 LT |
165 | |
166 | void (*trigger)(struct gameport *); | |
167 | ||
168 | Trigger. This function should trigger the ns558 oneshots. If set to NULL, | |
169 | outb(0xff, io) will be used. | |
170 | ||
9b0ce690 MCC |
171 | :: |
172 | ||
1da177e4 LT |
173 | unsigned char (*read)(struct gameport *); |
174 | ||
175 | Read the buttons and ns558 oneshot bits. If set to NULL, inb(io) will be | |
176 | used instead. | |
177 | ||
9b0ce690 MCC |
178 | :: |
179 | ||
180 | int (*cooked_read)(struct gameport *, int *axes, int *buttons); | |
1da177e4 LT |
181 | |
182 | If the gameport supports cooked mode, it should point this to its cooked | |
183 | read function. It should fill axes[0..3] with four values of the joystick axes | |
184 | and buttons[0] with four bits representing the buttons. | |
185 | ||
9b0ce690 MCC |
186 | :: |
187 | ||
188 | int (*calibrate)(struct gameport *, int *axes, int *max); | |
1da177e4 LT |
189 | |
190 | Function for calibrating the ADC hardware. When called, axes[0..3] should be | |
191 | pre-filled by cooked data by the caller, max[0..3] should be pre-filled with | |
192 | expected maximums for each axis. The calibrate() function should set the | |
193 | sensitivity of the ADC hardware so that the maximums fit in its range and | |
194 | recompute the axes[] values to match the new sensitivity or re-read them from | |
9b0ce690 MCC |
195 | the hardware so that they give valid values. |
196 | ||
197 | :: | |
1da177e4 LT |
198 | |
199 | int (*open)(struct gameport *, int mode); | |
200 | ||
201 | Open() serves two purposes. First a driver either opens the port in raw or | |
202 | in cooked mode, the open() callback can decide which modes are supported. | |
203 | Second, resource allocation can happen here. The port can also be enabled | |
204 | here. Prior to this call, other fields of the gameport struct (namely the io | |
205 | member) need not to be valid. | |
206 | ||
9b0ce690 MCC |
207 | :: |
208 | ||
1da177e4 LT |
209 | void (*close)(struct gameport *); |
210 | ||
211 | Close() should free the resources allocated by open, possibly disabling the | |
212 | gameport. | |
213 | ||
9b0ce690 MCC |
214 | :: |
215 | ||
ebe14885 RD |
216 | struct timer_list poll_timer; |
217 | unsigned int poll_interval; /* in msecs */ | |
218 | spinlock_t timer_lock; | |
219 | unsigned int poll_cnt; | |
220 | void (*poll_handler)(struct gameport *); | |
221 | struct gameport *parent, *child; | |
222 | struct gameport_driver *drv; | |
223 | struct mutex drv_mutex; /* protects serio->drv so attributes can pin driver */ | |
224 | struct device dev; | |
225 | struct list_head node; | |
1da177e4 LT |
226 | |
227 | For internal use by the gameport layer. | |
228 | ||
9b0ce690 MCC |
229 | :: |
230 | ||
231 | }; | |
1da177e4 LT |
232 | |
233 | Enjoy! |