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