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