Commit | Line | Data |
---|---|---|
17e2adf2 SP |
1 | Intel Integrated Sensor Hub (ISH) |
2 | =============================== | |
3 | ||
4 | A sensor hub enables the ability to offload sensor polling and algorithm | |
5 | processing to a dedicated low power co-processor. This allows the core | |
6 | processor to go into low power modes more often, resulting in the increased | |
7 | battery life. | |
8 | ||
9 | There are many vendors providing external sensor hubs confirming to HID | |
10 | Sensor usage tables, and used in several tablets, 2 in 1 convertible laptops | |
11 | and embedded products. Linux had this support since Linux 3.9. | |
12 | ||
13 | Intel® introduced integrated sensor hubs as a part of the SoC starting from | |
14 | Cherry Trail and now supported on multiple generations of CPU packages. There | |
15 | are many commercial devices already shipped with Integrated Sensor Hubs (ISH). | |
16 | These ISH also comply to HID sensor specification, but the difference is the | |
17 | transport protocol used for communication. The current external sensor hubs | |
18 | mainly use HID over i2C or USB. But ISH doesn't use either i2c or USB. | |
19 | ||
20 | 1. Overview | |
21 | ||
22 | Using a analogy with a usbhid implementation, the ISH follows a similar model | |
23 | for a very high speed communication: | |
24 | ||
25 | ----------------- ---------------------- | |
26 | | USB HID | --> | ISH HID | | |
27 | ----------------- ---------------------- | |
28 | ----------------- ---------------------- | |
29 | | USB protocol | --> | ISH Transport | | |
30 | ----------------- ---------------------- | |
31 | ----------------- ---------------------- | |
32 | | EHCI/XHCI | --> | ISH IPC | | |
33 | ----------------- ---------------------- | |
34 | PCI PCI | |
35 | ----------------- ---------------------- | |
36 | |Host controller| --> | ISH processor | | |
37 | ----------------- ---------------------- | |
38 | USB Link | |
39 | ----------------- ---------------------- | |
40 | | USB End points| --> | ISH Clients | | |
41 | ----------------- ---------------------- | |
42 | ||
43 | Like USB protocol provides a method for device enumeration, link management | |
44 | and user data encapsulation, the ISH also provides similar services. But it is | |
45 | very light weight tailored to manage and communicate with ISH client | |
46 | applications implemented in the firmware. | |
47 | ||
48 | The ISH allows multiple sensor management applications executing in the | |
49 | firmware. Like USB endpoints the messaging can be to/from a client. As part of | |
50 | enumeration process, these clients are identified. These clients can be simple | |
51 | HID sensor applications, sensor calibration application or senor firmware | |
52 | update application. | |
53 | ||
54 | The implementation model is similar, like USB bus, ISH transport is also | |
55 | implemented as a bus. Each client application executing in the ISH processor | |
56 | is registered as a device on this bus. The driver, which binds each device | |
57 | (ISH HID driver) identifies the device type and registers with the hid core. | |
58 | ||
59 | 2. ISH Implementation: Block Diagram | |
60 | ||
61 | --------------------------- | |
62 | | User Space Applications | | |
63 | --------------------------- | |
64 | ||
65 | ----------------IIO ABI---------------- | |
66 | -------------------------- | |
67 | | IIO Sensor Drivers | | |
68 | -------------------------- | |
69 | -------------------------- | |
70 | | IIO core | | |
71 | -------------------------- | |
72 | -------------------------- | |
73 | | HID Sensor Hub MFD | | |
74 | -------------------------- | |
75 | -------------------------- | |
76 | | HID Core | | |
77 | -------------------------- | |
78 | -------------------------- | |
79 | | HID over ISH Client | | |
80 | -------------------------- | |
81 | -------------------------- | |
82 | | ISH Transport (ISHTP) | | |
83 | -------------------------- | |
84 | -------------------------- | |
85 | | IPC Drivers | | |
86 | -------------------------- | |
87 | OS | |
88 | ---------------- PCI ----------------- | |
89 | Hardware + Firmware | |
90 | ---------------------------- | |
91 | | ISH Hardware/Firmware(FW) | | |
92 | ---------------------------- | |
93 | ||
94 | 3. High level processing in above blocks | |
95 | ||
96 | 3.1 Hardware Interface | |
97 | ||
98 | The ISH is exposed as "Non-VGA unclassified PCI device" to the host. The PCI | |
99 | product and vendor IDs are changed from different generations of processors. So | |
100 | the source code which enumerate drivers needs to update from generation to | |
101 | generation. | |
102 | ||
103 | 3.2 Inter Processor Communication (IPC) driver | |
104 | Location: drivers/hid/intel-ish-hid/ipc | |
105 | ||
106 | The IPC message used memory mapped I/O. The registers are defined in | |
107 | hw-ish-regs.h. | |
108 | ||
109 | 3.2.1 IPC/FW message types | |
110 | ||
111 | There are two types of messages, one for management of link and other messages | |
112 | are to and from transport layers. | |
113 | ||
114 | TX and RX of Transport messages | |
115 | ||
116 | A set of memory mapped register offers support of multi byte messages TX and | |
117 | RX (E.g.IPC_REG_ISH2HOST_MSG, IPC_REG_HOST2ISH_MSG). The IPC layer maintains | |
118 | internal queues to sequence messages and send them in order to the FW. | |
119 | Optionally the caller can register handler to get notification of completion. | |
120 | A door bell mechanism is used in messaging to trigger processing in host and | |
121 | client firmware side. When ISH interrupt handler is called, the ISH2HOST | |
122 | doorbell register is used by host drivers to determine that the interrupt | |
123 | is for ISH. | |
124 | ||
125 | Each side has 32 32-bit message registers and a 32-bit doorbell. Doorbell | |
126 | register has the following format: | |
127 | Bits 0..6: fragment length (7 bits are used) | |
128 | Bits 10..13: encapsulated protocol | |
129 | Bits 16..19: management command (for IPC management protocol) | |
130 | Bit 31: doorbell trigger (signal H/W interrupt to the other side) | |
131 | Other bits are reserved, should be 0. | |
132 | ||
133 | 3.2.2 Transport layer interface | |
134 | ||
135 | To abstract HW level IPC communication, a set of callbacks are registered. | |
136 | The transport layer uses them to send and receive messages. | |
137 | Refer to struct ishtp_hw_ops for callbacks. | |
138 | ||
139 | 3.3 ISH Transport layer | |
140 | Location: drivers/hid/intel-ish-hid/ishtp/ | |
141 | ||
142 | 3.3.1 A Generic Transport Layer | |
143 | ||
144 | The transport layer is a bi-directional protocol, which defines: | |
145 | - Set of commands to start, stop, connect, disconnect and flow control | |
146 | (ishtp/hbm.h) for details | |
147 | - A flow control mechanism to avoid buffer overflows | |
148 | ||
149 | This protocol resembles bus messages described in the following document: | |
150 | http://www.intel.com/content/dam/www/public/us/en/documents/technical-\ | |
151 | specifications/dcmi-hi-1-0-spec.pdf "Chapter 7: Bus Message Layer" | |
152 | ||
153 | 3.3.2 Connection and Flow Control Mechanism | |
154 | ||
155 | Each FW client and a protocol is identified by an UUID. In order to communicate | |
156 | to a FW client, a connection must be established using connect request and | |
157 | response bus messages. If successful, a pair (host_client_id and fw_client_id) | |
158 | will identify the connection. | |
159 | ||
160 | Once connection is established, peers send each other flow control bus messages | |
161 | independently. Every peer may send a message only if it has received a | |
162 | flow-control credit before. Once it sent a message, it may not send another one | |
163 | before receiving the next flow control credit. | |
164 | Either side can send disconnect request bus message to end communication. Also | |
165 | the link will be dropped if major FW reset occurs. | |
166 | ||
167 | 3.3.3 Peer to Peer data transfer | |
168 | ||
169 | Peer to Peer data transfer can happen with or without using DMA. Depending on | |
170 | the sensor bandwidth requirement DMA can be enabled by using module parameter | |
171 | ishtp_use_dma under intel_ishtp. | |
172 | ||
173 | Each side (host and FW) manages its DMA transfer memory independently. When an | |
174 | ISHTP client from either host or FW side wants to send something, it decides | |
175 | whether to send over IPC or over DMA; for each transfer the decision is | |
176 | independent. The sending side sends DMA_XFER message when the message is in | |
177 | the respective host buffer (TX when host client sends, RX when FW client | |
178 | sends). The recipient of DMA message responds with DMA_XFER_ACK, indicating | |
179 | the sender that the memory region for that message may be reused. | |
180 | ||
181 | DMA initialization is started with host sending DMA_ALLOC_NOTIFY bus message | |
182 | (that includes RX buffer) and FW responds with DMA_ALLOC_NOTIFY_ACK. | |
183 | Additionally to DMA address communication, this sequence checks capabilities: | |
184 | if thw host doesn't support DMA, then it won't send DMA allocation, so FW can't | |
185 | send DMA; if FW doesn't support DMA then it won't respond with | |
186 | DMA_ALLOC_NOTIFY_ACK, in which case host will not use DMA transfers. | |
187 | Here ISH acts as busmaster DMA controller. Hence when host sends DMA_XFER, | |
188 | it's request to do host->ISH DMA transfer; when FW sends DMA_XFER, it means | |
189 | that it already did DMA and the message resides at host. Thus, DMA_XFER | |
190 | and DMA_XFER_ACK act as ownership indicators. | |
191 | ||
192 | At initial state all outgoing memory belongs to the sender (TX to host, RX to | |
193 | FW), DMA_XFER transfers ownership on the region that contains ISHTP message to | |
194 | the receiving side, DMA_XFER_ACK returns ownership to the sender. A sender | |
195 | needs not wait for previous DMA_XFER to be ack'ed, and may send another message | |
196 | as long as remaining continuous memory in its ownership is enough. | |
197 | In principle, multiple DMA_XFER and DMA_XFER_ACK messages may be sent at once | |
198 | (up to IPC MTU), thus allowing for interrupt throttling. | |
199 | Currently, ISH FW decides to send over DMA if ISHTP message is more than 3 IPC | |
200 | fragments and via IPC otherwise. | |
201 | ||
202 | 3.3.4 Ring Buffers | |
203 | ||
204 | When a client initiate a connection, a ring or RX and TX buffers are allocated. | |
205 | The size of ring can be specified by the client. HID client set 16 and 32 for | |
206 | TX and RX buffers respectively. On send request from client, the data to be | |
207 | sent is copied to one of the send ring buffer and scheduled to be sent using | |
208 | bus message protocol. These buffers are required because the FW may have not | |
209 | have processed the last message and may not have enough flow control credits | |
210 | to send. Same thing holds true on receive side and flow control is required. | |
211 | ||
212 | 3.3.5 Host Enumeration | |
213 | ||
214 | The host enumeration bus command allow discovery of clients present in the FW. | |
215 | There can be multiple sensor clients and clients for calibration function. | |
216 | ||
217 | To ease in implantation and allow independent driver handle each client | |
218 | this transport layer takes advantage of Linux Bus driver model. Each | |
219 | client is registered as device on the the transport bus (ishtp bus). | |
220 | ||
221 | Enumeration sequence of messages: | |
222 | - Host sends HOST_START_REQ_CMD, indicating that host ISHTP layer is up. | |
223 | - FW responds with HOST_START_RES_CMD | |
224 | - Host sends HOST_ENUM_REQ_CMD (enumerate FW clients) | |
225 | - FW responds with HOST_ENUM_RES_CMD that includes bitmap of available FW | |
226 | client IDs | |
227 | - For each FW ID found in that bitmap host sends | |
228 | HOST_CLIENT_PROPERTIES_REQ_CMD | |
229 | - FW responds with HOST_CLIENT_PROPERTIES_RES_CMD. Properties include UUID, | |
230 | max ISHTP message size, etc. | |
231 | - Once host received properties for that last discovered client, it considers | |
232 | ISHTP device fully functional (and allocates DMA buffers) | |
233 | ||
234 | 3.4 HID over ISH Client | |
235 | Location: drivers/hid/intel-ish-hid | |
236 | ||
237 | The ISHTP client driver is responsible for: | |
238 | - enumerate HID devices under FW ISH client | |
239 | - Get Report descriptor | |
240 | - Register with HID core as a LL driver | |
241 | - Process Get/Set feature request | |
242 | - Get input reports | |
243 | ||
244 | 3.5 HID Sensor Hub MFD and IIO sensor drivers | |
245 | ||
246 | The functionality in these drivers is the same as an external sensor hub. | |
247 | Refer to | |
248 | Documentation/hid/hid-sensor.txt for HID sensor | |
249 | Documentation/ABI/testing/sysfs-bus-iio for IIO ABIs to user space | |
250 | ||
251 | 3.6 End to End HID transport Sequence Diagram | |
252 | ||
253 | HID-ISH-CLN ISHTP IPC HW | |
254 | | | | | | |
255 | | | |-----WAKE UP------------------>| | |
256 | | | | | | |
257 | | | |-----HOST READY--------------->| | |
258 | | | | | | |
259 | | | |<----MNG_RESET_NOTIFY_ACK----- | | |
260 | | | | | | |
261 | | |<----ISHTP_START------ | | | |
262 | | | | | | |
263 | | |<-----------------HOST_START_RES_CMD-------------------| | |
264 | | | | | | |
265 | | |------------------QUERY_SUBSCRIBER-------------------->| | |
266 | | | | | | |
267 | | |------------------HOST_ENUM_REQ_CMD------------------->| | |
268 | | | | | | |
269 | | |<-----------------HOST_ENUM_RES_CMD--------------------| | |
270 | | | | | | |
271 | | |------------------HOST_CLIENT_PROPERTIES_REQ_CMD------>| | |
272 | | | | | | |
273 | | |<-----------------HOST_CLIENT_PROPERTIES_RES_CMD-------| | |
274 | | Create new device on in ishtp bus | | | |
275 | | | | | | |
276 | | |------------------HOST_CLIENT_PROPERTIES_REQ_CMD------>| | |
277 | | | | | | |
278 | | |<-----------------HOST_CLIENT_PROPERTIES_RES_CMD-------| | |
279 | | Create new device on in ishtp bus | | | |
280 | | | | | | |
281 | | |--Repeat HOST_CLIENT_PROPERTIES_REQ_CMD-till last one--| | |
282 | | | | | | |
283 | probed() | |
284 | |----ishtp_cl_connect-->|----------------- CLIENT_CONNECT_REQ_CMD-------------->| | |
285 | | | | | | |
286 | | |<----------------CLIENT_CONNECT_RES_CMD----------------| | |
287 | | | | | | |
288 | |register event callback| | | | |
289 | | | | | | |
290 | |ishtp_cl_send( | |
291 | HOSTIF_DM_ENUM_DEVICES) |----------fill ishtp_msg_hdr struct write to HW----- >| | |
292 | | | | | | |
293 | | | |<-----IRQ(IPC_PROTOCOL_ISHTP---| | |
294 | | | | | | |
295 | |<--ENUM_DEVICE RSP-----| | | | |
296 | | | | | | |
297 | for each enumerated device | |
298 | |ishtp_cl_send( | |
299 | HOSTIF_GET_HID_DESCRIPTOR |----------fill ishtp_msg_hdr struct write to HW--- >| | |
300 | | | | | | |
301 | ...Response | |
302 | | | | | | |
303 | for each enumerated device | |
304 | |ishtp_cl_send( | |
305 | HOSTIF_GET_REPORT_DESCRIPTOR |----------fill ishtp_msg_hdr struct write to HW- >| | |
306 | | | | | | |
307 | | | | | | |
308 | hid_allocate_device | |
309 | | | | | | |
310 | hid_add_device | | | | |
311 | | | | | | |
312 | ||
313 | ||
314 | 3.7 ISH Debugging | |
315 | ||
316 | To debug ISH, event tracing mechanism is used. To enable debug logs | |
317 | echo 1 > /sys/kernel/debug/tracing/events/intel_ish/enable | |
318 | cat sys/kernel/debug/tracing/trace | |
319 | ||
320 | 3.8 ISH IIO sysfs Example on Lenovo thinkpad Yoga 260 | |
321 | ||
322 | root@otcpl-ThinkPad-Yoga-260:~# tree -l /sys/bus/iio/devices/ | |
323 | /sys/bus/iio/devices/ | |
324 | ├── iio:device0 -> ../../../devices/0044:8086:22D8.0001/HID-SENSOR-200073.9.auto/iio:device0 | |
325 | │ ├── buffer | |
326 | │ │ ├── enable | |
327 | │ │ ├── length | |
328 | │ │ └── watermark | |
329 | ... | |
330 | │ ├── in_accel_hysteresis | |
331 | │ ├── in_accel_offset | |
332 | │ ├── in_accel_sampling_frequency | |
333 | │ ├── in_accel_scale | |
334 | │ ├── in_accel_x_raw | |
335 | │ ├── in_accel_y_raw | |
336 | │ ├── in_accel_z_raw | |
337 | │ ├── name | |
338 | │ ├── scan_elements | |
339 | │ │ ├── in_accel_x_en | |
340 | │ │ ├── in_accel_x_index | |
341 | │ │ ├── in_accel_x_type | |
342 | │ │ ├── in_accel_y_en | |
343 | │ │ ├── in_accel_y_index | |
344 | │ │ ├── in_accel_y_type | |
345 | │ │ ├── in_accel_z_en | |
346 | │ │ ├── in_accel_z_index | |
347 | │ │ └── in_accel_z_type | |
348 | ... | |
349 | │ │ ├── devices | |
350 | │ │ │ │ ├── buffer | |
351 | │ │ │ │ │ ├── enable | |
352 | │ │ │ │ │ ├── length | |
353 | │ │ │ │ │ └── watermark | |
354 | │ │ │ │ ├── dev | |
355 | │ │ │ │ ├── in_intensity_both_raw | |
356 | │ │ │ │ ├── in_intensity_hysteresis | |
357 | │ │ │ │ ├── in_intensity_offset | |
358 | │ │ │ │ ├── in_intensity_sampling_frequency | |
359 | │ │ │ │ ├── in_intensity_scale | |
360 | │ │ │ │ ├── name | |
361 | │ │ │ │ ├── scan_elements | |
362 | │ │ │ │ │ ├── in_intensity_both_en | |
363 | │ │ │ │ │ ├── in_intensity_both_index | |
364 | │ │ │ │ │ └── in_intensity_both_type | |
365 | │ │ │ │ ├── trigger | |
366 | │ │ │ │ │ └── current_trigger | |
367 | ... | |
368 | │ │ │ │ ├── buffer | |
369 | │ │ │ │ │ ├── enable | |
370 | │ │ │ │ │ ├── length | |
371 | │ │ │ │ │ └── watermark | |
372 | │ │ │ │ ├── dev | |
373 | │ │ │ │ ├── in_magn_hysteresis | |
374 | │ │ │ │ ├── in_magn_offset | |
375 | │ │ │ │ ├── in_magn_sampling_frequency | |
376 | │ │ │ │ ├── in_magn_scale | |
377 | │ │ │ │ ├── in_magn_x_raw | |
378 | │ │ │ │ ├── in_magn_y_raw | |
379 | │ │ │ │ ├── in_magn_z_raw | |
380 | │ │ │ │ ├── in_rot_from_north_magnetic_tilt_comp_raw | |
381 | │ │ │ │ ├── in_rot_hysteresis | |
382 | │ │ │ │ ├── in_rot_offset | |
383 | │ │ │ │ ├── in_rot_sampling_frequency | |
384 | │ │ │ │ ├── in_rot_scale | |
385 | │ │ │ │ ├── name | |
386 | ... | |
387 | │ │ │ │ ├── scan_elements | |
388 | │ │ │ │ │ ├── in_magn_x_en | |
389 | │ │ │ │ │ ├── in_magn_x_index | |
390 | │ │ │ │ │ ├── in_magn_x_type | |
391 | │ │ │ │ │ ├── in_magn_y_en | |
392 | │ │ │ │ │ ├── in_magn_y_index | |
393 | │ │ │ │ │ ├── in_magn_y_type | |
394 | │ │ │ │ │ ├── in_magn_z_en | |
395 | │ │ │ │ │ ├── in_magn_z_index | |
396 | │ │ │ │ │ ├── in_magn_z_type | |
397 | │ │ │ │ │ ├── in_rot_from_north_magnetic_tilt_comp_en | |
398 | │ │ │ │ │ ├── in_rot_from_north_magnetic_tilt_comp_index | |
399 | │ │ │ │ │ └── in_rot_from_north_magnetic_tilt_comp_type | |
400 | │ │ │ │ ├── trigger | |
401 | │ │ │ │ │ └── current_trigger | |
402 | ... | |
403 | │ │ │ │ ├── buffer | |
404 | │ │ │ │ │ ├── enable | |
405 | │ │ │ │ │ ├── length | |
406 | │ │ │ │ │ └── watermark | |
407 | │ │ │ │ ├── dev | |
408 | │ │ │ │ ├── in_anglvel_hysteresis | |
409 | │ │ │ │ ├── in_anglvel_offset | |
410 | │ │ │ │ ├── in_anglvel_sampling_frequency | |
411 | │ │ │ │ ├── in_anglvel_scale | |
412 | │ │ │ │ ├── in_anglvel_x_raw | |
413 | │ │ │ │ ├── in_anglvel_y_raw | |
414 | │ │ │ │ ├── in_anglvel_z_raw | |
415 | │ │ │ │ ├── name | |
416 | │ │ │ │ ├── scan_elements | |
417 | │ │ │ │ │ ├── in_anglvel_x_en | |
418 | │ │ │ │ │ ├── in_anglvel_x_index | |
419 | │ │ │ │ │ ├── in_anglvel_x_type | |
420 | │ │ │ │ │ ├── in_anglvel_y_en | |
421 | │ │ │ │ │ ├── in_anglvel_y_index | |
422 | │ │ │ │ │ ├── in_anglvel_y_type | |
423 | │ │ │ │ │ ├── in_anglvel_z_en | |
424 | │ │ │ │ │ ├── in_anglvel_z_index | |
425 | │ │ │ │ │ └── in_anglvel_z_type | |
426 | │ │ │ │ ├── trigger | |
427 | │ │ │ │ │ └── current_trigger | |
428 | ... | |
429 | │ │ │ │ ├── buffer | |
430 | │ │ │ │ │ ├── enable | |
431 | │ │ │ │ │ ├── length | |
432 | │ │ │ │ │ └── watermark | |
433 | │ │ │ │ ├── dev | |
434 | │ │ │ │ ├── in_anglvel_hysteresis | |
435 | │ │ │ │ ├── in_anglvel_offset | |
436 | │ │ │ │ ├── in_anglvel_sampling_frequency | |
437 | │ │ │ │ ├── in_anglvel_scale | |
438 | │ │ │ │ ├── in_anglvel_x_raw | |
439 | │ │ │ │ ├── in_anglvel_y_raw | |
440 | │ │ │ │ ├── in_anglvel_z_raw | |
441 | │ │ │ │ ├── name | |
442 | │ │ │ │ ├── scan_elements | |
443 | │ │ │ │ │ ├── in_anglvel_x_en | |
444 | │ │ │ │ │ ├── in_anglvel_x_index | |
445 | │ │ │ │ │ ├── in_anglvel_x_type | |
446 | │ │ │ │ │ ├── in_anglvel_y_en | |
447 | │ │ │ │ │ ├── in_anglvel_y_index | |
448 | │ │ │ │ │ ├── in_anglvel_y_type | |
449 | │ │ │ │ │ ├── in_anglvel_z_en | |
450 | │ │ │ │ │ ├── in_anglvel_z_index | |
451 | │ │ │ │ │ └── in_anglvel_z_type | |
452 | │ │ │ │ ├── trigger | |
453 | │ │ │ │ │ └── current_trigger | |
454 | ... |