Documentation: Fix typos

Fix typos in Documentation.

Signed-off-by: Bjorn Helgaas <bhelgaas@google.com>
Link: https://lore.kernel.org/r/20230814212822.193684-4-helgaas@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

input: Documentation: corrections for multi-touch-protocol.rst

Correct hyphenation, spelling, and capitalization.

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Dmitry Torokhov <dmitry.torokhov@gmail.com>
Cc: linux-input@vger.kernel.org
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Cc: Henrik Rydberg <rydberg@bitmath.org>
Link: https://lore.kernel.org/r/20210302223523.20130-6-rdunlap@infradead.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Documentation: input: define ABS_PRESSURE/ABS_MT_PRESSURE resolution as grams

ABS_PRESSURE and ABS_MT_PRESSURE on touch devices usually represent
contact size (as a finger flattens with higher pressure the contact size
increases) and userspace translates the kernel pressure value back into
contact size. For example, libinput has pressure thresholds when a touch is
considered a palm (palm == large contact area -> high pressure). The values
themselves are on an arbitrary scale and device-specific.

On pressurepads however, the pressure axis may represent the real physical
pressure. Pressurepads are touchpads without a hinge but an actual pressure
sensor underneath the device instead, for example the Lenovo Yoga 9i.

A high-enough pressure is converted to a button click by the firmware.
Microsoft does not require a pressure axis to be present, see [1], so as seen
from userspace most pressurepads are identical to clickpads - one button and
INPUT_PROP_BUTTONPAD set.

However, pressurepads that export the pressure axis break userspace because
that axis no longer represents contact size, resulting in inconsistent touch
tracking, e.g. [2]. Userspace needs to know when a pressure axis represents
real pressure and the best way to do so is to define what the resolution
field means. Userspace can then treat data with a pressure resolution as
true pressure.

This patch documents that the pressure resolution is in units/gram. This
allows for fine-grained detail and tops out at roughly ~2000t, enough for the
devices we're dealing with. Grams is not a scientific pressure unit but the
alternative is:
- Pascal: defined as force per area and area is unreliable on many devices and
seems like the wrong option here anyway, especially for devices with a
single pressure sensor only.
- Newton: defined as mass * distance/acceleration and for the purposes of a
pressure axis, the distance is tricky to interpret and we get the data to
calculate acceleration from event timestamps anyway.

For the purposes of touch devices and digitizers, grams seems the best choice
and the easiest to interpret.

Bonus side effect: we can use the existing hwdb infrastructure in userspace to
fix devices that advertise false pressure.

[1] https://docs.microsoft.com/en-us/windows-hardware/design/component-guidelines/windows-precision-touchpad-required-hid-top-level-collections#windows-precision-touchpad-input-reports
[2] https://gitlab.freedesktop.org/libinput/libinput/-/issues/562

Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
Acked-by: Benjamin Tissoires <benjamin.tissoires@redhat.com>
Link: https://lore.kernel.org/r/20210112230310.GA149342@jelly
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Input: docs: fix spelling mistake "potocol" -> "protocol"

There is a minor spelling mistake in the documentation, fix it.

Signed-off-by: Colin Ian King <colin.king@canonical.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

input: add MT_TOOL_DIAL

A dial is a tool you place on a multitouch surface which reports its
orientation or a relative angle of rotation when rotating its knob.

Some examples are the Dell Totem (on the Canvas 27"), the Microsoft Dial,
or the Griffin Powermate, though the later can't be put on a touch surface.

We give some extra space to account for other types of fingers if we need
(MT_TOOL_THUMB)

Slightly change the documentation to not make it mandatory to update each
MT_TOOL we add.

Reviewed-by: Peter Hutterer <peter.hutterer@who-t.net>
Acked-by: Dmitry Torokhov <dmitry.torokhov@gmail.com>
Signed-off-by: Benjamin Tissoires <benjamin.tissoires@redhat.com>
Signed-off-by: Jiri Kosina <jkosina@suse.cz>

HID: hid-multitouch: support fine-grain orientation reporting

The current hid-multitouch driver only allow the report of two
orientations, vertical and horizontal. We use the Azimuth orientation
usage 0x3F under the Digitizer usage page to report orientation if the
device supports it.

Changelog:
v1 -> v2:
- Fix commit message.
- Remove resolution reporting for ABS_MT_ORIENTATION.
v2 -> v3:
- Fix commit message.
v3 -> v4:
- Fix ABS_MT_ORIENTATION ABS param range.
- Don't set ABS_MT_ORIENTATION in ABS_DG_HEIGHT when it is already
set by ABS_DG_AZIMUTH.
v4 -> v5:
- Improve multi-touch-protocol.rst documentation.

Signed-off-by: Wei-Ning Huang <wnhuang@chromium.org>
Signed-off-by: Wei-Ning Huang <wnhuang@google.com>
Reviewed-by: Dmitry Torokhov <dtor@chromium.org>
Reviewed-by: Henrik Rydberg <rydberg@bitmath.org>
Signed-off-by: Jiri Kosina <jkosina@suse.cz>

Input: docs - note that MT-A protocol is obsolete

Everyone should be using multitouch protocol B (slotted) now.

Signed-off-by: Dmitry Torokhov <dmitry.torokhov@gmail.com>

Input: create a book with Linux Input documentation

Now that all files under Documentation/input follows the ReST markup
language, rename them to *.rst and create a book for the Linux Input
subsystem.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Dmitry Torokhov <dmitry.torokhov@gmail.com>