HID Sensors Framework

HID 센서 framework와 report descriptor

HID 센서 framework는 sensor hub에 연결된 sensor driver를 구현하는 데 필요한 interface를 제공합니다. Sensor hub 자체는 HID device이며 HID 1.12 sensor usage table을 따르는 report descriptor를 제공합니다.

HID 1.12의 "HID Sensor Usages" 명세는 sensor usage를 표준화하면 hardware vendor가 USB 경계에서 일관된 Plug And Play interface를 제공할 수 있다고 설명합니다. 표준화가 의무는 아니지만, 운영체제는 vendor 사이에서 재사용할 수 있는 공통 device driver를 포함할 수 있으므로 vendor가 driver를 직접 제공해야 할 필요를 줄일 수 있습니다.

명세의 여러 usage ID는 sensor 종류뿐 아니라 개별 data field도 나타냅니다. Sensor마다 field 수가 달라질 수 있고 각 field의 길이와 순서는 report descriptor에 기록됩니다. 원문의 descriptor 일부는 다음과 같습니다.

     INPUT(1)[INPUT]
   ..
      Field(2)
        Physical(0020.0073)
        Usage(1)
          0020.045f
        Logical Minimum(-32767)
        Logical Maximum(32767)
        Report Size(8)
        Report Count(1)
        Report Offset(16)
        Flags(Variable Absolute)
  ..
  ..

이 report는 sensor page `0x20`에 3축 accelerometer `0x73`가 있음을 나타냅니다. 예시의 field 2는 motion intensity `0x045f`이며 logical minimum은 `-32767`, logical maximum은 `32767`입니다.

Input event의 raw data가 이 형식을 그대로 사용하므로 field 순서와 각 field 길이가 중요합니다. `Report Size(8)`, `Report Count(1)`, `Report Offset(16)`은 해당 값의 bit 배치를 결정합니다.

=====================
HID Sensors Framework
=====================
HID sensor framework provides necessary interfaces to implement sensor drivers,
which are connected to a sensor hub. The sensor hub is a HID device and it provides
a report descriptor conforming to HID 1.12 sensor usage tables.

Description from the HID 1.12 "HID Sensor Usages" specification:
"Standardization of HID usages for sensors would allow (but not require) sensor
hardware vendors to provide a consistent Plug And Play interface at the USB boundary,
thereby enabling some operating systems to incorporate common device drivers that
could be reused between vendors, alleviating any need for the vendors to provide
the drivers themselves."

This specification describes many usage IDs, which describe the type of sensor
and also the individual data fields. Each sensor can have variable number of
data fields. The length and order is specified in the report descriptor. For
example a part of report descriptor can look like::

     INPUT(1)[INPUT]
   ..
      Field(2)
        Physical(0020.0073)
        Usage(1)
          0020.045f
        Logical Minimum(-32767)
        Logical Maximum(32767)
        Report Size(8)
        Report Count(1)
        Report Offset(16)
        Flags(Variable Absolute)
  ..
  ..

The report is indicating "sensor page (0x20)" contains an accelerometer-3D (0x73).
This accelerometer-3D has some fields. Here for example field 2 is motion intensity
(0x045f) with a logical minimum value of -32767 and logical maximum of 32767. The
order of fields and length of each field is important as the input event raw
data will use this format.

Core driver와 개별 sensor processing

HID sensor 명세에는 서로 다른 data field 집합을 가진 많은 sensor 종류가 정의되어 있습니다. Accelerometer는 X, Y, Z data를 보내지만 ambient light sensor는 illumination data를 보내므로, 모든 sensor에 공통인 userspace input event 하나를 만들기 어렵습니다.

따라서 구현은 core HID driver와 개별 sensor processing 부분, 즉 sensor driver의 두 부분으로 나뉩니다.

Core driver인 `hid-sensor-hub`는 HID driver로 등록됩니다. Report descriptor를 parse하여 존재하는 모든 sensor를 식별하고, 명세의 usage ID를 `xxxx`로 사용한 `HID-SENSOR-xxxx` 이름의 MFD device를 추가합니다.

예를 들어 3축 accelerometer에는 `HID-SENSOR-200073`이 등록됩니다. 이 이름의 driver가 삽입되면 해당 기능의 probe routine이 호출됩니다. Accelerometer processing driver가 같은 이름으로 등록되어 있으면 3축 accelerometer가 감지될 때 probe됩니다.

Core driver는 processing driver가 특정 usage ID에 callback을 등록하고 event를 받을 수 있는 API를 제공합니다. 또한 input, feature, output report 각각을 가져오고 설정하는 parsing 함수도 제공합니다.

개별 processing driver는 core interface로 report를 parse하고 필요한 field index를 얻으며 event를 받습니다. Sensor 종류에 대해 정의된 표준 ABI를 사용하려면 IIO interface를 이용할 수 있습니다.

