doc: add a doc for trackpoints

doc/faqs.dox

@@ -17,6 +17,12 @@ This is a symptom of high-dpi mice (greater than 1000dpi). These devices
 need a udev hwdb entry to normalize their motion. See @ref
 motion_normalization for a detailed explanation.
 
+@section faq_fast_trackpoint My trackpoint moves too slow or too fast
+
+This is a symptom of an invalid trackpoint range. These devices need a udev
+hwdb entry to specify the range available so libinput can adjust the pointer
+acceleration accordingly. See @ref trackpoint_range for a detailed explanation.
+
 @section faq_enable_tapping Why isn't touchpad tap-to-click enabled by default
 
 See @ref tapping_default

doc/page-hierarchy.dox

@@ -20,6 +20,7 @@
 - @subpage motion_normalization
 - @subpage middle_button_emulation
 - @subpage button_debouncing
+- @subpage trackpoints
 
 @page tablets Graphics Tablets
 

doc/trackpoints.dox

@@ -0,0 +1,164 @@
+/**
+@page trackpoints Trackpoints and Pointing Sticks
+
+This page provides an overview of trackpoint handling in libinput, also
+refered to as Pointing Stick or Trackstick. The device itself is usually a
+round plastic stick between the G, H and B keys with a set of buttons below
+the space bar.
+
+@image html button-scrolling.svg "A trackpoint"
+
+libinput always treats the buttons below the space bar as the buttons that
+belong to the trackpoint even on the few laptops where the buttons are not
+physically wired to the trackpoint device anyway, see @ref t440_support.
+
+Trackpoint devices have @ref button_scrolling enabled by default. This may
+interfer with middle-button dragging, if middle-button dragging is required
+by a user then button scrolling must be disabled.
+
+@section trackpoint_range Motion range on trackpoints
+
+It is difficult to associate motion on a trackpoint with a physical
+reference. Unlike mice or touchpads where the motion can be
+measured in mm, the trackpoint only responds to pressure. Without special
+equipment it is impossible to measure identical pressure values across
+multiple laptops.
+
+The values provided by a trackpoint are motion deltas, usually corresponding
+to the pressure applied to the trackstick. For example, pressure towards the
+screen on a laptop provides negative y deltas at a fixed rate (e.g. every
+10ms). As the pressure increases, the delta increases too. As the pressure
+decreases, the delta decreases until it hits the neutral state.
+
+The delta range itself can vary greatly between laptops, some devices send a
+maximum delta value of 30, others can go beyond 100. To normalize the motion
+trackpoint, libinput uses the available delta range and fits its
+acceleration curve into this range. This requires calibration by the user,
+see @ref trackpoint_range_measure.
+
+@section trackpoint_range_measure Measuring the trackpoint range
+
+This section describes how to measure the trackpoint range and apply a hwdb
+entry to make this range known to libinput. libinput provides the tool
+`libinput measure trackpoint-range` for this task. This is an interactive
+tool and prints its instructions on the commandline. Example output from
+this tool is below:
+
+@code
+$ sudo libinput measure trackpoint-range
+This tool measures the commonly used pressure range of the
+trackpoint. Push the trackpoint:
+- Four times around the screen edges
+- From the top left to the bottom right and back, twice
+- From the top right to the bottom left and back, twice
+A minimum of 1000 events for each axis is required
+
+Movements should emulate fast pointer movement on the screen
+but not use excessive pressure that would not be used
+during day-to-day movement. For best results, run this tool
+several times to get an idea of the common range.
+
+Trackpoint sends: max x: 19, max y: 23 samples [121, 121]
+@endcode
+
+Once sufficient samples have been collected, the tool prints a simplified
+histogram for x and y axis deltas. This histogram should be used to
+<b>estimate</b> the appropriate trackpoint range. For example, let's look at
+the histogram below:
+
+@code
+Histogram for x axis deltas, in counts of 5
+ -30:
+ -29:
+ -28: +
+ -27: +
+ -26: ++
+ -25: ++++
+ -24: +++++
+ -23: ++
+ -22: ++++++
+ -21: +++
+ -20: ++++
+ -19: +++++++
+ -18: ++++++++++++
+ -17: ++++++++++++
+ -16: ++++++++++++
+ -15: ++++
+ -14: +++++
+ -13: +++++
+ -12: ++++++
+ -11: +++++
+ -10: +++
+  -9: ++++
+  -8: +++++++
+  -7: +++++++
+  -6: ++++++++++++
+  -5: ++++++++++++
+  -4: ++++++++++++
+  -3: +++++++++
+  -2: +++++++++
+  -1: ++++++++
+   0: +++++++
+   1: +++++
+   2: +++++
+   3: ++++++
+   4: ++++++
+   5: +++++++
+   6: ++++
+   7: ++
+   8: +++
+   9: +++
+  10: +++
+  11: +++
+  12: +++
+  13: ++++
+  14: ++++++
+  15: ++++
+  16: ++++
+  17: ++++
+  18: ++++++
+  19: +++++++
+  20: ++++
+  21: ++++++
+  22: ++++++
+  23: ++++++
+  24: ++++++
+  25: +++++++++
+  26: +++++++
+  27: ++++++++
+  28: +++++
+  29: ++
+  30: ++
+  31: +
+  32:
+  33:
+  34:
+@endcode
+
+The 0 delta is the neutral state, each + represents 5 events with that
+delta value. Note how the curve is distributed, it's not a classic bell
+curve. That can be a factor of the input provided or the firmware-based
+pointer acceleration.
+
+Overall, the majority of events appear to be in the 0-25 range with a few
+outliers. So the trackpoint range libinput should use for this particular
+device would be 25. Note how there is a fair bit of guesswork involved, a
+trackpoint's data is never clean enough to get a definitive value. It is
+generally better to take a (slightly) smaller range than one too large.
+
+The hwdb entry for the above should thus be:
+@code
+libinput:name:TPPS/2 IBM TrackPoint:dmi:bvn*:bvr*:bd*:svnLENOVO:pn*:pvrThinkPadT440:*
+  LIBINPUT_ATTR_TRACKPOINT_RANGE=25
+@endcode
+
+The first line contains the device name and an abbreviated version of the
+dmi modalias (see `/sys/class/dmi/id/modalias/`). This dmi string should be
+abbreviated to be as generic as possible (hence the *) but specific enough
+to match the laptop model.
+
+See @ref faq_hwdb_changes for instructions on how to add this match to the
+system.
+
+*/
+

meson.build

@@ -291,6 +291,7 @@ if get_option('documentation')
 		meson.source_root() + '/doc/touchpad-jumping-cursors.dox',
 		meson.source_root() + '/doc/touchpad-pressure.dox',
 		meson.source_root() + '/doc/touchpads.dox',
+		meson.source_root() + '/doc/trackpoints.dox',
 		meson.source_root() + '/doc/what-is-libinput.dox',
 		# dot drawings
 		meson.source_root() + '/doc/dot/seats-sketch.gv',