hwdb: add comments about matching entries

Follow-up for 57bb707d48131f4daad2b1b746eab586eb66b4f3.

This makes the comments in 60-evdev.hwdb, 60-keyboard.hwdb, and
70-pointingstick.hwdb consistent.

3 files changed, 59 insertions, 26 deletions

diff --git a/hwdb.d/60-evdev.hwdb b/hwdb.d/60-evdev.hwdb
index ef42637ed7..3fbe7ca8e7 100644
--- a/hwdb.d/60-evdev.hwdb
+++ b/hwdb.d/60-evdev.hwdb
@@ -1,11 +1,34 @@
 # This file is part of systemd.
 #
+# ########################### MATCHING #######################################
+#
 # The lookup keys are composed in:
 #   60-evdev.rules
 #
-# Match string formats:
-# evdev:<modalias>
-# evdev:name:<device name>:dmi:<dmi string>
+# Supported hardware matches are:
+#  - Generic input devices match:
+#      evdev:input:bZZZZvYYYYpXXXXeWWWW-VVVV
+#    This matches on the kernel modalias of the input-device, mainly:
+#    ZZZZ is the bus-id (see /usr/include/linux/input.h BUS_*), YYYY, XXXX and
+#    WWWW are the 4-digit hex uppercase vendor, product and version ID and VVVV
+#    is a variable-length input-modalias describing the device capabilities.
+#    The vendor, product and version ID for a device node "eventX" is listed
+#    in /sys/class/input/eventX/device/id.
+#
+#  - Input driver device name and DMI data match:
+#      evdev:name:<input device name>:dmi:bvn*:bvr*:bd*:svn<vendor>:pn*
+#    <input device name> is the name device specified by the
+#    driver, <vendor> is the firmware-provided string exported
+#    by the kernel DMI modalias, see /sys/class/dmi/id/modalias.
+#
+#  - Extended input driver device name, properties and DMI data match:
+#      evdev:name:<input device name>:phys:<phys>:ev:<ev>:dmi:bvn*:bvr*:bd*:svn<vendor>:pn*
+#    <input device name> is the name device specified by the
+#    driver, <phys> is the physical-device-path, "cat
+#    /sys/class/input/input?/phys", <ev> is the event bitmask, "cat
+#    /sys/class/input/input?/capabilities/ev" and <vendor> is the
+#    firmware-provided string exported by the kernel DMI modalias,
+#    see /sys/class/dmi/id/modalias.
 #
 # To add local entries, create a new file
 #   /etc/udev/hwdb.d/61-evdev-local.hwdb
diff --git a/hwdb.d/60-keyboard.hwdb b/hwdb.d/60-keyboard.hwdb
index cdf32107a9..9cfc2fb4ec 100644
--- a/hwdb.d/60-keyboard.hwdb
+++ b/hwdb.d/60-keyboard.hwdb
@@ -19,14 +19,14 @@
 #    This matches on the kernel modalias of the input-device, mainly:
 #    ZZZZ is the bus-id (see /usr/include/linux/input.h BUS_*), YYYY, XXXX and
 #    WWWW are the 4-digit hex uppercase vendor, product and version ID and VVVV
-#    is an arbitrary length input-modalias describing the device capabilities.
+#    is a variable-length input-modalias describing the device capabilities.
 #    The vendor, product and version ID for a device node "eventX" is listed
 #    in /sys/class/input/eventX/device/id.
 #
 #  - AT keyboard DMI data matches:
 #      evdev:atkbd:dmi:bvn*:bvr*:bd*:svn<vendor>:pn<product>:pvr*
 #    <vendor> and <product> are the firmware-provided strings
-#    exported by the kernel DMI modalias, see /sys/class/dmi/id/modalias
+#    exported by the kernel DMI modalias, see /sys/class/dmi/id/modalias.
 #
 #  - Input driver device name and DMI data match:
 #      evdev:name:<input device name>:dmi:bvn*:bvr*:bd*:svn<vendor>:pn*
@@ -41,7 +41,22 @@
 #    /sys/class/input/input?/phys", <ev> is the event bitmask, "cat
 #    /sys/class/input/input?/capabilities/ev" and <vendor> is the
 #    firmware-provided string exported by the kernel DMI modalias,