Implementation
==============

This specification defines many different types of sensors with different sets of
data fields. It is difficult to have a common input event to user space applications,
for different sensors. For example an accelerometer can send X,Y and Z data, whereas
an ambient light sensor can send illumination data.
So the implementation has two parts:

- Core HID driver
- Individual sensor processing part (sensor drivers)

Core driver
-----------
The core driver (hid-sensor-hub) registers as a HID driver. It parses
report descriptors and identifies all the sensors present. It adds an MFD device
with name HID-SENSOR-xxxx (where xxxx is usage id from the specification).

For example:

HID-SENSOR-200073 is registered for an Accelerometer 3D driver.

So if any driver with this name is inserted, then the probe routine for that
function will be called. So an accelerometer processing driver can register
with this name and will be probed if there is an accelerometer-3D detected.

The core driver provides a set of APIs which can be used by the processing
drivers to register and get events for that usage id. Also it provides parsing
functions, which get and set each input/feature/output report.

Individual sensor processing part (sensor drivers)
--------------------------------------------------

The processing driver will use an interface provided by the core driver to parse
the report and get the indexes of the fields and also can get events. This driver
can use IIO interface to use the standard ABI defined for a type of sensor.

Callback 구조와 등록 interface

각 processing driver는 callback 구조체에 `suspend`, `resume`, `capture_sample`, `send_event`를 설정할 수 있습니다.

`suspend`는 HID suspend를 받을 때, `resume`은 HID resume를 받을 때 호출됩니다. `capture_sample`은 sensor의 data field 하나에 대한 sample을 수집하며, `send_event`는 여러 data field를 포함할 수 있는 완전한 event 하나를 받았을 때 호출됩니다.

int (*suspend)(..)
int (*resume)(..)
int (*capture_sample)(..)
int (*send_event)(..)

`sensor_hub_register_callback()`은 `struct hid_sensor_hub_device *hsdev`, `u32 usage_id`, `struct hid_sensor_hub_callbacks *usage_callback`을 받아 usage ID에 callback을 등록합니다. 이 callback 함수들은 sleep하면 안 됩니다.

int sensor_hub_register_callback(
        struct hid_sensor_hub_device *hsdev,
        u32 usage_id,
        struct hid_sensor_hub_callbacks *usage_callback);

`sensor_hub_remove_callback()`은 `hsdev`와 `usage_id`를 받아 해당 usage ID의 callback을 제거합니다.

Core driver Interface
=====================

Callback structure::

  Each processing driver can use this structure to set some callbacks.
        int (*suspend)(..): Callback when HID suspend is received
        int (*resume)(..): Callback when HID resume is received
        int (*capture_sample)(..): Capture a sample for one of its data fields
        int (*send_event)(..): One complete event is received which can have
                               multiple data fields.

Registration functions::

  int sensor_hub_register_callback(struct hid_sensor_hub_device *hsdev,
                        u32 usage_id,
                        struct hid_sensor_hub_callbacks *usage_callback):

Registers callbacks for a usage id. The callback functions are not allowed
to sleep::


  int sensor_hub_remove_callback(struct hid_sensor_hub_device *hsdev,
                        u32 usage_id):

Removes callbacks for a usage id.

Field parsing, feature report와 raw input

`sensor_hub_input_get_attribute_info()`는 `hsdev`, report `type`, sensor `usage_id`, field `attr_usage_id`, 결과를 받을 `struct hid_sensor_hub_attribute_info *info`를 인자로 받습니다.

int sensor_hub_input_get_attribute_info(
        struct hid_sensor_hub_device *hsdev,
        u8 type,
        u32 usage_id,
        u32 attr_usage_id,
        struct hid_sensor_hub_attribute_info *info);

Processing driver는 관심 있는 field가 report descriptor에 존재하는지 찾을 수 있습니다. 존재하면 field를 개별적으로 get 또는 set하는 데 필요한 정보를 저장합니다. 이렇게 보관한 index를 사용하면 get/set 때마다 descriptor를 다시 검색해 field index를 찾지 않아도 됩니다.

`sensor_hub_set_feature()`는 `report_id`, `field_index`, `value`를 받아 feature report의 field 값을 설정합니다. 예를 들어 `sensor_hub_input_get_attribute_info()`로 미리 parse한 `report_interval` field를 직접 설정할 수 있습니다.

int sensor_hub_set_feature(
        struct hid_sensor_hub_device *hsdev,
        u32 report_id,
        u32 field_index,
        s32 value);

`sensor_hub_get_feature()`는 `report_id`, `field_index`, `s32 *value`를 받아 field 값을 가져옵니다. 원문은 이를 input report의 field 값을 읽는 interface라고 설명하며, 같은 `report_interval` 예에서 미리 얻은 index로 개별 값을 직접 가져옵니다.

