Care and feeding of your Human Interface Devices

HID event의 input·hiddev 분기

USB는 일반적인 input 형태의 HID device뿐 아니라 실제 human interface는 아니지만 통신 요구가 비슷한 장치에도 HID protocol을 사용합니다. 대표적인 두 예는 UPS 같은 power device와 고급 monitor의 monitor control입니다.

서로 다른 요구를 지원하기 위해 Linux USB system은 HID event를 두 interface에 제공합니다.

Input subsystem은 HID event를 keyboard, mouse, joystick 같은 일반 input device interface와 정규화된 event interface로 변환합니다. 관련 설명은 `Documentation/input/input.rst`에 있습니다.

Hiddev interface는 비교적 raw에 가까운 HID event를 제공합니다.

Device가 만든 HID event는 `usb.c`에서 `hid-core.c`로 들어간 뒤 두 경로로 갈라집니다. 한 경로는 `hid-input.c`를 통해 keyboard·mouse·joystick·event device에 도달하고, 다른 경로는 `hiddev.c`를 통해 power 또는 monitor control application에 도달합니다.

USB 이외 subsystem도 input subsystem에 event를 공급할 수 있지만, 이는 HID device interface에는 영향을 주지 않습니다.

================================================
Care and feeding of your Human Interface Devices
================================================

Introduction
============

In addition to the normal input type HID devices, USB also uses the
human interface device protocols for things that are not really human
interfaces, but have similar sorts of communication needs. The two big
examples for this are power devices (especially uninterruptible power
supplies) and monitor control on higher end monitors.

To support these disparate requirements, the Linux USB system provides
HID events to two separate interfaces:
* the input subsystem, which converts HID events into normal input
device interfaces (such as keyboard, mouse and joystick) and a
normalised event interface - see Documentation/input/input.rst
* the hiddev interface, which provides fairly raw HID events

The data flow for a HID event produced by a device is something like
the following::

 usb.c ---> hid-core.c  ----> hid-input.c ----> [keyboard/mouse/joystick/event]
                         |
                         |
                          --> hiddev.c ----> POWER / MONITOR CONTROL

In addition, other subsystems (apart from USB) can potentially feed
events into the input subsystem, but these have no effect on the HID
device interface.

Character device node와 API 전제

Hiddev interface는 일반 USB major를 사용하는 character interface이며 minor number는 96부터 111까지입니다. 따라서 major `180`, minor `96..111`로 `/dev/usb/hiddev0..15` node를 만듭니다.

mknod /dev/usb/hiddev0 c 180 96
mknod /dev/usb/hiddev1 c 180 97
mknod /dev/usb/hiddev2 c 180 98
mknod /dev/usb/hiddev3 c 180 99
mknod /dev/usb/hiddev4 c 180 100
mknod /dev/usb/hiddev5 c 180 101
mknod /dev/usb/hiddev6 c 180 102
mknod /dev/usb/hiddev7 c 180 103
mknod /dev/usb/hiddev8 c 180 104
mknod /dev/usb/hiddev9 c 180 105
mknod /dev/usb/hiddev10 c 180 106
mknod /dev/usb/hiddev11 c 180 107
mknod /dev/usb/hiddev12 c 180 108
mknod /dev/usb/hiddev13 c 180 109
mknod /dev/usb/hiddev14 c 180 110
mknod /dev/usb/hiddev15 c 180 111

Hiddev를 지원하는 userspace program이 device에 해당하는 올바른 interface를 열면 사용할 수 있습니다. 그런 program을 직접 작성해야 한다면 이어지는 API 설명을 따릅니다.

Hiddev API 설명은 `https://www.usb.org`에서 무료로 제공되는 HID specification과 함께 읽어야 합니다. 원문은 `http://www.linux-usb.org`의 편리한 link도 안내합니다.

Using the HID Device Interface
==============================

The hiddev interface is a char interface using the normal USB major,
with the minor numbers starting at 96 and finishing at 111. Therefore,
you need the following commands::

        mknod /dev/usb/hiddev0 c 180 96
        mknod /dev/usb/hiddev1 c 180 97
        mknod /dev/usb/hiddev2 c 180 98
        mknod /dev/usb/hiddev3 c 180 99
        mknod /dev/usb/hiddev4 c 180 100
        mknod /dev/usb/hiddev5 c 180 101
        mknod /dev/usb/hiddev6 c 180 102
        mknod /dev/usb/hiddev7 c 180 103
        mknod /dev/usb/hiddev8 c 180 104
        mknod /dev/usb/hiddev9 c 180 105
        mknod /dev/usb/hiddev10 c 180 106
        mknod /dev/usb/hiddev11 c 180 107
        mknod /dev/usb/hiddev12 c 180 108
        mknod /dev/usb/hiddev13 c 180 109
        mknod /dev/usb/hiddev14 c 180 110
        mknod /dev/usb/hiddev15 c 180 111

