1 2HID Sensors Framework 3====================== 4HID sensor framework provides necessary interfaces to implement sensor drivers, 5which are connected to a sensor hub. The sensor hub is a HID device and it provides 6a report descriptor conforming to HID 1.12 sensor usage tables. 7 8Description from the HID 1.12 "HID Sensor Usages" specification: 9"Standardization of HID usages for sensors would allow (but not require) sensor 10hardware vendors to provide a consistent Plug And Play interface at the USB boundary, 11thereby enabling some operating systems to incorporate common device drivers that 12could be reused between vendors, alleviating any need for the vendors to provide 13the drivers themselves." 14 15This specification describes many usage IDs, which describe the type of sensor 16and also the individual data fields. Each sensor can have variable number of 17data fields. The length and order is specified in the report descriptor. For 18example a part of report descriptor can look like: 19 20 INPUT(1)[INPUT] 21 .. 22 Field(2) 23 Physical(0020.0073) 24 Usage(1) 25 0020.045f 26 Logical Minimum(-32767) 27 Logical Maximum(32767) 28 Report Size(8) 29 Report Count(1) 30 Report Offset(16) 31 Flags(Variable Absolute) 32.. 33.. 34 35The report is indicating "sensor page (0x20)" contains an accelerometer-3D (0x73). 36This accelerometer-3D has some fields. Here for example field 2 is motion intensity 37(0x045f) with a logical minimum value of -32767 and logical maximum of 32767. The 38order of fields and length of each field is important as the input event raw 39data will use this format. 40 41 42Implementation 43================= 44 45This specification defines many different types of sensors with different sets of 46data fields. It is difficult to have a common input event to user space applications, 47for different sensors. For example an accelerometer can send X,Y and Z data, whereas 48an ambient light sensor can send illumination data. 49So the implementation has two parts: 50- Core hid driver 51- Individual sensor processing part (sensor drivers) 52 53Core driver 54----------- 55The core driver registers (hid-sensor-hub) registers as a HID driver. It parses 56report descriptors and identifies all the sensors present. It adds an MFD device 57with name HID-SENSOR-xxxx (where xxxx is usage id from the specification). 58For example 59HID-SENSOR-200073 is registered for an Accelerometer 3D driver. 60So if any driver with this name is inserted, then the probe routine for that 61function will be called. So an accelerometer processing driver can register 62with this name and will be probed if there is an accelerometer-3D detected. 63 64The core driver provides a set of APIs which can be used by the processing 65drivers to register and get events for that usage id. Also it provides parsing 66functions, which get and set each input/feature/output report. 67 68Individual sensor processing part (sensor drivers) 69----------- 70The processing driver will use an interface provided by the core driver to parse 71the report and get the indexes of the fields and also can get events. This driver 72can use IIO interface to use the standard ABI defined for a type of sensor. 73 74 75Core driver Interface 76===================== 77 78Callback structure: 79Each processing driver can use this structure to set some callbacks. 80 int (*suspend)(..): Callback when HID suspend is received 81 int (*resume)(..): Callback when HID resume is received 82 int (*capture_sample)(..): Capture a sample for one of its data fields 83 int (*send_event)(..): One complete event is received which can have 84 multiple data fields. 85 86Registration functions: 87int sensor_hub_register_callback(struct hid_sensor_hub_device *hsdev, 88 u32 usage_id, 89 struct hid_sensor_hub_callbacks *usage_callback): 90 91Registers callbacks for an usage id. The callback functions are not allowed 92to sleep. 93 94 95int sensor_hub_remove_callback(struct hid_sensor_hub_device *hsdev, 96 u32 usage_id): 97 98Removes callbacks for an usage id. 99 100 101Parsing function: 102int sensor_hub_input_get_attribute_info(struct hid_sensor_hub_device *hsdev, 103 u8 type, 104 u32 usage_id, u32 attr_usage_id, 105 struct hid_sensor_hub_attribute_info *info); 106 107A processing driver can look for some field of interest and check if it exists 108in a report descriptor. If it exists it will store necessary information 109so that fields can be set or get individually. 110These indexes avoid searching every time and getting field index to get or set. 111 112 113Set Feature report 114int sensor_hub_set_feature(struct hid_sensor_hub_device *hsdev, u32 report_id, 115 u32 field_index, s32 value); 116 117This interface is used to set a value for a field in feature report. For example 118if there is a field report_interval, which is parsed by a call to 119sensor_hub_input_get_attribute_info before, then it can directly set that individual 120field. 121 122 123int sensor_hub_get_feature(struct hid_sensor_hub_device *hsdev, u32 report_id, 124 u32 field_index, s32 *value); 125 126This interface is used to get a value for a field in input report. For example 127if there is a field report_interval, which is parsed by a call to 128sensor_hub_input_get_attribute_info before, then it can directly get that individual 129field value. 130 131 132int sensor_hub_input_attr_get_raw_value(struct hid_sensor_hub_device *hsdev, 133 u32 usage_id, 134 u32 attr_usage_id, u32 report_id); 135 136This is used to get a particular field value through input reports. For example 137accelerometer wants to poll X axis value, then it can call this function with 138the usage id of X axis. HID sensors can provide events, so this is not necessary 139to poll for any field. If there is some new sample, the core driver will call 140registered callback function to process the sample. 141