On Sun, 2016-06-26 at 19:32 +0100, Jonathan Cameron wrote:

On 22/06/16 06:40, Srinivas Pandruvada wrote:

quoted

Document explaining ISH HID operation and implementation.

Signed-off-by: Srinivas Pandruvada <srinivas.pandruvada@linux.intel
.com>

A few really trivial point inline.  I unfortunately don't have the
time to
dive into this in sufficient depth to grasp every detail, but the
description seems pretty comprehensive to me.

I would however, put a blank line between paragraphs to make it a
touch
easier to read...

Thanks. I will take care of your comments in the next revision.

Might even be worth taking this into a docbook file instead of
straight
text...

If we convert to docbook format, will it still go to Documentation/hid
folder, or somewhere else?

Thanks,
Srinivas

Jonathan

quoted

---
 Documentation/hid/intel-ish-hid.txt | 449
++++++++++++++++++++++++++++++++++++
 1 file changed, 449 insertions(+)
 create mode 100644 Documentation/hid/intel-ish-hid.txt

diff --git a/Documentation/hid/intel-ish-hid.txt

b/Documentation/hid/intel-ish-hid.txt
new file mode 100644
index 0000000..8557280

--- /dev/null
+++ b/Documentation/hid/intel-ish-hid.txt

@@ -0,0 +1,449 @@
+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.
+
+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.
+
+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) |
+	 ----------------------------
+
+------------------------------------------
+
+High level processing in above blocks:
+
+---
+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.
+
+---
+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.
+
+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.
+
+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.
+
+---
+ISH Transport layer
+Location: drivers/hid/intel-ish-hid/ishtp/
+
+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/techni
cal-\
+specifications/dcmi-hi-1-0-spec.pdf

blank line.

quoted

+Chater 7: Bus Message Layer

Chapter.

quoted

+
+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 FC credit.
+Either side can send disconnect request bus message to end
communication. Also
+the link will be dropped if major FW reset occurs.
+
+Peer to Peer data transfer
+The host allocates TX and RX buffers. 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. Host right now never decides to
send over DMA
+because at this time there is no streaming case for larger
messages.
+
+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
+processed last message and may not have enough flow control
credits to send.
+Same thing holds true on receive side and flow control is
required.
+
+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)
+
+---
+HID over ISH Client
+Location: drivers/hid/intel-ish-hid
+
+This implanted as ISHTP client driver, which

implanted is an odd word choice...

quoted

+- 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
+
+----
+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
+
+----
+
+==================================================================
======================
+End to End HID transport Sequence Diagram
+
+HID-ISH-CLN			ISHTP			IP
C				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---|
+	|			|			|	
			|
+	|			|<------------ DMA_XFER--------
-------------------------|
+	|<--ENUM_DEVICE RSP-----|			|		
		|
+	|			|------------ DMA_XFER_ACK-------
---------------------->|
+	|			|			|	
			|
+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			|			|	
			|
+	|			|			|	
			|
+
+
+==================================================================
======================
+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
+
+==================================================================
======================
+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
+...

--
To unsubscribe from this list: send the line "unsubscribe linux-input" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html