diff options
author | Dmitry Torokhov <dtor@insightbb.com> | 2007-04-29 23:42:08 -0400 |
---|---|---|
committer | Dmitry Torokhov <dtor@insightbb.com> | 2007-04-29 23:42:08 -0400 |
commit | 85796e7d939a39787f10a643477298678fed85db (patch) | |
tree | c51a8d839ad7b436cd63270a806b875c625d3053 | |
parent | fd013ce8d42a6667bea2a3c6dca37da8842ab2bf (diff) |
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>
-rw-r--r-- | Documentation/input/input-programming.txt | 125 |
1 files changed, 72 insertions, 53 deletions
diff --git a/Documentation/input/input-programming.txt b/Documentation/input/input-programming.txt index 180e0689676c..d9d523099bb7 100644 --- a/Documentation/input/input-programming.txt +++ b/Documentation/input/input-programming.txt | |||
@@ -1,5 +1,3 @@ | |||
1 | $Id: input-programming.txt,v 1.4 2001/05/04 09:47:14 vojtech Exp $ | ||
2 | |||
3 | Programming input drivers | 1 | Programming input drivers |
4 | ~~~~~~~~~~~~~~~~~~~~~~~~~ | 2 | ~~~~~~~~~~~~~~~~~~~~~~~~~ |
5 | 3 | ||
@@ -20,28 +18,51 @@ pressed or released a BUTTON_IRQ happens. The driver could look like: | |||
20 | #include <asm/irq.h> | 18 | #include <asm/irq.h> |
21 | #include <asm/io.h> | 19 | #include <asm/io.h> |
22 | 20 | ||
21 | static struct input_dev *button_dev; | ||
22 | |||
23 | static void button_interrupt(int irq, void *dummy, struct pt_regs *fp) | 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); | 25 | input_report_key(button_dev, BTN_1, inb(BUTTON_PORT) & 1); |
26 | input_sync(&button_dev); | 26 | input_sync(button_dev); |
27 | } | 27 | } |
28 | 28 | ||
29 | static int __init button_init(void) | 29 | static int __init button_init(void) |
30 | { | 30 | { |
31 | int error; | ||
32 | |||
31 | if (request_irq(BUTTON_IRQ, button_interrupt, 0, "button", NULL)) { | 33 | if (request_irq(BUTTON_IRQ, button_interrupt, 0, "button", NULL)) { |
32 | printk(KERN_ERR "button.c: Can't allocate irq %d\n", button_irq); | 34 | printk(KERN_ERR "button.c: Can't allocate irq %d\n", button_irq); |
33 | return -EBUSY; | 35 | return -EBUSY; |
34 | } | 36 | } |
35 | 37 | ||
36 | button_dev.evbit[0] = BIT(EV_KEY); | 38 | button_dev = input_allocate_device(); |
37 | button_dev.keybit[LONG(BTN_0)] = BIT(BTN_0); | 39 | if (!button_dev) { |
38 | 40 | printk(KERN_ERR "button.c: Not enough memory\n"); | |
39 | input_register_device(&button_dev); | 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 | static void __exit button_exit(void) | 63 | static void __exit button_exit(void) |
43 | { | 64 | { |
44 | input_unregister_device(&button_dev); | 65 | input_unregister_device(button_dev); |
45 | free_irq(BUTTON_IRQ, button_interrupt); | 66 | free_irq(BUTTON_IRQ, button_interrupt); |
46 | } | 67 | } |
47 | 68 | ||
@@ -58,17 +79,18 @@ 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 | 79 | booting the kernel, it grabs the required resources (it should also check |
59 | for the presence of the device). | 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 | parts of the input systems what it is - what events can be generated or | 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 | 85 | accepted by this input device. Our example device can only generate EV_KEY |
64 | events, and from those only BTN_0 event code. Thus we only set these two | 86 | type events, and from those only BTN_0 event code. Thus we only set these |
65 | bits. We could have used | 87 | two bits. We could have used |
66 | 88 | ||
67 | set_bit(EV_KEY, button_dev.evbit); | 89 | set_bit(EV_KEY, button_dev.evbit); |
68 | set_bit(BTN_0, button_dev.keybit); | 90 | set_bit(BTN_0, button_dev.keybit); |
69 | 91 | ||
70 | as well, but with more than single bits the first approach tends to be | 92 | as well, but with more than single bits the first approach tends to be |
71 | shorter. | 93 | shorter. |
72 | 94 | ||
73 | Then the example driver registers the input device structure by calling | 95 | Then the example driver registers the input device structure by calling |
74 | 96 | ||
@@ -76,16 +98,15 @@ Then the example driver registers the input device structure by calling | |||
76 | 98 | ||
77 | This adds the button_dev structure to linked lists of the input driver and | 99 | 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 | 100 | calls device handler modules _connect functions to tell them a new input |
79 | device has appeared. Because the _connect functions may call kmalloc(, | 101 | device has appeared. input_register_device() may sleep and therefore must |
80 | GFP_KERNEL), which can sleep, input_register_device() must not be called | 102 | not be called from an interrupt or with a spinlock held. |
81 | from an interrupt or with a spinlock held. | ||
82 | 103 | ||
83 | While in use, the only used function of the driver is | 104 | While in use, the only used function of the driver is |
84 | 105 | ||
85 | button_interrupt() | 106 | button_interrupt() |
86 | 107 | ||
87 | which upon every interrupt from the button checks its state and reports it | 108 | which upon every interrupt from the button checks its state and reports it |
88 | via the | 109 | via the |
89 | 110 | ||
90 | input_report_key() | 111 | input_report_key() |
91 | 112 | ||
@@ -113,16 +134,10 @@ 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 | 134 | 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: | 135 | again. To do that, we would add this to our example driver: |
115 | 136 | ||
116 | int button_used = 0; | ||
117 | |||
118 | static int button_open(struct input_dev *dev) | 137 | static int button_open(struct input_dev *dev) |
119 | { | 138 | { |
120 | if (button_used++) | ||
121 | return 0; | ||
122 | |||
123 | if (request_irq(BUTTON_IRQ, button_interrupt, 0, "button", NULL)) { | 139 | if (request_irq(BUTTON_IRQ, button_interrupt, 0, "button", NULL)) { |
124 | printk(KERN_ERR "button.c: Can't allocate irq %d\n", button_irq); | 140 | printk(KERN_ERR "button.c: Can't allocate irq %d\n", button_irq); |
125 | button_used--; | ||
126 | return -EBUSY; | 141 | return -EBUSY; |
127 | } | 142 | } |
128 | 143 | ||
@@ -131,20 +146,21 @@ static int button_open(struct input_dev *dev) | |||
131 | 146 | ||
132 | static void button_close(struct input_dev *dev) | 147 | static void button_close(struct input_dev *dev) |
133 | { | 148 | { |
134 | if (!--button_used) | 149 | free_irq(IRQ_AMIGA_VERTB, button_interrupt); |
135 | free_irq(IRQ_AMIGA_VERTB, button_interrupt); | ||
136 | } | 150 | } |
137 | 151 | ||
138 | static int __init button_init(void) | 152 | static int __init button_init(void) |
139 | { | 153 | { |
140 | ... | 154 | ... |
141 | button_dev.open = button_open; | 155 | button_dev->open = button_open; |
142 | button_dev.close = button_close; | 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 | 160 | Note that input core keeps track of number of users for the device and |
147 | function was called to know when exactly our device stops being used. | 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 | The open() callback should return a 0 in case of success or any nonzero value | 165 | 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. | 166 | in case of failure. The close() callback (which is void) must always succeed. |
@@ -175,7 +191,7 @@ set the corresponding bits and call the | |||
175 | 191 | ||
176 | input_report_rel(struct input_dev *dev, int code, int value) | 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 | However EV_ABS requires a little special care. Before calling | 196 | However EV_ABS requires a little special care. Before calling |
181 | input_register_device, you have to fill additional fields in the input_dev | 197 | input_register_device, you have to fill additional fields in the input_dev |
@@ -187,6 +203,10 @@ the ABS_X axis: | |||
187 | button_dev.absfuzz[ABS_X] = 4; | 203 | button_dev.absfuzz[ABS_X] = 4; |
188 | button_dev.absflat[ABS_X] = 8; | 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 | This setting would be appropriate for a joystick X axis, with the minimum of | 210 | 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 | 211 | 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 | 212 | it sometimes reports more, but it must be able to always reach the min and |
@@ -197,14 +217,7 @@ 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 | 217 | that the thing is precise and always returns to exactly the center position |
198 | (if it has any). | 218 | (if it has any). |
199 | 219 | ||
200 | 1.4 The void *private field | 220 | 1.4 NBITS(), LONG(), BIT() |
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 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | 221 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ |
209 | 222 | ||
210 | These three macros from input.h help some bitfield computations: | 223 | These three macros from input.h help some bitfield computations: |
@@ -213,13 +226,9 @@ These three macros from input.h help some bitfield computations: | |||
213 | LONG(x) - returns the index in the array in longs for bit x | 226 | 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 | 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 | The dev->name should be set before registering the input device by the input | 232 | 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 | 233 | device driver. It's a string like 'Generic button device' containing a |
225 | user friendly name of the device. | 234 | user friendly name of the device. |
@@ -234,15 +243,25 @@ driver. | |||
234 | 243 | ||
235 | The id and name fields can be passed to userland via the evdev interface. | 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 | 249 | These three fields should be used by input devices that have dense keymaps. |
241 | as scancodes. If not all scancodes can be known by autodetection, they may | 250 | The keycode is an array used to map from scancodes to input system keycodes. |
242 | need to be set by userland utilities. The keycode array then is an array | 251 | The keycode max should contain the size of the array and keycodesize the |
243 | used to map from scancodes to input system keycodes. The keycode max will | 252 | size of each entry in it (in bytes). |
244 | contain the size of the array and keycodesize the size of each entry in it | 253 | |
245 | (in bytes). | 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. | ||
246 | 265 | ||
247 | 1.8 Key autorepeat | 266 | 1.8 Key autorepeat |
248 | ~~~~~~~~~~~~~~~~~~ | 267 | ~~~~~~~~~~~~~~~~~~ |
@@ -266,7 +285,7 @@ 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, | 285 | driver can handle these events, it has to set the respective bits in evbit, |
267 | *and* also the callback routine: | 286 | *and* also the callback routine: |
268 | 287 | ||
269 | button_dev.event = button_event; | 288 | button_dev->event = button_event; |
270 | 289 | ||
271 | int button_event(struct input_dev *dev, unsigned int type, unsigned int code, int value); | 290 | int button_event(struct input_dev *dev, unsigned int type, unsigned int code, int value); |
272 | { | 291 | { |