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 providesa 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) sensorhardware vendors to provide a consistent Plug And Play interface at the USB boundary,thereby enabling some operating systems to incorporate common device drivers thatcould be reused between vendors, alleviating any need for the vendors to providethe drivers themselves.”

This specification describes many usage IDs, which describe the type of sensorand also the individual data fields. Each sensor can have variable number ofdata fields. The length and order is specified in the report descriptor. Forexample 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. Theorder of fields and length of each field is important as the input event rawdata will use this format.

Implementation

This specification defines many different types of sensors with different sets ofdata 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, whereasan 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 parsesreport descriptors and identifies all the sensors present. It adds an MFD devicewith 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 thatfunction will be called. So an accelerometer processing driver can registerwith 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 processingdrivers to register and get events for that usage id. Also it provides parsingfunctions, 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 parsethe report and get the indexes of the fields and also can get events. This drivercan use IIO interface to use the standard ABI defined for a type of sensor.

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 allowedto sleep:

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

Removes callbacks for a usage id.

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 existsin a report descriptor. If it exists it will store necessary informationso 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 exampleif there is a field report_interval, which is parsed by a call tosensor_hub_input_get_attribute_info before, then it can directly set thatindividual 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 exampleif there is a field report_interval, which is parsed by a call tosensor_hub_input_get_attribute_info before, then it can directly get thatindividual 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 exampleaccelerometer wants to poll X axis value, then it can call this function withthe usage id of X axis. HID sensors can provide events, so this is not necessaryto poll for any field. If there is some new sample, the core driver will callregistered callback function to process the sample.

HID Custom and generic Sensors

HID Sensor specification defines two special sensor usage types. Since theydon’t represent a standard sensor, it is not possible to define using Linux IIOtype interfaces.The purpose of these sensors is to extend the functionality or provide away to obfuscate the data being communicated by a sensor. Without knowing themapping between the data and its encapsulated form, it is difficult foran 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 likekeyboard attached/detached or lid open/close.

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

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:6feature-0-200316-minimum:0feature-0-200316-name:property-reporting-statefeature-0-200316-size:1feature-0-200316-unit-expo:0feature-0-200316-units:25feature-0-200316-value:1

How to enable such sensor?

By default sensor can be power gated. To enable sysfs attribute “enable” can beused:

$ 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 headerconsists of a 32-bit usage id, 64-bit time stamp and 32-bit length field of rawdata.