mirror of
https://github.com/edk2-porting/linux-next.git
synced 2024-12-23 04:34:11 +08:00
cca4786174
Rename the HID documentation files to ReST, add an index for them and adjust in order to produce a nice html output via the Sphinx build system. While here, fix the sysfs example from hid-sensor.txt, that has a lot of "?" instead of the proper UTF-8 characters that are produced by the tree command. At its new index.rst, let's add a :orphan: while this is not linked to the main index.rst file, in order to avoid build warnings. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Acked-by: Benjamin Tissoires <benjamin.tissoires@redhat.com> Signed-off-by: Benjamin Tissoires <benjamin.tissoires@redhat.com>
486 lines
24 KiB
ReStructuredText
486 lines
24 KiB
ReStructuredText
=================================
|
|
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.rst 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
|
|
...
|