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];
    bool inhibited;
};
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 the device in a packet (between EV_SYN/SYN_REPORT events). Used by event handlers to estimate size of the buffer needed to hold events. 
- 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 implement sparse keymaps. If not supplied default mechanism will be used. The method is being called while holding event_lock and thus must not sleep 
- getkeycode
- optional legacy method to retrieve current keymap. 
- ff
- force feedback structure associated with the device if device supports force feedback effects 
- poller
- poller structure associated with the device if device is set up to use polling mode 
- repeat_key
- stores key code of the last key pressed; used to implement software autorepeat 
- timer
- timer for software autorepeat 
- rep
- current values for autorepeat parameters (delay, rate) 
- mt
- pointer to multitouch state 
- absinfo
- array of - struct input_absinfoelements holding information about 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 device to start generating events (start polling thread, request an IRQ, submit URB, etc.). The meaning of open() is to start providing events to the input core.
- close
- this method is called when the very last user calls - input_close_device(). The meaning of close() is to stop providing events to the input core.
- flush
- purges the device. Most commonly used to get rid of force feedback effects loaded into the device when disconnecting from it 
- event
- event handler for events sent _to_ the device, like EV_LED or EV_SND. The device is expected to carry out the requested action (turn on a LED, play sound, etc.) The call is protected by event_lock and must not sleep 
- grab
- input handle that currently has the device grabbed (via EVIOCGRAB ioctl). When a handle grabs a device it becomes sole recipient for all input events coming from the device 
- event_lock
- this spinlock is taken when input core receives and 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 device has 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 this device. It is used by - input_open_device()and- input_close_device()to make sure that dev->open() is only called when the first user opens device and dev->close() is called when the very last user closes the device
- going_away
- marks devices that are in a middle of unregistering and causes input_open_device*() fail with -ENODEV. 
- dev
- driver model’s view of this device 
- h_list
- list of input handles associated with the device. When accessing 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 framework and needs not be explicitly unregistered or freed. 
- timestamp
- storage for a timestamp set by input_set_timestamp called by a driver 
- inhibited
- indicates that the input device is inhibited. If that is the case then input core ignores any events generated by the device. Device’s close() is called when it is being inhibited and its open() is called when it is being uninhibited. 
- 
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);
    unsigned int (*events)(struct input_handle *handle, 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 passive_observer;
    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 with interrupts disabled and dev->event_lock spinlock held and so it may not sleep 
- events
- event sequence handler. This method is being called by input core with interrupts disabled and dev->event_lock spinlock held and so it may not sleep. The method must return number of events passed to it. 
- filter
- similar to event; separates normal event handlers from “filters”. 
- match
- called after comparing device’s id with handler’s id_table to 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 by input core right after connect() method and also when a process that “grabbed” a device releases it 
- passive_observer
- set to - trueby drivers only interested in observing data stream from devices if there are other users present. Such drivers will not result in starting underlying hardware device when- input_open_device()is called for their handles
- legacy_minors
- set to - trueby drivers using legacy minor ranges
- minor
- beginning of range of 32 legacy minors for devices this driver can 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 can handle 
- 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. There are likely several handlers attached to any given input device at the same time. All of them will get their copy of input event generated by the device.
The very same structure is used to implement input filters. Input core
allows filters to run first and will not pass event to regular handlers
if any of the filters indicate that the event should be filtered (by
returning true 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;
    unsigned int (*handle_events)(struct input_handle *handle,struct input_value *vals, unsigned int count);
    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 deliver events 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 
- handle_events
- event sequence handler. It is set up by the input core according to event handling method specified in the handler. See input_handle_setup_event_handler(). This method is being called by the input core with interrupts disabled and dev->event_lock spinlock held and so it may not sleep. 
- 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 which it gets events 
- 
void input_set_events_per_packet(struct input_dev *dev, int n_events)¶
- tell handlers about the driver event rate 
Parameters
- struct input_dev *dev
- the input device used by the driver 
- int n_events
- the average number of events between calls to input_sync() 
Description
If the event rate sent from a device is unusually large, use this function to set the expected event rate. This will allow handlers to set up an appropriate buffer size for the event stream, in order to 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 being destroyed 
- private
- driver-specific data, will be freed automatically 
- ffbit
- bitmap of force feedback capabilities truly supported by device (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 owning an 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() need only be implemented if driver sets up FF_GAIN and FF_AUTOCENTER bits.
Note that playback(), set_gain() and set_autocenter() are called with dev->event_lock spinlock held and interrupts off and thus may not sleep.
- 
void input_event(struct input_dev *dev, unsigned int type, unsigned int code, int value)¶
- report new input event 
Parameters
- struct input_dev *dev
- device that generated the event 
- unsigned int type
- type of the event 
- unsigned int code
- event code 
- int value
- value of the event 
Description
This function should be used by drivers implementing various input
devices to report input events. See also input_inject_event().
NOTE
input_event() may be safely used right after input device was
allocated with input_allocate_device(), even before it is registered
with input_register_device(), but the event will not reach any of the
input handlers. Such early invocation of input_event() may be used
to ‘seed’ initial state of a switch or initial position of absolute
axis, etc.
- 
void input_inject_event(struct input_handle *handle, unsigned int type, unsigned int code, int value)¶
- send input event from input handler 
Parameters
- struct input_handle *handle
- input handle to send event through 
- unsigned int type
- type of the event 
- unsigned int code
- event code 
- int value
- value of the event 
Description
Similar to input_event() but will ignore event if device is
“grabbed” and handle injecting event is not the one that owns
the device.
Parameters
- struct input_dev *dev
- the input device emitting absolute events 
Description
If the absinfo struct the caller asked for is already allocated, this functions will not do anything.
- 
void input_copy_abs(struct input_dev *dst, unsigned int dst_axis, const struct input_dev *src, unsigned int src_axis)¶
- Copy absinfo from one input_dev to another 
Parameters
- struct input_dev *dst
- Destination input device to copy the abs settings to 
- unsigned int dst_axis
- ABS_* value selecting the destination axis 
- const struct input_dev *src
- Source input device to copy the abs settings from 
- unsigned int src_axis
- ABS_* value selecting the source axis 
Description
Set absinfo for the selected destination axis by copying it from the specified source input device’s source axis. This is useful to e.g. setup a pen/stylus input-device for combined touchscreen/pen hardware where the pen uses the same coordinates as the touchscreen.
- 
int input_grab_device(struct input_handle *handle)¶
- grabs device for exclusive use 
Parameters
- struct input_handle *handle
- input handle that wants to own the device 
Description
When a device is grabbed by an input handle all events generated by the device are delivered only to this handle. Also events injected by other input handles are ignored while device is grabbed.
- 
void input_release_device(struct input_handle *handle)¶
- release previously grabbed device 
Parameters
- struct input_handle *handle
- input handle that owns the device 
Description
Releases previously grabbed device so that other input handles can
start receiving input events. Upon release all handlers attached
to the device have their start() method called so they have a change
to synchronize device state with the rest of the system.
- 
int input_open_device(struct input_handle *handle)¶
- open input device 
Parameters
- struct input_handle *handle
- handle through which device is being accessed 
Description
This function should be called by input handlers when they want to start receive events from given input device.
- 
void input_close_device(struct input_handle *handle)¶
- close input device 
Parameters
- struct input_handle *handle
- handle through which device is being accessed 
Description
This function should be called by input handlers when they want 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 - struct input_keymap_entry
Parameters
- const struct input_keymap_entry *ke
- keymap entry containing scancode to be converted. 
- unsigned int *scancode
- pointer to the location where converted scancode should be stored. 
Description
This function is used to convert scancode stored in struct keymap_entry
into scalar form understood by legacy keymap handling methods. These
methods expect scancodes to be represented as ‘unsigned int’.
- 
int input_get_keycode(struct input_dev *dev, struct input_keymap_entry *ke)¶
- retrieve keycode currently mapped to a given scancode 
Parameters
- struct input_dev *dev
- input device which keymap is being queried 
- struct input_keymap_entry *ke
- keymap entry 
Description
This function should be called by anyone interested in retrieving current keymap. Presently evdev handlers use it.
- 
int input_set_keycode(struct input_dev *dev, const struct input_keymap_entry *ke)¶
- attribute a keycode to a given scancode 
Parameters
- struct input_dev *dev
- input device which keymap is being updated 
- const struct input_keymap_entry *ke
- new keymap entry 
Description
This function should be called by anyone needing to update current keymap. Presently keyboard and evdev handlers use it.
Parameters
- struct input_dev *dev
- input device whose state needs to be reset 
Description
This function tries to reset the state of an opened input device and bring 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 or NULL.
NOTE
Use input_free_device() to free devices that have not been
registered; input_unregister_device() should be used for already
registered devices.
Parameters
- struct device *dev
- device owning the input device being created 
Description
Returns prepared struct input_dev or NULL.
Managed input devices do not need to be explicitly unregistered or freed as it will be done automatically when owner device unbinds from its driver (or binding fails). Once managed input device is allocated, it is ready to be set up and registered in the same fashion as regular input 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 need not be explicitly unregistered or freed.
NOTE
the owner device is set up as parent of input device and users should not override it.
Parameters
- struct input_dev *dev
- input device to free 
Description
This function should only be used if input_register_device()
was not called yet or if it failed. Once device was registered
use input_unregister_device() and memory will be freed once last
reference to the device is dropped.
Device should be allocated by input_allocate_device().
NOTE
If there are references to the input device then memory will not be freed until last reference is dropped.
Parameters
- struct input_dev *dev
- input device to set timestamp for 
- ktime_t timestamp
- the time at which the event has occurred in CLOCK_MONOTONIC 
Description
This function is intended to provide to the input system a more accurate time of when an event actually occurred. The driver should call this function as soon as a timestamp is acquired ensuring clock conversions in input_set_timestamp are done correctly.
The system entering suspend state between timestamp acquisition and calling input_set_timestamp can result in inaccurate conversions.
Parameters
- struct input_dev *dev
- input device to get timestamp from 
Description
A valid timestamp is a timestamp of non-zero value.
- 
void input_set_capability(struct input_dev *dev, unsigned int type, unsigned int code)¶
- mark device as capable of a certain event 
Parameters
- struct input_dev *dev
- device that is capable of emitting or accepting event 
- unsigned int type
- type of the event (EV_KEY, EV_REL, etc...) 
- unsigned int code
- event code 
Description
In addition to setting up corresponding bit in appropriate capability bitmap the function also adjusts dev->evbit.
- 
void input_enable_softrepeat(struct input_dev *dev, int delay, int period)¶
- enable software autorepeat 
Parameters
- struct input_dev *dev
- input device 
- int delay
- repeat delay 
- int period
- repeat period 
Description
Enable software autorepeat on the input device.
Parameters
- struct input_dev *dev
- device to be registered 
Description
This function registers device with input core. The device must be
allocated with input_allocate_device() and all it’s capabilities
set up before registering.
If function fails the device must be freed with input_free_device().
Once device has been successfully registered it can be unregistered
with input_unregister_device(); input_free_device() should not be
called in this case.
Note that this function is also used to register managed input devices
(ones allocated with devm_input_allocate_device()). Such managed input
devices need not be explicitly unregistered or freed, their tear down
is controlled by the devres infrastructure. It is also worth noting
that tear down of managed input devices is internally a 2-step process:
registered managed input device is first unregistered, but stays in
memory and can still handle input_event() calls (although events will
not be delivered anywhere). The freeing of managed input device will
happen later, when devres stack is unwound to the point where device
allocation was made.
Parameters
- struct input_dev *dev
- device to be unregistered 
Description
This function unregisters an input device. Once device is unregistered the caller should not try to access it as it may get freed at any moment.
- 
int input_register_handler(struct input_handler *handler)¶
- register a new input handler 
Parameters
- struct input_handler *handler
- handler to be registered 
Description
This function registers a new input handler (interface) for input devices in the system and attaches it to all input devices that are compatible with the handler.
- 
void input_unregister_handler(struct input_handler *handler)¶
- unregisters an input handler 
Parameters
- struct input_handler *handler
- handler to be unregistered 
Description
This function disconnects a handler from its input devices and removes it from lists of known handlers.
- 
int input_handler_for_each_handle(struct input_handler *handler, void *data, int (*fn)(struct input_handle*, void*))¶
- handle iterator 
Parameters
- struct input_handler *handler
- input handler to iterate 
- void *data
- data for the callback 
- int (*fn)(struct input_handle *, void *)
- function to be called for each handle 
Description
Iterate over bus’s list of devices, and call fn for each, passing it data and stop when fn returns a non-zero value. The function is using RCU to traverse the list and therefore may be using in atomic contexts. The fn callback is invoked from RCU critical section and thus must not sleep.
- 
int input_register_handle(struct input_handle *handle)¶
- register a new input handle 
Parameters
- struct input_handle *handle
- handle to register 
Description
This function puts a new input handle onto device’s
and handler’s lists so that events can flow through
it once it is opened using input_open_device().
This function is supposed to be called from handler’s connect() method.
- 
void input_unregister_handle(struct input_handle *handle)¶
- unregister an input handle 
Parameters
- struct input_handle *handle
- handle to unregister 
Description
This function removes input handle from device’s and handler’s lists.
This function is supposed to be called from handler’s disconnect() method.
- 
int input_get_new_minor(int legacy_base, unsigned int legacy_num, bool allow_dynamic)¶
- allocates a new input minor number 
Parameters
- int legacy_base
- beginning or the legacy range to be searched 
- unsigned int legacy_num
- size of legacy range 
- bool allow_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 specifying legacy_base and legacy_num parameters and whether ID can be allocated from dynamic range if there are no free IDs in legacy range.
- 
void input_free_minor(unsigned int minor)¶
- release previously allocated minor 
Parameters
- unsigned int minor
- minor to be released 
Description
This function releases previously allocated input minor so that it can be reused later.
- 
int input_ff_upload(struct input_dev *dev, struct ff_effect *effect, struct file *file)¶
- upload effect into force-feedback device 
Parameters
- struct input_dev *dev
- input device 
- struct ff_effect *effect
- effect to be uploaded 
- struct file *file
- owner of the effect 
- 
int input_ff_erase(struct input_dev *dev, int effect_id, struct file *file)¶
- erase a force-feedback effect from device 
Parameters
- struct input_dev *dev
- input device to erase effect from 
- int effect_id
- id of the effect to be erased 
- struct file *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 same file handle that is requesting erase.
- 
int input_ff_event(struct input_dev *dev, unsigned int type, unsigned int code, int value)¶
- generic handler for force-feedback events 
Parameters
- struct input_dev *dev
- input device to send the effect to 
- unsigned int type
- event type (anything but EV_FF is ignored) 
- unsigned int code
- event code 
- int value
- event value 
Parameters
- struct input_dev *dev
- input device supporting force-feedback 
- unsigned int max_effects
- maximum number of effects supported by the device 
Description
This function allocates all necessary memory for a force feedback portion 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
- struct input_dev *dev
- input device supporting force feedback 
Description
This function is only needed in error path as input core will automatically free force feedback structures when device is destroyed.
- 
int input_ff_create_memless(struct input_dev *dev, void *data, int (*play_effect)(struct input_dev*, void*, struct ff_effect*))¶
- create memoryless force-feedback device 
Parameters
- struct input_dev *dev
- input device supporting force-feedback 
- void *data
- driver-specific data to be passed into play_effect 
- int (*play_effect)(struct input_dev *, void *, struct ff_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(struct input_dev *dev, unsigned int num_slots, unsigned int flags)¶
- initialize MT input slots 
Parameters
- struct input_dev *dev
- input device supporting MT events and finger tracking 
- unsigned int num_slots
- number of slots used by the device 
- unsigned int flags
- mt tasks to handle in core 
Description
This function allocates all necessary memory for MT slot handling in the input device, prepares the ABS_MT_SLOT and ABS_MT_TRACKING_ID events for use and sets up appropriate buffers. Depending on the flags set, it also performs pointer emulation and frame synchronization.
May be called repeatedly. Returns -EINVAL if attempting to reinitialize with a different number of slots.
Parameters
- struct input_dev *dev
- input device with allocated MT slots 
Description
This function is only needed in error path as the input core will automatically free the MT slots when the device is destroyed.
- 
bool input_mt_report_slot_state(struct input_dev *dev, unsigned int tool_type, bool active)¶
- report contact state 
Parameters
- struct input_dev *dev
- input device with allocated MT slots 
- unsigned int tool_type
- the tool type to use in this slot 
- bool active
- true if contact is active, false otherwise 
Description
Reports a contact via ABS_MT_TRACKING_ID, and optionally ABS_MT_TOOL_TYPE. If active is true and the slot is currently inactive, or if the tool type is changed, a new tracking id is assigned to the slot. The tool type is only reported if the corresponding absbit field is set.
Returns true if contact is active.
Parameters
- struct input_dev *dev
- input device with allocated MT slots 
- int count
- 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 for this device will produce output.
- 
void input_mt_report_pointer_emulation(struct input_dev *dev, bool use_count)¶
- common pointer emulation 
Parameters
- struct input_dev *dev
- input device with allocated MT slots 
- bool use_count
- report number of active contacts as finger count 
Description
Performs legacy pointer emulation via BTN_TOUCH, ABS_X, ABS_Y and ABS_PRESSURE. Touchpad finger count is emulated if use_count is true.
The input core ensures only the KEY and ABS axes already setup for this device will produce output.
Parameters
- struct input_dev *dev
- input device with allocated MT slots 
Description
Lift all slots not seen since the last call to this function.
Parameters
- struct input_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 performs pointer emulation.
- 
int input_mt_assign_slots(struct input_dev *dev, int *slots, const struct input_mt_pos *pos, int num_pos, int dmax)¶
- perform a best-match assignment 
Parameters
- struct input_dev *dev
- input device with allocated MT slots 
- int *slots
- the slot assignment to be filled 
- const struct input_mt_pos *pos
- the position array to match 
- int num_pos
- number of positions 
- int dmax
- maximum ABS_MT_POSITION displacement (zero for infinite) 
Description
Performs a best match against the current contacts and returns the slot assignment list. New contacts are assigned to unused slots.
The assignments are balanced so that all coordinate displacements are below 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
- struct input_dev *dev
- input device with allocated MT slots 
- int key
- the key of the sought slot 
Description
Returns the slot of the given key, if it exists, otherwise set 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() has
to be called at each frame.
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() macro representing keymap 
- keymap_size
- number of entries (initialized) in this keymap 
Description
This structure is supposed to be used by platform code to supply keymaps to drivers that implement matrix-like keypads/keyboards.
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 own private definitions. 
- code
- Device-specific data identifying the button/switch 
- {unnamed_union}
- anonymous 
- keycode
- KEY_* code assigned to a key/button 
- sw
- struct with code/value used by KE_SW and KE_VSW 
- sw.code
- SW_* code assigned to a switch 
- sw.value
- Value that should be sent in an input even when KE_SW switch is toggled. KE_VSW switches ignore this field and expect driver to supply value for the event. 
Description
This structure defines an entry in a sparse keymap used by some input devices for which traditional table-based approach is not suitable.
- 
struct key_entry *sparse_keymap_entry_from_scancode(struct input_dev *dev, unsigned int code)¶
- perform sparse keymap lookup 
Parameters
- struct input_dev *dev
- Input device using sparse keymap 
- unsigned int code
- Scan code 
Description
This function is used to perform struct key_entry lookup in an
input device using sparse keymap.
- 
struct key_entry *sparse_keymap_entry_from_keycode(struct input_dev *dev, unsigned int keycode)¶
- perform sparse keymap lookup 
Parameters
- struct input_dev *dev
- Input device using sparse keymap 
- unsigned int keycode
- Key code 
Description
This function is used to perform struct key_entry lookup in an
input device using sparse keymap.
- 
int sparse_keymap_setup(struct input_dev *dev, const struct key_entry *keymap, int (*setup)(struct input_dev*, struct key_entry*))¶
- set up sparse keymap for an input device 
Parameters
- struct input_dev *dev
- Input device 
- const struct key_entry *keymap
- Keymap in form of array of - key_entrystructures ending with- KE_ENDtype entry
- int (*setup)(struct input_dev *, struct key_entry *)
- Function that can be used to adjust keymap entries depending on device’s needs, may be - NULL
Description
The function calculates size and allocates copy of the original keymap after which sets up input device event bits appropriately. The allocated copy of the keymap is automatically freed when it is no longer needed.
- 
void sparse_keymap_report_entry(struct input_dev *dev, const struct key_entry *ke, unsigned int value, bool autorelease)¶
- report event corresponding to given key entry 
Parameters
- struct input_dev *dev
- Input device for which event should be reported 
- const struct key_entry *ke
- key entry describing event 
- unsigned int value
- Value that should be reported (ignored by - KE_SWentries)
- bool autorelease
- Signals whether release event should be emitted for - KE_KEYentries right after reporting press event, ignored by all other entries
Description
This function is used to report input event described by given
struct key_entry.
- 
bool sparse_keymap_report_event(struct input_dev *dev, unsigned int code, unsigned int value, bool autorelease)¶
- report event corresponding to given scancode 
Parameters
- struct input_dev *dev
- Input device using sparse keymap 
- unsigned int code
- Scan code 
- unsigned int value
- Value that should be reported (ignored by - KE_SWentries)
- bool autorelease
- Signals whether release event should be emitted for - KE_KEYentries right after reporting press event, ignored by all other entries
Description
This function is used to perform lookup in an input device using sparse
keymap and report corresponding event. Returns true if lookup was
successful and false otherwise.
PS/2 protocol support¶
- 
enum ps2_disposition¶
- indicates how received byte should be handled 
Constants
- PS2_PROCESS
- pass to the main protocol handler, process normally 
- PS2_IGNORE
- skip the byte 
- PS2_ERROR
- do not process the byte, abort command in progress 
- 
struct ps2dev¶
- represents a device using PS/2 protocol 
Definition:
struct ps2dev {
    struct serio *serio;
    struct mutex cmd_mutex;
    wait_queue_head_t wait;
    unsigned long flags;
    u8 cmdbuf[8];
    u8 cmdcnt;
    u8 nak;
    ps2_pre_receive_handler_t pre_receive_handler;
    ps2_receive_handler_t receive_handler;
};
Members
- serio
- a serio port used by the PS/2 device 
- cmd_mutex
- a mutex ensuring that only one command is executing at a time 
- wait
- a waitqueue used to signal completion from the serio interrupt handler 
- flags
- various internal flags indicating stages of PS/2 command execution 
- cmdbuf
- buffer holding command response 
- cmdcnt
- outstanding number of bytes of the command response 
- nak
- a byte transmitted by the device when it refuses command 
- pre_receive_handler
- checks communication errors and returns disposition ( - enum ps2_disposition) of the received data byte
- receive_handler
- main handler of particular PS/2 protocol, such as keyboard or mouse protocol 
- 
int ps2_sendbyte(struct ps2dev *ps2dev, u8 byte, unsigned int timeout)¶
- sends a byte to the device and wait for acknowledgement 
Parameters
- struct ps2dev *ps2dev
- a PS/2 device to send the data to 
- u8 byte
- data to be sent to the device 
- unsigned int timeout
- timeout for sending the data and receiving an acknowledge 
Description
The function doesn’t handle retransmission, the caller is expected to handle it when needed.
ps2_sendbyte() can only be called from a process context.
Parameters
- struct ps2dev *ps2dev
- a PS/2 device executing the command 
Description
Serializes a complex/compound command. Once command is finished
ps2_end_command() should be called.
Parameters
- struct ps2dev *ps2dev
- a PS/2 device executing the command 
- 
void ps2_drain(struct ps2dev *ps2dev, size_t maxbytes, unsigned int timeout)¶
- waits for device to transmit requested number of bytes and discards them 
Parameters
- struct ps2dev *ps2dev
- the PS/2 device that should be drained 
- size_t maxbytes
- maximum number of bytes to be drained 
- unsigned int timeout
- time to drain the device 
- 
bool ps2_is_keyboard_id(u8 id_byte)¶
- checks received ID byte against the list of known keyboard IDs 
Parameters
- u8 id_byte
- data byte that should be checked 
- 
int __ps2_command(struct ps2dev *ps2dev, u8 *param, unsigned int command)¶
- send a command to PS/2 device 
Parameters
- struct ps2dev *ps2dev
- the PS/2 device that should execute the command 
- u8 *param
- a buffer containing parameters to be sent along with the command, or place where the results of the command execution will be deposited, or both 
- unsigned int command
- command word that encodes the command itself, as well as number of additional parameter bytes that should be sent to the device and expected length of the command response 
Description
Not serialized. Callers should use ps2_begin_command() and ps2_end_command()
to ensure proper serialization for complex commands.
- 
int ps2_command(struct ps2dev *ps2dev, u8 *param, unsigned int command)¶
- send a command to PS/2 device 
Parameters
- struct ps2dev *ps2dev
- the PS/2 device that should execute the command 
- u8 *param
- a buffer containing parameters to be sent along with the command, or place where the results of the command execution will be deposited, or both 
- unsigned int command
- command word that encodes the command itself, as well as number of additional parameter bytes that should be sent to the device and expected length of the command response 
Note
ps2_command() serializes the command execution so that only one
command can be executed at a time for either individual port or the entire
8042 controller.
- 
int ps2_sliced_command(struct ps2dev *ps2dev, u8 command)¶
- sends an extended PS/2 command to a mouse 
Parameters
- struct ps2dev *ps2dev
- the PS/2 device that should execute the command 
- u8 command
- command byte 
Description
The command is sent using “sliced” syntax understood by advanced devices, such as Logitech or Synaptics touchpads. The command is encoded as: 0xE6 0xE8 rr 0xE8 ss 0xE8 tt 0xE8 uu where (rr*64)+(ss*16)+(tt*4)+uu is the command.
- 
void ps2_init(struct ps2dev *ps2dev, struct serio *serio, ps2_pre_receive_handler_t pre_receive_handler, ps2_receive_handler_t receive_handler)¶
- initializes ps2dev structure 
Parameters
- struct ps2dev *ps2dev
- structure to be initialized 
- struct serio *serio
- serio port associated with the PS/2 device 
- ps2_pre_receive_handler_t pre_receive_handler
- validation handler to check basic communication state 
- ps2_receive_handler_t receive_handler
- main protocol handler 
Description
Prepares ps2dev structure for use in drivers for PS/2 devices.
- 
irqreturn_t ps2_interrupt(struct serio *serio, u8 data, unsigned int flags)¶
- common interrupt handler for PS/2 devices 
Parameters
- struct serio *serio
- serio port for the device 
- u8 data
- a data byte received from the device 
- unsigned int flags
- flags such as - SERIO_PARITYor- SERIO_TIMEOUTindicating state of the data transfer
Description
ps2_interrupt() invokes pre-receive handler, optionally handles command
acknowledgement and response from the device, and finally passes the data
to the main protocol handler for future processing.