doc: expand on the palm detection documentation a bit

Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>

doc/palm-detection.dox

@@ -1,17 +1,40 @@
 /**
 @page palm_detection Palm detection
 
-Palm detection tries to identify accidental touches while typing.
+Palm detection tries to identify accidental touches while typing, while
+using the trackpoint and/or during general use of the touchpad area.
 
 On most laptops typing on the keyboard generates accidental touches on the
 touchpad with the palm (usually the area below the thumb). This can lead to
-cursor jumps or accidental clicks.
+cursor jumps or accidental clicks. On large touchpads, the palm may also
+touch the bottom edges of the touchpad during normal interaction.
 
 Interference from a palm depends on the size of the touchpad and the position
-of the user's hand. Data from touchpads showed that almost all palm events on a
-Lenovo T440 happened in the left-most and right-most 5% of the touchpad. The
-T440 series has one of the largest touchpads, other touchpads are less
-affected by palm touches.
+of the user's hand. Data from touchpads showed that almost all palm events
+during tying on a Lenovo T440 happened in the left-most and right-most 5% of
+the touchpad. The T440 series has one of the largest touchpads, other
+touchpads are less affected by palm touches.
+
+libinput has multiple ways of detecting a palm, each of which depends on
+hardware-specific capabilities.
+
+- @ref palm_tool
+- @ref palm_pressure
+- @ref palm_touch_size
+- @ref palm_exclusion_zones
+- @ref trackpoint-disabling
+- @ref disable-while-typing
+- @ref stylus-touch-arbitration
+
+Palm detection is always enabled, with the exception of
+disable-while-typing.
+
+@section palm_tool Palm detection based on firmware labelling
+
+Some devices provide palm detection in the firmware, forwarded by the kernel
+as the ```EV_ABS/ABS_MT_TOOL``` axis with a value of ```MT_TOOL_PALM```
+(whenever a palm is detected). libinput honors that value and switches that
+touch to a palm.
 
 @section palm_pressure Palm detection based on pressure
 
@@ -25,6 +48,16 @@ pressure changes as the user is typing.
 For some information on how to detect pressure on a touch and debug the
 pressure ranges, see @ref touchpad_pressure.
 
+@section palm_touch_size Palm detection based on touch size
+
+On touchads that support the `ABS_MT_TOUCH_MAJOR` axes, libinput can perform
+palm detection based on the size of the touch ellipse. This works similar to
+the pressure-based palm detection in that a touch is labelled as palm when
+it exceeds the (device-specific) touch size threshold.
+
+For some information on how to detect the size of a touch and debug the
+touch size ranges, see @ref touchpad_pressure.
+
 @section palm_exclusion_zones Palm exclusion zones
 
 libinput enables palm detection on the left, right and top edges of the
@@ -99,6 +132,17 @@ Notable behaviors of libinput's disable-while-typing feature:
 Disable-while-typing can be enabled and disabled by calling
 libinput_device_config_dwt_set_enabled().
 
+@section stylus-touch-arbitration Stylus-touch arbitration
+
+A special case of palm detection is touch arbitration on devices that
+support styli. When interacting with a stylus on the screen, parts of the
+hand may touch the surface and trigger touches. As the user is currently
+interacting with the stylus, these touches would interfer with the correct
+working of the stylus.
+
+libinput employs a method similar to @ref disable-while-typing to detect
+these touches and disables the touchpad accordingly.
+
 @section thumb-detection Thumb detection
 
 Many users rest their thumb on the touchpad while using the index finger to

doc/touchpad-pressure.dox

@@ -1,17 +1,18 @@
 /**
 @page touchpad_pressure Touchpad pressure-based touch detection
 
-libinput uses the touchpad pressure values to detect wether a finger has
-been placed on the touchpad. This is @ref kernel_pressure_information and
-combines with a libinput-specific hardware database to adjust the thresholds
-on a per-device basis. libinput uses pressure thresholds primarily to filter
-out accidental light touches but pressure information is also used for
-some @ref palm_detection.
+libinput uses the touchpad pressure values and/or touch size values to
+detect wether a finger has been placed on the touchpad. This is @ref
+kernel_pressure_information and combines with a libinput-specific hardware
+database to adjust the thresholds on a per-device basis. libinput uses
+these thresholds primarily to filter out accidental light touches but
+the information is also used for some @ref palm_detection.
 
-Pressure thresholds are **not** directly configurable by the user, rather it
-is planned that libinput provides custom pressure thresholds for each device
-where necessary. See @ref touchpad_pressure_hwdb for instructions for your
-local device.
+Pressure and touch size thresholds are **not** directly configurable by the
+user. Instead, libinput provides these thresholds for each device where
+necessary. See @ref touchpad_pressure_hwdb for instructions on how to adjust
+the pressure ranges and @ref touchpad_touch_size_hwdb for instructions on
+how to adjust the touch size ranges.
 
 @section kernel_pressure_information Information provided by the kernel
 
@@ -20,24 +21,29 @@ the touchpad. The most basic is the ```EV_KEY/BTN_TOUCH``` boolean event
 that simply announces physical contact with the touchpad. The decision when
 this event is sent is usually made by the kernel driver and may depend on
 device-specific thresholds. These thresholds are transparent to userspace
-and cannot be modified.
+and cannot be modified. On touchpads where pressure or touch size is not
+available, libinput uses ```BTN_TOUCH``` to determine when a finger is
+logically down.
 
 Many contemporary touchpad devices provide an absolute pressure axis in
 addition to ```BTN_TOUCH```. This pressure generally increases as the pressure
-increases, however few touchpads are capable of detection pressure. The
+increases, however few touchpads are capable of detecting true pressure. The
 pressure value is usually related to the covered area - as the pressure
 increases a finger flattens and thus covers a larger area. The range
 provided by the kernel is not mapped to a specific physical range and
 often requires adjustment. Pressure is sent by the ```ABS_PRESSURE``` axis
 for single-touch touchpads or ```ABS_MT_PRESSURE``` on multi-touch capable
-touchpads.
+touchpads. Some devices can detect multiple fingers but only provide
+```ABS_PRESSURE```.
 
 Some devices provide additional touch size information through
 the ```ABS_MT_TOUCH_MAJOR/ABS_MT_TOUCH_MINOR``` axes and/or
-the ```ABS_MT_WIDTH_MAJOR/ABS_MT_WIDTH_MINOR``` axes. While the kernel
-documentation specifies how these axes are supposed to be mapped, few
-devices forward
-reliable information.
+the ```ABS_MT_WIDTH_MAJOR/ABS_MT_WIDTH_MINOR``` axes. These axes specifcy
+the size of the touch ellipse. While the kernel documentation specifies how
+these axes are supposed to be mapped, few devices forward reliable
+information. libinput uses these values together with a device-specific hwdb
+entry. In other words, touch size detection does not work unless a hwdb
+entry is present for the device.
 
 @section touchpad_pressure_hwdb Debugging touchpad pressure ranges
 
@@ -50,6 +56,9 @@ updated pressure ranges when testing has completed.
 Use the ```libinput measure touchpad-pressure``` tool provided by libinput.
 This tool will search for your touchpad device and print some pressure
 statistics, including whether a touch is/was considered logically down.
+
+@note This tool will only work on touchpads with pressure.
+
 Example output of the tool is below:
 
 <pre>
@@ -117,4 +126,82 @@ Once the pressure ranges are deemed correct,
 @ref reporting_bugs "report a bug" to get the pressure ranges into the
 repository.
 
+@section touchpad_touch_size_hwdb Debugging touch size ranges
+
+This section describes how to determine the touchpad touch size ranges
+required for a touchpad device and how to add the required hwdb entry
+locally. Note that the hwdb entry is **not public API** and **may change at
+any time**. Users are advised to @ref reporting_bugs "report a bug" with the
+updated pressure ranges when testing has completed.
+
+Use the ```libinput measure touch-size``` tool provided by libinput.
+This tool will search for your touchpad device and print some touch size
+statistics, including whether a touch is/was considered logically down.
+
+@note This tool will only work on touchpads with the ```ABS_MT_MAJOR``` axis.
+
+Example output of the tool is below:
+
+<pre>
+$ sudo libinput measure touch-size --touch-thresholds 10:8 --palm-threshold 14
+Using ELAN Touchscreen: /dev/input/event5
+&nbsp;
+Ready for recording data.
+Touch sizes used: 10:8
+Palm size used: 14
+Place a single finger on the device to measure touch size.
+Ctrl+C to exit
+&nbsp;
+Sequence: major: [  9.. 11] minor: [  7..  9]
+Sequence: major: [  9.. 10] minor: [  7..  7]
+Sequence: major: [  9.. 14] minor: [  6..  9]  down
+Sequence: major: [ 11.. 11] minor: [  9..  9]  down
+Sequence: major: [  4.. 33] minor: [  1..  5]  down palm
+</pre>
+
+The example output shows five completed touch sequences. For each, the
+respective minimum and maximum pressure values are printed as well as some
+statistics. The ```down``` and ```palm``` tags show that sequence was considered
+logically down or a palm at some point. This is an interactive tool and its
+output may change frequently. Refer to the <i>libinput-measure-touch-size(1)</i> man
+page for more details.
+
+By default, this tool uses the udev hwdb entries for the touch size range. To
+narrow down on the best values for your device, specify the 'logically down'
+and 'logically up' pressure thresholds with the  ```--touch-thresholds``
+arguments as in the example above.
+
+Interact with the touchpad and check if the output of this tool matches your
+expectations.
+
+Once the thresholds are decided on (e.g. 10 and 8), they can be enabled with
+the following hwdb file:
+
+<pre>
+$> cat /etc/udev/hwdb.d/99-touchpad-pressure.hwdb
+libinput:name:*SynPS/2 Synaptics TouchPad:dmi:*svnHewlett-Packard:*pnHPCompaq6910p*
+ LIBINPUT_ATTR_TOUCH_SIZE_RANGE=10:8
+</pre>
+
+The first line is the match line and should be adjusted for the device name
+(see evemu-record's output) and for the local system, based on the
+information in ```/sys/class/dmi/id/modalias```. The modalias should be
+shortened to the specific system's information, usually system vendor (svn)
+and product name (pn).
+
+Once in place, you need to run the following to commands, adjusted for your
+device's event node (see @ref faq_hwdb_changes):
+<pre>
+    sudo udevadm hwdb --update
+    sudo udevadm test /sys/class/input/eventX
+</pre>
+
+If the touch size range property shows up correctly, restart X or the
+Wayland compositor and libinput should now use the correct thresholds.
+The @ref tools can be used to verify the correct functionality first without
+the need for a restart.
+
+Once the touch size ranges are deemed correct, @ref reporting_bugs "report a
+bug" to get the thresholds into the repository.
+
 */