Commit | Line | Data |
---|---|---|
1da177e4 LT |
1 | Programming input drivers |
2 | ~~~~~~~~~~~~~~~~~~~~~~~~~ | |
3 | ||
4 | 1. Creating an input device driver | |
5 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
6 | ||
7 | 1.0 The simplest example | |
8 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
9 | ||
10 | Here comes a very simple example of an input device driver. The device has | |
11 | just one button and the button is accessible at i/o port BUTTON_PORT. When | |
12 | pressed or released a BUTTON_IRQ happens. The driver could look like: | |
13 | ||
14 | #include <linux/input.h> | |
15 | #include <linux/module.h> | |
16 | #include <linux/init.h> | |
17 | ||
18 | #include <asm/irq.h> | |
19 | #include <asm/io.h> | |
20 | ||
85796e7d DT |
21 | static struct input_dev *button_dev; |
22 | ||
1da177e4 LT |
23 | static void button_interrupt(int irq, void *dummy, struct pt_regs *fp) |
24 | { | |
85796e7d DT |
25 | input_report_key(button_dev, BTN_1, inb(BUTTON_PORT) & 1); |
26 | input_sync(button_dev); | |
1da177e4 LT |
27 | } |
28 | ||
29 | static int __init button_init(void) | |
30 | { | |
85796e7d DT |
31 | int error; |
32 | ||
1da177e4 LT |
33 | if (request_irq(BUTTON_IRQ, button_interrupt, 0, "button", NULL)) { |
34 | printk(KERN_ERR "button.c: Can't allocate irq %d\n", button_irq); | |
35 | return -EBUSY; | |
36 | } | |
85796e7d DT |
37 | |
38 | button_dev = input_allocate_device(); | |
39 | if (!button_dev) { | |
40 | printk(KERN_ERR "button.c: Not enough memory\n"); | |
41 | error = -ENOMEM; | |
42 | goto err_free_irq; | |
43 | } | |
44 | ||
7b19ada2 JS |
45 | button_dev->evbit[0] = BIT_MASK(EV_KEY); |
46 | button_dev->keybit[BIT_WORD(BTN_0)] = BIT_MASK(BTN_0); | |
85796e7d DT |
47 | |
48 | error = input_register_device(button_dev); | |
49 | if (error) { | |
50 | printk(KERN_ERR "button.c: Failed to register device\n"); | |
51 | goto err_free_dev; | |
52 | } | |
53 | ||
54 | return 0; | |
55 | ||
56 | err_free_dev: | |
57 | input_free_device(button_dev); | |
58 | err_free_irq: | |
59 | free_irq(BUTTON_IRQ, button_interrupt); | |
60 | return error; | |
1da177e4 LT |
61 | } |
62 | ||
63 | static void __exit button_exit(void) | |
64 | { | |
85796e7d | 65 | input_unregister_device(button_dev); |
1da177e4 LT |
66 | free_irq(BUTTON_IRQ, button_interrupt); |
67 | } | |
68 | ||
69 | module_init(button_init); | |
70 | module_exit(button_exit); | |
71 | ||
72 | 1.1 What the example does | |
73 | ~~~~~~~~~~~~~~~~~~~~~~~~~ | |
74 | ||
75 | First it has to include the <linux/input.h> file, which interfaces to the | |
76 | input subsystem. This provides all the definitions needed. | |
77 | ||
78 | In the _init function, which is called either upon module load or when | |
79 | booting the kernel, it grabs the required resources (it should also check | |
80 | for the presence of the device). | |
81 | ||
01dd2fbf | 82 | Then it allocates a new input device structure with input_allocate_device() |
85796e7d | 83 | and sets up input bitfields. This way the device driver tells the other |
1da177e4 | 84 | parts of the input systems what it is - what events can be generated or |
85796e7d DT |
85 | accepted by this input device. Our example device can only generate EV_KEY |
86 | type events, and from those only BTN_0 event code. Thus we only set these | |
87 | two bits. We could have used | |
1da177e4 LT |
88 | |
89 | set_bit(EV_KEY, button_dev.evbit); | |
90 | set_bit(BTN_0, button_dev.keybit); | |
91 | ||
92 | as well, but with more than single bits the first approach tends to be | |
85796e7d | 93 | shorter. |
1da177e4 LT |
94 | |
95 | Then the example driver registers the input device structure by calling | |
96 | ||
97 | input_register_device(&button_dev); | |
98 | ||
99 | This adds the button_dev structure to linked lists of the input driver and | |
100 | calls device handler modules _connect functions to tell them a new input | |
85796e7d DT |
101 | device has appeared. input_register_device() may sleep and therefore must |
102 | not be called from an interrupt or with a spinlock held. | |
1da177e4 LT |
103 | |
104 | While in use, the only used function of the driver is | |
105 | ||
106 | button_interrupt() | |
107 | ||
108 | which upon every interrupt from the button checks its state and reports it | |
85796e7d | 109 | via the |
1da177e4 LT |
110 | |
111 | input_report_key() | |
112 | ||
113 | call to the input system. There is no need to check whether the interrupt | |
114 | routine isn't reporting two same value events (press, press for example) to | |
115 | the input system, because the input_report_* functions check that | |
116 | themselves. | |
117 | ||
118 | Then there is the | |
119 | ||
120 | input_sync() | |
121 | ||
122 | call to tell those who receive the events that we've sent a complete report. | |
123 | This doesn't seem important in the one button case, but is quite important | |
124 | for for example mouse movement, where you don't want the X and Y values | |
125 | to be interpreted separately, because that'd result in a different movement. | |
126 | ||
127 | 1.2 dev->open() and dev->close() | |
128 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
129 | ||
130 | In case the driver has to repeatedly poll the device, because it doesn't | |
131 | have an interrupt coming from it and the polling is too expensive to be done | |
132 | all the time, or if the device uses a valuable resource (eg. interrupt), it | |
133 | can use the open and close callback to know when it can stop polling or | |
134 | release the interrupt and when it must resume polling or grab the interrupt | |
135 | again. To do that, we would add this to our example driver: | |
136 | ||
1da177e4 LT |
137 | static int button_open(struct input_dev *dev) |
138 | { | |
1da177e4 LT |
139 | if (request_irq(BUTTON_IRQ, button_interrupt, 0, "button", NULL)) { |
140 | printk(KERN_ERR "button.c: Can't allocate irq %d\n", button_irq); | |
1da177e4 LT |
141 | return -EBUSY; |
142 | } | |
143 | ||
144 | return 0; | |
145 | } | |
146 | ||
147 | static void button_close(struct input_dev *dev) | |
148 | { | |
85796e7d | 149 | free_irq(IRQ_AMIGA_VERTB, button_interrupt); |
1da177e4 LT |
150 | } |
151 | ||
152 | static int __init button_init(void) | |
153 | { | |
154 | ... | |
85796e7d DT |
155 | button_dev->open = button_open; |
156 | button_dev->close = button_close; | |
1da177e4 LT |
157 | ... |
158 | } | |
159 | ||
85796e7d DT |
160 | Note that input core keeps track of number of users for the device and |
161 | makes sure that dev->open() is called only when the first user connects | |
162 | to the device and that dev->close() is called when the very last user | |
163 | disconnects. Calls to both callbacks are serialized. | |
1da177e4 LT |
164 | |
165 | The open() callback should return a 0 in case of success or any nonzero value | |
166 | in case of failure. The close() callback (which is void) must always succeed. | |
167 | ||
168 | 1.3 Basic event types | |
169 | ~~~~~~~~~~~~~~~~~~~~~ | |
170 | ||
171 | The most simple event type is EV_KEY, which is used for keys and buttons. | |
172 | It's reported to the input system via: | |
173 | ||
174 | input_report_key(struct input_dev *dev, int code, int value) | |
175 | ||
176 | See linux/input.h for the allowable values of code (from 0 to KEY_MAX). | |
177 | Value is interpreted as a truth value, ie any nonzero value means key | |
178 | pressed, zero value means key released. The input code generates events only | |
179 | in case the value is different from before. | |
180 | ||
181 | In addition to EV_KEY, there are two more basic event types: EV_REL and | |
182 | EV_ABS. They are used for relative and absolute values supplied by the | |
183 | device. A relative value may be for example a mouse movement in the X axis. | |
184 | The mouse reports it as a relative difference from the last position, | |
185 | because it doesn't have any absolute coordinate system to work in. Absolute | |
186 | events are namely for joysticks and digitizers - devices that do work in an | |
187 | absolute coordinate systems. | |
188 | ||
189 | Having the device report EV_REL buttons is as simple as with EV_KEY, simply | |
190 | set the corresponding bits and call the | |
191 | ||
192 | input_report_rel(struct input_dev *dev, int code, int value) | |
193 | ||
85796e7d | 194 | function. Events are generated only for nonzero value. |
1da177e4 LT |
195 | |
196 | However EV_ABS requires a little special care. Before calling | |
197 | input_register_device, you have to fill additional fields in the input_dev | |
198 | struct for each absolute axis your device has. If our button device had also | |
199 | the ABS_X axis: | |
200 | ||
201 | button_dev.absmin[ABS_X] = 0; | |
202 | button_dev.absmax[ABS_X] = 255; | |
203 | button_dev.absfuzz[ABS_X] = 4; | |
204 | button_dev.absflat[ABS_X] = 8; | |
205 | ||
85796e7d DT |
206 | Or, you can just say: |
207 | ||
208 | input_set_abs_params(button_dev, ABS_X, 0, 255, 4, 8); | |
209 | ||
1da177e4 LT |
210 | This setting would be appropriate for a joystick X axis, with the minimum of |
211 | 0, maximum of 255 (which the joystick *must* be able to reach, no problem if | |
212 | it sometimes reports more, but it must be able to always reach the min and | |
213 | max values), with noise in the data up to +- 4, and with a center flat | |
214 | position of size 8. | |
215 | ||
216 | If you don't need absfuzz and absflat, you can set them to zero, which mean | |
217 | that the thing is precise and always returns to exactly the center position | |
218 | (if it has any). | |
219 | ||
7b19ada2 | 220 | 1.4 BITS_TO_LONGS(), BIT_WORD(), BIT_MASK() |
1da177e4 LT |
221 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ |
222 | ||
7b19ada2 | 223 | These three macros from bitops.h help some bitfield computations: |
1da177e4 | 224 | |
7b19ada2 JS |
225 | BITS_TO_LONGS(x) - returns the length of a bitfield array in longs for |
226 | x bits | |
227 | BIT_WORD(x) - returns the index in the array in longs for bit x | |
228 | BIT_MASK(x) - returns the index in a long for bit x | |
1da177e4 | 229 | |
85796e7d | 230 | 1.5 The id* and name fields |
1da177e4 LT |
231 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
232 | ||
1da177e4 LT |
233 | The dev->name should be set before registering the input device by the input |
234 | device driver. It's a string like 'Generic button device' containing a | |
235 | user friendly name of the device. | |
236 | ||
237 | The id* fields contain the bus ID (PCI, USB, ...), vendor ID and device ID | |
238 | of the device. The bus IDs are defined in input.h. The vendor and device ids | |
239 | are defined in pci_ids.h, usb_ids.h and similar include files. These fields | |
240 | should be set by the input device driver before registering it. | |
241 | ||
242 | The idtype field can be used for specific information for the input device | |
243 | driver. | |
244 | ||
245 | The id and name fields can be passed to userland via the evdev interface. | |
246 | ||
85796e7d | 247 | 1.6 The keycode, keycodemax, keycodesize fields |
1da177e4 LT |
248 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
249 | ||
85796e7d DT |
250 | These three fields should be used by input devices that have dense keymaps. |
251 | The keycode is an array used to map from scancodes to input system keycodes. | |
252 | The keycode max should contain the size of the array and keycodesize the | |
253 | size of each entry in it (in bytes). | |
254 | ||
255 | Userspace can query and alter current scancode to keycode mappings using | |
256 | EVIOCGKEYCODE and EVIOCSKEYCODE ioctls on corresponding evdev interface. | |
257 | When a device has all 3 aforementioned fields filled in, the driver may | |
258 | rely on kernel's default implementation of setting and querying keycode | |
259 | mappings. | |
260 | ||
261 | 1.7 dev->getkeycode() and dev->setkeycode() | |
262 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
263 | getkeycode() and setkeycode() callbacks allow drivers to override default | |
264 | keycode/keycodesize/keycodemax mapping mechanism provided by input core | |
265 | and implement sparse keycode maps. | |
1da177e4 LT |
266 | |
267 | 1.8 Key autorepeat | |
268 | ~~~~~~~~~~~~~~~~~~ | |
269 | ||
270 | ... is simple. It is handled by the input.c module. Hardware autorepeat is | |
271 | not used, because it's not present in many devices and even where it is | |
272 | present, it is broken sometimes (at keyboards: Toshiba notebooks). To enable | |
273 | autorepeat for your device, just set EV_REP in dev->evbit. All will be | |
274 | handled by the input system. | |
275 | ||
276 | 1.9 Other event types, handling output events | |
277 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
278 | ||
279 | The other event types up to now are: | |
280 | ||
281 | EV_LED - used for the keyboard LEDs. | |
282 | EV_SND - used for keyboard beeps. | |
283 | ||
284 | They are very similar to for example key events, but they go in the other | |
285 | direction - from the system to the input device driver. If your input device | |
286 | driver can handle these events, it has to set the respective bits in evbit, | |
287 | *and* also the callback routine: | |
288 | ||
85796e7d | 289 | button_dev->event = button_event; |
1da177e4 LT |
290 | |
291 | int button_event(struct input_dev *dev, unsigned int type, unsigned int code, int value); | |
292 | { | |
293 | if (type == EV_SND && code == SND_BELL) { | |
294 | outb(value, BUTTON_BELL); | |
295 | return 0; | |
296 | } | |
297 | return -1; | |
298 | } | |
299 | ||
300 | This callback routine can be called from an interrupt or a BH (although that | |
301 | isn't a rule), and thus must not sleep, and must not take too long to finish. |