Linux input Subsystem (1)-event types

The input system protocol uses the type types and encoding codecs to represent the value of the input device and use this to inform the user of the space of the application.

The input protocol is a State-based protocol that is sent only if the corresponding event encoding has a change in the value of the parameter. However, the state is maintained by the Linux input subsystem, and the driver does not need to maintain the input state, and it is not problematic to issue events to the input subsystem even if the parameter values are not changed. User space can use the Eviocg*ioctls defined in Linux/input.h to get the current event encoding and the state of the parameters. The type of escalation event supported by the device can also be obtained through the SYSFS class/input/event*/device/capabilities/, which features the device and can be class/input/event*/device/ Properties to get.

###########################

Event types:

###########################

The types corresponds to a set of codes for the same logical input structure. Each type has a set of available codes for generating input events. For more information on the codes available for each type, refer to the Codes section.

* Ev_syn:

-For the split flag between events. Events can be split on time or space, as in the case of multi-touch protocols.

* Ev_key:

-Used to describe changes in the state of the keyboard, keys, or similar keyboard devices.

* Ev_rel:

-Used to describe a change in the value on a relative axis, for example: The mouse moves 5 units to the left.

* Ev_abs:

-Used to describe a change in values on a relative axis, such as a value describing the coordinates on a touchscreen.

* Ev_msc:

-Use this type to describe when you cannot match an existing type.

* EV_SW:

-Used to describe an input switch with two states.

* Ev_led:

-Used to control the on and off of the LED lights on the device.

* EV_SND:

-Used to give the device output prompt sound.

* Ev_rep:

-for devices that can be automatically duplicated (autorepeating).

* EV_FF:

-Used to send a mandatory feedback command to the input device. Vibration ）

* EV_PWR:

-especially for input of power switch.

* Ev_ff_status:

-A forced feedback state for the receiving device.

Event Codes:

===========

Event codes is used to more precisely define the type of events

Ev_syn:

----------

The Ev_syn event does not have a specific definition of values, and they are used only as defined in the event string that sends the Evdev.

* Syn_report:

-When multiple input data changes at the same time, Syn_report is used to package and synchronize the data. For example, a mouse move can escalate rel_x and rel_y two values, and then emit a syn_report. The next mouse movement can emit rel_x and rel_y two values again, followed by this other syn_report.

* Syn_config:

-tbd

* Syn_mt_report:

-Used to synchronize and detach touch events. For more information, refer to the kernel documentation: Multi-touch-protocol.txt.

* syn_dropped:

-A buffer overflow used to indicate the Evdev client's event queue. The client top cover ignores all events, including the next Syn_report event, and queries the device to get its status (using eviocg* IOCTLs).

Ev_key:

----------

The Ev_key event takes the form of key_<name> or btn_<name>, for example, the key_a represents a key on the keyboard, and when a key is pressed, an event with a key code and a value of 1 is emitted. When a key is released, an event of value 0 is emitted. Some hardware emits an event when the key is repeated, and the value of these events is 2. Usually,key_<name> is used as a key on the keyboard, while btn_<name> is used to switch button events.

Several ev_key of codes have special meanings:

* BTN_TOOL_<NAME>:

-These codes are used in conjunction with trackpad, tablet and touch screen devices that can use fingers, pens or other tools. When an event occurs and detects that a tool is in use, the corresponding Btn_tool_<name> code event should set value to 1 and value should be reset to 0 when the tool is no longer interacting with the input device. All the trackpad, when the event occurs, the tablet and touch screen of the use of at least one btn_tool_<name> code.

* Btn_touch:

The Btn_touch is used for touch contact events. When an input tool is judged to be a meaningful physical contact, the value of this attribute should be set to 1. The so-called meaningful physical contact can be any contact, or a contact that satisfies a defined condition. For example, the touchpad can set value to 1 when the pressure of the touch reaches a certain value, a tablet with a pen across but without touching the surface of the tablet, set the value of Btn_tool_pen to 1, and the value of Btn_touch to 0.

Note: In order to tie in with some old traditional mousedev analog drivers that can work, btn_touch must be emitted as the first evdevcode of a synchronization frame.

Note: For historical reasons, user space interprets touch devices with Btn_tool_finger and Btn_touch as touchpad, while similar touch devices without Btn_tool_finger are interpreted as touch screens. For backward compatibility with current user space applications, it is recommended that you follow this distinction principle. Later, this method of differentiation will be invalidated, and the device properties of the IOCTL Eviocgprop (defined in linux/input.h) will be used to transfer the type of the device.

* Btn_tool_finger, Btn_tool_doubletap,btn_tool_tripletap, Btn_tool_quadtap:

-These codes indicate that one, two, three and four fingers are involved in the operation of the touchpad and touch panel. For example, if a user tries to scroll the contents of the screen using two fingers on the touchpad, the value 1 Btn_tool_doubletap should be sent during the campaign. Note that all btn_tool_<name>codes and Btn_touch code are used for orthogonal purposes, and when a touchpad is touched by a finger, an event code should be generated in each of the two groups, At least one synchronization frame with a value of 1 btn_tool_<name>code.

Note: For historical reasons, some drivers will send multiple codes of the escalation hand index of value 1 in the same sync frame, but this method is now obsolete (no longer used).

Note: In a multi-finger touch drive, you should use the Input_mt_report_finger_count () function to emit these codes, see the kernel Documentation: Multi-touch-protocol.txt for details.

Ev_rel:

----------

The Ev_rel event describes the relative amount of variation of an attribute. For example, the mouse moves several units away to the left, but his absolute position is unknown. If we can know the absolute position, then we should use Ev_abs instead of Ev_rel.

