new file mode 100644
@@ -0,0 +1,454 @@
+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
+...
Document explaining ISH HID operation and implementation. Signed-off-by: Srinivas Pandruvada <srinivas.pandruvada@linux.intel.com> --- Documentation/hid/intel-ish-hid.txt | 454 ++++++++++++++++++++++++++++++++++++ 1 file changed, 454 insertions(+) create mode 100644 Documentation/hid/intel-ish-hid.txt