Input Subsystem¶
Input core¶
- struct
input_value¶ input value representation
Definition
struct input_value { __u16 type; __u16 code; __s32 value;};Members
type- type of value (EV_KEY, EV_ABS, etc)
code- the value code
value- the value
- struct
input_dev¶ represents an input device
Definition
struct input_dev { const char *name; const char *phys; const char *uniq; struct input_id id; unsigned long propbit[BITS_TO_LONGS(INPUT_PROP_CNT)]; unsigned long evbit[BITS_TO_LONGS(EV_CNT)]; unsigned long keybit[BITS_TO_LONGS(KEY_CNT)]; unsigned long relbit[BITS_TO_LONGS(REL_CNT)]; unsigned long absbit[BITS_TO_LONGS(ABS_CNT)]; unsigned long mscbit[BITS_TO_LONGS(MSC_CNT)]; unsigned long ledbit[BITS_TO_LONGS(LED_CNT)]; unsigned long sndbit[BITS_TO_LONGS(SND_CNT)]; unsigned long ffbit[BITS_TO_LONGS(FF_CNT)]; unsigned long swbit[BITS_TO_LONGS(SW_CNT)]; unsigned int hint_events_per_packet; unsigned int keycodemax; unsigned int keycodesize; void *keycode; int (*setkeycode)(struct input_dev *dev,const struct input_keymap_entry *ke, unsigned int *old_keycode); int (*getkeycode)(struct input_dev *dev, struct input_keymap_entry *ke); struct ff_device *ff; struct input_dev_poller *poller; unsigned int repeat_key; struct timer_list timer; int rep[REP_CNT]; struct input_mt *mt; struct input_absinfo *absinfo; unsigned long key[BITS_TO_LONGS(KEY_CNT)]; unsigned long led[BITS_TO_LONGS(LED_CNT)]; unsigned long snd[BITS_TO_LONGS(SND_CNT)]; unsigned long sw[BITS_TO_LONGS(SW_CNT)]; int (*open)(struct input_dev *dev); void (*close)(struct input_dev *dev); int (*flush)(struct input_dev *dev, struct file *file); int (*event)(struct input_dev *dev, unsigned int type, unsigned int code, int value); struct input_handle __rcu *grab; spinlock_t event_lock; struct mutex mutex; unsigned int users; bool going_away; struct device dev; struct list_head h_list; struct list_head node; unsigned int num_vals; unsigned int max_vals; struct input_value *vals; bool devres_managed; ktime_t timestamp[INPUT_CLK_MAX];};Members
name- name of the device
phys- physical path to the device in the system hierarchy
uniq- unique identification code for the device (if device has it)
id- id of the device (struct input_id)
propbit- bitmap of device properties and quirks
evbit- bitmap of types of events supported by the device (EV_KEY,EV_REL, etc.)
keybit- bitmap of keys/buttons this device has
relbit- bitmap of relative axes for the device
absbit- bitmap of absolute axes for the device
mscbit- bitmap of miscellaneous events supported by the device
ledbit- bitmap of leds present on the device
sndbit- bitmap of sound effects supported by the device
ffbit- bitmap of force feedback effects supported by the device
swbit- bitmap of switches present on the device
hint_events_per_packet- average number of events generated by thedevice in a packet (between EV_SYN/SYN_REPORT events). Used byevent handlers to estimate size of the buffer needed to holdevents.
keycodemax- size of keycode table
keycodesize- size of elements in keycode table
keycode- map of scancodes to keycodes for this device
setkeycode- optional method to alter current keymap, used to implementsparse keymaps. If not supplied default mechanism will be used.The method is being called while holding event_lock and thus mustnot sleep
getkeycode- optional legacy method to retrieve current keymap.
ff- force feedback structure associated with the device if devicesupports force feedback effects
poller- poller structure associated with the device if device isset up to use polling mode
repeat_key- stores key code of the last key pressed; used to implementsoftware autorepeat
timer- timer for software autorepeat
rep- current values for autorepeat parameters (delay, rate)
mt- pointer to multitouch state
absinfo- array of
structinput_absinfoelements holding informationabout absolute axes (current value, min, max, flat, fuzz,resolution) key- reflects current state of device’s keys/buttons
led- reflects current state of device’s LEDs
snd- reflects current state of sound effects
sw- reflects current state of device’s switches
open- this method is called when the very first user calls
input_open_device(). The driver must prepare the deviceto start generating events (start polling thread,request an IRQ, submit URB, etc.) close- this method is called when the very last user calls
input_close_device(). flush- purges the device. Most commonly used to get rid of forcefeedback effects loaded into the device when disconnectingfrom it
event- event handler for events sent _to_ the device, like EV_LEDor EV_SND. The device is expected to carry out the requestedaction (turn on a LED, play sound, etc.) The call is protectedbyevent_lock and must not sleep
grab- input handle that currently has the device grabbed (viaEVIOCGRAB ioctl). When a handle grabs a device it becomes solerecipient for all input events coming from the device
event_lock- this spinlock is taken when input core receivesand processes a new event for the device (in
input_event()).Code that accesses and/or modifies parameters of a device(such as keymap or absmin, absmax, absfuzz, etc.) after devicehas been registered with input core must take this lock. mutex- serializes calls to open(), close() and flush() methods
users- stores number of users (input handlers) that opened thisdevice. It is used by
input_open_device()andinput_close_device()to make sure that dev->open() is only called when the firstuser opens device and dev->close() is called when the verylast user closes the device going_away- marks devices that are in a middle of unregistering andcauses input_open_device*() fail with -ENODEV.
dev- driver model’s view of this device
h_list- list of input handles associated with the device. Whenaccessing the list dev->mutex must be held
node- used to place the device onto input_dev_list
num_vals- number of values queued in the current frame
max_vals- maximum number of values queued in a frame
vals- array of values queued in the current frame
devres_managed- indicates that devices is managed with devres frameworkand needs not be explicitly unregistered or freed.
timestamp- storage for a timestamp set by input_set_timestamp calledby a driver
- struct
input_handler¶ implements one of interfaces for input devices
Definition
struct input_handler { void *private; void (*event)(struct input_handle *handle, unsigned int type, unsigned int code, int value); void (*events)(struct input_handle *handle, const struct input_value *vals, unsigned int count); bool (*filter)(struct input_handle *handle, unsigned int type, unsigned int code, int value); bool (*match)(struct input_handler *handler, struct input_dev *dev); int (*connect)(struct input_handler *handler, struct input_dev *dev, const struct input_device_id *id); void (*disconnect)(struct input_handle *handle); void (*start)(struct input_handle *handle); bool legacy_minors; int minor; const char *name; const struct input_device_id *id_table; struct list_head h_list; struct list_head node;};Members
private- driver-specific data
event- event handler. This method is being called by input core withinterrupts disabled and dev->event_lock spinlock held and soit may not sleep
events- event sequence handler. This method is being called byinput core with interrupts disabled and dev->event_lockspinlock held and so it may not sleep
filter- similar toevent; separates normal event handlers from“filters”.
match- called after comparing device’s id with handler’s id_tableto perform fine-grained matching between device and handler
connect- called when attaching a handler to an input device
disconnect- disconnects a handler from input device
start- starts handler for given handle. This function is called byinput core right after connect() method and also when a processthat “grabbed” a device releases it
legacy_minors- set to
trueby drivers using legacy minor ranges minor- beginning of range of 32 legacy minors for devices this drivercan provide
name- name of the handler, to be shown in /proc/bus/input/handlers
id_table- pointer to a table of input_device_ids this driver canhandle
h_list- list of input handles associated with the handler
node- for placing the driver onto input_handler_list
Description
Input handlers attach to input devices and create input handles. Thereare likely several handlers attached to any given input device at thesame time. All of them will get their copy of input event generated bythe device.
The very same structure is used to implement input filters. Input coreallows filters to run first and will not pass event to regular handlersif any of the filters indicate that the event should be filtered (byreturningtrue from their filter() method).
Note that input core serializes calls to connect() and disconnect()methods.
- struct
input_handle¶ links input device with an input handler
Definition
struct input_handle { void *private; int open; const char *name; struct input_dev *dev; struct input_handler *handler; struct list_head d_node; struct list_head h_node;};Members
private- handler-specific data
open- counter showing whether the handle is ‘open’, i.e. should deliverevents from its device
name- name given to the handle by handler that created it
dev- input device the handle is attached to
handler- handler that works with the device through this handle
d_node- used to put the handle on device’s list of attached handles
h_node- used to put the handle on handler’s list of handles from whichit gets events
- void
input_set_events_per_packet(structinput_dev * dev, int n_events)¶ tell handlers about the driver event rate
Parameters
structinput_dev*dev- the input device used by the driver
intn_events- the average number of events between calls to input_sync()
Description
If the event rate sent from a device is unusually large, use thisfunction to set the expected event rate. This will allow handlersto set up an appropriate buffer size for the event stream, in orderto minimize information loss.
- struct
ff_device¶ force-feedback part of an input device
Definition
struct ff_device { int (*upload)(struct input_dev *dev, struct ff_effect *effect, struct ff_effect *old); int (*erase)(struct input_dev *dev, int effect_id); int (*playback)(struct input_dev *dev, int effect_id, int value); void (*set_gain)(struct input_dev *dev, u16 gain); void (*set_autocenter)(struct input_dev *dev, u16 magnitude); void (*destroy)(struct ff_device *); void *private; unsigned long ffbit[BITS_TO_LONGS(FF_CNT)]; struct mutex mutex; int max_effects; struct ff_effect *effects; struct file *effect_owners[];};Members
upload- Called to upload an new effect into device
erase- Called to erase an effect from device
playback- Called to request device to start playing specified effect
set_gain- Called to set specified gain
set_autocenter- Called to auto-center device
destroy- called by input core when parent input device is beingdestroyed
private- driver-specific data, will be freed automatically
ffbit- bitmap of force feedback capabilities truly supported bydevice (not emulated like ones in input_dev->ffbit)
mutex- mutex for serializing access to the device
max_effects- maximum number of effects supported by device
effects- pointer to an array of effects currently loaded into device
effect_owners- array of effect owners; when file handle owningan effect gets closed the effect is automatically erased
Description
Every force-feedback device must implement upload() and playback()methods; erase() is optional. set_gain() and set_autocenter() needonly be implemented if driver sets up FF_GAIN and FF_AUTOCENTERbits.
Note that playback(), set_gain() and set_autocenter() are called withdev->event_lock spinlock held and interrupts off and thus may notsleep.
- void
input_event(structinput_dev * dev, unsigned int type, unsigned int code, int value)¶ report new input event
Parameters
structinput_dev*dev- device that generated the event
unsignedinttype- type of the event
unsignedintcode- event code
intvalue- value of the event
Description
This function should be used by drivers implementing various inputdevices to report input events. See alsoinput_inject_event().
NOTE
input_event() may be safely used right after input device wasallocated withinput_allocate_device(), even before it is registeredwithinput_register_device(), but the event will not reach any of theinput handlers. Such early invocation ofinput_event() may be usedto ‘seed’ initial state of a switch or initial position of absoluteaxis, etc.
- void
input_inject_event(structinput_handle * handle, unsigned int type, unsigned int code, int value)¶ send input event from input handler
Parameters
structinput_handle*handle- input handle to send event through
unsignedinttype- type of the event
unsignedintcode- event code
intvalue- value of the event
Description
Similar toinput_event() but will ignore event if device is“grabbed” and handle injecting event is not the one that ownsthe device.
Parameters
structinput_dev*dev- the input device emitting absolute events
Description
If the absinfo struct the caller asked for is already allocated, thisfunctions will not do anything.
- int
input_grab_device(structinput_handle * handle)¶ grabs device for exclusive use
Parameters
structinput_handle*handle- input handle that wants to own the device
Description
When a device is grabbed by an input handle all events generated bythe device are delivered only to this handle. Also events injectedby other input handles are ignored while device is grabbed.
- void
input_release_device(structinput_handle * handle)¶ release previously grabbed device
Parameters
structinput_handle*handle- input handle that owns the device
Description
Releases previously grabbed device so that other input handles canstart receiving input events. Upon release all handlers attachedto the device have their start() method called so they have a changeto synchronize device state with the rest of the system.
- int
input_open_device(structinput_handle * handle)¶ open input device
Parameters
structinput_handle*handle- handle through which device is being accessed
Description
This function should be called by input handlers when theywant to start receive events from given input device.
- void
input_close_device(structinput_handle * handle)¶ close input device
Parameters
structinput_handle*handle- handle through which device is being accessed
Description
This function should be called by input handlers when theywant to stop receive events from given input device.
- int
input_scancode_to_scalar(const struct input_keymap_entry * ke, unsigned int * scancode)¶ converts scancode in
structinput_keymap_entry
Parameters
conststructinput_keymap_entry*ke- keymap entry containing scancode to be converted.
unsignedint*scancode- pointer to the location where converted scancode shouldbe stored.
Description
This function is used to convert scancode stored instructkeymap_entryinto scalar form understood by legacy keymap handling methods. Thesemethods expect scancodes to be represented as ‘unsigned int’.
- int
input_get_keycode(structinput_dev * dev, struct input_keymap_entry * ke)¶ retrieve keycode currently mapped to a given scancode
Parameters
structinput_dev*dev- input device which keymap is being queried
structinput_keymap_entry*ke- keymap entry
Description
This function should be called by anyone interested in retrieving currentkeymap. Presently evdev handlers use it.
- int
input_set_keycode(structinput_dev * dev, const struct input_keymap_entry * ke)¶ attribute a keycode to a given scancode
Parameters
structinput_dev*dev- input device which keymap is being updated
conststructinput_keymap_entry*ke- new keymap entry
Description
This function should be called by anyone needing to update currentkeymap. Presently keyboard and evdev handlers use it.
Parameters
structinput_dev*dev- input device whose state needs to be reset
Description
This function tries to reset the state of an opened input device andbring internal state and state if the hardware in sync with each other.We mark all keys as released, restore LED state, repeat rate, etc.
Parameters
void- no arguments
Description
Returns prepared struct input_dev orNULL.
NOTE
Useinput_free_device() to free devices that have not beenregistered;input_unregister_device() should be used for alreadyregistered devices.
Parameters
structdevice*dev- device owning the input device being created
Description
Returns prepared struct input_dev orNULL.
Managed input devices do not need to be explicitly unregistered orfreed as it will be done automatically when owner device unbinds fromits driver (or binding fails). Once managed input device is allocated,it is ready to be set up and registered in the same fashion as regularinput device. There are no special devm_input_device_[un]register()variants, regular ones work with both managed and unmanaged devices,should you need them. In most cases however, managed input device neednot be explicitly unregistered or freed.
NOTE
the owner device is set up as parent of input device and usersshould not override it.
Parameters
structinput_dev*dev- input device to free
Description
This function should only be used ifinput_register_device()was not called yet or if it failed. Once device was registereduseinput_unregister_device() and memory will be freed once lastreference to the device is dropped.
Device should be allocated byinput_allocate_device().
NOTE
If there are references to the input device then memorywill not be freed until last reference is dropped.
Parameters
structinput_dev*dev- input device to set timestamp for
ktime_ttimestamp- the time at which the event has occurredin CLOCK_MONOTONIC
Description
This function is intended to provide to the input system a moreaccurate time of when an event actually occurred. The driver shouldcall this function as soon as a timestamp is acquired ensuringclock conversions in input_set_timestamp are done correctly.
The system entering suspend state between timestamp acquisition andcalling input_set_timestamp can result in inaccurate conversions.
Parameters
structinput_dev*dev- input device to get timestamp from
Description
A valid timestamp is a timestamp of non-zero value.
- void
input_set_capability(structinput_dev * dev, unsigned int type, unsigned int code)¶ mark device as capable of a certain event
Parameters
structinput_dev*dev- device that is capable of emitting or accepting event
unsignedinttype- type of the event (EV_KEY, EV_REL, etc…)
unsignedintcode- event code
Description
In addition to setting up corresponding bit in appropriate capabilitybitmap the function also adjusts dev->evbit.
- void
input_enable_softrepeat(structinput_dev * dev, int delay, int period)¶ enable software autorepeat
Parameters
structinput_dev*dev- input device
intdelay- repeat delay
intperiod- repeat period
Description
Enable software autorepeat on the input device.
Parameters
structinput_dev*dev- device to be registered
Description
This function registers device with input core. The device must beallocated withinput_allocate_device() and all it’s capabilitiesset up before registering.If function fails the device must be freed withinput_free_device().Once device has been successfully registered it can be unregisteredwithinput_unregister_device();input_free_device() should not becalled in this case.
Note that this function is also used to register managed input devices(ones allocated withdevm_input_allocate_device()). Such managed inputdevices need not be explicitly unregistered or freed, their tear downis controlled by the devres infrastructure. It is also worth notingthat tear down of managed input devices is internally a 2-step process:registered managed input device is first unregistered, but stays inmemory and can still handleinput_event() calls (although events willnot be delivered anywhere). The freeing of managed input device willhappen later, when devres stack is unwound to the point where deviceallocation was made.
Parameters
structinput_dev*dev- device to be unregistered
Description
This function unregisters an input device. Once device is unregisteredthe caller should not try to access it as it may get freed at any moment.
- int
input_register_handler(structinput_handler * handler)¶ register a new input handler
Parameters
structinput_handler*handler- handler to be registered
Description
This function registers a new input handler (interface) for inputdevices in the system and attaches it to all input devices thatare compatible with the handler.
- void
input_unregister_handler(structinput_handler * handler)¶ unregisters an input handler
Parameters
structinput_handler*handler- handler to be unregistered
Description
This function disconnects a handler from its input devices andremoves it from lists of known handlers.
- int
input_handler_for_each_handle(structinput_handler * handler, void * data, int (*fn)(structinput_handle *, void *))¶ handle iterator
Parameters
structinput_handler*handler- input handler to iterate
void*data- data for the callback
int(*)(structinput_handle*,void*)fn- function to be called for each handle
Description
Iterate overbus’s list of devices, and callfn for each, passingitdata and stop whenfn returns a non-zero value. The function isusing RCU to traverse the list and therefore may be using in atomiccontexts. Thefn callback is invoked from RCU critical section andthus must not sleep.
- int
input_register_handle(structinput_handle * handle)¶ register a new input handle
Parameters
structinput_handle*handle- handle to register
Description
This function puts a new input handle onto device’sand handler’s lists so that events can flow throughit once it is opened usinginput_open_device().
This function is supposed to be called from handler’sconnect() method.
- void
input_unregister_handle(structinput_handle * handle)¶ unregister an input handle
Parameters
structinput_handle*handle- handle to unregister
Description
This function removes input handle from device’sand handler’s lists.
This function is supposed to be called from handler’sdisconnect() method.
- int
input_get_new_minor(int legacy_base, unsigned int legacy_num, bool allow_dynamic)¶ allocates a new input minor number
Parameters
intlegacy_base- beginning or the legacy range to be searched
unsignedintlegacy_num- size of legacy range
boolallow_dynamic- whether we can also take ID from the dynamic range
Description
This function allocates a new device minor for from input major namespace.Caller can request legacy minor by specifyinglegacy_base andlegacy_numparameters and whether ID can be allocated from dynamic range if there areno free IDs in legacy range.
- void
input_free_minor(unsigned int minor)¶ release previously allocated minor
Parameters
unsignedintminor- minor to be released
Description
This function releases previously allocated input minor so that it can bereused later.
- int
input_ff_upload(structinput_dev * dev, struct ff_effect * effect, struct file * file)¶ upload effect into force-feedback device
Parameters
structinput_dev*dev- input device
structff_effect*effect- effect to be uploaded
structfile*file- owner of the effect
- int
input_ff_erase(structinput_dev * dev, int effect_id, struct file * file)¶ erase a force-feedback effect from device
Parameters
structinput_dev*dev- input device to erase effect from
inteffect_id- id of the effect to be erased
structfile*file- purported owner of the request
Description
This function erases a force-feedback effect from specified device.The effect will only be erased if it was uploaded through the samefile handle that is requesting erase.
- int
input_ff_event(structinput_dev * dev, unsigned int type, unsigned int code, int value)¶ generic handler for force-feedback events
Parameters
structinput_dev*dev- input device to send the effect to
unsignedinttype- event type (anything but EV_FF is ignored)
unsignedintcode- event code
intvalue- event value
Parameters
structinput_dev*dev- input device supporting force-feedback
unsignedintmax_effects- maximum number of effects supported by the device
Description
This function allocates all necessary memory for a force feedbackportion of an input device and installs all default handlers.dev->ffbit should be already set up before calling this function.Once ff device is created you need to setup its upload, erase,playback and other handlers before registering input device
Parameters
structinput_dev*dev- input device supporting force feedback
Description
This function is only needed in error path as input core willautomatically free force feedback structures when device isdestroyed.
- int
input_ff_create_memless(structinput_dev * dev, void * data, int (*play_effect)(structinput_dev *, void *, struct ff_effect *))¶ create memoryless force-feedback device
Parameters
structinput_dev*dev- input device supporting force-feedback
void*data- driver-specific data to be passed intoplay_effect
int(*)(structinput_dev*,void*,structff_effect*)play_effect- driver-specific method for playing FF effect
Multitouch Library¶
- struct
input_mt_slot¶ represents the state of an input MT slot
Definition
struct input_mt_slot { int abs[ABS_MT_LAST - ABS_MT_FIRST + 1]; unsigned int frame; unsigned int key;};Members
abs- holds current values of ABS_MT axes for this slot
frame- last frame at which
input_mt_report_slot_state()was called key- optional driver designation of this slot
- struct
input_mt¶ state of tracked contacts
Definition
struct input_mt { int trkid; int num_slots; int slot; unsigned int flags; unsigned int frame; int *red; struct input_mt_slot slots[];};Members
trkid- stores MT tracking ID for the next contact
num_slots- number of MT slots the device uses
slot- MT slot currently being transmitted
flags- input_mt operation flags
frame- increases every time
input_mt_sync_frame()is called red- reduced cost matrix for in-kernel tracking
slots- array of slots holding current values of tracked contacts
- struct
input_mt_pos¶ contact position
Definition
struct input_mt_pos { s16 x, y;};Members
x- horizontal coordinate
y- vertical coordinate
- int
input_mt_init_slots(structinput_dev * dev, unsigned int num_slots, unsigned int flags)¶ initialize MT input slots
Parameters
structinput_dev*dev- input device supporting MT events and finger tracking
unsignedintnum_slots- number of slots used by the device
unsignedintflags- mt tasks to handle in core
Description
This function allocates all necessary memory for MT slot handlingin the input device, prepares the ABS_MT_SLOT andABS_MT_TRACKING_ID events for use and sets up appropriate buffers.Depending on the flags set, it also performs pointer emulation andframe synchronization.
May be called repeatedly. Returns -EINVAL if attempting toreinitialize with a different number of slots.
Parameters
structinput_dev*dev- input device with allocated MT slots
Description
This function is only needed in error path as the input core willautomatically free the MT slots when the device is destroyed.
- bool
input_mt_report_slot_state(structinput_dev * dev, unsigned int tool_type, bool active)¶ report contact state
Parameters
structinput_dev*dev- input device with allocated MT slots
unsignedinttool_type- the tool type to use in this slot
boolactive- true if contact is active, false otherwise
Description
Reports a contact via ABS_MT_TRACKING_ID, and optionallyABS_MT_TOOL_TYPE. If active is true and the slot is currentlyinactive, or if the tool type is changed, a new tracking id isassigned to the slot. The tool type is only reported if thecorresponding absbit field is set.
Returns true if contact is active.
Parameters
structinput_dev*dev- input device with allocated MT slots
intcount- the number of contacts
Description
Reports the contact count via BTN_TOOL_FINGER, BTN_TOOL_DOUBLETAP,BTN_TOOL_TRIPLETAP and BTN_TOOL_QUADTAP.
The input core ensures only the KEY events already setup forthis device will produce output.
- void
input_mt_report_pointer_emulation(structinput_dev * dev, bool use_count)¶ common pointer emulation
Parameters
structinput_dev*dev- input device with allocated MT slots
booluse_count- report number of active contacts as finger count
Description
Performs legacy pointer emulation via BTN_TOUCH, ABS_X, ABS_Y andABS_PRESSURE. Touchpad finger count is emulated if use_count is true.
The input core ensures only the KEY and ABS axes already setup forthis device will produce output.
Parameters
structinput_dev*dev- input device with allocated MT slots
Description
Lift all slots not seen since the last call to this function.
Parameters
structinput_dev*dev- input device with allocated MT slots
Description
Close the frame and prepare the internal state for a new one.Depending on the flags, marks unused slots as inactive and performspointer emulation.
- int
input_mt_assign_slots(structinput_dev * dev, int * slots, const structinput_mt_pos * pos, int num_pos, int dmax)¶ perform a best-match assignment
Parameters
structinput_dev*dev- input device with allocated MT slots
int*slots- the slot assignment to be filled
conststructinput_mt_pos*pos- the position array to match
intnum_pos- number of positions
intdmax- maximum ABS_MT_POSITION displacement (zero for infinite)
Description
Performs a best match against the current contacts and returnsthe slot assignment list. New contacts are assigned to unusedslots.
The assignments are balanced so that all coordinate displacements arebelow the euclidian distance dmax. If no such assignment can be found,some contacts are assigned to unused slots.
Returns zero on success, or negative error in case of failure.
Parameters
structinput_dev*dev- input device with allocated MT slots
intkey- the key of the sought slot
Description
Returns the slot of the given key, if it exists, otherwiseset the key on the first unused slot and return.
If no available slot can be found, -1 is returned.Note that for this function to work properly,input_mt_sync_frame() hasto be called at each frame.
Polled input devices¶
- struct
input_polled_dev¶ simple polled input device
Definition
struct input_polled_dev { void *private; void (*open)(struct input_polled_dev *dev); void (*close)(struct input_polled_dev *dev); void (*poll)(struct input_polled_dev *dev); unsigned int poll_interval; unsigned int poll_interval_max; unsigned int poll_interval_min; struct input_dev *input;};Members
private- private driver data.
open- driver-supplied method that prepares device for polling(enabled the device and maybe flushes device state).
close- driver-supplied method that is called when device is nolonger being polled. Used to put device into low power mode.
poll- driver-supplied method that polls the device and postsinput events (mandatory).
poll_interval- specifies how often the poll() method should be called.Defaults to 500 msec unless overridden when registering the device.
poll_interval_max- specifies upper bound for the poll interval.Defaults to the initial value ofpoll_interval.
poll_interval_min- specifies lower bound for the poll interval.Defaults to 0.
input- input device structure associated with the polled device.Must be properly initialized by the driver (id, name, phys, bits).
Description
Polled input device provides a skeleton for supporting simple inputdevices that do not raise interrupts but have to be periodicallyscanned or polled to detect changes in their state.
- structinput_polled_dev *
input_allocate_polled_device(void)¶ allocate memory for polled device
Parameters
void- no arguments
Description
The function allocates memory for a polled device and alsofor an input device associated with this polled device.
- structinput_polled_dev *
devm_input_allocate_polled_device(structdevice * dev)¶ allocate managed polled device
Parameters
structdevice*dev- device owning the polled device being created
Description
Returns preparedstructinput_polled_dev orNULL.
Managed polled input devices do not need to be explicitly unregisteredor freed as it will be done automatically when owner device unbindsfrom * its driver (or binding fails). Once such managed polled deviceis allocated, it is ready to be set up and registered in the samefashion as regular polled input devices (usinginput_register_polled_device() function).
If you want to manually unregister and free such managed polled devices,it can be still done by callinginput_unregister_polled_device() andinput_free_polled_device(), although it is rarely needed.
NOTE
the owner device is set up as parent of input device and usersshould not override it.
- void
input_free_polled_device(structinput_polled_dev * dev)¶ free memory allocated for polled device
Parameters
structinput_polled_dev*dev- device to free
Description
The function frees memory allocated for polling device and dropsreference to the associated input device.
- int
input_register_polled_device(structinput_polled_dev * dev)¶ register polled device
Parameters
structinput_polled_dev*dev- device to register
Description
The function registers previously initialized polled input devicewith input layer. The device should be allocated with call toinput_allocate_polled_device(). Callers should also set up poll()method and set up capabilities (id, name, phys, bits) of thecorresponding input_dev structure.
- void
input_unregister_polled_device(structinput_polled_dev * dev)¶ unregister polled device
Parameters
structinput_polled_dev*dev- device to unregister
Description
The function unregisters previously registered polled inputdevice from input layer. Polling is stopped and device isready to be freed with call toinput_free_polled_device().
Matrix keyboards/keypads¶
- struct
matrix_keymap_data¶ keymap for matrix keyboards
Definition
struct matrix_keymap_data { const uint32_t *keymap; unsigned int keymap_size;};Members
keymap- pointer to array of uint32 values encoded with KEY() macrorepresenting keymap
keymap_size- number of entries (initialized) in this keymap
Description
This structure is supposed to be used by platform code to supplykeymaps to drivers that implement matrix-like keypads/keyboards.
- struct
matrix_keypad_platform_data¶ platform-dependent keypad data
Definition
struct matrix_keypad_platform_data { const struct matrix_keymap_data *keymap_data; const unsigned int *row_gpios; const unsigned int *col_gpios; unsigned int num_row_gpios; unsigned int num_col_gpios; unsigned int col_scan_delay_us; unsigned int debounce_ms; unsigned int clustered_irq; unsigned int clustered_irq_flags; bool active_low; bool wakeup; bool no_autorepeat; bool drive_inactive_cols;};Members
keymap_data- pointer to
matrix_keymap_data row_gpios- pointer to array of gpio numbers representing rows
col_gpios- pointer to array of gpio numbers reporesenting colums
num_row_gpios- actual number of row gpios used by device
num_col_gpios- actual number of col gpios used by device
col_scan_delay_us- delay, measured in microseconds, that isneeded before we can keypad after activating column gpio
debounce_ms- debounce interval in milliseconds
clustered_irq- may be specified if interrupts of all row/column GPIOsare bundled to one single irq
clustered_irq_flags- flags that are needed for the clustered irq
active_low- gpio polarity
wakeup- controls whether the device should be set up as wakeupsource
no_autorepeat- disable key autorepeat
drive_inactive_cols- drive inactive columns during scan, rather thanmaking them inputs.
Description
This structure represents platform-specific data that use used bymatrix_keypad driver to perform proper initialization.
Sparse keymap support¶
- struct
key_entry¶ keymap entry for use in sparse keymap
Definition
struct key_entry { int type; u32 code; union { u16 keycode; struct { u8 code; u8 value; } sw; };};Members
type- Type of the key entry (KE_KEY, KE_SW, KE_VSW, KE_END);drivers are allowed to extend the list with their ownprivate definitions.
code- Device-specific data identifying the button/switch
{unnamed_union}- anonymous
keycode- KEY_* code assigned to a key/button
sw.code- SW_* code assigned to a switch
sw.value- Value that should be sent in an input even when KE_SWswitch is toggled. KE_VSW switches ignore this field andexpect driver to supply value for the event.
Description
This structure defines an entry in a sparse keymap used by someinput devices for which traditional table-based approach is notsuitable.
- structkey_entry *
sparse_keymap_entry_from_scancode(structinput_dev * dev, unsigned int code)¶ perform sparse keymap lookup
Parameters
structinput_dev*dev- Input device using sparse keymap
unsignedintcode- Scan code
Description
This function is used to performstructkey_entry lookup in aninput device using sparse keymap.
- structkey_entry *
sparse_keymap_entry_from_keycode(structinput_dev * dev, unsigned int keycode)¶ perform sparse keymap lookup
Parameters
structinput_dev*dev- Input device using sparse keymap
unsignedintkeycode- Key code
Description
This function is used to performstructkey_entry lookup in aninput device using sparse keymap.
- int
sparse_keymap_setup(structinput_dev * dev, const structkey_entry * keymap, int (*setup)(structinput_dev *, structkey_entry *))¶ set up sparse keymap for an input device
Parameters
structinput_dev*dev- Input device
conststructkey_entry*keymap- Keymap in form of array of
key_entrystructures endingwithKE_ENDtype entry int(*)(structinput_dev*,structkey_entry*)setup- Function that can be used to adjust keymap entriesdepending on device’s needs, may be
NULL
Description
The function calculates size and allocates copy of the originalkeymap after which sets up input device event bits appropriately.The allocated copy of the keymap is automatically freed when itis no longer needed.
- void
sparse_keymap_report_entry(structinput_dev * dev, const structkey_entry * ke, unsigned int value, bool autorelease)¶ report event corresponding to given key entry
Parameters
structinput_dev*dev- Input device for which event should be reported
conststructkey_entry*ke- key entry describing event
unsignedintvalue- Value that should be reported (ignored by
KE_SWentries) boolautorelease- Signals whether release event should be emitted for
KE_KEYentries right after reporting press event, ignored by all otherentries
Description
This function is used to report input event described by givenstructkey_entry.
- bool
sparse_keymap_report_event(structinput_dev * dev, unsigned int code, unsigned int value, bool autorelease)¶ report event corresponding to given scancode
Parameters
structinput_dev*dev- Input device using sparse keymap
unsignedintcode- Scan code
unsignedintvalue- Value that should be reported (ignored by
KE_SWentries) boolautorelease- Signals whether release event should be emitted for
KE_KEYentries right after reporting press event, ignored by all otherentries
Description
This function is used to perform lookup in an input device using sparsekeymap and report corresponding event. Returnstrue if lookup wassuccessful andfalse otherwise.