Documentation/input/input-programming.rst

2 Creating an input device driver
8 Here comes a very simple example of an input device driver. The device has
12     #include <linux/input.h>
34 		    return -EBUSY;
40 		    error = -ENOMEM;
44 	    button_dev->evbit[0] = BIT_MASK(EV_KEY);
45 	    button_dev->keybit[BIT_WORD(BTN_0)] = BIT_MASK(BTN_0);
74 First it has to include the <linux/input.h> file, which interfaces to the
75 input subsystem. This provides all the definitions needed.
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
88 	set_bit(EV_KEY, button_dev->evbit);
89 	set_bit(BTN_0, button_dev->keybit);
94 Then the example driver registers the input device structure by calling::
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
112 call to the input system. There is no need to check whether the interrupt
114 the input system, because the input_report_* functions check that
126 dev->open() and dev->close()
140 		    return -EBUSY;
154 	    button_dev->open = button_open;
155 	    button_dev->close = button_close;
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
164 The open() callback should return a 0 in case of success or any non-zero value
167 Inhibiting input devices
170 Inhibiting a device means ignoring input events from it. As such it is about
171 maintaining relationships with input handlers - either already existing
175 If a device is inhibited, no input handler will receive events from it.
180 is to stop providing events to the input core and that of open() is to start
181 providing events to the input core.
185 releasing the runtime-PM reference it got in open() when the driver is using
186 runtime-PM.
189 input handlers. Userspace might want to inhibit a device in anticipation before
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
195 inhibiting, sleeping and being a wakeup source is driver-specific.
197 Taking the analogy with the network devices - bringing a network interface down
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.
205 wakeup source.
207 If a device is to be considered a wakeup source while inhibited, special care
211 wakeup events. The device is going to sleep anyway.
217 It's reported to the input system via::
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
231 events are namely for joysticks and digitizers - devices that do work in an
239 function. Events are generated only for non-zero values.
258 max values), with noise in the data up to +- 4, and with a center flat
270 	BITS_TO_LONGS(x) - returns the length of a bitfield array in longs for
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
278 The dev->name should be set before registering the input device by the input
283 of the device. The bus IDs are defined in input.h. The vendor and device IDs
285 should be set by the input device driver before registering it.
287 The idtype field can be used for specific information for the input device
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.
306 dev->getkeycode() and dev->setkeycode()
310 keycode/keycodesize/keycodemax mapping mechanism provided by input core
316 ... is simple. It is handled by the input.c module. Hardware autorepeat is
319 autorepeat for your device, just set EV_REP in dev->evbit. All will be
320 handled by the input system.
327 - EV_LED - used for the keyboard LEDs.
328 - EV_SND - used for keyboard beeps.
331 direction - from the system to the input device driver. If your input device
335     button_dev->event = button_event;
344 	    return -1;