So you point your hiddev compliant user-space program at the correct
interface for your device, and it all just works.

Assuming that you have a hiddev compliant user-space program, of
course. If you need to write one, read on.


The HIDDEV API
==============

This description should be read in conjunction with the HID
specification, freely available from https://www.usb.org, and
conveniently linked of http://www.linux-usb.org.

Report·field·usage와 read event

Hiddev API는 `read()` interface와 여러 `ioctl()` call을 사용합니다.

HID device는 report라는 data bundle로 host와 data를 교환합니다. 각 report는 field로 나뉘며, 각 field는 하나 이상의 usage를 가질 수 있습니다. HID core에서 각각의 usage는 signed 32-bit 값 하나를 가집니다.

`read()`는 event interface입니다. HID device state가 바뀌면 device는 변경 값을 포함한 report를 interrupt transfer로 보냅니다. `hid-core.c`가 report를 parse하고 report 안에서 바뀐 개별 usage를 `hiddev.c`에 반환합니다.

기본 mode에서 hiddev는 각 usage 변경을 `struct hiddev_event`로 reader에 제공합니다.

struct hiddev_event {
        unsigned hid;
        signed int value;
};

`hid`에는 변경된 상태의 HID usage identifier가, `value`에는 새 값이 들어갑니다. 이 구조체와 유용한 define·구조체는 `<linux/hiddev.h>`에 정의되어 있습니다.

HID usage identifier는 HID usage page를 상위 16-bit로 shift한 값과 usage code를 OR하여 만듭니다. 뒤에서 설명하는 `HIDIOCSFLAG` ioctl로 `read()` 동작을 변경할 수 있습니다.

The hiddev API uses a read() interface, and a set of ioctl() calls.

HID devices exchange data with the host computer using data
bundles called "reports".  Each report is divided into "fields",
each of which can have one or more "usages".  In the hid-core,
each one of these usages has a single signed 32-bit value.

read():
-------

This is the event interface.  When the HID device's state changes,
it performs an interrupt transfer containing a report which contains
the changed value.  The hid-core.c module parses the report, and
returns to hiddev.c the individual usages that have changed within
the report.  In its basic mode, the hiddev will make these individual
usage changes available to the reader using a struct hiddev_event::

       struct hiddev_event {
           unsigned hid;
           signed int value;
       };

containing the HID usage identifier for the status that changed, and
the value that it was changed to. Note that the structure is defined
within <linux/hiddev.h>, along with some other useful #defines and
structures.  The HID usage identifier is a composite of the HID usage
page shifted to the 16 high order bits ORed with the usage code.  The
behavior of the read() function can be modified using the HIDIOCSFLAG
ioctl() described below.

Version·application·collection·device ioctl

`ioctl()`은 hiddev의 control interface입니다.

`HIDIOCGVERSION`은 read-only `int`로 hiddev driver의 version code를 가져옵니다.

`HIDIOCAPPLICATION`은 HID device에 연관된 application usage를 반환합니다. `ioctl()`의 세 번째 argument로 가져올 application index를 지정하므로 application collection이 여러 개인 device에서 유용합니다.

Index가 device의 application collection 수보다 크거나 같아 유효하지 않으면 `HIDIOCAPPLICATION`은 `-1`을 반환합니다. Collection 수는 `hiddev_devinfo`의 `num_applications` field로 미리 알 수 있습니다.

`HIDIOCGCOLLECTIONINFO`는 read/write `struct hiddev_collection_info`를 사용합니다. Application collection뿐 아니라 device의 모든 collection과 hierarchy level까지 반환하므로 앞 ioctl의 superset입니다.

Caller는 원하는 collection index를 구조체의 `index` field에 넣고, ioctl이 나머지 field를 채웁니다. 마지막 collection index보다 크면 `-1`을 반환하고 `errno`를 `-EINVAL`로 설정합니다.

`HIDIOCGDEVINFO`는 device를 설명하는 read-only `struct hiddev_devinfo`를 가져옵니다.

`HIDIOCGSTRING`은 read/write `struct hiddev_string_descriptor`를 사용해 device의 string descriptor를 가져옵니다. Caller가 반환받을 descriptor를 나타내도록 `index` field를 채워야 합니다.

`HIDIOCINITREPORT`는 kernel에 device의 모든 input·feature report 값을 가져오도록 지시합니다. 이후 모든 usage 구조체가 현재 device 값을 가지며 device 변경에 따라 유지됩니다.

