Commit 85796e7d939a39787f10a643477298678fed85db
1 parent
fd013ce8d4
Exists in
master
and in
4 other branches
Input: update some documentation
Input-programming.txt got out of sync with the latest changes in input core; let's refresh it. Signed-off-by: Dmitry Torokhov <dtor@mail.ru>
Showing 1 changed file with 72 additions and 53 deletions Side-by-side Diff
Documentation/input/input-programming.txt
1 | -$Id: input-programming.txt,v 1.4 2001/05/04 09:47:14 vojtech Exp $ | |
2 | - | |
3 | 1 | Programming input drivers |
4 | 2 | ~~~~~~~~~~~~~~~~~~~~~~~~~ |
5 | 3 | |
6 | 4 | |
7 | 5 | |
8 | 6 | |
9 | 7 | |
... | ... | @@ -20,28 +18,51 @@ |
20 | 18 | #include <asm/irq.h> |
21 | 19 | #include <asm/io.h> |
22 | 20 | |
21 | +static struct input_dev *button_dev; | |
22 | + | |
23 | 23 | static void button_interrupt(int irq, void *dummy, struct pt_regs *fp) |
24 | 24 | { |
25 | - input_report_key(&button_dev, BTN_1, inb(BUTTON_PORT) & 1); | |
26 | - input_sync(&button_dev); | |
25 | + input_report_key(button_dev, BTN_1, inb(BUTTON_PORT) & 1); | |
26 | + input_sync(button_dev); | |
27 | 27 | } |
28 | 28 | |
29 | 29 | static int __init button_init(void) |
30 | 30 | { |
31 | + int error; | |
32 | + | |
31 | 33 | if (request_irq(BUTTON_IRQ, button_interrupt, 0, "button", NULL)) { |
32 | 34 | printk(KERN_ERR "button.c: Can't allocate irq %d\n", button_irq); |
33 | 35 | return -EBUSY; |
34 | 36 | } |
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); | |
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 | + | |
45 | + button_dev->evbit[0] = BIT(EV_KEY); | |
46 | + button_dev->keybit[LONG(BTN_0)] = BIT(BTN_0); | |
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; | |
40 | 61 | } |
41 | 62 | |
42 | 63 | static void __exit button_exit(void) |
43 | 64 | { |
44 | - input_unregister_device(&button_dev); | |
65 | + input_unregister_device(button_dev); | |
45 | 66 | free_irq(BUTTON_IRQ, button_interrupt); |
46 | 67 | } |
47 | 68 | |
48 | 69 | |
49 | 70 | |
... | ... | @@ -58,17 +79,18 @@ |
58 | 79 | booting the kernel, it grabs the required resources (it should also check |
59 | 80 | for the presence of the device). |
60 | 81 | |
61 | -Then it sets the input bitfields. This way the device driver tells the other | |
82 | +Then it allocates a new input device structure with input_aloocate_device() | |
83 | +and sets up input bitfields. This way the device driver tells the other | |
62 | 84 | 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 | |
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 | |
66 | 88 | |
67 | 89 | set_bit(EV_KEY, button_dev.evbit); |
68 | 90 | set_bit(BTN_0, button_dev.keybit); |
69 | 91 | |
70 | 92 | as well, but with more than single bits the first approach tends to be |
71 | -shorter. | |
93 | +shorter. | |
72 | 94 | |
73 | 95 | Then the example driver registers the input device structure by calling |
74 | 96 | |
75 | 97 | |
... | ... | @@ -76,16 +98,15 @@ |
76 | 98 | |
77 | 99 | This adds the button_dev structure to linked lists of the input driver and |
78 | 100 | 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. | |
101 | +device has appeared. input_register_device() may sleep and therefore must | |
102 | +not be called from an interrupt or with a spinlock held. | |
82 | 103 | |
83 | 104 | While in use, the only used function of the driver is |
84 | 105 | |
85 | 106 | button_interrupt() |
86 | 107 | |
87 | 108 | which upon every interrupt from the button checks its state and reports it |
88 | -via the | |
109 | +via the | |
89 | 110 | |
90 | 111 | input_report_key() |
91 | 112 | |
92 | 113 | |
93 | 114 | |
... | ... | @@ -113,16 +134,10 @@ |
113 | 134 | release the interrupt and when it must resume polling or grab the interrupt |
114 | 135 | again. To do that, we would add this to our example driver: |
115 | 136 | |
116 | -int button_used = 0; | |
117 | - | |
118 | 137 | static int button_open(struct input_dev *dev) |
119 | 138 | { |
120 | - if (button_used++) | |
121 | - return 0; | |
122 | - | |
123 | 139 | if (request_irq(BUTTON_IRQ, button_interrupt, 0, "button", NULL)) { |
124 | 140 | printk(KERN_ERR "button.c: Can't allocate irq %d\n", button_irq); |
125 | - button_used--; | |
126 | 141 | return -EBUSY; |
127 | 142 | } |
128 | 143 | |
129 | 144 | |
130 | 145 | |
... | ... | @@ -131,20 +146,21 @@ |
131 | 146 | |
132 | 147 | static void button_close(struct input_dev *dev) |
133 | 148 | { |
134 | - if (!--button_used) | |
135 | - free_irq(IRQ_AMIGA_VERTB, button_interrupt); | |
149 | + free_irq(IRQ_AMIGA_VERTB, button_interrupt); | |
136 | 150 | } |
137 | 151 | |
138 | 152 | static int __init button_init(void) |
139 | 153 | { |
140 | 154 | ... |
141 | - button_dev.open = button_open; | |
142 | - button_dev.close = button_close; | |
155 | + button_dev->open = button_open; | |
156 | + button_dev->close = button_close; | |
143 | 157 | ... |
144 | 158 | } |
145 | 159 | |
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. | |
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. | |
148 | 164 | |
149 | 165 | The open() callback should return a 0 in case of success or any nonzero value |
150 | 166 | in case of failure. The close() callback (which is void) must always succeed. |
... | ... | @@ -175,7 +191,7 @@ |
175 | 191 | |
176 | 192 | input_report_rel(struct input_dev *dev, int code, int value) |
177 | 193 | |
178 | -function. Events are generated only for nonzero value. | |
194 | +function. Events are generated only for nonzero value. | |
179 | 195 | |
180 | 196 | However EV_ABS requires a little special care. Before calling |
181 | 197 | input_register_device, you have to fill additional fields in the input_dev |
... | ... | @@ -187,6 +203,10 @@ |
187 | 203 | button_dev.absfuzz[ABS_X] = 4; |
188 | 204 | button_dev.absflat[ABS_X] = 8; |
189 | 205 | |
206 | +Or, you can just say: | |
207 | + | |
208 | + input_set_abs_params(button_dev, ABS_X, 0, 255, 4, 8); | |
209 | + | |
190 | 210 | This setting would be appropriate for a joystick X axis, with the minimum of |
191 | 211 | 0, maximum of 255 (which the joystick *must* be able to reach, no problem if |
192 | 212 | it sometimes reports more, but it must be able to always reach the min and |
... | ... | @@ -197,14 +217,7 @@ |
197 | 217 | that the thing is precise and always returns to exactly the center position |
198 | 218 | (if it has any). |
199 | 219 | |
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() | |
220 | +1.4 NBITS(), LONG(), BIT() | |
208 | 221 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ |
209 | 222 | |
210 | 223 | These three macros from input.h help some bitfield computations: |
211 | 224 | |
... | ... | @@ -213,13 +226,9 @@ |
213 | 226 | LONG(x) - returns the index in the array in longs for bit x |
214 | 227 | BIT(x) - returns the index in a long for bit x |
215 | 228 | |
216 | -1.6 The number, id* and name fields | |
229 | +1.5 The id* and name fields | |
217 | 230 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
218 | 231 | |
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 | 232 | The dev->name should be set before registering the input device by the input |
224 | 233 | device driver. It's a string like 'Generic button device' containing a |
225 | 234 | user friendly name of the device. |
226 | 235 | |
227 | 236 | |
... | ... | @@ -234,16 +243,26 @@ |
234 | 243 | |
235 | 244 | The id and name fields can be passed to userland via the evdev interface. |
236 | 245 | |
237 | -1.7 The keycode, keycodemax, keycodesize fields | |
246 | +1.6 The keycode, keycodemax, keycodesize fields | |
238 | 247 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
239 | 248 | |
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). | |
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). | |
246 | 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 | + | |
260 | +1.7 dev->getkeycode() and dev->setkeycode() | |
261 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
262 | +getkeycode() and setkeycode() callbacks allow drivers to override default | |
263 | +keycode/keycodesize/keycodemax mapping mechanism provided by input core | |
264 | +and implement sparse keycode maps. | |
265 | + | |
247 | 266 | 1.8 Key autorepeat |
248 | 267 | ~~~~~~~~~~~~~~~~~~ |
249 | 268 | |
... | ... | @@ -266,7 +285,7 @@ |
266 | 285 | driver can handle these events, it has to set the respective bits in evbit, |
267 | 286 | *and* also the callback routine: |
268 | 287 | |
269 | - button_dev.event = button_event; | |
288 | + button_dev->event = button_event; | |
270 | 289 | |
271 | 290 | int button_event(struct input_dev *dev, unsigned int type, unsigned int code, int value); |
272 | 291 | { |