The root document usually has a special :ref:`genindex` link to the
generated index. This is also the case for Documentation/index.rst. The
other index.rst files deeper in the directory hierarchy usually don't.
For SPHINXDIRS builds, the root document isn't Documentation/index.rst,
but some other index.rst in the hierarchy. Currently they have a
".. only::" block to add the index link when doing SPHINXDIRS html
builds.
This is obviously very tedious and repetitive. The link is also added to
all index.rst files in the hierarchy for SPHINXDIRS builds, not just the
root document.
Put the boilerplate in a sphinx-includes/subproject-index.rst file, and
include it at the end of the root document for subproject builds in an
ad-hoc source-read extension defined in conf.py.
For now, keep having the boilerplate in translations, because this
approach currently doesn't cover translated index link headers.
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Cc: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Tested-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
[jc: did s/doctree/kern_doc_dir/ ]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260123143149.2024303-1-jani.nikula@intel.com>
And expand it to encompass all pressure pads.
Definition: "pressure pad" as used here as includes all touchpads that
use physical pressure to convert to click, without physical hinges. Also
called haptic touchpads in general parlance, Synaptics calls them
ForcePads.
Most (all?) pressure pads are currently advertised as
INPUT_PROP_BUTTONPAD. The suggestion to identify them as pressure pads
by defining the resolution on ABS_MT_PRESSURE has been in the docs since
commit 20ccc8dd38 ("Documentation: input: define
ABS_PRESSURE/ABS_MT_PRESSURE resolution as grams") but few devices
provide this information.
In userspace it's thus impossible to determine whether a device is a
true pressure pad (pressure equals pressure) or a normal clickpad with
(pressure equals finger size).
Commit 7075ae4ac9 ("Input: add INPUT_PROP_HAPTIC_TOUCHPAD") introduces
INPUT_PROP_HAPTIC_TOUCHPAD but restricted it to those touchpads that
have support for userspace-controlled effects. Let's expand and rename
that definition to include all pressure pad touchpads since those that
do support FF effects can be identified by the presence of the
FF_HAPTIC bit.
This means:
- clickpad: INPUT_PROP_BUTTONPAD
- pressurepad: INPUT_PROP_BUTTONPAD + INPUT_PROP_PRESSUREPAD
- pressurepad with configurable haptics:
INPUT_PROP_BUTTONPAD + INPUT_PROP_PRESSUREPAD + FF_HAPTIC
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
Acked-by: Benjamin Tissoires <bentiss@kernel.org>
Link: https://patch.msgid.link/20251106114534.GA405512@tassie
Signed-off-by: Dmitry Torokhov <dmitry.torokhov@gmail.com>
Many controllers these days have started including grip buttons. As
there has been no particular assigned BTN_* constants for these, they've
been haphazardly assigned to BTN_TRIGGER_HAPPY*. Unfortunately, the
assignment of these has varied significantly between drivers.
Add and document new constants for these grip buttons.
Signed-off-by: Vicki Pfau <vi@endrift.com>
Link: https://lore.kernel.org/r/20250702040102.125432-2-vi@endrift.com
Signed-off-by: Dmitry Torokhov <dmitry.torokhov@gmail.com>
The Linux kernel is notorious for misspelling X-Box, X-box, XBox or XBOX;
the official spelling is actually just Xbox. Plain and simple.
Tried to respect the existing notes but still following the style guide.
No functional changes intended. This only affects ancillary parts.
Signed-off-by: Ismael Ferreras Morezuelas <swyterzone@gmail.com>
Link: https://lore.kernel.org/r/401b1d94-1348-15fd-b48f-a80e8885c7a4@gmail.com
Signed-off-by: Dmitry Torokhov <dmitry.torokhov@gmail.com>
The HID core stack used to be very relaxed considering the BTN_TOOL_*
usage. With the recent commits, we should now enforce to have only one
tool at a time, meaning that we can now express that requirement in the
docs.
Signed-off-by: Benjamin Tissoires <benjamin.tissoires@redhat.com>
Reviewed-by: Ping Cheng <ping.cheng@wacom.com>
Acked-by: Peter Hutterer <peter.hutterer@who-t.net>
Signed-off-by: Jiri Kosina <jkosina@suse.cz>
Pull input updates from Dmitry Torokhov:
- three new touchscreen drivers: Hycon HY46XX, ILITEK Lego Series,
and MStar MSG2638
- a new driver for Azoteq IQS626A proximity and touch controller
- addition of Amazon Game Controller to the list of devices handled
by the xpad driver
- Elan touchscreen driver will avoid binding to devices described as
I2CHID compatible in ACPI tables
- various driver fixes
* 'for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/dtor/input: (56 commits)
Input: xpad - add support for Amazon Game Controller
Input: ili210x - add missing negation for touch indication on ili210x
MAINTAINERS: repair reference in HYCON HY46XX TOUCHSCREEN SUPPORT
Input: add driver for the Hycon HY46XX touchpanel series
dt-bindings: touchscreen: Add HY46XX bindings
dt-bindings: Add Hycon Technology vendor prefix
Input: cyttsp - flag the device properly
Input: cyttsp - set abs params for ABS_MT_TOUCH_MAJOR
Input: cyttsp - drop the phys path
Input: cyttsp - reduce reset pulse timings
Input: cyttsp - error message on boot mode exit error
Input: apbps2 - remove useless variable
Input: mms114 - support MMS136
Input: mms114 - convert bindings to YAML and extend
Input: Add support for ILITEK Lego Series
dt-bindings: input: touchscreen: ilitek_ts_i2c: Add bindings
Input: add MStar MSG2638 touchscreen driver
dt-bindings: input/touchscreen: add bindings for msg2638
Input: silead - add workaround for x86 BIOS-es which bring the chip up in a stuck state
Input: elants_i2c - do not bind to i2c-hid compatible ACPI instantiated devices
...
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>
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>
Now that the latex_documents are handled automatically, we can
remove those extra conf.py files.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Rename the HID documentation files to ReST, add an
index for them and adjust in order to produce a nice html
output via the Sphinx build system.
While here, fix the sysfs example from hid-sensor.txt, that
has a lot of "?" instead of the proper UTF-8 characters that
are produced by the tree command.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Benjamin Tissoires <benjamin.tissoires@redhat.com>
Signed-off-by: Benjamin Tissoires <benjamin.tissoires@redhat.com>