다만 최신 kernel은 attach 시 device report를 자동 초기화하므로 일반적으로 `HIDIOCINITREPORT`를 사용할 필요가 없습니다.

ioctl():
--------

This is the control interface. There are a number of controls:

HIDIOCGVERSION
  - int (read)

 Gets the version code out of the hiddev driver.

HIDIOCAPPLICATION
  - (none)

This ioctl call returns the HID application usage associated with the
HID device. The third argument to ioctl() specifies which application
index to get. This is useful when the device has more than one
application collection. If the index is invalid (greater or equal to
the number of application collections this device has) the ioctl
returns -1. You can find out beforehand how many application
collections the device has from the num_applications field from the
hiddev_devinfo structure.

HIDIOCGCOLLECTIONINFO
  - struct hiddev_collection_info (read/write)

This returns a superset of the information above, providing not only
application collections, but all the collections the device has.  It
also returns the level the collection lives in the hierarchy.
The user passes in a hiddev_collection_info struct with the index
field set to the index that should be returned.  The ioctl fills in
the other fields.  If the index is larger than the last collection
index, the ioctl returns -1 and sets errno to -EINVAL.

HIDIOCGDEVINFO
  - struct hiddev_devinfo (read)

Gets a hiddev_devinfo structure which describes the device.

HIDIOCGSTRING
  - struct hiddev_string_descriptor (read/write)

Gets a string descriptor from the device. The caller must fill in the
"index" field to indicate which descriptor should be returned.

HIDIOCINITREPORT
  - (none)

Instructs the kernel to retrieve all input and feature report values
from the device. At this point, all the usage structures will contain
current values for the device, and will maintain it as the device
changes.  Note that the use of this ioctl is unnecessary in general,
since later kernels automatically initialize the reports from the
device at attach time.

Report 조회·전송과 ID 열거

`HIDIOCGNAME`은 가변 길이 string으로 device name을 가져옵니다.

`HIDIOCGREPORT`는 write `struct hiddev_report_info`를 받아 device에서 feature 또는 input report를 가져오도록 kernel에 지시합니다. 모든 report를 갱신하는 INITREPORT와 달리 선택한 usage 구조체만 갱신합니다.

`HIDIOCSREPORT`는 write `struct hiddev_report_info`로 report를 device에 보냅니다. 전송 전에 아래의 `HIDIOCSUSAGE` call로 report의 개별 usage value를 채운 뒤 report 전체를 보낼 수 있습니다.

`HIDIOCGREPORTINFO`는 read/write `struct hiddev_report_info`를 채웁니다. Report는 input·output·feature type과 ID로 찾으므로 caller가 이 field들을 먼저 채워야 합니다.

ID는 device가 보고한 실제 report ID인 absolute ID이거나 relative ID일 수 있습니다. 첫 report에는 `HID_REPORT_ID_FIRST`, 특정 `report_id` 다음 report에는 `HID_REPORT_ID_NEXT | report_id`를 사용합니다.

Report ID에 대한 사전 정보가 없으면 이 relative ID로 유효한 ID를 열거하는 것이 올바른 사용법입니다. 다음 ID가 더 없으면 ioctl이 non-zero를 반환하며, 실제 report ID는 반환된 `hiddev_report_info`에 채워집니다.

HIDIOCGNAME
  - string (variable length)

Gets the device name

HIDIOCGREPORT
  - struct hiddev_report_info (write)

Instructs the kernel to get a feature or input report from the device,
in order to selectively update the usage structures (in contrast to
INITREPORT).

HIDIOCSREPORT
  - struct hiddev_report_info (write)

Instructs the kernel to send a report to the device. This report can
be filled in by the user through HIDIOCSUSAGE calls (below) to fill in
individual usage values in the report before sending the report in full
to the device.

HIDIOCGREPORTINFO
  - struct hiddev_report_info (read/write)

Fills in a hiddev_report_info structure for the user. The report is
looked up by type (input, output or feature) and id, so these fields
must be filled in by the user. The ID can be absolute -- the actual
report id as reported by the device -- or relative --
HID_REPORT_ID_FIRST for the first report, and (HID_REPORT_ID_NEXT |
report_id) for the next report after report_id. Without a priori
information about report ids, the right way to use this ioctl is to
use the relative IDs above to enumerate the valid IDs. The ioctl
returns non-zero when there is no more next ID. The real report ID is
filled into the returned hiddev_report_info structure.

Field·usage·collection 조회와 usage 설정

