On 22/06/16 06:40, Srinivas Pandruvada wrote: > Document explaining ISH HID operation and implementation. > > Signed-off-by: Srinivas Pandruvada <srinivas.pandruvada@xxxxxxxxxxxxxxx> 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... Might even be worth taking this into a docbook file instead of straight text... Jonathan > --- > 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/technical-\ > +specifications/dcmi-hi-1-0-spec.pdf blank line. > +Chater 7: Bus Message Layer Chapter. > + > +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... > +- 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 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---| > + | | | | > + | |<------------ 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-iio" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