int sensor_hub_get_feature(
        struct hid_sensor_hub_device *hsdev,
        u32 report_id,
        u32 field_index,
        s32 *value);

`sensor_hub_input_attr_get_raw_value()`는 sensor `usage_id`, field `attr_usage_id`, `report_id`를 사용해 input report에서 특정 field의 raw 값을 가져옵니다. Accelerometer가 X axis 값을 poll하려면 X axis의 usage ID로 이 함수를 호출할 수 있습니다.

하지만 HID sensor는 event를 제공할 수 있으므로 모든 field를 poll할 필요는 없습니다. 새 sample이 생기면 core driver가 등록된 callback을 호출하여 sample을 처리하게 합니다.

Parsing function::

  int sensor_hub_input_get_attribute_info(struct hid_sensor_hub_device *hsdev,
                        u8 type,
                        u32 usage_id, u32 attr_usage_id,
                        struct hid_sensor_hub_attribute_info *info);

A processing driver can look for some field of interest and check if it exists
in a report descriptor. If it exists it will store necessary information
so that fields can be set or get individually.
These indexes avoid searching every time and getting field index to get or set.


Set Feature report::

  int sensor_hub_set_feature(struct hid_sensor_hub_device *hsdev, u32 report_id,
                        u32 field_index, s32 value);

This interface is used to set a value for a field in feature report. For example
if there is a field report_interval, which is parsed by a call to
sensor_hub_input_get_attribute_info before, then it can directly set that
individual field::


  int sensor_hub_get_feature(struct hid_sensor_hub_device *hsdev, u32 report_id,
                        u32 field_index, s32 *value);

This interface is used to get a value for a field in input report. For example
if there is a field report_interval, which is parsed by a call to
sensor_hub_input_get_attribute_info before, then it can directly get that
individual field value::


  int sensor_hub_input_attr_get_raw_value(struct hid_sensor_hub_device *hsdev,
                        u32 usage_id,
                        u32 attr_usage_id, u32 report_id);

This is used to get a particular field value through input reports. For example
accelerometer wants to poll X axis value, then it can call this function with
the usage id of X axis. HID sensors can provide events, so this is not necessary
to poll for any field. If there is some new sample, the core driver will call
registered callback function to process the sample.

Custom·generic sensor의 목적과 공개 방식

HID Sensor 명세는 두 가지 특별한 sensor usage type을 정의합니다. 이들은 표준 sensor를 나타내지 않으므로 Linux IIO type interface로 정의할 수 없습니다.

이 sensor들은 기능을 확장하거나 sensor가 전달하는 data를 난독화하는 데 사용됩니다. Data와 encapsulated form의 mapping을 모르면 application이나 driver가 어떤 data가 전달되는지 판단하기 어렵습니다.

이 특성은 vendor가 전용 application을 제공하는 차별화된 use case를 가능하게 합니다. 흔한 예는 다른 sensor를 debug하거나 keyboard attach/detach, lid open/close 같은 event를 제공하는 것입니다.

Application이 이러한 sensor를 사용할 수 있도록 kernel은 sysfs attribute group과 attribute, misc device interface로 공개합니다.

----------

HID Custom and generic Sensors
------------------------------


HID Sensor specification defines two special sensor usage types. Since they
don't represent a standard sensor, it is not possible to define using Linux IIO
type interfaces.
The purpose of these sensors is to extend the functionality or provide a
way to obfuscate the data being communicated by a sensor. Without knowing the
mapping between the data and its encapsulated form, it is difficult for
an application/driver to determine what data is being communicated by the sensor.
This allows some differentiating use cases, where vendor can provide applications.
Some common use cases are debug other sensors or to provide some events like
keyboard attached/detached or lid open/close.

To allow application to utilize these sensors, here they are exported using sysfs
attribute groups, attributes and misc device interface.

Sysfs field 표현과 접근 속성

다음 sysfs 예시는 `HID-SENSOR-2000e1.6.auto` custom sensor의 field 구조를 보여 줍니다. Sensor에는 feature field 두 개와 input field 두 개가 있습니다.

/sys/devices/pci0000:00/INT33C2:00/i2c-0/i2c-INT33D1:00/0018:8086:09FA.0001/HID-SENSOR-2000e1.6.auto
├── enable_sensor
├── feature-0-200316
│   ├── feature-0-200316-maximum
│   ├── feature-0-200316-minimum
│   ├── feature-0-200316-name
│   ├── feature-0-200316-size
│   ├── feature-0-200316-unit-expo
│   ├── feature-0-200316-units
│   └── feature-0-200316-value
├── feature-1-200201
├── input-0-200201
└── input-1-200202

