lkml.org 
[lkml]   [2016]   [Jun]   [27]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
SubjectRe: [PATCH v2 1/6] Documentation: hid: Intel ISH HID document
From
Date
On Sun, 2016-06-26 at 19:32 +0100, Jonathan Cameron wrote:
> On 22/06/16 06:40, Srinivas Pandruvada wrote:
> >
> > 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
> >
> > ---
> >  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.
> >
> > +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 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
> > +...
> >

\
 
 \ /
  Last update: 2016-06-27 18:01    [W:0.380 / U:0.120 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site