`HIDIOCGFIELDINFO`는 read/write `struct hiddev_field_info`에 report와 연관된 field 정보를 반환합니다. Caller는 앞 절처럼 `report_id`, `report_type`을 채우고 `field_index`도 지정해야 합니다.

`field_index`는 이전 `HIDIOCGREPORTINFO`에서 반환된 `maxfield`를 기준으로 `0`부터 `maxfield-1` 사이여야 합니다.

`HIDIOCGUCODE`는 read/write `struct hiddev_usage_ref`를 사용합니다. Report type, report ID, field index와 field 안의 usage index를 미리 채우면 `usage_code`를 반환합니다.

`HIDIOCGUSAGE`는 `hiddev_usage_ref`에 usage 값을 반환합니다. 위와 같이 위치를 모두 지정할 수도 있고 `report_type`만 채운 뒤 `report_id`에 `HID_REPORT_ID_UNKNOWN`을 지정할 수도 있습니다.

UNKNOWN mode에서 usage를 찾으면 `hiddev_usage_ref`에 그 usage와 연관된 report·field 정보가 채워집니다.

`HIDIOCSUSAGE`는 write `hiddev_usage_ref`로 output report의 usage 값을 설정합니다. Caller는 위 field와 함께 `value`도 채웁니다.

`HIDIOGCOLLECTIONINDEX`는 write `hiddev_usage_ref`가 나타내는 usage의 collection index를 반환하여 collection hierarchy에서 usage가 놓인 위치를 알려 줍니다.

HIDIOCGFIELDINFO
  - struct hiddev_field_info (read/write)

Returns the field information associated with a report in a
hiddev_field_info structure. The user must fill in report_id and
report_type in this structure, as above. The field_index should also
be filled in, which should be a number from 0 and maxfield-1, as
returned from a previous HIDIOCGREPORTINFO call.

HIDIOCGUCODE
  - struct hiddev_usage_ref (read/write)

Returns the usage_code in a hiddev_usage_ref structure, given that
its report type, report id, field index, and index within the
field have already been filled into the structure.

HIDIOCGUSAGE
  - struct hiddev_usage_ref (read/write)

Returns the value of a usage in a hiddev_usage_ref structure. The
usage to be retrieved can be specified as above, or the user can
choose to fill in the report_type field and specify the report_id as
HID_REPORT_ID_UNKNOWN. In this case, the hiddev_usage_ref will be
filled in with the report and field information associated with this
usage if it is found.

HIDIOCSUSAGE
  - struct hiddev_usage_ref (write)

Sets the value of a usage in an output report.  The user fills in
the hiddev_usage_ref structure as above, but additionally fills in
the value field.

HIDIOGCOLLECTIONINDEX
  - struct hiddev_usage_ref (write)

Returns the collection index associated with this usage.  This
indicates where in the collection hierarchy this usage sits.

read mode flag와 report notification

`HIDIOCGFLAG`은 read-only `int`로 mode flag를 조회하고 `HIDIOCSFLAG`은 write `int`로 `read()`에 영향을 주는 mode flag를 교체합니다.

`HIDDEV_FLAG_UREF`를 설정하면 `read()`가 `struct hiddev_event` 대신 `struct hiddev_usage_ref`를 반환합니다. 더 큰 구조체이지만 report에 같은 usage code를 가진 usage가 여러 개 있을 때 report·field 위치를 함께 제공해 모호성을 해결합니다.

`HIDDEV_FLAG_REPORT`는 `HIDDEV_FLAG_UREF`와 함께만 사용할 수 있습니다. Device가 report를 보내면 `read()`가 `report_type`과 `report_id`를 채우고 `field_index`를 `FIELD_INDEX_NONE`으로 둔 `struct hiddev_usage_ref`를 반환합니다.

이 특별한 record는 개별 usage 변경 외에 device가 report 하나를 전송했다는 추가 notification 역할을 합니다.

HIDIOCGFLAG
  - int (read)
HIDIOCSFLAG
  - int (write)

These operations respectively inspect and replace the mode flags
that influence the read() call above.  The flags are as follows:

    HIDDEV_FLAG_UREF
      - read() calls will now return
        struct hiddev_usage_ref instead of struct hiddev_event.
        This is a larger structure, but in situations where the
        device has more than one usage in its reports with the
        same usage code, this mode serves to resolve such
        ambiguity.

    HIDDEV_FLAG_REPORT
      - This flag can only be used in conjunction
        with HIDDEV_FLAG_UREF.  With this flag set, when the device
        sends a report, a struct hiddev_usage_ref will be returned
        to read() filled in with the report_type and report_id, but
        with field_index set to FIELD_INDEX_NONE.  This serves as
        additional notification when the device has sent a report.