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