mirror of
https://gitlab.freedesktop.org/libinput/libinput.git
synced 2025-12-25 04:40:05 +01:00
cbd4f35442
This is a large commit because it's difficult to split this up and we don't care about bisecting here anyway. doxygen is going to produce the API documentation only sphinx is going to produce the prose user (and a bit of developer) documentation. The source split is doc/api and doc/user. Steps performed: - run the doxygen-to-sphinx.sh script to convert all .dox sources to .rst - manually fixed the .rst to render correctly - add a few extra .rst documents to generate the right hierarchy - hook up sphinx-build in meson - add a new @mainpage for doxygen more aimed at developers For the build directory: - sphinx produces /Documentation - doxygen now produces /api/ These need to be manually combined in the wayland-web repo, meson doesn't support subdirectories as output paths within the build dir and the documentation doesn't need to be installed anywhere. Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
260 lines
11 KiB
ReStructuredText
260 lines
11 KiB
ReStructuredText
.. _udev_config:
|
|
|
|
==============================================================================
|
|
Static device configuration via udev
|
|
==============================================================================
|
|
|
|
libinput supports some static configuration through udev properties.
|
|
These properties are read when the device is initially added
|
|
to libinput's device list, i.e. before the
|
|
**LIBINPUT_EVENT_DEVICE_ADDED** event is generated.
|
|
|
|
The following udev properties are supported:
|
|
|
|
LIBINPUT_CALIBRATION_MATRIX
|
|
Sets the calibration matrix, see
|
|
**libinput_device_config_calibration_get_default_matrix()**. If unset,
|
|
defaults to the identity matrix.
|
|
|
|
The udev property is parsed as 6 floating point numbers separated by a
|
|
single space each (scanf(3) format ``"%f %f %f %f %f %f"``).
|
|
The 6 values represent the first two rows of the calibration matrix as
|
|
described in **libinput_device_config_calibration_set_matrix()**.
|
|
|
|
Example values are: ::
|
|
|
|
ENV{LIBINPUT_CALIBRATION_MATRIX}="1 0 0 0 1 0" # default
|
|
ENV{LIBINPUT_CALIBRATION_MATRIX}="0 -1 1 1 0 0" # 90 degree clockwise
|
|
ENV{LIBINPUT_CALIBRATION_MATRIX}="-1 0 1 0 -1 1" # 180 degree clockwise
|
|
ENV{LIBINPUT_CALIBRATION_MATRIX}="0 1 0 -1 0 1" # 270 degree clockwise
|
|
ENV{LIBINPUT_CALIBRATION_MATRIX}="-1 0 1 0 1 0" # reflect along y axis
|
|
|
|
|
|
LIBINPUT_DEVICE_GROUP
|
|
A string identifying the **libinput_device_group** for this device. Two
|
|
devices with the same property value are grouped into the same device group,
|
|
the value itself is irrelevant otherwise.
|
|
|
|
LIBINPUT_IGNORE_DEVICE
|
|
If set to anything other than "0", the device is ignored by libinput.
|
|
See :ref:`ignoring_devices` for more details.
|
|
|
|
ID_SEAT
|
|
Assigns the physical :ref:`seat <seats>` for this device. See
|
|
**libinput_seat_get_physical_name()**. Defaults to "seat0".
|
|
|
|
ID_INPUT
|
|
If this property is set, the device is considered an input device. Any
|
|
device with this property missing will be ignored, see :ref:`udev_device_type`.
|
|
|
|
ID_INPUT_KEYBOARD, ID_INPUT_KEY, ID_INPUT_MOUSE, ID_INPUT_TOUCHPAD, ID_INPUT_TOUCHSCREEN, ID_INPUT_TABLET, ID_INPUT_JOYSTICK, ID_INPUT_ACCELEROMETER
|
|
If any of the above is set, libinput initializes the device as the given
|
|
type, see :ref:`udev_device_type`. Note that for historical reasons more than
|
|
one of these may be set at any time, libinput will select only one of these
|
|
to determine the device type. To ensure libinput selects the correct device
|
|
type, only set one of them.
|
|
|
|
WL_SEAT
|
|
Assigns the logical :ref:`seat <seats>` for this device. See
|
|
**libinput_seat_get_logical_name()** context. Defaults to "default".
|
|
|
|
MOUSE_DPI
|
|
HW resolution and sampling frequency of a relative pointer device.
|
|
See :ref:`motion_normalization` for details.
|
|
|
|
MOUSE_WHEEL_CLICK_ANGLE
|
|
The angle in degrees for each click on a mouse wheel. See
|
|
**libinput_pointer_get_axis_source()** for details.
|
|
|
|
|
|
Below is an example udev rule to assign "seat1" to a device from vendor
|
|
0x012a with the model ID of 0x034b. ::
|
|
|
|
ACTION=="add|change", KERNEL=="event[0-9]*", ENV{ID_VENDOR_ID}=="012a", \
|
|
ENV{ID_MODEL_ID}=="034b", ENV{ID_SEAT}="seat1"
|
|
|
|
|
|
|
|
.. _udev_device_type:
|
|
|
|
------------------------------------------------------------------------------
|
|
Device type assignment via udev
|
|
------------------------------------------------------------------------------
|
|
|
|
libinput requires the **ID_INPUT** property to be set on a device,
|
|
otherwise the device will be ignored. In addition, one of
|
|
**ID_INPUT_KEYBOARD, ID_INPUT_KEY, ID_INPUT_MOUSE, ID_INPUT_TOUCHPAD,
|
|
ID_INPUT_TOUCHSCREEN, ID_INPUT_TABLET, ID_INPUT_JOYSTICK,
|
|
ID_INPUT_ACCELEROMETER** must be set on the device to determine the
|
|
device type. The usual error handling applies within libinput and a device
|
|
type label does not guarantee that the device is initialized by libinput.
|
|
If a device fails to meet the requirements for a device type (e.g. a keyboard
|
|
labelled as touchpad) the device will not be available through libinput.
|
|
|
|
Only one device type should be set per device at a type, though libinput can
|
|
handle some combinations for historical reasons.
|
|
|
|
Below is an example udev rule to remove an **ID_INPUT_TOUCHPAD** setting
|
|
and change it into an **ID_INPUT_TABLET** setting. This rule would apply
|
|
for a device with the vendor/model ID of 012a/034b. ::
|
|
|
|
ACTION=="add|change", KERNEL=="event[0-9]*", ENV{ID_VENDOR_ID}=="012a", \
|
|
ENV{ID_MODEL_ID}=="034b", ENV{ID_INPUT_TOUCHPAD}="", ENV{ID_INPUT_TABLET}="1"
|
|
|
|
|
|
|
|
.. _ignoring_devices:
|
|
|
|
------------------------------------------------------------------------------
|
|
Ignoring specific devices
|
|
------------------------------------------------------------------------------
|
|
|
|
If a device has the **LIBINPUT_IGNORE_DEVICE** udev property set to any
|
|
value but "0", that device is not initialized by libinput. For a context
|
|
created with **libinput_udev_create_context()**, the device is silently ignored
|
|
and never shows up. If the device is added with **libinput_path_add_device()**
|
|
to a context created with **libinput_path_create_context()**, adding the device
|
|
will fail and return NULL (see that function's documentation for more
|
|
information).
|
|
|
|
If the property value is exactly "0", then the property is considered unset
|
|
and libinput initializes the device normally.
|
|
|
|
This property should be used for devices that are correctly detected as
|
|
input devices (see :ref:`udev_device_type`) but that should not be used by
|
|
libinput. It is recommended that devices that should not be handled as input
|
|
devices at all unset the **ID_INPUT** and related properties instead. The
|
|
**LIBINPUT_IGNORE_DEVICE** property signals that only libinput should
|
|
ignore this property but other parts of the stack (if any) should continue
|
|
treating this device normally.
|
|
|
|
|
|
.. _model_specific_configuration:
|
|
|
|
------------------------------------------------------------------------------
|
|
Model-specific configuration
|
|
------------------------------------------------------------------------------
|
|
|
|
As of libinput 1.12, model-specific configuration is stored in the
|
|
:ref:`device-quirks` and not in the hwdb anymore. Please see @ref device-quirks for
|
|
details.
|
|
|
|
.. _model_specific_configuration_x220fw81:
|
|
|
|
..............................................................................
|
|
Lenovo x220 with touchpad firmware v8.1
|
|
..............................................................................
|
|
|
|
The property **LIBINPUT_MODEL_LENOVO_X220_TOUCHPAD_FW81** may be set by a
|
|
user in a local hwdb file. This property designates the touchpad on a Lenovo
|
|
x220 with a touchpad firmware version 8.1. When this firmware version is
|
|
installed, the touchpad is imprecise. The touchpad device does not send
|
|
continuos x/y axis position updates, a behavior also observed on its
|
|
successor model, the Lenovo x230 which has the same firmware version. If the
|
|
above property is set, libinput adjusts its behavior to better suit this
|
|
particular model.
|
|
|
|
The touchpad firmware version cannot be detected automatically by libinput,
|
|
local configuration is required to set this property. Refer to the libinput
|
|
model quirks hwdb for instructions.
|
|
|
|
This property must not be used for any other purpose, no specific behavior
|
|
is guaranteed.
|
|
|
|
|
|
.. _hwdb:
|
|
|
|
------------------------------------------------------------------------------
|
|
Configuring the hwdb
|
|
------------------------------------------------------------------------------
|
|
|
|
This section outlines how to query the
|
|
`udev hwdb <https://www.freedesktop.org/software/systemd/man/hwdb.html>`_
|
|
and reload properties so they are available to libinput.
|
|
|
|
The hwdb contains a set of match rules that assign udev properties that are
|
|
available to libinput when the device is connected and/or libinput is
|
|
initialized. This section only describes the hwdb in relation to libinput,
|
|
it is not a full documentation on how the hwdb works.
|
|
|
|
libinput's use of the hwdb is limited to properties systemd and custom
|
|
rules files (where available) provide. Hardware-specific quirks as used by
|
|
libinput are in the :ref:`device-quirks` system.
|
|
|
|
.. _hwdb_querying:
|
|
|
|
..............................................................................
|
|
Querying the hwdb
|
|
..............................................................................
|
|
|
|
libinput only uses device nodes in the form of ``/dev/input/eventX`` where X
|
|
is the number of the specific device. Running ``libinput debug-events`` lists
|
|
all devices currently available to libinput and their event node name: ::
|
|
|
|
$> sudo libinput debug-events
|
|
-event2 DEVICE_ADDED Power Button seat0 default group1 cap:k
|
|
-event5 DEVICE_ADDED Video Bus seat0 default group2 cap:k
|
|
-event0 DEVICE_ADDED Lid Switch seat0 default group3 cap:S
|
|
|
|
...
|
|
|
|
Note the event node name for your device and translate it into a syspath in
|
|
the form of ``/sys/class/input/eventX``. This path can be supplied to ``udevadm
|
|
info`` ::
|
|
|
|
$> udevadm info
|
|
P: /devices/LNXSYSTM:00/LNXSYBUS:00/PNP0C0D:00/input/input0/event0
|
|
N: input/event0
|
|
E: DEVNAME=/dev/input/event0
|
|
E: DEVPATH=/devices/LNXSYSTM:00/LNXSYBUS:00/PNP0C0D:00/input/input0/event0
|
|
E: ID_INPUT=1
|
|
E: ID_INPUT_SWITCH=1
|
|
E: MAJOR=13
|
|
E: MINOR=64
|
|
E: SUBSYSTEM=input
|
|
E: TAGS=:power-switch:
|
|
E: USEC_INITIALIZED=7167898
|
|
|
|
Lines starting with ``E:`` are udev properties available to libinput. For
|
|
example, the above device's ``ID_INPUT_SWITCH`` property will cause libinput
|
|
to treat this device as switch device.
|
|
|
|
|
|
.. _hwdb_reloading:
|
|
|
|
..............................................................................
|
|
Reloading the hwdb
|
|
..............................................................................
|
|
|
|
The actual hwdb is stored in binary file on-disk and must be updated
|
|
manually whenever a ``.hwdb`` file changes. This is required both when a user
|
|
manually edits the ``.hwdb`` file but also when the git tree is updated (and
|
|
that update causes a hwdb change).
|
|
|
|
To update the binary file on-disk, run: ::
|
|
|
|
sudo udevadm hwdb --update
|
|
|
|
Then, to trigger a reload of all properties on your device, run: ::
|
|
|
|
sudo udevadm trigger /sys/class/input/eventX
|
|
|
|
Then check with ``udevadm info`` whether the properties were updated, see
|
|
:ref:`hwdb_querying`. If a new property does not appear on the device, use ``udevadm
|
|
test`` to check for error messages by udev and the hwdb (e.g. syntax errors
|
|
in the udev rules files). ::
|
|
|
|
sudo udevadm test /sys/class/input/eventX
|
|
|
|
.. _hwdb_modifying:
|
|
|
|
..............................................................................
|
|
Modifying the hwdb
|
|
..............................................................................
|
|
|
|
.. warning:: This section has been removed as it no longer applies in libinput 1.12
|
|
and later. libinput users should not need to modify the hwdb, any
|
|
device-specific quirks must go in to the :ref:`device-quirks` system.
|
|
|
|
For information about older libinput versions, please see the documentation
|
|
for your version avaialable in: https://wayland.freedesktop.org/libinput/doc/
|