sphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget /translations/zh_CN/hid/hidintromodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget /translations/zh_TW/hid/hidintromodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget /translations/it_IT/hid/hidintromodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget /translations/ja_JP/hid/hidintromodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget /translations/ko_KR/hid/hidintromodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget /translations/sp_SP/hid/hidintromodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhcomment)}(h SPDX-License-Identifier: GPL-2.0h]h SPDX-License-Identifier: GPL-2.0}hhsbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1hhhhhh:/var/lib/git/docbuild/linux/Documentation/hid/hidintro.rsthKubhsection)}(hhh](htitle)}(h&Introduction to HID report descriptorsh]h&Introduction to HID report descriptors}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh paragraph)}(hThis chapter is meant to give a broad overview of what HID report descriptors are, and of how a casual (non-kernel) programmer can deal with HID devices that are not working well with Linux.h]hThis chapter is meant to give a broad overview of what HID report descriptors are, and of how a casual (non-kernel) programmer can deal with HID devices that are not working well with Linux.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubhtopic)}(hhh]h bullet_list)}(hhh](h list_item)}(hhh]h)}(hhh]h reference)}(hhh]h Introduction}(hhhhhNhNubah}(h]id4ah ]h"]h$]h&]refid introductionuh1hhhubah}(h]h ]h"]h$]h&]uh1hhhubah}(h]h ]h"]h$]h&]uh1hhhubh)}(hhh](h)}(hhh]h)}(hhh]hParsing HID report descriptors}(hjhhhNhNubah}(h]id5ah ]h"]h$]h&]refidparsing-hid-report-descriptorsuh1hhj ubah}(h]h ]h"]h$]h&]uh1hhj ubh)}(hhh]h)}(hhh]h)}(hhh]h)}(hhh]h!Output, Input and Feature Reports}(hj.hhhNhNubah}(h]id6ah ]h"]h$]h&]refid output-input-and-feature-reportsuh1hhj+ubah}(h]h ]h"]h$]h&]uh1hhj(ubah}(h]h ]h"]h$]h&]uh1hhj%ubah}(h]h ]h"]h$]h&]uh1hhj ubeh}(h]h ]h"]h$]h&]uh1hhhubh)}(hhh]h)}(hhh]h)}(hhh]h(Collections, Report IDs and Evdev events}(hj\hhhNhNubah}(h]id7ah ]h"]h$]h&]refid'collections-report-ids-and-evdev-eventsuh1hhjYubah}(h]h ]h"]h$]h&]uh1hhjVubah}(h]h ]h"]h$]h&]uh1hhhubh)}(hhh]h)}(hhh]h)}(hhh]hEvents}(hj~hhhNhNubah}(h]id8ah ]h"]h$]h&]refideventsuh1hhj{ubah}(h]h ]h"]h$]h&]uh1hhjxubah}(h]h ]h"]h$]h&]uh1hhhubh)}(hhh](h)}(hhh]h)}(hhh]hWhen something does not work}(hjhhhNhNubah}(h]id9ah ]h"]h$]h&]refidwhen-something-does-not-workuh1hhjubah}(h]h ]h"]h$]h&]uh1hhjubh)}(hhh](h)}(hhh]h)}(hhh]h)}(hhh]hQuirks}(hjhhhNhNubah}(h]id10ah ]h"]h$]h&]refidquirksuh1hhjubah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]uh1hhjubh)}(hhh]h)}(hhh]h)}(hhh]hFixing HID report descriptors}(hjhhhNhNubah}(h]id11ah ]h"]h$]h&]refidfixing-hid-report-descriptorsuh1hhjubah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]uh1hhjubh)}(hhh]h)}(hhh]h)}(hhh]h)Modifying the transmitted data on the fly}(hjhhhNhNubah}(h]id12ah ]h"]h$]h&]refid)modifying-the-transmitted-data-on-the-flyuh1hhjubah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]uh1hhjubh)}(hhh]h)}(hhh]h)}(hhh]hWriting a specialized driver}(hj%hhhNhNubah}(h]id13ah ]h"]h$]h&]refidwriting-a-specialized-driveruh1hhj"ubah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]uh1hhjubeh}(h]h ]h"]h$]h&]uh1hhjubeh}(h]h ]h"]h$]h&]uh1hhhubeh}(h]h ]h"]h$]h&]uh1hhhhhhNhNubah}(h]contentsah ](contentslocaleh"]contentsah$]h&]uh1hhhhK hhhhubhcompound)}(hhh]htoctree)}(hhh]h}(h]h ]h"]h$]h&]h hid/hidintroentries]Nhid/hidreport-parsinga includefiles]jpamaxdepthKcaptionNglobhidden includehiddennumberedK titlesonly rawentries]uh1jbhhhKhj_ubah}(h]h ]toctree-wrapperah"]h$]h&]uh1j]hhhhhhhNubh)}(hhh](h)}(h Introductionh]h Introduction}(hjhhhNhNubah}(h]h ]h"]h$]h&]refidhuh1hhjhhhhhKubh)}(hHID stands for Human Interface Device, and can be whatever device you are using to interact with a computer, be it a mouse, a touchpad, a tablet, a microphone.h]hHID stands for Human Interface Device, and can be whatever device you are using to interact with a computer, be it a mouse, a touchpad, a tablet, a microphone.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hXkMany HID devices work out the box, even if their hardware is different. For example, mice can have any number of buttons; they may have a wheel; movement sensitivity differs between different models, and so on. Nonetheless, most of the time everything just works, without the need to have specialized code in the kernel for every mouse model developed since 1970.h]hXkMany HID devices work out the box, even if their hardware is different. For example, mice can have any number of buttons; they may have a wheel; movement sensitivity differs between different models, and so on. Nonetheless, most of the time everything just works, without the need to have specialized code in the kernel for every mouse model developed since 1970.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hXThis is because modern HID devices do advertise their capabilities through the *HID report descriptor*, a fixed set of bytes describing exactly what *HID reports* may be sent between the device and the host and the meaning of each individual bit in those reports. For example, a HID Report Descriptor may specify that "in a report with ID 3 the bits from 8 to 15 is the delta x coordinate of a mouse".h](hOThis is because modern HID devices do advertise their capabilities through the }(hjhhhNhNubhemphasis)}(h*HID report descriptor*h]hHID report descriptor}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh/, a fixed set of bytes describing exactly what }(hjhhhNhNubj)}(h *HID reports*h]h HID reports}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh may be sent between the device and the host and the meaning of each individual bit in those reports. For example, a HID Report Descriptor may specify that “in a report with ID 3 the bits from 8 to 15 is the delta x coordinate of a mouse”.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK#hjhhubh)}(hXUThe HID report itself then merely carries the actual data values without any extra meta information. Note that HID reports may be sent from the device ("Input Reports", i.e. input events), to the device ("Output Reports" to e.g. change LEDs) or used for device configuration ("Feature reports"). A device may support one or more HID reports.h]hXaThe HID report itself then merely carries the actual data values without any extra meta information. Note that HID reports may be sent from the device (“Input Reports”, i.e. input events), to the device (“Output Reports” to e.g. change LEDs) or used for device configuration (“Feature reports”). A device may support one or more HID reports.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK*hjhhubh)}(hXThe HID subsystem is in charge of parsing the HID report descriptors, and converts HID events into normal input device interfaces (see Documentation/hid/hid-transport.rst). Devices may misbehave because the HID report descriptor provided by the device is wrong, or because it needs to be dealt with in a special way, or because some special device or interaction mode is not handled by the default code.h]hXThe HID subsystem is in charge of parsing the HID report descriptors, and converts HID events into normal input device interfaces (see Documentation/hid/hid-transport.rst). Devices may misbehave because the HID report descriptor provided by the device is wrong, or because it needs to be dealt with in a special way, or because some special device or interaction mode is not handled by the default code.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK0hjhhubh)}(hThe format of HID report descriptors is described by two documents, available from the `USB Implementers Forum `_ `HID web page `_ address:h](hWThe format of HID report descriptors is described by two documents, available from the }(hjhhhNhNubh)}(h0`USB Implementers Forum `_h]hUSB Implementers Forum}(hj hhhNhNubah}(h]h ]h"]h$]h&]nameUSB Implementers Forumrefurihttps://www.usb.org/uh1hhjubhtarget)}(h h]h}(h]usb-implementers-forumah ]h"]usb implementers forumah$]h&]refurijuh1j referencedKhjubh }(hjhhhNhNubh)}(h)`HID web page `_h]h HID web page}(hj0hhhNhNubah}(h]h ]h"]h$]h&]name HID web pagejhttps://www.usb.org/hiduh1hhjubj)}(h h]h}(h] hid-web-pageah ]h"] hid web pageah$]h&]refurij@uh1jj+Khjubh address:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK7hjhhubh block_quote)}(h* the `HID USB Device Class Definition `_ (HID Spec from now on) * the `HID Usage Tables `_ (HUT from now on) h]h)}(hhh](h)}(hthe `HID USB Device Class Definition `_ (HID Spec from now on)h]h)}(hthe `HID USB Device Class Definition `_ (HID Spec from now on)h](hthe }(hjehhhNhNubh)}(hi`HID USB Device Class Definition `_h]hHID USB Device Class Definition}(hjmhhhNhNubah}(h]h ]h"]h$]h&]nameHID USB Device Class DefinitionjDhttps://www.usb.org/document-library/device-class-definition-hid-111uh1hhjeubj)}(hG h]h}(h]hid-usb-device-class-definitionah ]h"]hid usb device class definitionah$]h&]refurij}uh1jj+Khjeubh (HID Spec from now on)}(hjehhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK;hjaubah}(h]h ]h"]h$]h&]uh1hhj^ubh)}(hathe `HID Usage Tables `_ (HUT from now on) h]h)}(h`the `HID Usage Tables `_ (HUT from now on)h](hthe }(hjhhhNhNubh)}(hJ`HID Usage Tables `_h]hHID Usage Tables}(hjhhhNhNubah}(h]h ]h"]h$]h&]nameHID Usage Tablesj4https://usb.org/document-library/hid-usage-tables-14uh1hhjubj)}(h7 h]h}(h]hid-usage-tablesah ]h"]hid usage tablesah$]h&]refurijuh1jj+Khjubh (HUT from now on)}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK=hjubah}(h]h ]h"]h$]h&]uh1hhj^ubeh}(h]h ]h"]h$]h&]bullet*uh1hhhhK;hjZubah}(h]h ]h"]h$]h&]uh1jXhhhK;hjhhubh)}(hThe HID subsystem can deal with different transport drivers (USB, I2C, Bluetooth, etc.). See Documentation/hid/hid-transport.rst.h]hThe HID subsystem can deal with different transport drivers (USB, I2C, Bluetooth, etc.). See Documentation/hid/hid-transport.rst.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK?hjhhubeh}(h]hah ]h"] introductionah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hParsing HID report descriptorsh]hParsing HID report descriptors}(hjhhhNhNubah}(h]h ]h"]h$]h&]jjuh1hhjhhhhhKCubh)}(hThe current list of HID devices can be found at ``/sys/bus/hid/devices/``. For each device, say ``/sys/bus/hid/devices/0003\:093A\:2510.0002/``, one can read the corresponding report descriptor::h](h0The current list of HID devices can be found at }(hj hhhNhNubhliteral)}(h``/sys/bus/hid/devices/``h]h/sys/bus/hid/devices/}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh. For each device, say }(hj hhhNhNubj)}(h/``/sys/bus/hid/devices/0003\:093A\:2510.0002/``h]h+/sys/bus/hid/devices/0003\:093A\:2510.0002/}(hj%hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh3, one can read the corresponding report descriptor:}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKEhjhhubh literal_block)}(hX$ hexdump -C /sys/bus/hid/devices/0003\:093A\:2510.0002/report_descriptor 00000000 05 01 09 02 a1 01 09 01 a1 00 05 09 19 01 29 03 |..............).| 00000010 15 00 25 01 75 01 95 03 81 02 75 05 95 01 81 01 |..%.u.....u.....| 00000020 05 01 09 30 09 31 09 38 15 81 25 7f 75 08 95 03 |...0.1.8..%.u...| 00000030 81 06 c0 c0 |....| 00000034h]hX$ hexdump -C /sys/bus/hid/devices/0003\:093A\:2510.0002/report_descriptor 00000000 05 01 09 02 a1 01 09 01 a1 00 05 09 19 01 29 03 |..............).| 00000010 15 00 25 01 75 01 95 03 81 02 75 05 95 01 81 01 |..%.u.....u.....| 00000020 05 01 09 30 09 31 09 38 15 81 25 7f 75 08 95 03 |...0.1.8..%.u...| 00000030 81 06 c0 c0 |....| 00000034}hj?sbah}(h]h ]h"]h$]h&]hhuh1j=hhhKIhjhhubh)}(hhOptional: the HID report descriptor can be read also by directly accessing the hidraw driver [#hidraw]_.h](h]Optional: the HID report descriptor can be read also by directly accessing the hidraw driver }(hjMhhhNhNubhfootnote_reference)}(h [#hidraw]_h]h1}(hjWhhhNhNubah}(h]id1ah ]h"]h$]h&]autoKjhidrawdocnamejmuh1jUhjMresolvedKubh.}(hjMhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKPhjhhubh)}(hXThe basic structure of HID report descriptors is defined in the HID spec, while HUT "defines constants that can be interpreted by an application to identify the purpose and meaning of a data field in a HID report". Each entry is defined by at least two bytes, where the first one defines what type of value is following and is described in the HID spec, while the second one carries the actual value and is described in the HUT.h]hXThe basic structure of HID report descriptors is defined in the HID spec, while HUT “defines constants that can be interpreted by an application to identify the purpose and meaning of a data field in a HID report”. Each entry is defined by at least two bytes, where the first one defines what type of value is following and is described in the HID spec, while the second one carries the actual value and is described in the HUT.}(hjthhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKShjhhubh)}(hXHID report descriptors can, in principle, be painstakingly parsed by hand, byte by byte.h]hXHID report descriptors can, in principle, be painstakingly parsed by hand, byte by byte.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK[hjhhubh)}(hA short introduction on how to do this is sketched in Documentation/hid/hidreport-parsing.rst; you only need to understand it if you need to patch HID report descriptors.h]hA short introduction on how to do this is sketched in Documentation/hid/hidreport-parsing.rst; you only need to understand it if you need to patch HID report descriptors.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK^hjhhubh)}(hIn practice you should not parse HID report descriptors by hand; rather, you should use an existing parser. Among all the available onesh]hIn practice you should not parse HID report descriptors by hand; rather, you should use an existing parser. Among all the available ones}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKbhjhhubjY)}(hX@* the online `USB Descriptor and Request Parser `_; * `hidrdd `_, that provides very detailed and somewhat verbose descriptions (verbosity can be useful if you are not familiar with HID report descriptors); * `hid-tools `_, a complete utility set that allows, among other things, to record and replay the raw HID reports and to debug and replay HID devices. It is being actively developed by the Linux HID subsystem maintainers. h]h)}(hhh](h)}(h]the online `USB Descriptor and Request Parser `_;h]h)}(h]the online `USB Descriptor and Request Parser `_;h](h the online }(hjhhhNhNubh)}(hQ`USB Descriptor and Request Parser `_h]h!USB Descriptor and Request Parser}(hjhhhNhNubah}(h]h ]h"]h$]h&]name!USB Descriptor and Request Parserj*http://eleccelerator.com/usbdescreqparser/uh1hhjubj)}(h- h]h}(h]!usb-descriptor-and-request-parserah ]h"]!usb descriptor and request parserah$]h&]refurijuh1jj+Khjubh;}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKehjubah}(h]h ]h"]h$]h&]uh1hhjubh)}(h`hidrdd `_, that provides very detailed and somewhat verbose descriptions (verbosity can be useful if you are not familiar with HID report descriptors);h]h)}(h`hidrdd `_, that provides very detailed and somewhat verbose descriptions (verbosity can be useful if you are not familiar with HID report descriptors);h](h)}(h.`hidrdd `_h]hhidrdd}(hjhhhNhNubah}(h]h ]h"]h$]h&]namehidrddj"https://github.com/abend0c1/hidrdduh1hhjubj)}(h% h]h}(h]hidrddah ]h"]hidrddah$]h&]refurijuh1jj+Khjubh, that provides very detailed and somewhat verbose descriptions (verbosity can be useful if you are not familiar with HID report descriptors);}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKghjubah}(h]h ]h"]h$]h&]uh1hhjubh)}(hX`hid-tools `_, a complete utility set that allows, among other things, to record and replay the raw HID reports and to debug and replay HID devices. It is being actively developed by the Linux HID subsystem maintainers. h]h)}(hX`hid-tools `_, a complete utility set that allows, among other things, to record and replay the raw HID reports and to debug and replay HID devices. It is being actively developed by the Linux HID subsystem maintainers.h](h)}(h@`hid-tools `_h]h hid-tools}(hj+hhhNhNubah}(h]h ]h"]h$]h&]name hid-toolsj1https://gitlab.freedesktop.org/libevdev/hid-toolsuh1hhj'ubj)}(h4 h]h}(h] hid-toolsah ]h"] hid-toolsah$]h&]refurij;uh1jj+Khj'ubh, a complete utility set that allows, among other things, to record and replay the raw HID reports and to debug and replay HID devices. It is being actively developed by the Linux HID subsystem maintainers.}(hj'hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKkhj#ubah}(h]h ]h"]h$]h&]uh1hhjubeh}(h]h ]h"]h$]h&]jjuh1hhhhKehjubah}(h]h ]h"]h$]h&]uh1jXhhhKehjhhubh)}(hParsing the mouse HID report descriptor with `hid-tools `_ leads to (explanations interposed)::h](h-Parsing the mouse HID report descriptor with }(hjehhhNhNubh)}(h@`hid-tools `_h]h hid-tools}(hjmhhhNhNubah}(h]h ]h"]h$]h&]name hid-toolsj1https://gitlab.freedesktop.org/libevdev/hid-toolsuh1hhjeubj)}(h4 h]h}(h]id2ah ]h"]h$] hid-toolsah&]refurij}uh1jj+Khjeubh$ leads to (explanations interposed):}(hjehhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKqhjhhubj>)}(hX$ ./hid-decode /sys/bus/hid/devices/0003\:093A\:2510.0002/report_descriptor # device 0:0 # 0x05, 0x01, // Usage Page (Generic Desktop) 0 # 0x09, 0x02, // Usage (Mouse) 2 # 0xa1, 0x01, // Collection (Application) 4 # 0x09, 0x01, // Usage (Pointer) 6 # 0xa1, 0x00, // Collection (Physical) 8 # 0x05, 0x09, // Usage Page (Button) 10h]hX$ ./hid-decode /sys/bus/hid/devices/0003\:093A\:2510.0002/report_descriptor # device 0:0 # 0x05, 0x01, // Usage Page (Generic Desktop) 0 # 0x09, 0x02, // Usage (Mouse) 2 # 0xa1, 0x01, // Collection (Application) 4 # 0x09, 0x01, // Usage (Pointer) 6 # 0xa1, 0x00, // Collection (Physical) 8 # 0x05, 0x09, // Usage Page (Button) 10}hjsbah}(h]h ]h"]h$]h&]hhuh1j=hhhKuhjhhubh)}(hwhat follows is a button ::h]hwhat follows is a button}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK~hjhhubj>)}(h# 0x19, 0x01, // Usage Minimum (1) 12 # 0x29, 0x03, // Usage Maximum (3) 14h]h# 0x19, 0x01, // Usage Minimum (1) 12 # 0x29, 0x03, // Usage Maximum (3) 14}hjsbah}(h]h ]h"]h$]h&]hhuh1j=hhhKhjhhubh)}(hBfirst button is button number 1, last button is button number 3 ::h]h?first button is button number 1, last button is button number 3}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj>)}(h# 0x15, 0x00, // Logical Minimum (0) 16 # 0x25, 0x01, // Logical Maximum (1) 18h]h# 0x15, 0x00, // Logical Minimum (0) 16 # 0x25, 0x01, // Logical Maximum (1) 18}hjsbah}(h]h ]h"]h$]h&]hhuh1j=hhhKhjhhubh)}(hVeach button can send values from 0 up to including 1 (i.e. they are binary buttons) ::h]hSeach button can send values from 0 up to including 1 (i.e. they are binary buttons)}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj>)}(hI# 0x75, 0x01, // Report Size (1) 20h]hI# 0x75, 0x01, // Report Size (1) 20}hjsbah}(h]h ]h"]h$]h&]hhuh1j=hhhKhjhhubh)}(h)each button is sent as exactly one bit ::h]h&each button is sent as exactly one bit}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj>)}(hI# 0x95, 0x03, // Report Count (3) 22h]hI# 0x95, 0x03, // Report Count (3) 22}hjsbah}(h]h ]h"]h$]h&]hhuh1j=hhhKhjhhubh)}(hAand there are three of those bits (matching the three buttons) ::h]h>and there are three of those bits (matching the three buttons)}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj>)}(hI# 0x81, 0x02, // Input (Data,Var,Abs) 24h]hI# 0x81, 0x02, // Input (Data,Var,Abs) 24}hj!sbah}(h]h ]h"]h$]h&]hhuh1j=hhhKhjhhubh)}(hit's actual Data (not constant padding), they represent a single variable (Var) and their values are Absolute (not relative); See HID spec Sec. 6.2.2.5 "Input, Output, and Feature Items" ::h]hit’s actual Data (not constant padding), they represent a single variable (Var) and their values are Absolute (not relative); See HID spec Sec. 6.2.2.5 “Input, Output, and Feature Items”}(hj/hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj>)}(hI# 0x75, 0x05, // Report Size (5) 26h]hI# 0x75, 0x05, // Report Size (5) 26}hj=sbah}(h]h ]h"]h$]h&]hhuh1j=hhhKhjhhubh)}(h7five additional padding bits, needed to reach a byte ::h]h4five additional padding bits, needed to reach a byte}(hjKhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj>)}(hI# 0x95, 0x01, // Report Count (1) 28h]hI# 0x95, 0x01, // Report Count (1) 28}hjYsbah}(h]h ]h"]h$]h&]hhuh1j=hhhKhjhhubh)}(h)those five bits are repeated only once ::h]h&those five bits are repeated only once}(hjghhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj>)}(hI# 0x81, 0x01, // Input (Cnst,Arr,Abs) 30h]hI# 0x81, 0x01, // Input (Cnst,Arr,Abs) 30}hjusbah}(h]h ]h"]h$]h&]hhuh1j=hhhKhjhhubh)}(h)}(hX'# 0x05, 0x01, // Usage Page (Generic Desktop) 32 # 0x09, 0x30, // Usage (X) 34 # 0x09, 0x31, // Usage (Y) 36 # 0x09, 0x38, // Usage (Wheel) 38h]hX'# 0x05, 0x01, // Usage Page (Generic Desktop) 32 # 0x09, 0x30, // Usage (X) 34 # 0x09, 0x31, // Usage (Y) 36 # 0x09, 0x38, // Usage (Wheel) 38}hjsbah}(h]h ]h"]h$]h&]hhuh1j=hhhKhjhhubh)}(h_The mouse has also two physical positions (Usage (X), Usage (Y)) and a wheel (Usage (Wheel)) ::h]h\The mouse has also two physical positions (Usage (X), Usage (Y)) and a wheel (Usage (Wheel))}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj>)}(h# 0x15, 0x81, // Logical Minimum (-127) 40 # 0x25, 0x7f, // Logical Maximum (127) 42h]h# 0x15, 0x81, // Logical Minimum (-127) 40 # 0x25, 0x7f, // Logical Maximum (127) 42}hjsbah}(h]h ]h"]h$]h&]hhuh1j=hhhKhjhhubh)}(hEeach of them can send values ranging from -127 up to including 127 ::h]hBeach of them can send values ranging from -127 up to including 127}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj>)}(hI# 0x75, 0x08, // Report Size (8) 44h]hI# 0x75, 0x08, // Report Size (8) 44}hjsbah}(h]h ]h"]h$]h&]hhuh1j=hhhKhjhhubh)}(h%which is represented by eight bits ::h]h"which is represented by eight bits}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj>)}(hI# 0x95, 0x03, // Report Count (3) 46h]hI# 0x95, 0x03, // Report Count (3) 46}hjsbah}(h]h ]h"]h$]h&]hhuh1j=hhhKhjhhubh)}(hDand there are three of those eight bits, matching X, Y and Wheel. ::h]hAand there are three of those eight bits, matching X, Y and Wheel.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj>)}(hI# 0x81, 0x06, // Input (Data,Var,Rel) 48h]hI# 0x81, 0x06, // Input (Data,Var,Rel) 48}hjsbah}(h]h ]h"]h$]h&]hhuh1j=hhhKhjhhubh)}(hwThis time the data values are Relative (Rel), i.e. they represent the change from the previously sent report (event) ::h]htThis time the data values are Relative (Rel), i.e. they represent the change from the previously sent report (event)}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj>)}(hXT# 0xc0, // End Collection 50 # 0xc0, // End Collection 51 # R: 52 05 01 09 02 a1 01 09 01 a1 00 05 09 19 01 29 03 15 00 25 01 75 01 95 03 81 02 75 05 95 01 81 01 05 01 09 30 09 31 09 38 15 81 25 7f 75 08 95 03 81 06 c0 c0 N: device 0:0 I: 3 0001 0001h]hXT# 0xc0, // End Collection 50 # 0xc0, // End Collection 51 # R: 52 05 01 09 02 a1 01 09 01 a1 00 05 09 19 01 29 03 15 00 25 01 75 01 95 03 81 02 75 05 95 01 81 01 05 01 09 30 09 31 09 38 15 81 25 7f 75 08 95 03 81 06 c0 c0 N: device 0:0 I: 3 0001 0001}hjsbah}(h]h ]h"]h$]h&]hhuh1j=hhhKhjhhubh)}(hThis Report Descriptor tells us that the mouse input will be transmitted using four bytes: the first one for the buttons (three bits used, five for padding), the last three for the mouse X, Y and wheel changes, respectively.h]hThis Report Descriptor tells us that the mouse input will be transmitted using four bytes: the first one for the buttons (three bits used, five for padding), the last three for the mouse X, Y and wheel changes, respectively.}(hj+hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hX7Indeed, for any event, the mouse will send a *report* of four bytes. We can check the values sent by resorting e.g. to the `hid-recorder` tool, from `hid-tools `_: The sequence of bytes sent by clicking and releasing button 1, then button 2, then button 3 is::h](h-Indeed, for any event, the mouse will send a }(hj9hhhNhNubj)}(h*report*h]hreport}(hjAhhhNhNubah}(h]h ]h"]h$]h&]uh1jhj9ubhF of four bytes. We can check the values sent by resorting e.g. to the }(hj9hhhNhNubhtitle_reference)}(h`hid-recorder`h]h hid-recorder}(hjUhhhNhNubah}(h]h ]h"]h$]h&]uh1jShj9ubh tool, from }(hj9hhhNhNubh)}(h@`hid-tools `_h]h hid-tools}(hjghhhNhNubah}(h]h ]h"]h$]h&]name hid-toolsj1https://gitlab.freedesktop.org/libevdev/hid-toolsuh1hhj9ubj)}(h4 h]h}(h]id3ah ]h"]h$] hid-toolsah&]refurijwuh1jj+Khj9ubha: The sequence of bytes sent by clicking and releasing button 1, then button 2, then button 3 is:}(hj9hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj>)}(hXS$ sudo ./hid-recorder /dev/hidraw1 .... output of hid-decode .... # Button: 1 0 0 | # | X: 0 | Y: 0 | Wheel: 0 E: 000000.000000 4 01 00 00 00 # Button: 0 0 0 | # | X: 0 | Y: 0 | Wheel: 0 E: 000000.183949 4 00 00 00 00 # Button: 0 1 0 | # | X: 0 | Y: 0 | Wheel: 0 E: 000001.959698 4 02 00 00 00 # Button: 0 0 0 | # | X: 0 | Y: 0 | Wheel: 0 E: 000002.103899 4 00 00 00 00 # Button: 0 0 1 | # | X: 0 | Y: 0 | Wheel: 0 E: 000004.855799 4 04 00 00 00 # Button: 0 0 0 | # | X: 0 | Y: 0 | Wheel: 0 E: 000005.103864 4 00 00 00 00h]hXS$ sudo ./hid-recorder /dev/hidraw1 .... output of hid-decode .... # Button: 1 0 0 | # | X: 0 | Y: 0 | Wheel: 0 E: 000000.000000 4 01 00 00 00 # Button: 0 0 0 | # | X: 0 | Y: 0 | Wheel: 0 E: 000000.183949 4 00 00 00 00 # Button: 0 1 0 | # | X: 0 | Y: 0 | Wheel: 0 E: 000001.959698 4 02 00 00 00 # Button: 0 0 0 | # | X: 0 | Y: 0 | Wheel: 0 E: 000002.103899 4 00 00 00 00 # Button: 0 0 1 | # | X: 0 | Y: 0 | Wheel: 0 E: 000004.855799 4 04 00 00 00 # Button: 0 0 0 | # | X: 0 | Y: 0 | Wheel: 0 E: 000005.103864 4 00 00 00 00}hjsbah}(h]h ]h"]h$]h&]hhuh1j=hhhKhjhhubh)}(hThis example shows that when button 2 is clicked, the bytes ``02 00 00 00`` are sent, and the immediately subsequent event (``00 00 00 00``) is the release of button 2 (no buttons are pressed, remember that the data values are *absolute*).h](h)}(hX_# Button: 1 0 0 | # | X: 0 | Y: 0 | Wheel: 0 E: 000044.175830 4 01 00 00 00 # Button: 1 1 0 | # | X: 0 | Y: 0 | Wheel: 0 E: 000045.975997 4 03 00 00 00 # Button: 0 1 0 | # | X: 0 | Y: 0 | Wheel: 0 E: 000047.407930 4 02 00 00 00 # Button: 0 0 0 | # | X: 0 | Y: 0 | Wheel: 0 E: 000049.199919 4 00 00 00 00h]hX_# Button: 1 0 0 | # | X: 0 | Y: 0 | Wheel: 0 E: 000044.175830 4 01 00 00 00 # Button: 1 1 0 | # | X: 0 | Y: 0 | Wheel: 0 E: 000045.975997 4 03 00 00 00 # Button: 0 1 0 | # | X: 0 | Y: 0 | Wheel: 0 E: 000047.407930 4 02 00 00 00 # Button: 0 0 0 | # | X: 0 | Y: 0 | Wheel: 0 E: 000049.199919 4 00 00 00 00}hjsbah}(h]h ]h"]h$]h&]hhuh1j=hhhKhjhhubh)}(hwhere with ``03 00 00 00`` both buttons are pressed, and with the subsequent ``02 00 00 00`` button 1 is released while button 2 is still active.h](h where with }(hjhhhNhNubj)}(h``03 00 00 00``h]h 03 00 00 00}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh3 both buttons are pressed, and with the subsequent }(hjhhhNhNubj)}(h``02 00 00 00``h]h 02 00 00 00}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh5 button 1 is released while button 2 is still active.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hhh](h)}(h!Output, Input and Feature Reportsh]h!Output, Input and Feature Reports}(hj2hhhNhNubah}(h]h ]h"]h$]h&]jj7uh1hhj/hhhhhKubh)}(hXCHID devices can have Input Reports, like in the mouse example, Output Reports, and Feature Reports. "Output" means that the information is sent to the device. For example, a joystick with force feedback will have some output; the led of a keyboard would need an output as well. "Input" means that data come from the device.h]hXKHID devices can have Input Reports, like in the mouse example, Output Reports, and Feature Reports. “Output” means that the information is sent to the device. For example, a joystick with force feedback will have some output; the led of a keyboard would need an output as well. “Input” means that data come from the device.}(hj@hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj/hhubh)}(h"Feature"s are not meant to be consumed by the end user and define configuration options for the device. They can be queried from the host; when declared as *Volatile* they should be changed by the host.h](h“Feature”s are not meant to be consumed by the end user and define configuration options for the device. They can be queried from the host; when declared as }(hjNhhhNhNubj)}(h *Volatile*h]hVolatile}(hjVhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjNubh$ they should be changed by the host.}(hjNhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj/hhubeh}(h]j=ah ]h"]!output, input and feature reportsah$]h&]uh1hhjhhhhhKubeh}(h]jah ]h"]parsing hid report descriptorsah$]h&]uh1hhhhhhhhKCubh)}(hhh](h)}(h(Collections, Report IDs and Evdev eventsh]h(Collections, Report IDs and Evdev events}(hjhhhNhNubah}(h]h ]h"]h$]h&]jjeuh1hhj|hhhhhMubh)}(hA single device can logically group data into different independent sets, called a *Collection*. Collections can be nested and there are different types of collections (see the HID spec 6.2.2.6 "Collection, End Collection Items" for details).h](hSA single device can logically group data into different independent sets, called a }(hjhhhNhNubj)}(h *Collection*h]h Collection}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh. Collections can be nested and there are different types of collections (see the HID spec 6.2.2.6 “Collection, End Collection Items” for details).}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM hj|hhubh)}(hXLDifferent reports are identified by means of different *Report ID* fields, i.e. a number identifying the structure of the immediately following report. Whenever a Report ID is needed it is transmitted as the first byte of any report. A device with only one supported HID report (like the mouse example above) may omit the report ID.h](h7Different reports are identified by means of different }(hjhhhNhNubj)}(h *Report ID*h]h Report ID}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubhX  fields, i.e. a number identifying the structure of the immediately following report. Whenever a Report ID is needed it is transmitted as the first byte of any report. A device with only one supported HID report (like the mouse example above) may omit the report ID.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj|hhubh)}(h.Consider the following HID report descriptor::h]h-Consider the following HID report descriptor:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj|hhubj>)}(hX05 01 09 02 A1 01 85 01 05 09 19 01 29 05 15 00 25 01 95 05 75 01 81 02 95 01 75 03 81 01 05 01 09 30 09 31 16 00 F8 26 FF 07 75 0C 95 02 81 06 09 38 15 80 25 7F 75 08 95 01 81 06 05 0C 0A 38 02 15 80 25 7F 75 08 95 01 81 06 C0 05 01 09 02 A1 01 85 02 05 09 19 01 29 05 15 00 25 01 95 05 75 01 81 02 95 01 75 03 81 01 05 01 09 30 09 31 16 00 F8 26 FF 07 75 0C 95 02 81 06 09 38 15 80 25 7F 75 08 95 01 81 06 05 0C 0A 38 02 15 80 25 7F 75 08 95 01 81 06 C0 05 01 09 07 A1 01 85 05 05 07 15 00 25 01 09 29 09 3E 09 4B 09 4E 09 E3 09 E8 09 E8 09 E8 75 01 95 08 81 02 95 00 81 01 C0 05 0C 09 01 A1 01 85 06 15 00 25 01 75 01 95 01 09 3F 81 06 09 3F 81 06 09 3F 81 06 09 3F 81 06 09 3F 81 06 09 3F 81 06 09 3F 81 06 09 3F 81 06 C0 05 0C 09 01 A1 01 85 03 09 05 15 00 26 FF 00 75 08 95 02 B1 02 C0h]hX05 01 09 02 A1 01 85 01 05 09 19 01 29 05 15 00 25 01 95 05 75 01 81 02 95 01 75 03 81 01 05 01 09 30 09 31 16 00 F8 26 FF 07 75 0C 95 02 81 06 09 38 15 80 25 7F 75 08 95 01 81 06 05 0C 0A 38 02 15 80 25 7F 75 08 95 01 81 06 C0 05 01 09 02 A1 01 85 02 05 09 19 01 29 05 15 00 25 01 95 05 75 01 81 02 95 01 75 03 81 01 05 01 09 30 09 31 16 00 F8 26 FF 07 75 0C 95 02 81 06 09 38 15 80 25 7F 75 08 95 01 81 06 05 0C 0A 38 02 15 80 25 7F 75 08 95 01 81 06 C0 05 01 09 07 A1 01 85 05 05 07 15 00 25 01 09 29 09 3E 09 4B 09 4E 09 E3 09 E8 09 E8 09 E8 75 01 95 08 81 02 95 00 81 01 C0 05 0C 09 01 A1 01 85 06 15 00 25 01 75 01 95 01 09 3F 81 06 09 3F 81 06 09 3F 81 06 09 3F 81 06 09 3F 81 06 09 3F 81 06 09 3F 81 06 09 3F 81 06 C0 05 0C 09 01 A1 01 85 03 09 05 15 00 26 FF 00 75 08 95 02 B1 02 C0}hjsbah}(h]h ]h"]h$]h&]hhuh1j=hhhMhj|hhubh)}(hXAfter parsing it (try to parse it on your own using the suggested tools!) one can see that the device presents two ``Mouse`` Application Collections (with reports identified by Reports IDs 1 and 2, respectively), a ``Keypad`` Application Collection (whose report is identified by the Report ID 5) and two ``Consumer Controls`` Application Collections, (with Report IDs 6 and 3, respectively). Note, however, that a device can have different Report IDs for the same Application Collection.h](hsAfter parsing it (try to parse it on your own using the suggested tools!) one can see that the device presents two }(hjhhhNhNubj)}(h ``Mouse``h]hMouse}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh[ Application Collections (with reports identified by Reports IDs 1 and 2, respectively), a }(hjhhhNhNubj)}(h ``Keypad``h]hKeypad}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubhP Application Collection (whose report is identified by the Report ID 5) and two }(hjhhhNhNubj)}(h``Consumer Controls``h]hConsumer Controls}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh Application Collections, (with Report IDs 6 and 3, respectively). Note, however, that a device can have different Report IDs for the same Application Collection.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM*hj|hhubh)}(hThe data sent will begin with the Report ID byte, and will be followed by the corresponding information. For example, the data transmitted for the last consumer control::h]hThe data sent will begin with the Report ID byte, and will be followed by the corresponding information. For example, the data transmitted for the last consumer control:}(hj- hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM3hj|hhubj>)}(hX0x05, 0x0C, // Usage Page (Consumer) 0x09, 0x01, // Usage (Consumer Control) 0xA1, 0x01, // Collection (Application) 0x85, 0x03, // Report ID (3) 0x09, 0x05, // Usage (Headphone) 0x15, 0x00, // Logical Minimum (0) 0x26, 0xFF, 0x00, // Logical Maximum (255) 0x75, 0x08, // Report Size (8) 0x95, 0x02, // Report Count (2) 0xB1, 0x02, // Feature (Data,Var,Abs,No Wrap,Linear,Preferred State,No Null Position,Non-volatile) 0xC0, // End Collectionh]hX0x05, 0x0C, // Usage Page (Consumer) 0x09, 0x01, // Usage (Consumer Control) 0xA1, 0x01, // Collection (Application) 0x85, 0x03, // Report ID (3) 0x09, 0x05, // Usage (Headphone) 0x15, 0x00, // Logical Minimum (0) 0x26, 0xFF, 0x00, // Logical Maximum (255) 0x75, 0x08, // Report Size (8) 0x95, 0x02, // Report Count (2) 0xB1, 0x02, // Feature (Data,Var,Abs,No Wrap,Linear,Preferred State,No Null Position,Non-volatile) 0xC0, // End Collection}hj; sbah}(h]h ]h"]h$]h&]hhuh1j=hhhM7hj|hhubh)}(hwill be of three bytes: the first for the Report ID (3), the next two for the headphone, with two (``Report Count (2)``) bytes (``Report Size (8)``), each ranging from 0 (``Logical Minimum (0)``) to 255 (``Logical Maximum (255)``).h](hcwill be of three bytes: the first for the Report ID (3), the next two for the headphone, with two (}(hjI hhhNhNubj)}(h``Report Count (2)``h]hReport Count (2)}(hjQ hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjI ubh ) bytes (}(hjI hhhNhNubj)}(h``Report Size (8)``h]hReport Size (8)}(hjc hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjI ubh), each ranging from 0 (}(hjI hhhNhNubj)}(h``Logical Minimum (0)``h]hLogical Minimum (0)}(hju hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjI ubh ) to 255 (}(hjI hhhNhNubj)}(h``Logical Maximum (255)``h]hLogical Maximum (255)}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjI ubh).}(hjI hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMChj|hhubh)}(hX?All the Input data sent by the device should be translated into corresponding Evdev events, so that the remaining part of the stack can know what is going on, e.g. the bit for the first button translates into the ``EV_KEY/BTN_LEFT`` evdev event and relative X movement translates into the ``EV_REL/REL_X`` evdev event".h](hAll the Input data sent by the device should be translated into corresponding Evdev events, so that the remaining part of the stack can know what is going on, e.g. the bit for the first button translates into the }(hj hhhNhNubj)}(h``EV_KEY/BTN_LEFT``h]hEV_KEY/BTN_LEFT}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh9 evdev event and relative X movement translates into the }(hj hhhNhNubj)}(h``EV_REL/REL_X``h]h EV_REL/REL_X}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh evdev event”.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMHhj|hhubeh}(h]jkah ]h"](collections, report ids and evdev eventsah$]h&]uh1hhhhhhhhMubh)}(hhh](h)}(hEventsh]hEvents}(hj hhhNhNubah}(h]h ]h"]h$]h&]jjuh1hhj hhhhhMOubh)}(hXIn Linux, one ``/dev/input/event*`` is created for each ``Application Collection``. Going back to the mouse example, and repeating the sequence where one clicks and holds button 1, then clicks and holds button 2, releases button 1, and finally releases button 2, one gets::h](hIn Linux, one }(hj hhhNhNubj)}(h``/dev/input/event*``h]h/dev/input/event*}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh is created for each }(hj hhhNhNubj)}(h``Application Collection``h]hApplication Collection}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh. Going back to the mouse example, and repeating the sequence where one clicks and holds button 1, then clicks and holds button 2, releases button 1, and finally releases button 2, one gets:}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMQhj hhubj>)}(hX $ sudo libinput record /dev/input/event1 # libinput record version: 1 ndevices: 1 libinput: version: "1.23.0" git: "unknown" system: os: "opensuse-tumbleweed:20230619" kernel: "6.3.7-1-default" dmi: "dmi:bvnHP:bvrU77Ver.01.05.00:bd03/24/2022:br5.0:efr20.29:svnHP:pnHPEliteBook64514inchG9NotebookPC:pvr:rvnHP:rn89D2:rvrKBCVersion14.1D.00:cvnHP:ct10:cvr:sku5Y3J1EA#ABZ:" devices: - node: /dev/input/event1 evdev: # Name: PixArt HP USB Optical Mouse # ID: bus 0x3 vendor 0x3f0 product 0x94a version 0x111 # Supported Events: # Event type 0 (EV_SYN) # Event type 1 (EV_KEY) # Event code 272 (BTN_LEFT) # Event code 273 (BTN_RIGHT) # Event code 274 (BTN_MIDDLE) # Event type 2 (EV_REL) # Event code 0 (REL_X) # Event code 1 (REL_Y) # Event code 8 (REL_WHEEL) # Event code 11 (REL_WHEEL_HI_RES) # Event type 4 (EV_MSC) # Event code 4 (MSC_SCAN) # Properties: name: "PixArt HP USB Optical Mouse" id: [3, 1008, 2378, 273] codes: 0: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15] # EV_SYN 1: [272, 273, 274] # EV_KEY 2: [0, 1, 8, 11] # EV_REL 4: [4] # EV_MSC properties: [] hid: [ 0x05, 0x01, 0x09, 0x02, 0xa1, 0x01, 0x09, 0x01, 0xa1, 0x00, 0x05, 0x09, 0x19, 0x01, 0x29, 0x03, 0x15, 0x00, 0x25, 0x01, 0x95, 0x08, 0x75, 0x01, 0x81, 0x02, 0x05, 0x01, 0x09, 0x30, 0x09, 0x31, 0x09, 0x38, 0x15, 0x81, 0x25, 0x7f, 0x75, 0x08, 0x95, 0x03, 0x81, 0x06, 0xc0, 0xc0 ] udev: properties: - ID_INPUT=1 - ID_INPUT_MOUSE=1 - LIBINPUT_DEVICE_GROUP=3/3f0/94a:usb-0000:05:00.3-2 quirks: events: # Current time is 12:31:56 - evdev: - [ 0, 0, 4, 4, 30] # EV_MSC / MSC_SCAN 30 (obfuscated) - [ 0, 0, 1, 272, 1] # EV_KEY / BTN_LEFT 1 - [ 0, 0, 0, 0, 0] # ------------ SYN_REPORT (0) ---------- +0ms - evdev: - [ 1, 207892, 4, 4, 30] # EV_MSC / MSC_SCAN 30 (obfuscated) - [ 1, 207892, 1, 273, 1] # EV_KEY / BTN_RIGHT 1 - [ 1, 207892, 0, 0, 0] # ------------ SYN_REPORT (0) ---------- +1207ms - evdev: - [ 2, 367823, 4, 4, 30] # EV_MSC / MSC_SCAN 30 (obfuscated) - [ 2, 367823, 1, 272, 0] # EV_KEY / BTN_LEFT 0 - [ 2, 367823, 0, 0, 0] # ------------ SYN_REPORT (0) ---------- +1160ms # Current time is 12:32:00 - evdev: - [ 3, 247617, 4, 4, 30] # EV_MSC / MSC_SCAN 30 (obfuscated) - [ 3, 247617, 1, 273, 0] # EV_KEY / BTN_RIGHT 0 - [ 3, 247617, 0, 0, 0] # ------------ SYN_REPORT (0) ---------- +880msh]hX $ sudo libinput record /dev/input/event1 # libinput record version: 1 ndevices: 1 libinput: version: "1.23.0" git: "unknown" system: os: "opensuse-tumbleweed:20230619" kernel: "6.3.7-1-default" dmi: "dmi:bvnHP:bvrU77Ver.01.05.00:bd03/24/2022:br5.0:efr20.29:svnHP:pnHPEliteBook64514inchG9NotebookPC:pvr:rvnHP:rn89D2:rvrKBCVersion14.1D.00:cvnHP:ct10:cvr:sku5Y3J1EA#ABZ:" devices: - node: /dev/input/event1 evdev: # Name: PixArt HP USB Optical Mouse # ID: bus 0x3 vendor 0x3f0 product 0x94a version 0x111 # Supported Events: # Event type 0 (EV_SYN) # Event type 1 (EV_KEY) # Event code 272 (BTN_LEFT) # Event code 273 (BTN_RIGHT) # Event code 274 (BTN_MIDDLE) # Event type 2 (EV_REL) # Event code 0 (REL_X) # Event code 1 (REL_Y) # Event code 8 (REL_WHEEL) # Event code 11 (REL_WHEEL_HI_RES) # Event type 4 (EV_MSC) # Event code 4 (MSC_SCAN) # Properties: name: "PixArt HP USB Optical Mouse" id: [3, 1008, 2378, 273] codes: 0: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15] # EV_SYN 1: [272, 273, 274] # EV_KEY 2: [0, 1, 8, 11] # EV_REL 4: [4] # EV_MSC properties: [] hid: [ 0x05, 0x01, 0x09, 0x02, 0xa1, 0x01, 0x09, 0x01, 0xa1, 0x00, 0x05, 0x09, 0x19, 0x01, 0x29, 0x03, 0x15, 0x00, 0x25, 0x01, 0x95, 0x08, 0x75, 0x01, 0x81, 0x02, 0x05, 0x01, 0x09, 0x30, 0x09, 0x31, 0x09, 0x38, 0x15, 0x81, 0x25, 0x7f, 0x75, 0x08, 0x95, 0x03, 0x81, 0x06, 0xc0, 0xc0 ] udev: properties: - ID_INPUT=1 - ID_INPUT_MOUSE=1 - LIBINPUT_DEVICE_GROUP=3/3f0/94a:usb-0000:05:00.3-2 quirks: events: # Current time is 12:31:56 - evdev: - [ 0, 0, 4, 4, 30] # EV_MSC / MSC_SCAN 30 (obfuscated) - [ 0, 0, 1, 272, 1] # EV_KEY / BTN_LEFT 1 - [ 0, 0, 0, 0, 0] # ------------ SYN_REPORT (0) ---------- +0ms - evdev: - [ 1, 207892, 4, 4, 30] # EV_MSC / MSC_SCAN 30 (obfuscated) - [ 1, 207892, 1, 273, 1] # EV_KEY / BTN_RIGHT 1 - [ 1, 207892, 0, 0, 0] # ------------ SYN_REPORT (0) ---------- +1207ms - evdev: - [ 2, 367823, 4, 4, 30] # EV_MSC / MSC_SCAN 30 (obfuscated) - [ 2, 367823, 1, 272, 0] # EV_KEY / BTN_LEFT 0 - [ 2, 367823, 0, 0, 0] # ------------ SYN_REPORT (0) ---------- +1160ms # Current time is 12:32:00 - evdev: - [ 3, 247617, 4, 4, 30] # EV_MSC / MSC_SCAN 30 (obfuscated) - [ 3, 247617, 1, 273, 0] # EV_KEY / BTN_RIGHT 0 - [ 3, 247617, 0, 0, 0] # ------------ SYN_REPORT (0) ---------- +880ms}hj sbah}(h]h ]h"]h$]h&]hhuh1j=hhhMVhj hhubh)}(hXNote: if ``libinput record`` is not available on your system try using ``evemu-record``.h](h Note: if }(hj) hhhNhNubj)}(h``libinput record``h]hlibinput record}(hj1 hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj) ubh+ is not available on your system try using }(hj) hhhNhNubj)}(h``evemu-record``h]h evemu-record}(hjC hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj) ubh.}(hj) hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj hhubeh}(h]jah ]h"]eventsah$]h&]uh1hhhhhhhhMOubh)}(hhh](h)}(hWhen something does not workh]hWhen something does not work}(hje hhhNhNubah}(h]h ]h"]h$]h&]jjuh1hhjb hhhhhMubh)}(hTThere can be a number of reasons why a device does not behave correctly. For exampleh]hTThere can be a number of reasons why a device does not behave correctly. For example}(hjs hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjb hhubh)}(hhh](h)}(hXJThe HID report descriptor provided by the HID device may be wrong because e.g. * it does not follow the standard, so that the kernel will not able to make sense of the HID report descriptor; * the HID report descriptor *does not match* what is actually sent by the device (this can be verified by reading the raw HID data);h](h)}(hNThe HID report descriptor provided by the HID device may be wrong because e.g.h]hNThe HID report descriptor provided by the HID device may be wrong because e.g.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubh)}(hhh](h)}(hmit does not follow the standard, so that the kernel will not able to make sense of the HID report descriptor;h]h)}(hmit does not follow the standard, so that the kernel will not able to make sense of the HID report descriptor;h]hmit does not follow the standard, so that the kernel will not able to make sense of the HID report descriptor;}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1hhj ubh)}(hthe HID report descriptor *does not match* what is actually sent by the device (this can be verified by reading the raw HID data);h]h)}(hthe HID report descriptor *does not match* what is actually sent by the device (this can be verified by reading the raw HID data);h](hthe HID report descriptor }(hj hhhNhNubj)}(h*does not match*h]hdoes not match}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubhX what is actually sent by the device (this can be verified by reading the raw HID data);}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1hhj ubeh}(h]h ]h"]h$]h&]jjuh1hhhhMhj ubeh}(h]h ]h"]h$]h&]uh1hhj hhhNhNubh)}(hAthe HID report descriptor may need some "quirks" (see later on). h]h)}(h@the HID report descriptor may need some "quirks" (see later on).h]hDthe HID report descriptor may need some “quirks” (see later on).}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1hhj hhhhhNubeh}(h]h ]h"]h$]h&]jjuh1hhhhMhjb hhubh)}(hAs a consequence, a ``/dev/input/event*`` may not be created for each Application Collection, and/or the events there may not match what you would expect.h](hAs a consequence, a }(hj hhhNhNubj)}(h``/dev/input/event*``h]h/dev/input/event*}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubhq may not be created for each Application Collection, and/or the events there may not match what you would expect.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjb hhubh)}(hhh](h)}(hQuirksh]hQuirks}(hj( hhhNhNubah}(h]h ]h"]h$]h&]jjuh1hhj% hhhhhMubh)}(hThere are some known peculiarities of HID devices that the kernel knows how to fix - these are called the HID quirks and a list of those is available in `include/linux/hid.h`.h](hThere are some known peculiarities of HID devices that the kernel knows how to fix - these are called the HID quirks and a list of those is available in }(hj6 hhhNhNubjT)}(h`include/linux/hid.h`h]hinclude/linux/hid.h}(hj> hhhNhNubah}(h]h ]h"]h$]h&]uh1jShj6 ubh.}(hj6 hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj% hhubh)}(hShould this be the case, it should be enough to add the required quirk in the kernel, for the HID device at hand. This can be done in the file `drivers/hid/hid-quirks.c`. How to do it should be relatively straightforward after looking into the file.h](hShould this be the case, it should be enough to add the required quirk in the kernel, for the HID device at hand. This can be done in the file }(hjV hhhNhNubjT)}(h`drivers/hid/hid-quirks.c`h]hdrivers/hid/hid-quirks.c}(hj^ hhhNhNubah}(h]h ]h"]h$]h&]uh1jShjV ubhP. How to do it should be relatively straightforward after looking into the file.}(hjV hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj% hhubh)}(hDThe list of currently defined quirks, from `include/linux/hid.h`, ish](h+The list of currently defined quirks, from }(hjv hhhNhNubjT)}(h`include/linux/hid.h`h]hinclude/linux/hid.h}(hj~ hhhNhNubah}(h]h ]h"]h$]h&]uh1jShjv ubh, is}(hjv hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj% hhubh line_block)}(hhh](hh)}(h**HID_QUIRK_NOTOUCH**:h](hstrong)}(h**HID_QUIRK_NOTOUCH**h]hHID_QUIRK_NOTOUCH}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j hj ubh:}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hindentKhj hQ/var/lib/git/docbuild/linux/Documentation/hid/hidintro:449: ./include/linux/hid.hhKubj )}(h(**HID_QUIRK_IGNORE**: ignore this deviceh](j )}(h**HID_QUIRK_IGNORE**h]hHID_QUIRK_IGNORE}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j hj ubh: ignore this device}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hj Khj hj hKubj )}(h**HID_QUIRK_NOGET**:h](j )}(h**HID_QUIRK_NOGET**h]hHID_QUIRK_NOGET}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j hj ubh:}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hj Khj hj hKubj )}(h**HID_QUIRK_HIDDEV_FORCE**:h](j )}(h**HID_QUIRK_HIDDEV_FORCE**h]hHID_QUIRK_HIDDEV_FORCE}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j hj ubh:}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hj Khj hj hKubj )}(h**HID_QUIRK_BADPAD**:h](j )}(h**HID_QUIRK_BADPAD**h]hHID_QUIRK_BADPAD}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j hj ubh:}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hj Khj hj hKubj )}(h**HID_QUIRK_MULTI_INPUT**:h](j )}(h**HID_QUIRK_MULTI_INPUT**h]hHID_QUIRK_MULTI_INPUT}(hj0 hhhNhNubah}(h]h ]h"]h$]h&]uh1j hj, ubh:}(hj, hhhNhNubeh}(h]h ]h"]h$]h&]uh1hj Khj hj hKubj )}(h**HID_QUIRK_HIDINPUT_FORCE**:h](j )}(h**HID_QUIRK_HIDINPUT_FORCE**h]hHID_QUIRK_HIDINPUT_FORCE}(hjL hhhNhNubah}(h]h ]h"]h$]h&]uh1j hjH ubh:}(hjH hhhNhNubeh}(h]h ]h"]h$]h&]uh1hj Khj hj hKubj )}(h**HID_QUIRK_ALWAYS_POLL**:h](j )}(h**HID_QUIRK_ALWAYS_POLL**h]hHID_QUIRK_ALWAYS_POLL}(hjh hhhNhNubah}(h]h ]h"]h$]h&]uh1j hjd ubh:}(hjd hhhNhNubeh}(h]h ]h"]h$]h&]uh1hj Khj hj hKubj )}(h**HID_QUIRK_INPUT_PER_APP**:h](j )}(h**HID_QUIRK_INPUT_PER_APP**h]hHID_QUIRK_INPUT_PER_APP}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j hj ubh:}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hj Khj hj hKubj )}(h**HID_QUIRK_X_INVERT**:h](j )}(h**HID_QUIRK_X_INVERT**h]hHID_QUIRK_X_INVERT}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j hj ubh:}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hj Khj hj hKubj )}(h**HID_QUIRK_Y_INVERT**:h](j )}(h**HID_QUIRK_Y_INVERT**h]hHID_QUIRK_Y_INVERT}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j hj ubh:}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hj Khj hj hKubj )}(h"**HID_QUIRK_SKIP_OUTPUT_REPORTS**:h](j )}(h!**HID_QUIRK_SKIP_OUTPUT_REPORTS**h]hHID_QUIRK_SKIP_OUTPUT_REPORTS}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j hj ubh:}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hj Khj hj hKubj )}(h$**HID_QUIRK_SKIP_OUTPUT_REPORT_ID**:h](j )}(h#**HID_QUIRK_SKIP_OUTPUT_REPORT_ID**:h]hHID_QUIRK_SKIP_OUTPUT_REPORT_ID}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j hj ubh:}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hj Khj hj hKubj )}(h+**HID_QUIRK_NO_OUTPUT_REPORTS_ON_INTR_EP**:h](j )}(h***HID_QUIRK_NO_OUTPUT_REPORTS_ON_INTR_EP**h]h&HID_QUIRK_NO_OUTPUT_REPORTS_ON_INTR_EP}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j hj ubh:}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hj Khj hj hKubj )}(h"**HID_QUIRK_HAVE_SPECIAL_DRIVER**:h](j )}(h!**HID_QUIRK_HAVE_SPECIAL_DRIVER**h]hHID_QUIRK_HAVE_SPECIAL_DRIVER}(hj, hhhNhNubah}(h]h ]h"]h$]h&]uh1j hj( ubh:}(hj( hhhNhNubeh}(h]h ]h"]h$]h&]uh1hj Khj hj hKubj )}(h+**HID_QUIRK_INCREMENT_USAGE_ON_DUPLICATE**:h](j )}(h***HID_QUIRK_INCREMENT_USAGE_ON_DUPLICATE**h]h&HID_QUIRK_INCREMENT_USAGE_ON_DUPLICATE}(hjH hhhNhNubah}(h]h ]h"]h$]h&]uh1j hjD ubh:}(hjD hhhNhNubeh}(h]h ]h"]h$]h&]uh1hj Khj hj hKubj )}(h#**HID_QUIRK_IGNORE_SPECIAL_DRIVER**h]j )}(hjb h]hHID_QUIRK_IGNORE_SPECIAL_DRIVER}(hjd hhhNhNubah}(h]h ]h"]h$]h&]uh1j hj` ubah}(h]h ]h"]h$]h&]uh1hj Khj hj hKubj )}(h!**HID_QUIRK_FULLSPEED_INTERVAL**:h](j )}(h **HID_QUIRK_FULLSPEED_INTERVAL**h]hHID_QUIRK_FULLSPEED_INTERVAL}(hj{ hhhNhNubah}(h]h ]h"]h$]h&]uh1j hjw ubh:}(hjw hhhNhNubeh}(h]h ]h"]h$]h&]uh1hj Khj hj hKubj )}(h**HID_QUIRK_NO_INIT_REPORTS**:h](j )}(h**HID_QUIRK_NO_INIT_REPORTS**h]hHID_QUIRK_NO_INIT_REPORTS}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j hj ubh:}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hj Khj hj hKubj )}(h**HID_QUIRK_NO_IGNORE**:h](j )}(h**HID_QUIRK_NO_IGNORE**h]hHID_QUIRK_NO_IGNORE}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j hj ubh:}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hj Khj hj hKubj )}(h**HID_QUIRK_NO_INPUT_SYNC**:h](j )}(h**HID_QUIRK_NO_INPUT_SYNC**h]hHID_QUIRK_NO_INPUT_SYNC}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j hj ubh:}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hj Khj hj hKubeh}(h]h ]h"]h$]h&]uh1j hj% hhhj hNubh)}(hXCQuirks for USB devices can be specified while loading the usbhid module, see ``modinfo usbhid``, although the proper fix should go into hid-quirks.c and **be submitted upstream**. See Documentation/process/submitting-patches.rst for guidelines on how to submit a patch. Quirks for other busses need to go into hid-quirks.c.h](hMQuirks for USB devices can be specified while loading the usbhid module, see }(hj hhhNhNubj)}(h``modinfo usbhid``h]hmodinfo usbhid}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh:, although the proper fix should go into hid-quirks.c and }(hj hhhNhNubj )}(h**be submitted upstream**h]hbe submitted upstream}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j hj ubh. See Documentation/process/submitting-patches.rst for guidelines on how to submit a patch. Quirks for other busses need to go into hid-quirks.c.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj% hhubeh}(h]jah ]h"]quirksah$]h&]uh1hhjb hhhhhMubh)}(hhh](h)}(hFixing HID report descriptorsh]hFixing HID report descriptors}(hj)hhhNhNubah}(h]h ]h"]h$]h&]jjuh1hhj&hhhhhMubh)}(hShould you need to patch HID report descriptors the easiest way is to resort to eBPF, as described in Documentation/hid/hid-bpf.rst.h]hShould you need to patch HID report descriptors the easiest way is to resort to eBPF, as described in Documentation/hid/hid-bpf.rst.}(hj7hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj&hhubh)}(hBasically, you can change any byte of the original HID report descriptor. The examples in samples/hid should be a good starting point for your code, see e.g. `samples/hid/hid_mouse.bpf.c`::h](hBasically, you can change any byte of the original HID report descriptor. The examples in samples/hid should be a good starting point for your code, see e.g. }(hjEhhhNhNubjT)}(h`samples/hid/hid_mouse.bpf.c`h]hsamples/hid/hid_mouse.bpf.c}(hjMhhhNhNubah}(h]h ]h"]h$]h&]uh1jShjEubh:}(hjEhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj&hhubj>)}(hSEC("fmod_ret/hid_bpf_rdesc_fixup") int BPF_PROG(hid_rdesc_fixup, struct hid_bpf_ctx *hctx) { .... data[39] = 0x31; data[41] = 0x30; return 0; }h]hSEC("fmod_ret/hid_bpf_rdesc_fixup") int BPF_PROG(hid_rdesc_fixup, struct hid_bpf_ctx *hctx) { .... data[39] = 0x31; data[41] = 0x30; return 0; }}hjesbah}(h]h ]h"]h$]h&]hhuh1j=hhhMhj&hhubh)}(hOf course this can be also done within the kernel source code, see e.g. `drivers/hid/hid-aureal.c` or `drivers/hid/hid-samsung.c` for a slightly more complex file.h](hHOf course this can be also done within the kernel source code, see e.g. }(hjshhhNhNubjT)}(h`drivers/hid/hid-aureal.c`h]hdrivers/hid/hid-aureal.c}(hj{hhhNhNubah}(h]h ]h"]h$]h&]uh1jShjsubh or }(hjshhhNhNubjT)}(h`drivers/hid/hid-samsung.c`h]hdrivers/hid/hid-samsung.c}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jShjsubh" for a slightly more complex file.}(hjshhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj&hhubh)}(hCheck Documentation/hid/hidreport-parsing.rst if you need any help navigating the HID manuals and understanding the exact meaning of the HID report descriptor hex numbers.h]hCheck Documentation/hid/hidreport-parsing.rst if you need any help navigating the HID manuals and understanding the exact meaning of the HID report descriptor hex numbers.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj&hhubh)}(hX-Whatever solution you come up with, please remember to **submit the fix to the HID maintainers**, so that it can be directly integrated in the kernel and that particular HID device will start working for everyone else. See Documentation/process/submitting-patches.rst for guidelines on how to do this.h](h7Whatever solution you come up with, please remember to }(hjhhhNhNubj )}(h)**submit the fix to the HID maintainers**h]h%submit the fix to the HID maintainers}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j hjubh, so that it can be directly integrated in the kernel and that particular HID device will start working for everyone else. See Documentation/process/submitting-patches.rst for guidelines on how to do this.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj&hhubeh}(h]jah ]h"]fixing hid report descriptorsah$]h&]uh1hhjb hhhhhMubh)}(hhh](h)}(h)Modifying the transmitted data on the flyh]h)Modifying the transmitted data on the fly}(hjhhhNhNubah}(h]h ]h"]h$]h&]jj uh1hhjhhhhhMubh)}(huUsing eBPF it is also possible to modify the data exchanged with the device. See again the examples in `samples/hid`.h](hgUsing eBPF it is also possible to modify the data exchanged with the device. See again the examples in }(hjhhhNhNubjT)}(h `samples/hid`h]h samples/hid}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jShjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hLAgain, **please post your fix**, so that it can be integrated in the kernel!h](hAgain, }(hj hhhNhNubj )}(h**please post your fix**h]hplease post your fix}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j hj ubh-, so that it can be integrated in the kernel!}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubeh}(h]jah ]h"])modifying the transmitted data on the flyah$]h&]uh1hhjb hhhhhMubh)}(hhh](h)}(hWriting a specialized driverh]hWriting a specialized driver}(hj5hhhNhNubah}(h]h ]h"]h$]h&]jj.uh1hhj2hhhhhMubh)}(h'This should really be your last resort.h]h'This should really be your last resort.}(hjChhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj2hhubhrubric)}(h Footnotesh]h Footnotes}(hjShhhNhNubah}(h]h ]h"]h$]h&]uh1jQhj2hhhhhMubhfootnote)}(hXread hidraw: see Documentation/hid/hidraw.rst and file `samples/hidraw/hid-example.c` for an example. The output of ``hid-example`` would be, for the same mouse:: $ sudo ./hid-example Report Descriptor Size: 52 Report Descriptor: 5 1 9 2 a1 1 9 1 a1 0 5 9 19 1 29 3 15 0 25 1 75 1 95 3 81 2 75 5 95 1 81 1 5 1 9 30 9 31 9 38 15 81 25 7f 75 8 95 3 81 6 c0 c0 Raw Name: PixArt USB Optical Mouse Raw Phys: usb-0000:05:00.4-2.3/input0 Raw Info: bustype: 3 (USB) vendor: 0x093a product: 0x2510 ...h](hlabel)}(hhh]h1}(hjihhhNhNubah}(h]h ]h"]h$]h&]uh1jghjchhhNhNubh)}(hread hidraw: see Documentation/hid/hidraw.rst and file `samples/hidraw/hid-example.c` for an example. The output of ``hid-example`` would be, for the same mouse::h](h7read hidraw: see Documentation/hid/hidraw.rst and file }(hjvhhhNhNubjT)}(h`samples/hidraw/hid-example.c`h]hsamples/hidraw/hid-example.c}(hj~hhhNhNubah}(h]h ]h"]h$]h&]uh1jShjvubh for an example. The output of }(hjvhhhNhNubj)}(h``hid-example``h]h hid-example}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjvubh would be, for the same mouse:}(hjvhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjcubj>)}(hXb$ sudo ./hid-example Report Descriptor Size: 52 Report Descriptor: 5 1 9 2 a1 1 9 1 a1 0 5 9 19 1 29 3 15 0 25 1 75 1 95 3 81 2 75 5 95 1 81 1 5 1 9 30 9 31 9 38 15 81 25 7f 75 8 95 3 81 6 c0 c0 Raw Name: PixArt USB Optical Mouse Raw Phys: usb-0000:05:00.4-2.3/input0 Raw Info: bustype: 3 (USB) vendor: 0x093a product: 0x2510 ...h]hXb$ sudo ./hid-example Report Descriptor Size: 52 Report Descriptor: 5 1 9 2 a1 1 9 1 a1 0 5 9 19 1 29 3 15 0 25 1 75 1 95 3 81 2 75 5 95 1 81 1 5 1 9 30 9 31 9 38 15 81 25 7f 75 8 95 3 81 6 c0 c0 Raw Name: PixArt USB Optical Mouse Raw Phys: usb-0000:05:00.4-2.3/input0 Raw Info: bustype: 3 (USB) vendor: 0x093a product: 0x2510 ...}hjsbah}(h]h ]h"]h$]h&]hhuh1j=hhhMhjcubeh}(h]jgah ]h"]hidrawah$]h&]jaajfKjhjmuh1jahhhMhj2hhubeh}(h]j4ah ]h"]writing a specialized driverah$]h&]uh1hhjb hhhhhMubeh}(h]jah ]h"]when something does not workah$]h&]uh1hhhhhhhhMubeh}(h]&introduction-to-hid-report-descriptorsah ]h"]&introduction to hid report descriptorsah$]h&]uh1hhhhhhhhKubeh}(h]h ]h"]h$]h&]sourcehuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(hN generatorN datestampN source_linkN source_urlN toc_backlinksentryfootnote_backlinksK sectnum_xformKstrip_commentsNstrip_elements_with_classesN strip_classesN report_levelK halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-siginput_encoding_error_handlerstrictoutput_encodingutf-8output_encoding_error_handlerjerror_encodingutf-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourceh _destinationN _config_files]7/var/lib/git/docbuild/linux/Documentation/docutils.confafile_insertion_enabled raw_enabledKline_length_limitM'pep_referencesN pep_base_urlhttps://peps.python.org/pep_file_url_templatepep-%04drfc_referencesN rfc_base_url&https://datatracker.ietf.org/doc/html/ tab_widthKtrim_footnote_reference_spacesyntax_highlightlong smart_quotessmartquotes_locales]character_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xform image_loadinglinkembed_stylesheetcloak_email_addressessection_self_linkenvNubreporterNindirect_targets]substitution_defs}substitution_names}refnames}hidraw]jWasrefids}jg]jWasnameids}(jjjZjUjhj'j$jJjGjjjjjyjjjjj jEjBjrj=j jkj_ jjjj#jjjj/jjj4jjgu nametypes}(jjZjj'jJjjjyjjjEjrj j_ jj#jj/jjuh}(jhjUhhjj$jjGjAjj~jjjjjajWjjj jjBj<jj~j~jxj=j/jkj|jj jjb jj% jj&jjj4j2jgjchhjjj7j.jej\jj~jjjjjjj jj.j%u footnote_refs}j6]jWas citation_refs} autofootnotes]jcaautofootnote_refs]jWasymbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}jK sRparse_messages](hsystem_message)}(hhh]h)}(h,Duplicate explicit target name: "hid-tools".h]h0Duplicate explicit target name: “hid-tools”.}(hjahhhNhNubah}(h]h ]h"]h$]h&]uh1hhj^ubah}(h]h ]h"]h$]h&]jalevelKtypeINFOsourcehlineKuh1j\hjhhhhhKsubj])}(hhh]h)}(h,Duplicate explicit target name: "hid-tools".h]h0Duplicate explicit target name: “hid-tools”.}(hj}hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjzubah}(h]h ]h"]h$]h&]j~alevelKtypejwsourcehlineKuh1j\hjhhhhhKubetransform_messages] transformerN include_log] decorationNhhub.