Commit | Line | Data |
---|---|---|
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. | |
b2eafd72 SP |
141 | |
142 | ||
143 | ---------- | |
144 | ||
145 | HID Custom and generic Sensors | |
146 | ||
147 | HID Sensor specification defines two special sensor usage types. Since they | |
148 | don't represent a standard sensor, it is not possible to define using Linux IIO | |
149 | type interfaces. | |
150 | The purpose of these sensors is to extend the functionality or provide a | |
151 | way to obfuscate the data being communicated by a sensor. Without knowing the | |
152 | mapping between the data and its encapsulated form, it is difficult for | |
153 | an application/driver to determine what data is being communicated by the sensor. | |
154 | This allows some differentiating use cases, where vendor can provide applications. | |
155 | Some common use cases are debug other sensors or to provide some events like | |
156 | keyboard attached/detached or lid open/close. | |
157 | ||
158 | To allow application to utilize these sensors, here they are exported uses sysfs | |
159 | attribute groups, attributes and misc device interface. | |
160 | ||
161 | An example of this representation on sysfs: | |
162 | /sys/devices/pci0000:00/INT33C2:00/i2c-0/i2c-INT33D1:00/0018:8086:09FA.0001/HID-SENSOR-2000e1.6.auto$ tree -R | |
163 | . | |
164 | ????????? enable_sensor | |
165 | ????????? feature-0-200316 | |
166 | ??????? ????????? feature-0-200316-maximum | |
167 | ??????? ????????? feature-0-200316-minimum | |
168 | ??????? ????????? feature-0-200316-name | |
169 | ??????? ????????? feature-0-200316-size | |
170 | ??????? ????????? feature-0-200316-unit-expo | |
171 | ??????? ????????? feature-0-200316-units | |
172 | ??????? ????????? feature-0-200316-value | |
173 | ????????? feature-1-200201 | |
174 | ??????? ????????? feature-1-200201-maximum | |
175 | ??????? ????????? feature-1-200201-minimum | |
176 | ??????? ????????? feature-1-200201-name | |
177 | ??????? ????????? feature-1-200201-size | |
178 | ??????? ????????? feature-1-200201-unit-expo | |
179 | ??????? ????????? feature-1-200201-units | |
180 | ??????? ????????? feature-1-200201-value | |
181 | ????????? input-0-200201 | |
182 | ??????? ????????? input-0-200201-maximum | |
183 | ??????? ????????? input-0-200201-minimum | |
184 | ??????? ????????? input-0-200201-name | |
185 | ??????? ????????? input-0-200201-size | |
186 | ??????? ????????? input-0-200201-unit-expo | |
187 | ??????? ????????? input-0-200201-units | |
188 | ??????? ????????? input-0-200201-value | |
189 | ????????? input-1-200202 | |
190 | ??????? ????????? input-1-200202-maximum | |
191 | ??????? ????????? input-1-200202-minimum | |
192 | ??????? ????????? input-1-200202-name | |
193 | ??????? ????????? input-1-200202-size | |
194 | ??????? ????????? input-1-200202-unit-expo | |
195 | ??????? ????????? input-1-200202-units | |
196 | ??????? ????????? input-1-200202-value | |
197 | ||
198 | Here there is a custom sensors with four fields, two feature and two inputs. | |
199 | Each field is represented by a set of attributes. All fields except the "value" | |
200 | are read only. The value field is a RW field. | |
201 | Example | |
202 | /sys/bus/platform/devices/HID-SENSOR-2000e1.6.auto/feature-0-200316$ grep -r . * | |
203 | feature-0-200316-maximum:6 | |
204 | feature-0-200316-minimum:0 | |
205 | feature-0-200316-name:property-reporting-state | |
206 | feature-0-200316-size:1 | |
207 | feature-0-200316-unit-expo:0 | |
208 | feature-0-200316-units:25 | |
209 | feature-0-200316-value:1 | |
210 | ||
211 | How to enable such sensor? | |
212 | By default sensor can be power gated. To enable sysfs attribute "enable" can be | |
213 | used. | |
214 | $ echo 1 > enable_sensor | |
215 | ||
216 | Once enabled and powered on, sensor can report value using HID reports. | |
217 | These reports are pushed using misc device interface in a FIFO order. | |
218 | /dev$ tree | grep HID-SENSOR-2000e1.6.auto | |
219 | ??????? ????????? 10:53 -> ../HID-SENSOR-2000e1.6.auto | |
220 | ????????? HID-SENSOR-2000e1.6.auto | |
221 | ||
222 | Each reports can be of variable length preceded by a header. This header | |
223 | consist of a 32 bit usage id, 64 bit time stamp and 32 bit length field of raw | |
224 | data. |