Manual parsing of HID report descriptors | Linux 6.18.37

요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.

1. 요약·해설

원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.

요약·해설

hidreport-parsing.rst:1-49

HID descriptor short item은 prefix의 2-bit size, 2-bit type, 4-bit tag와 뒤따르는 payload로 구성됩니다. 예제 `05 01 09 02`는 Generic Desktop Page의 Mouse usage입니다.

문서 위치

항목값

SourceDocumentation/hid/hidreport-parsing.rst

분량49 source lines

Prefixsize · type · tag

예제05 01 09 02

Source와 핵심 범위입니다.

핵심 흐름

Prefix bit 분해Item type·function 결정Payload 길이 readHID Spec·HUT로 값 해석

이 문서가 설명하는 작업 순서입니다.

2. 영어 원문 전체

번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.

원문 전체 펼치기

1 .. SPDX-License-Identifier: GPL-2.0

3 ========================================

4 Manual parsing of HID report descriptors

5 ========================================

7 Consider again the mouse HID report descriptor

8 introduced in Documentation/hid/hidintro.rst::

10 $ hexdump -C /sys/bus/hid/devices/0003\:093A\:2510.0002/report_descriptor

11 00000000 05 01 09 02 a1 01 09 01 a1 00 05 09 19 01 29 03 |..............).|

12 00000010 15 00 25 01 75 01 95 03 81 02 75 05 95 01 81 01 |..%.u.....u.....|

13 00000020 05 01 09 30 09 31 09 38 15 81 25 7f 75 08 95 03 |...0.1.8..%.u...|

14 00000030 81 06 c0 c0 |....|

15 00000034

17 and try to parse it by hand.

19 Start with the first number, 0x05: it carries 2 bits for the

20 length of the item, 2 bits for the type of the item and 4 bits for the

21 function::

23 +----------+

24 | 00000101 |

25 +----------+

26 ^^

27 ---- Length of data (see HID spec 6.2.2.2)

28 ^^

29 ------ Type of the item (see HID spec 6.2.2.2, then jump to 6.2.2.7)

30 ^^^^

31 --------- Function of the item (see HID spec 6.2.2.7, then HUT Sec 3)

33 In our case, the length is 1 byte, the type is ``Global`` and the

34 function is ``Usage Page``, thus for parsing the value 0x01 in the second byte

35 we need to refer to HUT Sec 3.

37 The second number is the actual data, and its meaning can be found in

38 the HUT. We have a ``Usage Page``, thus we need to refer to HUT

39 Sec. 3, "Usage Pages"; from there, one sees that ``0x01`` stands for

40 ``Generic Desktop Page``.

42 Moving now to the second two bytes, and following the same scheme,

43 ``0x09`` (i.e. ``00001001``) will be followed by one byte (``01``)

44 and is a ``Local`` item (``10``). Thus, the meaning of the remaining four bits

45 (``0000``) is given in the HID spec Sec. 6.2.2.8 "Local Items", so that

46 we have a ``Usage``. From HUT, Sec. 4, "Generic Desktop Page", we see that

47 0x02 stands for ``Mouse``.

49 The following numbers can be parsed in the same way.

3. 한국어 전문 번역

영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.

Short item prefix 0x05 해독

1-35

`Documentation/hid/hidintro.rst`에서 사용한 mouse descriptor를 다시 보고 수동으로 parse합니다.

첫 byte `0x05`, binary `00000101`은 item data 길이 2bit, item type 2bit, function 또는 tag 4bit를 담습니다.

하위 2bit는 data 길이이며 HID Spec 6.2.2.2를 봅니다. 다음 2bit는 item type이며 같은 절에서 시작해 6.2.2.7을 확인합니다. 상위 4bit는 item function이고 HID Spec 6.2.2.7과 HUT 3절을 사용합니다.

이 예에서 data 길이는 1byte, type은 `Global`, function은 `Usage Page`입니다. 따라서 둘째 byte `0x01`을 해석하려면 HUT 3절을 봐야 합니다.

0x05 short-item prefix

Bits값의미

7..40000Function/tag = Usage Page

3..201Type = Global

1..001Data length = 1 byte

원문의 bit ASCII 그림을 구조화했습니다.

Short item 해독

Prefix byte를 binary로 변환하위 2bit로 payload length 결정다음 2bit로 Main·Global·Local type 결정상위 4bit로 item function 결정뒤따르는 payload를 HID Spec·HUT로 해석

Prefix에서 data byte 의미까지의 순서입니다.

.. SPDX-License-Identifier: GPL-2.0

========================================
Manual parsing of HID report descriptors
========================================

Consider again the mouse HID report descriptor
introduced in Documentation/hid/hidintro.rst::

  $ 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

and try to parse it by hand.

Start with the first number, 0x05: it carries 2 bits for the
length of the item, 2 bits for the type of the item and 4 bits for the
function::

  +----------+
  | 00000101 |
  +----------+
          ^^
          ---- Length of data (see HID spec 6.2.2.2)
        ^^
        ------ Type of the item (see HID spec 6.2.2.2, then jump to 6.2.2.7)
    ^^^^
    --------- Function of the item (see HID spec 6.2.2.7, then HUT Sec 3)

In our case, the length is 1 byte, the type is ``Global`` and the
function is ``Usage Page``, thus for parsing the value 0x01 in the second byte
we need to refer to HUT Sec 3.

Usage Page와 Usage item 해독

36-49

둘째 byte는 실제 data이며 의미는 HUT에서 찾습니다. 앞 item이 `Usage Page`이므로 HUT 3절 Usage Pages를 확인하면 `0x01`은 `Generic Desktop Page`입니다.

다음 두 byte도 같은 방식으로 해석합니다. `0x09`, binary `00001001`은 1byte payload가 뒤따르는 `Local` item입니다.

남은 상위 4bit `0000`의 의미는 HID Spec 6.2.2.8 Local Items에 따라 `Usage`입니다. HUT 4절 Generic Desktop Page에서 payload `0x02`는 `Mouse`임을 확인합니다.

뒤따르는 descriptor byte도 같은 방식으로 계속 parse할 수 있습니다.

첫 두 descriptor item

BytesTypeFunctionValue

05 01GlobalUsage PageGeneric Desktop Page

09 02LocalUsageMouse

Prefix와 payload 해석 결과입니다.

Usage 해석 연결

05 01에서 Generic Desktop Page 선택다음 prefix 09를 Local Usage로 해석1byte payload 02 read현재 Generic Desktop HUT table 조회Usage Mouse로 결정

Global page가 뒤의 local usage namespace를 정합니다.


The second number is the actual data, and its meaning can be found in
the HUT. We have a ``Usage Page``, thus we need to refer to HUT
Sec. 3, "Usage Pages"; from there, one sees that ``0x01`` stands for
``Generic Desktop Page``.

Moving now to the second two bytes, and following the same scheme,
``0x09`` (i.e. ``00001001``) will be followed by one byte (``01``)
and is a ``Local`` item (``10``). Thus, the meaning of the remaining four bits
(``0000``) is given in the HID spec Sec. 6.2.2.8 "Local Items", so that
we have a ``Usage``. From HUT, Sec. 4, "Generic Desktop Page",  we see that
0x02 stands for ``Mouse``.

The following numbers can be parsed in the same way.