각 field는 `maximum`, `minimum`, `name`, `size`, `unit-expo`, `units`, `value` 속성 집합으로 표현됩니다. `value`를 제외한 모든 field 속성은 read-only이고 `value` field는 read-write입니다.

예제 `feature-0-200316`은 `property-reporting-state`라는 이름을 가지며 minimum `0`, maximum `6`, size `1`, unit exponent `0`, units `25`, 현재 value `1`을 보고합니다.

/sys/bus/platform/devices/HID-SENSOR-2000e1.6.auto/feature-0-200316$ grep -r . *
feature-0-200316-maximum:6
feature-0-200316-minimum:0
feature-0-200316-name:property-reporting-state
feature-0-200316-size:1
feature-0-200316-unit-expo:0
feature-0-200316-units:25
feature-0-200316-value:1

An example of this representation on sysfs::

  /sys/devices/pci0000:00/INT33C2:00/i2c-0/i2c-INT33D1:00/0018:8086:09FA.0001/HID-SENSOR-2000e1.6.auto$ tree -R
  .
  │   ├──  enable_sensor
  │   │   ├── feature-0-200316
  │   │   │   ├── feature-0-200316-maximum
  │   │   │   ├── feature-0-200316-minimum
  │   │   │   ├── feature-0-200316-name
  │   │   │   ├── feature-0-200316-size
  │   │   │   ├── feature-0-200316-unit-expo
  │   │   │   ├── feature-0-200316-units
  │   │   │   ├── feature-0-200316-value
  │   │   ├── feature-1-200201
  │   │   │   ├── feature-1-200201-maximum
  │   │   │   ├── feature-1-200201-minimum
  │   │   │   ├── feature-1-200201-name
  │   │   │   ├── feature-1-200201-size
  │   │   │   ├── feature-1-200201-unit-expo
  │   │   │   ├── feature-1-200201-units
  │   │   │   ├── feature-1-200201-value
  │   │   ├── input-0-200201
  │   │   │   ├── input-0-200201-maximum
  │   │   │   ├── input-0-200201-minimum
  │   │   │   ├── input-0-200201-name
  │   │   │   ├── input-0-200201-size
  │   │   │   ├── input-0-200201-unit-expo
  │   │   │   ├── input-0-200201-units
  │   │   │   ├── input-0-200201-value
  │   │   ├── input-1-200202
  │   │   │   ├── input-1-200202-maximum
  │   │   │   ├── input-1-200202-minimum
  │   │   │   ├── input-1-200202-name
  │   │   │   ├── input-1-200202-size
  │   │   │   ├── input-1-200202-unit-expo
  │   │   │   ├── input-1-200202-units
  │   │   │   ├── input-1-200202-value

Here there is a custom sensor with four fields: two feature and two inputs.
Each field is represented by a set of attributes. All fields except the "value"
are read only. The value field is a read-write field.

Example::

  /sys/bus/platform/devices/HID-SENSOR-2000e1.6.auto/feature-0-200316$ grep -r . *
  feature-0-200316-maximum:6
  feature-0-200316-minimum:0
  feature-0-200316-name:property-reporting-state
  feature-0-200316-size:1
  feature-0-200316-unit-expo:0
  feature-0-200316-units:25
  feature-0-200316-value:1

Sensor 활성화와 misc FIFO report

Custom sensor는 기본적으로 power-gated 상태일 수 있습니다. 활성화하려면 sysfs의 `enable_sensor` attribute에 `1`을 씁니다.

$ echo 1 > enable_sensor

Sensor가 활성화되고 전원이 켜지면 HID report로 값을 보고할 수 있습니다. 이 report들은 misc device interface를 통해 FIFO 순서로 전달됩니다.

/dev$ tree | grep HID-SENSOR-2000e1.6.auto
│   │   │   ├── 10:53 -> ../HID-SENSOR-2000e1.6.auto
│   ├── HID-SENSOR-2000e1.6.auto

각 report의 길이는 가변이며 앞에 header가 붙습니다. Header는 32-bit usage ID, 64-bit timestamp, 32-bit raw data length field로 구성됩니다.

How to enable such sensor?
^^^^^^^^^^^^^^^^^^^^^^^^^^

By default sensor can be power gated. To enable sysfs attribute "enable" can be
used::

        $ echo 1 > enable_sensor

Once enabled and powered on, sensor can report value using HID reports.
These reports are pushed using misc device interface in a FIFO order::

        /dev$ tree | grep HID-SENSOR-2000e1.6.auto
        │   │   │   ├── 10:53 -> ../HID-SENSOR-2000e1.6.auto
        │   ├──  HID-SENSOR-2000e1.6.auto

Each report can be of variable length preceded by a header. This header
consists of a 32-bit usage id, 64-bit time stamp and 32-bit length field of raw
data.