-#    see /sys/class/dmi/id/modalias
+#    see /sys/class/dmi/id/modalias.
+#
+# To add local entries, create a new file
+#   /etc/udev/hwdb.d/61-keyboard-local.hwdb
+# and add your rules there. To load the new rules execute (as root):
+#   systemd-hwdb update
+#   udevadm trigger /dev/input/eventXX
+# where /dev/input/eventXX is the keyboard in question. If in doubt, simply use
+# /dev/input/event* to reload all input rules.
+#
+# If your changes are generally applicable, preferably send them as a pull
+# request to
+#   https://github.com/systemd/systemd
+# or create a bug report on https://github.com/systemd/systemd/issues and
+# include your new rules, a description of the device, and the output of
+#   udevadm info /dev/input/eventXX.
 
 # ######################### KEY MAPPING ######################################
 #
@@ -76,22 +91,6 @@
 # Examples of such devices: Chromebooks where the top row is used for both
 # media and F1-F10 keys.
 
-# To update this file, create a new file
-#   /etc/udev/hwdb.d/70-keyboard.hwdb
-# and add your rules there. To load the new rules execute (as root):
-#   systemd-hwdb update
-#   udevadm trigger /dev/input/eventXX
-# where /dev/input/eventXX is the keyboard in question. If in
-# doubt, simply reload all input rules
-#   udevadm trigger --verbose --sysname-match="event*"
-#
-# If your changes are generally applicable, preferably send them as a pull
-# request to
-#   https://github.com/systemd/systemd
-# or create a bug report on https://github.com/systemd/systemd/issues and
-# include your new rules, a description of the device, and the output of
-#   udevadm info /dev/input/eventXX.
-
 ##########################################
 # Acer
 ##########################################
diff --git a/hwdb.d/70-pointingstick.hwdb b/hwdb.d/70-pointingstick.hwdb
index 00f28c6034..d1e8a7689f 100644
--- a/hwdb.d/70-pointingstick.hwdb
+++ b/hwdb.d/70-pointingstick.hwdb
@@ -4,6 +4,8 @@
 # laptop pointingsticks have the same speed / feel, and per model adjustment
 # of the IBM TrackPoint driver's sensitivity setting
 #
+# ########################### MATCHING #######################################
+#
 # The lookup keys are composed in:
 #   60-evdev.rules
 #
@@ -13,7 +15,7 @@
 #    This matches on the kernel modalias of the input-device, mainly:
 #    ZZZZ is the bus-id (see /usr/include/linux/input.h BUS_*), YYYY, XXXX and
 #    WWW are the 4-digit hex uppercase vendor, product and version ID and VVVV
-#    is an arbitrary length input-modalias describing the device capabilities.
+#    is a variable-length input-modalias describing the device capabilities.
 #    The vendor, product and version ID for a device node "eventX" is listed
 #    in /sys/class/input/eventX/device/id.
 #
@@ -21,15 +23,24 @@
 #      evdev:name:<input device name>:dmi:bvn*:bvr*:bd*:svn<vendor>:pn*:*
 #    <input device name> is the name device specified by the driver,
 #    <vendor> is the firmware-provided string from the kernel DMI modalias,
-#    see /sys/class/dmi/id/modalias
+#    see /sys/class/dmi/id/modalias.
+#
+#  - Extended input driver device name, properties and DMI data match:
+#      evdev:name:<input device name>:phys:<phys>:ev:<ev>:dmi:bvn*:bvr*:bd*:svn<vendor>:pn*
+#    <input device name> is the name device specified by the
+#    driver, <phys> is the physical-device-path, "cat
+#    /sys/class/input/input?/phys", <ev> is the event bitmask, "cat
+#    /sys/class/input/input?/capabilities/ev" and <vendor> is the
+#    firmware-provided string exported by the kernel DMI modalias,
+#    see /sys/class/dmi/id/modalias.
 #
 # To add local entries, create a new file
 #   /etc/udev/hwdb.d/71-pointingstick-local.hwdb
 # and add your rules there. To load the new rules execute (as root):
 #   systemd-hwdb update
 #   udevadm trigger /dev/input/eventXX
-# where /dev/input/eventXX is the pointingstick in question. If in
-# doubt, simply use /dev/input/event* to reload all input rules.
+# where /dev/input/eventXX is the pointingstick in question. If in doubt, simply
+# use /dev/input/event* to reload all input rules.
 #
 # If your changes are generally applicable, preferably send them as a pull
 # request to