doc/user: document the new list-kernel-devices tool

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

1 files changed, 52 insertions, 1 deletions

diff --git a/doc/user/tools.rst b/doc/user/tools.rst
index 85b207c0..53109e06 100644
--- a/doc/user/tools.rst
+++ b/doc/user/tools.rst
@@ -11,8 +11,10 @@ available in the **libinput(1)** man page.
 
 The most common tools used are:
 
-- ``libinput list-devices``: to list locally available devices,
+- ``libinput list-devices``: to list locally available devices as seen by libinput,
   see :ref:`here <libinput-list-devices>`
+- ``libinput list-kernel-devices``: to list locally available devices as seen by the kernel,
+  see :ref:`here <libinput-list-kernel-devices>`
 - ``libinput debug-events``: to monitor and debug events,
   see :ref:`here <libinput-debug-events>`
 - ``libinput debug-gui``: to visualize events,
@@ -76,6 +78,55 @@ button-areas but clickfinger is available.
 .. note:: This tool is intended for human-consumption and may change its output
           at any time.
 
+.. _libinput-list-kernel-devices:
+
+------------------------------------------------------------------------------
+libinput list-kernel-devices
+------------------------------------------------------------------------------
+
+The ``libinput list-kernel-devices`` command shows the devices known by **the
+kernel**. This command can help identify issues when a device is not handled by
+libinput.
+
+::
+
+    $ libinput list-kernel-devices
+    /dev/input/event0:	Sleep Button
+    /dev/input/event1:	Power Button
+    /dev/input/event2:	Power Button
+    /dev/input/event3:	Microsoft Microsoft® 2.4GHz Transceiver v9.0
+    /dev/input/event4:	Microsoft Microsoft® 2.4GHz Transceiver v9.0 Mouse
+    [...]
+
+
+In some cases, knowing about the HID devices behind the kernel's event nodes
+can be useful. To list HID devices, supply the ``--hid`` commandline flag:
+
+::
+
+    $ libinput list-kernel-devices --hid
+    hid:
+    - name:   'Logitech Gaming Mouse G303'
+      id:     '046d:c080'
+      driver: 'hid-generic'
+      hidraw: ['/dev/hidraw6']
+      evdev:  ['/dev/input/event13']
+
+    - name:   'Logitech Gaming Mouse G303'
+      id:     '046d:c080'
+      driver: 'hid-generic'
+      hidraw: ['/dev/hidraw7']
+      evdev:  ['/dev/input/event14']
+
+    - name:   'Microsoft Microsoft® 2.4GHz Transceiver v9.0'
+      id:     '045e:07a5'
+      driver: 'hid-generic'
+      hidraw: ['/dev/hidraw0']
+      evdev:  ['/dev/input/event3']
+
+.. note:: This tool is intended for human-consumption and may change its output
+          at any time.
+
 .. _libinput-debug-events:
 
 ------------------------------------------------------------------------------