path: root/doc
diff options
authorPeter Hutterer <>2015-08-04 12:32:00 +1000
committerPeter Hutterer <>2015-08-04 12:32:00 +1000
commit6bfc36f9cfc0ed39b581fdea2761008d3c40d3a5 (patch)
tree64ef27610c41a8a35b01c4f5123d5611eb0e0c75 /doc
parenta7bd84a7eebe8838666a07a00f7cd8ebb9e5db98 (diff)
parent603ac39e3b76fff453410995d7f11c9ace504ec6 (diff)
Merge branch 'master' into tablet-support
Diffstat (limited to 'doc')
5 files changed, 261 insertions, 1 deletions
diff --git a/doc/ b/doc/
index 4c487a3a..ff65e5ce 100644
--- a/doc/
+++ b/doc/
@@ -18,13 +18,15 @@ header_files = \
$(srcdir)/normalization-of-relative-motion.dox \
$(srcdir)/palm-detection.dox \
$(srcdir)/page-hierarchy.dox \
+ $(srcdir)/reporting-bugs.dox \
$(srcdir)/scrolling.dox \
$(srcdir)/seats.dox \
$(srcdir)/t440-support.dox \
$(srcdir)/tablet-support.dox \
$(srcdir)/tapping.dox \
$(srcdir)/test-suite.dox \
- $(srcdir)/tools.dox
+ $(srcdir)/tools.dox \
+ $(srcdir)/touchpads.dox
diagram_files = \
$(srcdir)/dot/seats-sketch.gv \
diff --git a/doc/page-hierarchy.dox b/doc/page-hierarchy.dox
index 78592fc2..1e82535f 100644
--- a/doc/page-hierarchy.dox
+++ b/doc/page-hierarchy.dox
@@ -25,6 +25,7 @@
- @subpage faq
- @subpage tools
+- @subpage reporting_bugs
@page developers Developers
diff --git a/doc/reporting-bugs.dox b/doc/reporting-bugs.dox
new file mode 100644
index 00000000..0755a9ee
--- /dev/null
+++ b/doc/reporting-bugs.dox
@@ -0,0 +1,88 @@
+@page reporting_bugs Reporting bugs
+A new bug can be filed here:
+When reporting bugs against libinput, please follow the instructions below
+and provide the required data. This will speed up triage, resulting in a
+quicker bugfix.
+First, try to identify the bugi by reproducing it reliably. The more
+specific a bug description is, the easier it is to fix. The @ref
+libinput-debug-events helper tool can help identify whether the bug is in
+libinput at all. This tool is a direct hook to libinput without a desktop
+stack in between and can thus help to identify whether a bug is in libinput
+or in one of the higher layers. See the @ref libinput-debug-events section
+for information on this tool.
+@section triage Required information for triage
+When you file a bug, please attach the following information:
+- a virtual description of your input device, see @ref evemu. This is the
+ most important piece of information, do not forget it!
+- the libinput version. Either the package version from your distribution
+ or, when running from git: <tt>git log -n 1 HEAD</tt> or <tt>git describe
+ HEAD</tt>. As a last resort: <tt>libinput-list-devices --version</tt>.
+- the current libinput settings for the device. This is a bit harder to
+ obtain, for now we'll assume you are running X11. The current settings can
+ be obtained with <tt>xinput list-props "your device name"</tt>. Use
+ <tt>xinput list</tt> to obtain the device name.
+- if the device is a touchpad or a pointing stick, the vendor model number
+ of your laptop, and the content of <tt>/sys/class/dmi/id/modalias</tt>.
+- if the device is a touchpad, the physical dimensions of your touchpad in
+ mm
+@section evemu Recording devices with evemu
+<a href="">evemu</a> records the
+device capabilities together with the event stream from the kernel. On our
+side, this allows us to recreate a virtual device identical to your device
+and re-play the event sequence, hopefully triggering the same bug.
+evemu-record takes a <tt>/dev/input/eventX</tt> event node, but without arguments
+it will simply show the list of devices and let you select:
+$ sudo evemu-record > scroll.evemu
+Available devices:
+/dev/input/event0: Lid Switch
+/dev/input/event1: Sleep Button
+/dev/input/event2: Power Button
+/dev/input/event3: AT Translated Set 2 keyboard
+/dev/input/event4: SynPS/2 Synaptics TouchPad
+/dev/input/event5: Video Bus
+/dev/input/event6: ELAN Touchscreen
+/dev/input/event10: ThinkPad Extra Buttons
+/dev/input/event11: HDA Intel HDMI HDMI/DP,pcm=3
+/dev/input/event12: HDA Intel HDMI HDMI/DP,pcm=7
+/dev/input/event13: HDA Intel HDMI HDMI/DP,pcm=8
+/dev/input/event14: HDA Intel PCH Dock Mic
+/dev/input/event15: HDA Intel PCH Mic
+/dev/input/event16: HDA Intel PCH Dock Headphone
+/dev/input/event17: HDA Intel PCH Headphone
+/dev/input/event18: Integrated Camera
+/dev/input/event19: TPPS/2 IBM TrackPoint
+Select the device event number [0-19]:
+Select the device that triggers the issue, then reproduce the bug and Ctrl+C
+the process. The resulting recording, ("scroll.evemu" in this example) will
+contain the sequence required to reproduce the bug. If the bug fails to
+reproduce during recording, simply Ctrl+C and restart evemu-record.
+Always start the recording from a neutral state, i.e. without any buttons or
+keys down, with the position of the device in the neutral position, without
+touching the screen/touchpad.
+@note The longer the recording, the harder it is to identify the event
+sequence triggering the bug. Please keep the event sequence as short as possible.
+To verify that the recording contains the bug, you can replay it on your
+device. For example, to replay the sequence recorded in the example above:
+$ sudo evemu-play /dev/input/event4 < scroll.evemu
+If the bug is triggered by replaying on your device, attach the recording to
+the bug report.
diff --git a/doc/scrolling.dox b/doc/scrolling.dox
index 658fe4b6..0c03c98d 100644
--- a/doc/scrolling.dox
+++ b/doc/scrolling.dox
@@ -44,6 +44,13 @@ movements will translate into tiny scroll movements.
Scrolling in both directions at once is possible by meeting the required
distance thresholds to enable each direction separately.
+Two-finger scrolling requires the touchpad to track both touch points with
+reasonable precision. Unfortunately, some so-called "semi-mt" touchpads can
+only track the bounding box of the two fingers rather than the actual
+position of each finger. In addition, that bounding box usually suffers from
+a low resolution, causing jumpy movement during two-finger scrolling.
+libinput does not provide two-finger scrolling on those touchpads.
@section edge_scrolling Edge scrolling
On some touchpads, edge scrolling is available, triggered by moving a single
diff --git a/doc/touchpads.dox b/doc/touchpads.dox
new file mode 100644
index 00000000..fa509bc6
--- /dev/null
+++ b/doc/touchpads.dox
@@ -0,0 +1,162 @@
+@page touchpads Touchpads
+This page provides an outline of touchpad devices. Touchpads aren't simply
+categorised into a single type, instead they have a set of properties, a
+combination of number of physical buttons, multitouch support abilities and
+other properties.
+@section touchpads_buttons Number of buttons
+@subsection touchapds_buttons_phys Physically separate buttons
+Touchpads with physical buttons usually provide two buttons, left and right.
+A few touchpads with three buttons exist, and Apple used to have touchpads
+with a single physical buttons until ca 2008. Touchpads with only two
+buttons require the software stack to emulate a middle button. libinput does
+this when both buttons are pressed simultaneously.
+Note that many Lenovo laptops provide a pointing stick above the touchpad.
+This pointing stick has a set of physical buttons just above the touchpad.
+While many users use those as substitute touchpad buttons, they logically
+belong to the pointing stick. The *40 and *50 series are an exception here,
+the former had no physical buttons on the touchpad and required the top
+section of the pad to emulate pointing stick buttons, the *50 series has
+physical buttons but they are wired to the touchpads. The kernel re-routes
+those buttons through the trackstick device. See @ref t440_support for more
+@subsection touchpads_buttons_clickpads Clickpads
+Clickpads are the most common type of touchpads these days. A Clickpad has
+no separate physical buttons, instead the touchpad itself is clickable as a
+whole, i.e. a user presses down on the touch area and triggers a physical
+click. Clickpads thus only provide a single button, everything else needs to
+be software-emulated. See @ref clickpad_softbuttons for more information.
+Clickpads are labelled by the kernel with the @c INPUT_PROP_BUTTONPAD input
+@subsection touchpads_buttons_forcepads Forcepads
+Forcepads are Clickpads without a physical button underneath the hardware.
+They provide pressure and may have a vibration element that is
+software-controlled. This element can simulate the feel of a physical
+click or be co-opted for other tasks.
+@section touchpads_touch Touch capabilities
+Virtually all touchpads available now can <b>detect</b> multiple fingers on
+the touchpad, i.e. provide information on how many fingers are on the
+touchpad. The touch capabilities described here specify how many fingers a
+device can <b>track</b>, i.e. provide reliable positional information for.
+In the kernel each finger is tracked in a so-called "slot", the number of
+slots thus equals the number of simultaneous touches a device can track.
+@subsection touchapds_touch_st Single-touch touchpads
+Single-finger touchpads can track a single touchpoint. Most single-touch
+touchpads can also detect three fingers on the touchpad, but no positional
+information is provided for those. In libinput, these touches are termed
+"fake touches". The kernel sends @c BTN_TOOL_DOUBLETAP, @c
+multiple fingers are detected.
+@subsection touchpads_touch_mt Pure multi-touch touchpads
+Pure multi-touch touchpads are those that can track, i.e. identify the
+location of all fingers on the touchpad. Apple's touchpads support 16
+touches, others support 5 touches like the Synaptics touchpads when using
+These touchpads usually also provide extra information. Apple touchpads
+provide an ellipsis and the orientation of the ellipsis for each touch point.
+Other touchpads provide a pressure value for each touch point (see @ref
+Note that the kernel sends @c BTN_TOOL_DOUBLETAP, @c
+all touches for backwards compatibility. libinput ignores these events if
+the touchpad can track touches correctly.
+@subsection touchpads_touch_partial_mt Partial multi-touch touchpads
+The vast majority of touchpads fall into this category, the half-way
+point between single-touch and pure multi-touch. These devices can track N
+fingers, but detect more than N. For example, when using the serial
+protocol, Synaptics touchpads can track two fingers but may detect up to
+The number of slots may limit which features are available in libinput.
+Any device with two slots can support two-finger scrolling, but @ref
+thumb-detection or @ref palm_detection may be limited if only two slots are
+@subsection touchpads_touch_semi_mt Semi-mt touchpads
+A sub-class of partial multi-touch touchpads. These touchpads can
+technically detect two fingers but the location of both is limited to the
+bounding box, i.e. the first touch is always the top-left one and the second
+touch is the bottom-right one. Coordinates jump around as fingers move past
+each other.
+Many semi-mt touchpads also have a lower resolution for the second touch, or
+both touches. This may limit some features such as @ref gestures or
+@ref scrolling.
+Semi-mt are labelled by the kernel with the @c INPUT_PROP_SEMI_MT input
+@section touchpads_mis Other touchpad properties
+@subsection touchpads_external External touchpads
+External touchpads are USB or Bluetooth touchpads not in a laptop chassis,
+e.g. Apple Magic Trackpad or the Logitech T650. These are usually @ref
+touchpads_buttons_clickpads the biggest difference is that they can be
+removed or added at runtime.
+One interaction method that is only possible on external touchpads is a
+thumb resting on the very edge/immediately next to the touchpad. On the far
+edge, touchpads don't always detect the finger location so clicking with a
+thumb barely touching the edge makes it hard or impossible to figure out
+which software button area the finger is on.
+These touchpads also don't need @ref palm_detection - since they're not
+located underneath the keyboard, accidental palm touches are a non-issue.
+@subsection touchpads_pressure_handling Touchpads pressure handling
+Pressure is usually directly related to contact area. Human fingers flatten
+out as the pressure on the pad increases, resulting in a bigger contact area
+and the firmware then calculates that back into a ressure reading.
+libinput uses pressure to detect accidental palm contact and thumbs, though
+pressure data is often device-specific and unreliable.
+@subsection touchpads_circular Circular touchpads
+Only listed for completeness, circular touchpads have not been used in
+laptops for a number of years. These touchpad shaped in an ellipsis or
+@subsection touchpads_tablets Graphics tablets
+Touch-capable graphics tablets are effectively external touchpads, with two
+differentiators: they are larger than normal touchpads and they have no
+regular touchpad buttons. They either work like a @ref
+touchpads_buttons_forcepads Forcepad, or rely on interaction methods that
+don't require buttons (like @ref tapping). Since the physical device is
+shared with the pen input, some touch arbitration is required to avoid touch
+input interfering when the pen is in use.
+@subsection touchpads_edge_zone Dedicated edge scroll area
+Before @ref twofinger_scrolling became the default scroll method, some
+touchpads provided a marking on the touch area that designates the
+edge to be used for scrolling. A finger movement in that edge zone should
+trigger vertical motions. Some touchpads had markers for a horizontal
+scroll area too at the bottom of the touchpad.