| Intel Integrated Sensor Hub (ISH) | |
| =============================== | |
| A sensor hub enables the ability to offload sensor polling and algorithm | |
| processing to a dedicated low power co-processor. This allows the core | |
| processor to go into low power modes more often, resulting in the increased | |
| battery life. | |
| There are many vendors providing external sensor hubs confirming to HID | |
| Sensor usage tables, and used in several tablets, 2 in 1 convertible laptops | |
| and embedded products. Linux had this support since Linux 3.9. | |
| Intel® introduced integrated sensor hubs as a part of the SoC starting from | |
| Cherry Trail and now supported on multiple generations of CPU packages. There | |
| are many commercial devices already shipped with Integrated Sensor Hubs (ISH). | |
| These ISH also comply to HID sensor specification, but the difference is the | |
| transport protocol used for communication. The current external sensor hubs | |
| mainly use HID over i2C or USB. But ISH doesn't use either i2c or USB. | |
| 1. Overview | |
| Using a analogy with a usbhid implementation, the ISH follows a similar model | |
| for a very high speed communication: | |
| ----------------- ---------------------- | |
| | USB HID | --> | ISH HID | | |
| ----------------- ---------------------- | |
| ----------------- ---------------------- | |
| | USB protocol | --> | ISH Transport | | |
| ----------------- ---------------------- | |
| ----------------- ---------------------- | |
| | EHCI/XHCI | --> | ISH IPC | | |
| ----------------- ---------------------- | |
| PCI PCI | |
| ----------------- ---------------------- | |
| |Host controller| --> | ISH processor | | |
| ----------------- ---------------------- | |
| USB Link | |
| ----------------- ---------------------- | |
| | USB End points| --> | ISH Clients | | |
| ----------------- ---------------------- | |
| Like USB protocol provides a method for device enumeration, link management | |
| and user data encapsulation, the ISH also provides similar services. But it is | |
| very light weight tailored to manage and communicate with ISH client | |
| applications implemented in the firmware. | |
| The ISH allows multiple sensor management applications executing in the | |
| firmware. Like USB endpoints the messaging can be to/from a client. As part of | |
| enumeration process, these clients are identified. These clients can be simple | |
| HID sensor applications, sensor calibration application or senor firmware | |
| update application. | |
| The implementation model is similar, like USB bus, ISH transport is also | |
| implemented as a bus. Each client application executing in the ISH processor | |
| is registered as a device on this bus. The driver, which binds each device | |
| (ISH HID driver) identifies the device type and registers with the hid core. | |
| 2. ISH Implementation: Block Diagram | |
| --------------------------- | |
| | User Space Applications | | |
| --------------------------- | |
| ----------------IIO ABI---------------- | |
| -------------------------- | |
| | IIO Sensor Drivers | | |
| -------------------------- | |
| -------------------------- | |
| | IIO core | | |
| -------------------------- | |
| -------------------------- | |
| | HID Sensor Hub MFD | | |
| -------------------------- | |
| -------------------------- | |
| | HID Core | | |
| -------------------------- | |
| -------------------------- | |
| | HID over ISH Client | | |
| -------------------------- | |
| -------------------------- | |
| | ISH Transport (ISHTP) | | |
| -------------------------- | |
| -------------------------- | |
| | IPC Drivers | | |
| -------------------------- | |
| OS | |
| ---------------- PCI ----------------- | |
| Hardware + Firmware | |
| ---------------------------- | |
| | ISH Hardware/Firmware(FW) | | |
| ---------------------------- | |
| 3. High level processing in above blocks | |
| 3.1 Hardware Interface | |
| The ISH is exposed as "Non-VGA unclassified PCI device" to the host. The PCI | |
| product and vendor IDs are changed from different generations of processors. So | |
| the source code which enumerate drivers needs to update from generation to | |
| generation. | |
| 3.2 Inter Processor Communication (IPC) driver | |
| Location: drivers/hid/intel-ish-hid/ipc | |
| The IPC message used memory mapped I/O. The registers are defined in | |
| hw-ish-regs.h. | |
| 3.2.1 IPC/FW message types | |
| There are two types of messages, one for management of link and other messages | |
| are to and from transport layers. | |
| TX and RX of Transport messages | |
| A set of memory mapped register offers support of multi byte messages TX and | |
| RX (E.g.IPC_REG_ISH2HOST_MSG, IPC_REG_HOST2ISH_MSG). The IPC layer maintains | |
| internal queues to sequence messages and send them in order to the FW. | |
| Optionally the caller can register handler to get notification of completion. | |
| A door bell mechanism is used in messaging to trigger processing in host and | |
| client firmware side. When ISH interrupt handler is called, the ISH2HOST | |
| doorbell register is used by host drivers to determine that the interrupt | |
| is for ISH. | |
| Each side has 32 32-bit message registers and a 32-bit doorbell. Doorbell | |
| register has the following format: | |
| Bits 0..6: fragment length (7 bits are used) | |
| Bits 10..13: encapsulated protocol | |
| Bits 16..19: management command (for IPC management protocol) | |
| Bit 31: doorbell trigger (signal H/W interrupt to the other side) | |
| Other bits are reserved, should be 0. | |
| 3.2.2 Transport layer interface | |
| To abstract HW level IPC communication, a set of callbacks are registered. | |
| The transport layer uses them to send and receive messages. | |
| Refer to struct ishtp_hw_ops for callbacks. | |
| 3.3 ISH Transport layer | |
| Location: drivers/hid/intel-ish-hid/ishtp/ | |
| 3.3.1 A Generic Transport Layer | |
| The transport layer is a bi-directional protocol, which defines: | |
| - Set of commands to start, stop, connect, disconnect and flow control | |
| (ishtp/hbm.h) for details | |
| - A flow control mechanism to avoid buffer overflows | |
| This protocol resembles bus messages described in the following document: | |
| http://www.intel.com/content/dam/www/public/us/en/documents/technical-\ | |
| specifications/dcmi-hi-1-0-spec.pdf "Chapter 7: Bus Message Layer" | |
| 3.3.2 Connection and Flow Control Mechanism | |
| Each FW client and a protocol is identified by an UUID. In order to communicate | |
| to a FW client, a connection must be established using connect request and | |
| response bus messages. If successful, a pair (host_client_id and fw_client_id) | |
| will identify the connection. | |
| Once connection is established, peers send each other flow control bus messages | |
| independently. Every peer may send a message only if it has received a | |
| flow-control credit before. Once it sent a message, it may not send another one | |
| before receiving the next flow control credit. | |
| Either side can send disconnect request bus message to end communication. Also | |
| the link will be dropped if major FW reset occurs. | |
| 3.3.3 Peer to Peer data transfer | |
| Peer to Peer data transfer can happen with or without using DMA. Depending on | |
| the sensor bandwidth requirement DMA can be enabled by using module parameter | |
| ishtp_use_dma under intel_ishtp. | |
| Each side (host and FW) manages its DMA transfer memory independently. When an | |
| ISHTP client from either host or FW side wants to send something, it decides | |
| whether to send over IPC or over DMA; for each transfer the decision is | |
| independent. The sending side sends DMA_XFER message when the message is in | |
| the respective host buffer (TX when host client sends, RX when FW client | |
| sends). The recipient of DMA message responds with DMA_XFER_ACK, indicating | |
| the sender that the memory region for that message may be reused. | |
| DMA initialization is started with host sending DMA_ALLOC_NOTIFY bus message | |
| (that includes RX buffer) and FW responds with DMA_ALLOC_NOTIFY_ACK. | |
| Additionally to DMA address communication, this sequence checks capabilities: | |
| if thw host doesn't support DMA, then it won't send DMA allocation, so FW can't | |
| send DMA; if FW doesn't support DMA then it won't respond with | |
| DMA_ALLOC_NOTIFY_ACK, in which case host will not use DMA transfers. | |
| Here ISH acts as busmaster DMA controller. Hence when host sends DMA_XFER, | |
| it's request to do host->ISH DMA transfer; when FW sends DMA_XFER, it means | |
| that it already did DMA and the message resides at host. Thus, DMA_XFER | |
| and DMA_XFER_ACK act as ownership indicators. | |
| At initial state all outgoing memory belongs to the sender (TX to host, RX to | |
| FW), DMA_XFER transfers ownership on the region that contains ISHTP message to | |
| the receiving side, DMA_XFER_ACK returns ownership to the sender. A sender | |
| needs not wait for previous DMA_XFER to be ack'ed, and may send another message | |
| as long as remaining continuous memory in its ownership is enough. | |
| In principle, multiple DMA_XFER and DMA_XFER_ACK messages may be sent at once | |
| (up to IPC MTU), thus allowing for interrupt throttling. | |
| Currently, ISH FW decides to send over DMA if ISHTP message is more than 3 IPC | |
| fragments and via IPC otherwise. | |
| 3.3.4 Ring Buffers | |
| When a client initiate a connection, a ring or RX and TX buffers are allocated. | |
| The size of ring can be specified by the client. HID client set 16 and 32 for | |
| TX and RX buffers respectively. On send request from client, the data to be | |
| sent is copied to one of the send ring buffer and scheduled to be sent using | |
| bus message protocol. These buffers are required because the FW may have not | |
| have processed the last message and may not have enough flow control credits | |
| to send. Same thing holds true on receive side and flow control is required. | |
| 3.3.5 Host Enumeration | |
| The host enumeration bus command allow discovery of clients present in the FW. | |
| There can be multiple sensor clients and clients for calibration function. | |
| To ease in implantation and allow independent driver handle each client | |
| this transport layer takes advantage of Linux Bus driver model. Each | |
| client is registered as device on the the transport bus (ishtp bus). | |
| Enumeration sequence of messages: | |
| - Host sends HOST_START_REQ_CMD, indicating that host ISHTP layer is up. | |
| - FW responds with HOST_START_RES_CMD | |
| - Host sends HOST_ENUM_REQ_CMD (enumerate FW clients) | |
| - FW responds with HOST_ENUM_RES_CMD that includes bitmap of available FW | |
| client IDs | |
| - For each FW ID found in that bitmap host sends | |
| HOST_CLIENT_PROPERTIES_REQ_CMD | |
| - FW responds with HOST_CLIENT_PROPERTIES_RES_CMD. Properties include UUID, | |
| max ISHTP message size, etc. | |
| - Once host received properties for that last discovered client, it considers | |
| ISHTP device fully functional (and allocates DMA buffers) | |
| 3.4 HID over ISH Client | |
| Location: drivers/hid/intel-ish-hid | |
| The ISHTP client driver is responsible for: | |
| - enumerate HID devices under FW ISH client | |
| - Get Report descriptor | |
| - Register with HID core as a LL driver | |
| - Process Get/Set feature request | |
| - Get input reports | |
| 3.5 HID Sensor Hub MFD and IIO sensor drivers | |
| The functionality in these drivers is the same as an external sensor hub. | |
| Refer to | |
| Documentation/hid/hid-sensor.txt for HID sensor | |
| Documentation/ABI/testing/sysfs-bus-iio for IIO ABIs to user space | |
| 3.6 End to End HID transport Sequence Diagram | |
| HID-ISH-CLN ISHTP IPC HW | |
| | | | | | |
| | | |-----WAKE UP------------------>| | |
| | | | | | |
| | | |-----HOST READY--------------->| | |
| | | | | | |
| | | |<----MNG_RESET_NOTIFY_ACK----- | | |
| | | | | | |
| | |<----ISHTP_START------ | | | |
| | | | | | |
| | |<-----------------HOST_START_RES_CMD-------------------| | |
| | | | | | |
| | |------------------QUERY_SUBSCRIBER-------------------->| | |
| | | | | | |
| | |------------------HOST_ENUM_REQ_CMD------------------->| | |
| | | | | | |
| | |<-----------------HOST_ENUM_RES_CMD--------------------| | |
| | | | | | |
| | |------------------HOST_CLIENT_PROPERTIES_REQ_CMD------>| | |
| | | | | | |
| | |<-----------------HOST_CLIENT_PROPERTIES_RES_CMD-------| | |
| | Create new device on in ishtp bus | | | |
| | | | | | |
| | |------------------HOST_CLIENT_PROPERTIES_REQ_CMD------>| | |
| | | | | | |
| | |<-----------------HOST_CLIENT_PROPERTIES_RES_CMD-------| | |
| | Create new device on in ishtp bus | | | |
| | | | | | |
| | |--Repeat HOST_CLIENT_PROPERTIES_REQ_CMD-till last one--| | |
| | | | | | |
| probed() | |
| |----ishtp_cl_connect-->|----------------- CLIENT_CONNECT_REQ_CMD-------------->| | |
| | | | | | |
| | |<----------------CLIENT_CONNECT_RES_CMD----------------| | |
| | | | | | |
| |register event callback| | | | |
| | | | | | |
| |ishtp_cl_send( | |
| HOSTIF_DM_ENUM_DEVICES) |----------fill ishtp_msg_hdr struct write to HW----- >| | |
| | | | | | |
| | | |<-----IRQ(IPC_PROTOCOL_ISHTP---| | |
| | | | | | |
| |<--ENUM_DEVICE RSP-----| | | | |
| | | | | | |
| for each enumerated device | |
| |ishtp_cl_send( | |
| HOSTIF_GET_HID_DESCRIPTOR |----------fill ishtp_msg_hdr struct write to HW--- >| | |
| | | | | | |
| ...Response | |
| | | | | | |
| for each enumerated device | |
| |ishtp_cl_send( | |
| HOSTIF_GET_REPORT_DESCRIPTOR |----------fill ishtp_msg_hdr struct write to HW- >| | |
| | | | | | |
| | | | | | |
| hid_allocate_device | |
| | | | | | |
| hid_add_device | | | | |
| | | | | | |
| 3.7 ISH Debugging | |
| To debug ISH, event tracing mechanism is used. To enable debug logs | |
| echo 1 > /sys/kernel/debug/tracing/events/intel_ish/enable | |
| cat sys/kernel/debug/tracing/trace | |
| 3.8 ISH IIO sysfs Example on Lenovo thinkpad Yoga 260 | |
| root@otcpl-ThinkPad-Yoga-260:~# tree -l /sys/bus/iio/devices/ | |
| /sys/bus/iio/devices/ | |
| ├── iio:device0 -> ../../../devices/0044:8086:22D8.0001/HID-SENSOR-200073.9.auto/iio:device0 | |
| │ ├── buffer | |
| │ │ ├── enable | |
| │ │ ├── length | |
| │ │ └── watermark | |
| ... | |
| │ ├── in_accel_hysteresis | |
| │ ├── in_accel_offset | |
| │ ├── in_accel_sampling_frequency | |
| │ ├── in_accel_scale | |
| │ ├── in_accel_x_raw | |
| │ ├── in_accel_y_raw | |
| │ ├── in_accel_z_raw | |
| │ ├── name | |
| │ ├── scan_elements | |
| │ │ ├── in_accel_x_en | |
| │ │ ├── in_accel_x_index | |
| │ │ ├── in_accel_x_type | |
| │ │ ├── in_accel_y_en | |
| │ │ ├── in_accel_y_index | |
| │ │ ├── in_accel_y_type | |
| │ │ ├── in_accel_z_en | |
| │ │ ├── in_accel_z_index | |
| │ │ └── in_accel_z_type | |
| ... | |
| │ │ ├── devices | |
| │ │ │ │ ├── buffer | |
| │ │ │ │ │ ├── enable | |
| │ │ │ │ │ ├── length | |
| │ │ │ │ │ └── watermark | |
| │ │ │ │ ├── dev | |
| │ │ │ │ ├── in_intensity_both_raw | |
| │ │ │ │ ├── in_intensity_hysteresis | |
| │ │ │ │ ├── in_intensity_offset | |
| │ │ │ │ ├── in_intensity_sampling_frequency | |
| │ │ │ │ ├── in_intensity_scale | |
| │ │ │ │ ├── name | |
| │ │ │ │ ├── scan_elements | |
| │ │ │ │ │ ├── in_intensity_both_en | |
| │ │ │ │ │ ├── in_intensity_both_index | |
| │ │ │ │ │ └── in_intensity_both_type | |
| │ │ │ │ ├── trigger | |
| │ │ │ │ │ └── current_trigger | |
| ... | |
| │ │ │ │ ├── buffer | |
| │ │ │ │ │ ├── enable | |
| │ │ │ │ │ ├── length | |
| │ │ │ │ │ └── watermark | |
| │ │ │ │ ├── dev | |
| │ │ │ │ ├── in_magn_hysteresis | |
| │ │ │ │ ├── in_magn_offset | |
| │ │ │ │ ├── in_magn_sampling_frequency | |
| │ │ │ │ ├── in_magn_scale | |
| │ │ │ │ ├── in_magn_x_raw | |
| │ │ │ │ ├── in_magn_y_raw | |
| │ │ │ │ ├── in_magn_z_raw | |
| │ │ │ │ ├── in_rot_from_north_magnetic_tilt_comp_raw | |
| │ │ │ │ ├── in_rot_hysteresis | |
| │ │ │ │ ├── in_rot_offset | |
| │ │ │ │ ├── in_rot_sampling_frequency | |
| │ │ │ │ ├── in_rot_scale | |
| │ │ │ │ ├── name | |
| ... | |
| │ │ │ │ ├── scan_elements | |
| │ │ │ │ │ ├── in_magn_x_en | |
| │ │ │ │ │ ├── in_magn_x_index | |
| │ │ │ │ │ ├── in_magn_x_type | |
| │ │ │ │ │ ├── in_magn_y_en | |
| │ │ │ │ │ ├── in_magn_y_index | |
| │ │ │ │ │ ├── in_magn_y_type | |
| │ │ │ │ │ ├── in_magn_z_en | |
| │ │ │ │ │ ├── in_magn_z_index | |
| │ │ │ │ │ ├── in_magn_z_type | |
| │ │ │ │ │ ├── in_rot_from_north_magnetic_tilt_comp_en | |
| │ │ │ │ │ ├── in_rot_from_north_magnetic_tilt_comp_index | |
| │ │ │ │ │ └── in_rot_from_north_magnetic_tilt_comp_type | |
| │ │ │ │ ├── trigger | |
| │ │ │ │ │ └── current_trigger | |
| ... | |
| │ │ │ │ ├── buffer | |
| │ │ │ │ │ ├── enable | |
| │ │ │ │ │ ├── length | |
| │ │ │ │ │ └── watermark | |
| │ │ │ │ ├── dev | |
| │ │ │ │ ├── in_anglvel_hysteresis | |
| │ │ │ │ ├── in_anglvel_offset | |
| │ │ │ │ ├── in_anglvel_sampling_frequency | |
| │ │ │ │ ├── in_anglvel_scale | |
| │ │ │ │ ├── in_anglvel_x_raw | |
| │ │ │ │ ├── in_anglvel_y_raw | |
| │ │ │ │ ├── in_anglvel_z_raw | |
| │ │ │ │ ├── name | |
| │ │ │ │ ├── scan_elements | |
| │ │ │ │ │ ├── in_anglvel_x_en | |
| │ │ │ │ │ ├── in_anglvel_x_index | |
| │ │ │ │ │ ├── in_anglvel_x_type | |
| │ │ │ │ │ ├── in_anglvel_y_en | |
| │ │ │ │ │ ├── in_anglvel_y_index | |
| │ │ │ │ │ ├── in_anglvel_y_type | |
| │ │ │ │ │ ├── in_anglvel_z_en | |
| │ │ │ │ │ ├── in_anglvel_z_index | |
| │ │ │ │ │ └── in_anglvel_z_type | |
| │ │ │ │ ├── trigger | |
| │ │ │ │ │ └── current_trigger | |
| ... | |
| │ │ │ │ ├── buffer | |
| │ │ │ │ │ ├── enable | |
| │ │ │ │ │ ├── length | |
| │ │ │ │ │ └── watermark | |
| │ │ │ │ ├── dev | |
| │ │ │ │ ├── in_anglvel_hysteresis | |
| │ │ │ │ ├── in_anglvel_offset | |
| │ │ │ │ ├── in_anglvel_sampling_frequency | |
| │ │ │ │ ├── in_anglvel_scale | |
| │ │ │ │ ├── in_anglvel_x_raw | |
| │ │ │ │ ├── in_anglvel_y_raw | |
| │ │ │ │ ├── in_anglvel_z_raw | |
| │ │ │ │ ├── name | |
| │ │ │ │ ├── scan_elements | |
| │ │ │ │ │ ├── in_anglvel_x_en | |
| │ │ │ │ │ ├── in_anglvel_x_index | |
| │ │ │ │ │ ├── in_anglvel_x_type | |
| │ │ │ │ │ ├── in_anglvel_y_en | |
| │ │ │ │ │ ├── in_anglvel_y_index | |
| │ │ │ │ │ ├── in_anglvel_y_type | |
| │ │ │ │ │ ├── in_anglvel_z_en | |
| │ │ │ │ │ ├── in_anglvel_z_index | |
| │ │ │ │ │ └── in_anglvel_z_type | |
| │ │ │ │ ├── trigger | |
| │ │ │ │ │ └── current_trigger | |
| ... |