| 1 | ===============================
|
| 2 | Creating an input device driver
|
| 3 | ===============================
|
| 4 |
|
| 5 | The simplest example
|
| 6 | ~~~~~~~~~~~~~~~~~~~~
|
| 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
|
| 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 | ~~~~~~~~~~~~~~~~~~~~~
|
| 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 |
|
| 81 | Then it allocates a new input device structure with input_allocate_device()
|
| 82 | and sets up input bitfields. This way the device driver tells the other
|
| 83 | parts of the input systems what it is - what events can be generated or
|
| 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
|
| 86 | two bits. We could have used::
|
| 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
|
| 92 | shorter.
|
| 93 |
|
| 94 | Then the example driver registers the input device structure by calling::
|
| 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
|
| 100 | device has appeared. input_register_device() may sleep and therefore must
|
| 101 | not be called from an interrupt or with a spinlock held.
|
| 102 |
|
| 103 | While in use, the only used function of the driver is::
|
| 104 |
|
| 105 | button_interrupt()
|
| 106 |
|
| 107 | which upon every interrupt from the button checks its state and reports it
|
| 108 | via the::
|
| 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 |
|
| 117 | Then there is the::
|
| 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 example for 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 |
|
| 126 | dev->open() and dev->close()
|
| 127 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
| 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 (e.g. 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
|
| 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 | }
|
| 158 |
|
| 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.
|
| 163 |
|
| 164 | The open() callback should return a 0 in case of success or any non-zero value
|
| 165 | in case of failure. The close() callback (which is void) must always succeed.
|
| 166 |
|
| 167 | Inhibiting input devices
|
| 168 | ~~~~~~~~~~~~~~~~~~~~~~~~
|
| 169 |
|
| 170 | Inhibiting a device means ignoring input events from it. As such it is about
|
| 171 | maintaining relationships with input handlers - either already existing
|
| 172 | relationships, or relationships to be established while the device is in
|
| 173 | inhibited state.
|
| 174 |
|
| 175 | If a device is inhibited, no input handler will receive events from it.
|
| 176 |
|
| 177 | The fact that nobody wants events from the device is exploited further, by
|
| 178 | calling device's close() (if there are users) and open() (if there are users) on
|
| 179 | inhibit and uninhibit operations, respectively. Indeed, the meaning of close()
|
| 180 | is to stop providing events to the input core and that of open() is to start
|
| 181 | providing events to the input core.
|
| 182 |
|
| 183 | Calling the device's close() method on inhibit (if there are users) allows the
|
| 184 | driver to save power. Either by directly powering down the device or by
|
| 185 | releasing the runtime-PM reference it got in open() when the driver is using
|
| 186 | runtime-PM.
|
| 187 |
|
| 188 | Inhibiting and uninhibiting are orthogonal to opening and closing the device by
|
| 189 | input handlers. Userspace might want to inhibit a device in anticipation before
|
| 190 | any handler is positively matched against it.
|
| 191 |
|
| 192 | Inhibiting and uninhibiting are orthogonal to device's being a wakeup source,
|
| 193 | too. Being a wakeup source plays a role when the system is sleeping, not when
|
| 194 | the system is operating. How drivers should program their interaction between
|
| 195 | inhibiting, sleeping and being a wakeup source is driver-specific.
|
| 196 |
|
| 197 | Taking the analogy with the network devices - bringing a network interface down
|
| 198 | doesn't mean that it should be impossible be wake the system up on LAN through
|
| 199 | this interface. So, there may be input drivers which should be considered wakeup
|
| 200 | sources even when inhibited. Actually, in many I2C input devices their interrupt
|
| 201 | is declared a wakeup interrupt and its handling happens in driver's core, which
|
| 202 | is not aware of input-specific inhibit (nor should it be). Composite devices
|
| 203 | containing several interfaces can be inhibited on a per-interface basis and e.g.
|
| 204 | inhibiting one interface shouldn't affect the device's capability of being a
|
| 205 | wakeup source.
|
| 206 |
|
| 207 | If a device is to be considered a wakeup source while inhibited, special care
|
| 208 | must be taken when programming its suspend(), as it might need to call device's
|
| 209 | open(). Depending on what close() means for the device in question, not
|
| 210 | opening() it before going to sleep might make it impossible to provide any
|
| 211 | wakeup events. The device is going to sleep anyway.
|
| 212 |
|
| 213 | Basic event types
|
| 214 | ~~~~~~~~~~~~~~~~~
|
| 215 |
|
| 216 | The most simple event type is EV_KEY, which is used for keys and buttons.
|
| 217 | It's reported to the input system via::
|
| 218 |
|
| 219 | input_report_key(struct input_dev *dev, int code, int value)
|
| 220 |
|
| 221 | See uapi/linux/input-event-codes.h for the allowable values of code (from 0 to
|
| 222 | KEY_MAX). Value is interpreted as a truth value, i.e. any non-zero value means
|
| 223 | key pressed, zero value means key released. The input code generates events only
|
| 224 | in case the value is different from before.
|
| 225 |
|
| 226 | In addition to EV_KEY, there are two more basic event types: EV_REL and
|
| 227 | EV_ABS. They are used for relative and absolute values supplied by the
|
| 228 | device. A relative value may be for example a mouse movement in the X axis.
|
| 229 | The mouse reports it as a relative difference from the last position,
|
| 230 | because it doesn't have any absolute coordinate system to work in. Absolute
|
| 231 | events are namely for joysticks and digitizers - devices that do work in an
|
| 232 | absolute coordinate systems.
|
| 233 |
|
| 234 | Having the device report EV_REL buttons is as simple as with EV_KEY; simply
|
| 235 | set the corresponding bits and call the::
|
| 236 |
|
| 237 | input_report_rel(struct input_dev *dev, int code, int value)
|
| 238 |
|
| 239 | function. Events are generated only for non-zero values.
|
| 240 |
|
| 241 | However EV_ABS requires a little special care. Before calling
|
| 242 | input_register_device, you have to fill additional fields in the input_dev
|
| 243 | struct for each absolute axis your device has. If our button device had also
|
| 244 | the ABS_X axis::
|
| 245 |
|
| 246 | button_dev.absmin[ABS_X] = 0;
|
| 247 | button_dev.absmax[ABS_X] = 255;
|
| 248 | button_dev.absfuzz[ABS_X] = 4;
|
| 249 | button_dev.absflat[ABS_X] = 8;
|
| 250 |
|
| 251 | Or, you can just say::
|
| 252 |
|
| 253 | input_set_abs_params(button_dev, ABS_X, 0, 255, 4, 8);
|
| 254 |
|
| 255 | This setting would be appropriate for a joystick X axis, with the minimum of
|
| 256 | 0, maximum of 255 (which the joystick *must* be able to reach, no problem if
|
| 257 | it sometimes reports more, but it must be able to always reach the min and
|
| 258 | max values), with noise in the data up to +- 4, and with a center flat
|
| 259 | position of size 8.
|
| 260 |
|
| 261 | If you don't need absfuzz and absflat, you can set them to zero, which mean
|
| 262 | that the thing is precise and always returns to exactly the center position
|
| 263 | (if it has any).
|
| 264 |
|
| 265 | BITS_TO_LONGS(), BIT_WORD(), BIT_MASK()
|
| 266 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
| 267 |
|
| 268 | These three macros from bitops.h help some bitfield computations::
|
| 269 |
|
| 270 | BITS_TO_LONGS(x) - returns the length of a bitfield array in longs for
|
| 271 | x bits
|
| 272 | BIT_WORD(x) - returns the index in the array in longs for bit x
|
| 273 | BIT_MASK(x) - returns the index in a long for bit x
|
| 274 |
|
| 275 | The id* and name fields
|
| 276 | ~~~~~~~~~~~~~~~~~~~~~~~
|
| 277 |
|
| 278 | The dev->name should be set before registering the input device by the input
|
| 279 | device driver. It's a string like 'Generic button device' containing a
|
| 280 | user friendly name of the device.
|
| 281 |
|
| 282 | The id* fields contain the bus ID (PCI, USB, ...), vendor ID and device ID
|
| 283 | of the device. The bus IDs are defined in input.h. The vendor and device IDs
|
| 284 | are defined in pci_ids.h, usb_ids.h and similar include files. These fields
|
| 285 | should be set by the input device driver before registering it.
|
| 286 |
|
| 287 | The idtype field can be used for specific information for the input device
|
| 288 | driver.
|
| 289 |
|
| 290 | The id and name fields can be passed to userland via the evdev interface.
|
| 291 |
|
| 292 | The keycode, keycodemax, keycodesize fields
|
| 293 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
| 294 |
|
| 295 | These three fields should be used by input devices that have dense keymaps.
|
| 296 | The keycode is an array used to map from scancodes to input system keycodes.
|
| 297 | The keycode max should contain the size of the array and keycodesize the
|
| 298 | size of each entry in it (in bytes).
|
| 299 |
|
| 300 | Userspace can query and alter current scancode to keycode mappings using
|
| 301 | EVIOCGKEYCODE and EVIOCSKEYCODE ioctls on corresponding evdev interface.
|
| 302 | When a device has all 3 aforementioned fields filled in, the driver may
|
| 303 | rely on kernel's default implementation of setting and querying keycode
|
| 304 | mappings.
|
| 305 |
|
| 306 | dev->getkeycode() and dev->setkeycode()
|
| 307 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
| 308 |
|
| 309 | getkeycode() and setkeycode() callbacks allow drivers to override default
|
| 310 | keycode/keycodesize/keycodemax mapping mechanism provided by input core
|
| 311 | and implement sparse keycode maps.
|
| 312 |
|
| 313 | Key autorepeat
|
| 314 | ~~~~~~~~~~~~~~
|
| 315 |
|
| 316 | |
| 317 | not used, because it's not present in many devices and even where it is
|
| 318 | present, it is broken sometimes (at keyboards: Toshiba notebooks). To enable
|
| 319 | autorepeat for your device, just set EV_REP in dev->evbit. All will be
|
| 320 | handled by the input system.
|
| 321 |
|
| 322 | Other event types, handling output events
|
| 323 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
| 324 |
|
| 325 | The other event types up to now are:
|
| 326 |
|
| 327 | - EV_LED - used for the keyboard LEDs.
|
| 328 | - EV_SND - used for keyboard beeps.
|
| 329 |
|
| 330 | They are very similar to for example key events, but they go in the other
|
| 331 | direction - from the system to the input device driver. If your input device
|
| 332 | driver can handle these events, it has to set the respective bits in evbit,
|
| 333 | *and* also the callback routine::
|
| 334 |
|
| 335 | button_dev->event = button_event;
|
| 336 |
|
| 337 | int button_event(struct input_dev *dev, unsigned int type,
|
| 338 | unsigned int code, int value)
|
| 339 | {
|
| 340 | if (type == EV_SND && code == SND_BELL) {
|
| 341 | outb(value, BUTTON_BELL);
|
| 342 | return 0;
|
| 343 | }
|
| 344 | return -1;
|
| 345 | }
|
| 346 |
|
| 347 | This callback routine can be called from an interrupt or a BH (although that
|
| 348 | isn't a rule), and thus must not sleep, and must not take too long to finish.
|