The following are the special meanings of the codes that belong to Ev_rel:

* Rel_wheel, Rel_hwheel:

-These two codes are used for the corresponding vertical direction and horizontal direction of the rollers.

Ev_abs:

----------

The Ev_abs event describes the absolute change value of an attribute, for example, the touchpad uses it to emit an absolute coordinate value for the current position.

The following are the special meanings of the codes that belong to Ev_abs:

* Abs_distance:

-Used to describe how far the touch tool is from the touch surface. This event should only be emitted when the touch tool is floating on the surface, that is, on the touch surface, but the value of Btn_touch is 0. If the input device can work in 3-D coordinates, it is better to consider using Abs_z.

* ABS_MT_<NAME>:

-Used to describe a multi-finger touch input device. For details, please refer to the kernel documentation: Multi-touch-protocol.txt.

EV_SW:

----------

The EV_SW event is used to describe the state of a two-state switch, for example, Sw_lid code to indicate that the laptop's screen is closed.

When binding a device or resuming back from the suspend state, the driver must escalate the current state of the switch. This ensures that the state of the device, kernel, and user space is kept in sync.

At resume, the input subsystem will escalate this repeating state message if the state of the switch is the same as before the suspend. The driver does not have to remember the state of the switch at any time.

Ev_msc:

----------

When an event cannot be described with another event type, using Ev_msc is an escalation of the input and output events.

Ev_led:

----------

The ev_led event is used to set or query the status of LEDs on the device.

Ev_rep:

----------

The ev_rep is used to indicate automatic repeating events (autorepeating).

EV_SND:

----------

EV_SND is used to pronounce commands on those simple audible devices.

EV_FF:

----------

The Ev_ff event is used to initialize devices with forced feedback and to allow these devices to emit feedback actions.

EV_PWR:

----------

The EV_PWR event is a special type that is a dedicated event for power management and is not currently well defined and will be perfected in the future.

Device properties (Devices properties):

=================

Normally, the user space is based on the data emitted by the device (such as the types of the event) to establish an input device, when two devices emit the same event types, then the device features can provide additional identification information.

Input_prop_direct + input_prop_pointer:

--------------------------------------

The Input_prop_direct feature indicates that the coordinates of the device correspond directly to the screen coordinates (no trivial conversion operations, such as scaling, inversion, rotation, etc.). Non-direct input devices require some necessary transformations, such as absolute to relative transformations on the touchpad. Typical direct input devices are: touch screen, tablet, non-direct input device: touchpad, mouse.

The Input_prop_pointer feature indicates that the device does not use the screen to get input information, which requires a pointer on the screen to track the user's movement. Typical pointing devices are: trackpad, mouse, non-pointing device: Touch panel.

If Input_prop_direct or Input_prop_pointer are not set, the device will be considered undefined, and its type needs to be deduced using the types of the event in the traditional way.

Input_prop_buttonpad:

--------------------

Some touchpad, its keys are located at the bottom of the touchpad, so press the touchpad will produce a key message, for this device, you should set this feature. Since 2009, it has become more and more common to configure the notebooks and MacBooks of this touchpad.

Initially, this key feature is encoded in the bcm5974 driver by the version field of the name, and for backward compatibility, it is necessary for the user space to be checked in both of these ways.

INPUT_PROP_SEMI_MT:

------------------

Between 2008 and 2011, many touchpad can only detect multiple touchpoints, but do not know their independent position, just know the number of contacts and a rectangle that surrounds them. For such a device, this semi-multitouch feature should be set.

Different devices, the rectangle may surround all the touch points, just like a bounding box, or it may just surround a part of a touch point, such as the last two touch points. This uncertainty limits the usefulness of the rectangle, but some gesture recognition will analyze it.

If the INPUT_PROP_SEMI_MT attribute is not set, the device is assumed to be a full multi-touch device.

Guidelines for use:

==========

The following guidelines ensure that single-touch and multi-touch work properly, and for more detailed information, refer to the documentation: Multi-touch-protocol.txt.

Mouse:

----------

Rel_{x,y} must be escalated when the mouse is moved. When the primary key is pressed, the btn_left must be escalated. When other keys are pressed, btn_{middle,right,4,5,etc.} should be reported. When the wheel scrolls on the mouse, the Rel_wheel and Rel_hwheel event should be escalated.

Touch screen:

----------

When touch occurs, you must use abs_{x,y} to escalate the location of the touch. When the touch is valid, the Btn_touch must be escalated without having to use btn_{mouse,left,middle,right} to indicate a touch event. If possible,,btn_tool_<name> events can also be reported.

For new hardware, you should set the Input_prop_direct feature.

Touch Panel:

----------

The traditional trackpad simply reports relative location information just like the mouse above.

The trackpad with absolute position information needs to escalate the location information of the touch point via abs_{x,y}. Similarly, the Btn_touch event should be escalated when the touch is valid. If multi-touch is supported, the number of effective touches should be escalated through btn_tool_<name>.

For new hardware, you should set the Input_prop_pointer feature.

Tablets:

----------

When a pen or other tool is effectively detected, the Btn_tool_<name> event must be escalated, and the touch location information must be escalated with abs_{x,y}, and the Btn_touch event should be escalated. The BTN_{STYLUS,STYLUS2} message should be escalated when the button on the Touch tool is valid. In addition to Btn_{mouse,left}, any other key message can be used to escalate the keys on the Tablet, btn_{0,1,2,etc} is a good choice for unmarked keys, avoiding the use of special keys: like Btn_forward, Unless the device specifically indicates that this is the key.

For new hardware, both Input_prop_direct and Input_prop_pointer should be set.

Linux input Subsystem (1)-event types