Merge branch 'for-5.12/doc' into for-linus
- HID documentation fixes from Randy Dunlap
This commit is contained in:
Jiri Kosina
Коммит
f8dd50e097
|
|
@ -3,13 +3,13 @@
|
|||
|
||||
AMD Sensor Fusion Hub
|
||||
=====================
|
||||
AMD Sensor Fusion Hub (SFH) is part of an SOC starting from Ryzen based platforms.
|
||||
AMD Sensor Fusion Hub (SFH) is part of an SOC starting from Ryzen-based platforms.
|
||||
The solution is working well on several OEM products. AMD SFH uses HID over PCIe bus.
|
||||
In terms of architecture it resembles ISH, however the major difference is all
|
||||
the HID reports are generated as part of the kernel driver.
|
||||
|
||||
1. Block Diagram
|
||||
================
|
||||
Block Diagram
|
||||
-------------
|
||||
|
||||
::
|
||||
|
||||
|
|
@ -45,20 +45,20 @@ the HID reports are generated as part of the kernel driver.
|
|||
AMD HID Transport Layer
|
||||
-----------------------
|
||||
AMD SFH transport is also implemented as a bus. Each client application executing in the AMD MP2 is
|
||||
registered as a device on this bus. Here: MP2 which is an ARM core connected to x86 for processing
|
||||
registered as a device on this bus. Here, MP2 is an ARM core connected to x86 for processing
|
||||
sensor data. The layer, which binds each device (AMD SFH HID driver) identifies the device type and
|
||||
registers with the hid core. Transport layer attach a constant "struct hid_ll_driver" object with
|
||||
registers with the HID core. Transport layer attaches a constant "struct hid_ll_driver" object with
|
||||
each device. Once a device is registered with HID core, the callbacks provided via this struct are
|
||||
used by HID core to communicate with the device. AMD HID Transport layer implements the synchronous calls.
|
||||
|
||||
AMD HID Client Layer
|
||||
--------------------
|
||||
This layer is responsible to implement HID request and descriptors. As firmware is OS agnostic, HID
|
||||
This layer is responsible to implement HID requests and descriptors. As firmware is OS agnostic, HID
|
||||
client layer fills the HID request structure and descriptors. HID client layer is complex as it is
|
||||
interface between MP2 PCIe layer and HID. HID client layer initialized the MP2 PCIe layer and holds
|
||||
the instance of MP2 layer. It identifies the number of sensors connected using MP2-PCIe layer. Base
|
||||
on that allocates the DRAM address for each and every sensor and pass it to MP2-PCIe driver.On
|
||||
enumeration of each the sensor, client layer fills the HID Descriptor structure and HID input repor
|
||||
interface between MP2 PCIe layer and HID. HID client layer initializes the MP2 PCIe layer and holds
|
||||
the instance of MP2 layer. It identifies the number of sensors connected using MP2-PCIe layer. Based
|
||||
on that allocates the DRAM address for each and every sensor and passes it to MP2-PCIe driver. On
|
||||
enumeration of each sensor, client layer fills the HID Descriptor structure and HID input report
|
||||
structure. HID Feature report structure is optional. The report descriptor structure varies from
|
||||
sensor to sensor.
|
||||
|
||||
|
|
@ -72,7 +72,7 @@ The communication between X86 and MP2 is split into three parts.
|
|||
2. Data transfer via DRAM.
|
||||
3. Supported sensor info via P2C registers.
|
||||
|
||||
Commands are sent to MP2 using C2P Mailbox registers. Writing into C2P Message registers generate
|
||||
Commands are sent to MP2 using C2P Mailbox registers. Writing into C2P Message registers generates
|
||||
interrupt to MP2. The client layer allocates the physical memory and the same is sent to MP2 via
|
||||
the PCI layer. MP2 firmware writes the command output to the access DRAM memory which the client
|
||||
layer has allocated. Firmware always writes minimum of 32 bytes into DRAM. So as a protocol driver
|
||||
|
|
|
|||
|
|
@ -64,7 +64,7 @@ Case2 ReportID_3 TP Absolute
|
|||
|
||||
Command Read/Write
|
||||
------------------
|
||||
To read/write to RAM, need to send a commands to the device.
|
||||
To read/write to RAM, need to send a command to the device.
|
||||
|
||||
The command format is as below.
|
||||
|
||||
|
|
@ -80,7 +80,7 @@ Byte6 Value Byte
|
|||
Byte7 Checksum
|
||||
===== ======================
|
||||
|
||||
Command Byte is read=0xD1/write=0xD2 .
|
||||
Command Byte is read=0xD1/write=0xD2.
|
||||
|
||||
Address is read/write RAM address.
|
||||
|
||||
|
|
|
|||
|
|
@ -48,12 +48,12 @@ for different sensors. For example an accelerometer can send X,Y and Z data, whe
|
|||
an ambient light sensor can send illumination data.
|
||||
So the implementation has two parts:
|
||||
|
||||
- Core hid driver
|
||||
- Core HID driver
|
||||
- Individual sensor processing part (sensor drivers)
|
||||
|
||||
Core driver
|
||||
-----------
|
||||
The core driver registers (hid-sensor-hub) registers as a HID driver. It parses
|
||||
The core driver (hid-sensor-hub) registers as a HID driver. It parses
|
||||
report descriptors and identifies all the sensors present. It adds an MFD device
|
||||
with name HID-SENSOR-xxxx (where xxxx is usage id from the specification).
|
||||
|
||||
|
|
@ -95,14 +95,14 @@ Registration functions::
|
|||
u32 usage_id,
|
||||
struct hid_sensor_hub_callbacks *usage_callback):
|
||||
|
||||
Registers callbacks for an usage id. The callback functions are not allowed
|
||||
Registers callbacks for a usage id. The callback functions are not allowed
|
||||
to sleep::
|
||||
|
||||
|
||||
int sensor_hub_remove_callback(struct hid_sensor_hub_device *hsdev,
|
||||
u32 usage_id):
|
||||
|
||||
Removes callbacks for an usage id.
|
||||
Removes callbacks for a usage id.
|
||||
|
||||
|
||||
Parsing function::
|
||||
|
|
@ -166,7 +166,7 @@ This allows some differentiating use cases, where vendor can provide application
|
|||
Some common use cases are debug other sensors or to provide some events like
|
||||
keyboard attached/detached or lid open/close.
|
||||
|
||||
To allow application to utilize these sensors, here they are exported uses sysfs
|
||||
To allow application to utilize these sensors, here they are exported using sysfs
|
||||
attribute groups, attributes and misc device interface.
|
||||
|
||||
An example of this representation on sysfs::
|
||||
|
|
@ -207,9 +207,9 @@ An example of this representation on sysfs::
|
|||
│ │ │ ├── input-1-200202-units
|
||||
│ │ │ ├── input-1-200202-value
|
||||
|
||||
Here there is a custom sensors with four fields, two feature and two inputs.
|
||||
Here there is a custom sensor with four fields: two feature and two inputs.
|
||||
Each field is represented by a set of attributes. All fields except the "value"
|
||||
are read only. The value field is a RW field.
|
||||
are read only. The value field is a read-write field.
|
||||
|
||||
Example::
|
||||
|
||||
|
|
@ -237,6 +237,6 @@ These reports are pushed using misc device interface in a FIFO order::
|
|||
│ │ │ ├── 10:53 -> ../HID-SENSOR-2000e1.6.auto
|
||||
│ ├── HID-SENSOR-2000e1.6.auto
|
||||
|
||||
Each reports can be of variable length preceded by a header. This header
|
||||
consist of a 32 bit usage id, 64 bit time stamp and 32 bit length field of raw
|
||||
Each report can be of variable length preceded by a header. This header
|
||||
consists of a 32-bit usage id, 64-bit time stamp and 32-bit length field of raw
|
||||
data.
|
||||
|
|
|
|||
|
|
@ -12,8 +12,8 @@ Bluetooth, I2C and user-space I/O drivers.
|
|||
|
||||
The HID subsystem is designed as a bus. Any I/O subsystem may provide HID
|
||||
devices and register them with the HID bus. HID core then loads generic device
|
||||
drivers on top of it. The transport drivers are responsible of raw data
|
||||
transport and device setup/management. HID core is responsible of
|
||||
drivers on top of it. The transport drivers are responsible for raw data
|
||||
transport and device setup/management. HID core is responsible for
|
||||
report-parsing, report interpretation and the user-space API. Device specifics
|
||||
and quirks are handled by all layers depending on the quirk.
|
||||
|
||||
|
|
@ -67,7 +67,7 @@ Transport drivers attach a constant "struct hid_ll_driver" object with each
|
|||
device. Once a device is registered with HID core, the callbacks provided via
|
||||
this struct are used by HID core to communicate with the device.
|
||||
|
||||
Transport drivers are responsible of detecting device failures and unplugging.
|
||||
Transport drivers are responsible for detecting device failures and unplugging.
|
||||
HID core will operate a device as long as it is registered regardless of any
|
||||
device failures. Once transport drivers detect unplug or failure events, they
|
||||
must unregister the device from HID core and HID core will stop using the
|
||||
|
|
@ -101,7 +101,7 @@ properties in common.
|
|||
channel. Any unrequested incoming or outgoing data report must be sent on
|
||||
this channel and is never acknowledged by the remote side. Devices usually
|
||||
send their input events on this channel. Outgoing events are normally
|
||||
not send via intr, except if high throughput is required.
|
||||
not sent via intr, except if high throughput is required.
|
||||
- Control Channel (ctrl): The ctrl channel is used for synchronous requests and
|
||||
device management. Unrequested data input events must not be sent on this
|
||||
channel and are normally ignored. Instead, devices only send management
|
||||
|
|
@ -161,7 +161,7 @@ allowed on the intr channel and are the only means of data there.
|
|||
payload may be blocked by the underlying transport driver if the
|
||||
specification does not allow them.
|
||||
- SET_REPORT: A SET_REPORT request has a report ID plus data as payload. It is
|
||||
sent from host to device and a device must update it's current report state
|
||||
sent from host to device and a device must update its current report state
|
||||
according to the given data. Any of the 3 report types can be used. However,
|
||||
INPUT reports as payload might be blocked by the underlying transport driver
|
||||
if the specification does not allow them.
|
||||
|
|
@ -294,7 +294,7 @@ The available HID callbacks are:
|
|||
void (*request) (struct hid_device *hdev, struct hid_report *report,
|
||||
int reqtype)
|
||||
|
||||
Send an HID request on the ctrl channel. "report" contains the report that
|
||||
Send a HID request on the ctrl channel. "report" contains the report that
|
||||
should be sent and "reqtype" the request type. Request-type can be
|
||||
HID_REQ_SET_REPORT or HID_REQ_GET_REPORT.
|
||||
|
||||
|
|
|
|||
|
|
@ -27,7 +27,7 @@ the following::
|
|||
--> hiddev.c ----> POWER / MONITOR CONTROL
|
||||
|
||||
In addition, other subsystems (apart from USB) can potentially feed
|
||||
events into the input subsystem, but these have no effect on the hid
|
||||
events into the input subsystem, but these have no effect on the HID
|
||||
device interface.
|
||||
|
||||
Using the HID Device Interface
|
||||
|
|
@ -73,7 +73,7 @@ The hiddev API uses a read() interface, and a set of ioctl() calls.
|
|||
HID devices exchange data with the host computer using data
|
||||
bundles called "reports". Each report is divided into "fields",
|
||||
each of which can have one or more "usages". In the hid-core,
|
||||
each one of these usages has a single signed 32 bit value.
|
||||
each one of these usages has a single signed 32-bit value.
|
||||
|
||||
read():
|
||||
-------
|
||||
|
|
@ -113,7 +113,7 @@ HIDIOCAPPLICATION
|
|||
- (none)
|
||||
|
||||
This ioctl call returns the HID application usage associated with the
|
||||
hid device. The third argument to ioctl() specifies which application
|
||||
HID device. The third argument to ioctl() specifies which application
|
||||
index to get. This is useful when the device has more than one
|
||||
application collection. If the index is invalid (greater or equal to
|
||||
the number of application collections this device has) the ioctl
|
||||
|
|
@ -181,7 +181,7 @@ looked up by type (input, output or feature) and id, so these fields
|
|||
must be filled in by the user. The ID can be absolute -- the actual
|
||||
report id as reported by the device -- or relative --
|
||||
HID_REPORT_ID_FIRST for the first report, and (HID_REPORT_ID_NEXT |
|
||||
report_id) for the next report after report_id. Without a-priori
|
||||
report_id) for the next report after report_id. Without a priori
|
||||
information about report ids, the right way to use this ioctl is to
|
||||
use the relative IDs above to enumerate the valid IDs. The ioctl
|
||||
returns non-zero when there is no more next ID. The real report ID is
|
||||
|
|
@ -200,7 +200,7 @@ HIDIOCGUCODE
|
|||
- struct hiddev_usage_ref (read/write)
|
||||
|
||||
Returns the usage_code in a hiddev_usage_ref structure, given that
|
||||
given its report type, report id, field index, and index within the
|
||||
its report type, report id, field index, and index within the
|
||||
field have already been filled into the structure.
|
||||
|
||||
HIDIOCGUSAGE
|
||||
|
|
|
|||
|
|
@ -21,7 +21,7 @@ Hidraw is the only alternative, short of writing a custom kernel driver, for
|
|||
these non-conformant devices.
|
||||
|
||||
A benefit of hidraw is that its use by userspace applications is independent
|
||||
of the underlying hardware type. Currently, Hidraw is implemented for USB
|
||||
of the underlying hardware type. Currently, hidraw is implemented for USB
|
||||
and Bluetooth. In the future, as new hardware bus types are developed which
|
||||
use the HID specification, hidraw will be expanded to add support for these
|
||||
new bus types.
|
||||
|
|
@ -31,9 +31,10 @@ create hidraw device nodes. Udev will typically create the device nodes
|
|||
directly under /dev (eg: /dev/hidraw0). As this location is distribution-
|
||||
and udev rule-dependent, applications should use libudev to locate hidraw
|
||||
devices attached to the system. There is a tutorial on libudev with a
|
||||
working example at:
|
||||
working example at::
|
||||
|
||||
http://www.signal11.us/oss/udev/
|
||||
https://web.archive.org/web/2019*/www.signal11.us
|
||||
|
||||
The HIDRAW API
|
||||
---------------
|
||||
|
|
|
|||
|
|
@ -4,19 +4,19 @@ 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
|
||||
processor to go into low power modes more often, resulting in 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.
|
||||
There are many vendors providing external sensor hubs conforming to HID
|
||||
Sensor usage tables. These may be found in tablets, 2-in-1 convertible laptops
|
||||
and embedded products. Linux has 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
|
||||
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.
|
||||
mainly use HID over I2C or USB. But ISH doesn't use either I2C or USB.
|
||||
|
||||
1. Overview
|
||||
===========
|
||||
|
|
@ -35,7 +35,7 @@ for a very high speed communication::
|
|||
----------------- ----------------------
|
||||
PCI PCI
|
||||
----------------- ----------------------
|
||||
|Host controller| --> | ISH processor |
|
||||
|Host controller| --> | ISH processor |
|
||||
----------------- ----------------------
|
||||
USB Link
|
||||
----------------- ----------------------
|
||||
|
|
@ -50,13 +50,13 @@ 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.
|
||||
HID sensor applications, sensor calibration applications or sensor firmware
|
||||
update applications.
|
||||
|
||||
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 HID driver) identifies the device type and registers with the HID core.
|
||||
|
||||
2. ISH Implementation: Block Diagram
|
||||
====================================
|
||||
|
|
@ -104,7 +104,7 @@ is registered as a device on this bus. The driver, which binds each device
|
|||
|
||||
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
|
||||
the source code which enumerates drivers needs to update from generation to
|
||||
generation.
|
||||
|
||||
3.2 Inter Processor Communication (IPC) driver
|
||||
|
|
@ -112,41 +112,42 @@ generation.
|
|||
|
||||
Location: drivers/hid/intel-ish-hid/ipc
|
||||
|
||||
The IPC message used memory mapped I/O. The registers are defined in
|
||||
The IPC message uses 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.
|
||||
There are two types of messages, one for management of link and another for
|
||||
messages 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.
|
||||
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 firmware.
|
||||
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
|
||||
A doorbell 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.
|
||||
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.
|
||||
To abstract HW level IPC communication, a set of callbacks is registered.
|
||||
The transport layer uses them to send and receive messages.
|
||||
Refer to struct ishtp_hw_ops for callbacks.
|
||||
Refer to struct ishtp_hw_ops for callbacks.
|
||||
|
||||
3.3 ISH Transport layer
|
||||
-----------------------
|
||||
|
|
@ -158,7 +159,7 @@ Location: drivers/hid/intel-ish-hid/ishtp/
|
|||
|
||||
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
|
||||
(see ishtp/hbm.h for details)
|
||||
- A flow control mechanism to avoid buffer overflows
|
||||
|
||||
This protocol resembles bus messages described in the following document:
|
||||
|
|
@ -168,14 +169,14 @@ 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
|
||||
Each FW client and a protocol is identified by a 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
|
||||
flow-control credit before. Once it has 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.
|
||||
|
|
@ -209,7 +210,7 @@ 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
|
||||
need 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.
|
||||
|
|
@ -219,8 +220,8 @@ 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
|
||||
When a client initiates a connection, a ring of RX and TX buffers is allocated.
|
||||
The size of ring can be specified by the client. HID client sets 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
|
||||
|
|
@ -230,10 +231,10 @@ 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.
|
||||
The host enumeration bus command allows 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
|
||||
To ease implementation and allow independent drivers to handle each client,
|
||||
this transport layer takes advantage of Linux Bus driver model. Each
|
||||
client is registered as device on the transport bus (ishtp bus).
|
||||
|
||||
|
|
@ -270,7 +271,7 @@ The ISHTP client driver is responsible for:
|
|||
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
|
||||
Documentation/ABI/testing/sysfs-bus-iio for IIO ABIs to user space.
|
||||
|
||||
3.6 End to End HID transport Sequence Diagram
|
||||
---------------------------------------------
|
||||
|
|
@ -341,9 +342,10 @@ Documentation/ABI/testing/sysfs-bus-iio for IIO ABIs to user space
|
|||
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
|
||||
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
|
||||
-----------------------------------------------------
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@ UHID - User-space I/O driver support for HID subsystem
|
|||
======================================================
|
||||
|
||||
UHID allows user-space to implement HID transport drivers. Please see
|
||||
hid-transport.txt for an introduction into HID transport drivers. This document
|
||||
hid-transport.rst for an introduction into HID transport drivers. This document
|
||||
relies heavily on the definitions declared there.
|
||||
|
||||
With UHID, a user-space transport driver can create kernel hid-devices for each
|
||||
|
|
@ -15,7 +15,7 @@ There is an example user-space application in ./samples/uhid/uhid-example.c
|
|||
The UHID API
|
||||
------------
|
||||
|
||||
UHID is accessed through a character misc-device. The minor-number is allocated
|
||||
UHID is accessed through a character misc-device. The minor number is allocated
|
||||
dynamically so you need to rely on udev (or similar) to create the device node.
|
||||
This is /dev/uhid by default.
|
||||
|
||||
|
|
@ -45,23 +45,23 @@ The "type" field defines the payload. For each type, there is a
|
|||
payload-structure available in the union "u" (except for empty payloads). This
|
||||
payload contains management and/or device data.
|
||||
|
||||
The first thing you should do is sending an UHID_CREATE2 event. This will
|
||||
register the device. UHID will respond with an UHID_START event. You can now
|
||||
The first thing you should do is send a UHID_CREATE2 event. This will
|
||||
register the device. UHID will respond with a UHID_START event. You can now
|
||||
start sending data to and reading data from UHID. However, unless UHID sends the
|
||||
UHID_OPEN event, the internally attached HID Device Driver has no user attached.
|
||||
That is, you might put your device asleep unless you receive the UHID_OPEN
|
||||
event. If you receive the UHID_OPEN event, you should start I/O. If the last
|
||||
user closes the HID device, you will receive an UHID_CLOSE event. This may be
|
||||
followed by an UHID_OPEN event again and so on. There is no need to perform
|
||||
user closes the HID device, you will receive a UHID_CLOSE event. This may be
|
||||
followed by a UHID_OPEN event again and so on. There is no need to perform
|
||||
reference-counting in user-space. That is, you will never receive multiple
|
||||
UHID_OPEN events without an UHID_CLOSE event. The HID subsystem performs
|
||||
UHID_OPEN events without a UHID_CLOSE event. The HID subsystem performs
|
||||
ref-counting for you.
|
||||
You may decide to ignore UHID_OPEN/UHID_CLOSE, though. I/O is allowed even
|
||||
though the device may have no users.
|
||||
|
||||
If you want to send data on the interrupt channel to the HID subsystem, you send
|
||||
an HID_INPUT2 event with your raw data payload. If the kernel wants to send data
|
||||
on the interrupt channel to the device, you will read an UHID_OUTPUT event.
|
||||
a HID_INPUT2 event with your raw data payload. If the kernel wants to send data
|
||||
on the interrupt channel to the device, you will read a UHID_OUTPUT event.
|
||||
Data requests on the control channel are currently limited to GET_REPORT and
|
||||
SET_REPORT (no other data reports on the control channel are defined so far).
|
||||
Those requests are always synchronous. That means, the kernel sends
|
||||
|
|
@ -71,7 +71,7 @@ the response via UHID_GET_REPORT_REPLY and UHID_SET_REPORT_REPLY to the kernel.
|
|||
The kernel blocks internal driver-execution during such round-trips (times out
|
||||
after a hard-coded period).
|
||||
|
||||
If your device disconnects, you should send an UHID_DESTROY event. This will
|
||||
If your device disconnects, you should send a UHID_DESTROY event. This will
|
||||
unregister the device. You can now send UHID_CREATE2 again to register a new
|
||||
device.
|
||||
If you close() the fd, the device is automatically unregistered and destroyed
|
||||
|
|
@ -125,7 +125,7 @@ UHID_START:
|
|||
This is sent when the HID device is started. Consider this as an answer to
|
||||
UHID_CREATE2. This is always the first event that is sent. Note that this
|
||||
event might not be available immediately after write(UHID_CREATE2) returns.
|
||||
Device drivers might required delayed setups.
|
||||
Device drivers might require delayed setups.
|
||||
This event contains a payload of type uhid_start_req. The "dev_flags" field
|
||||
describes special behaviors of a device. The following flags are defined:
|
||||
|
||||
|
|
@ -149,7 +149,7 @@ UHID_STOP:
|
|||
reloaded/changed the device driver loaded on your HID device (or some other
|
||||
maintenance actions happened).
|
||||
|
||||
You can usually ignored any UHID_STOP events safely.
|
||||
You can usually ignore any UHID_STOP events safely.
|
||||
|
||||
UHID_OPEN:
|
||||
This is sent when the HID device is opened. That is, the data that the HID
|
||||
|
|
@ -166,17 +166,17 @@ UHID_OUTPUT:
|
|||
This is sent if the HID device driver wants to send raw data to the I/O
|
||||
device on the interrupt channel. You should read the payload and forward it to
|
||||
the device. The payload is of type "struct uhid_output_req".
|
||||
This may be received even though you haven't received UHID_OPEN, yet.
|
||||
This may be received even though you haven't received UHID_OPEN yet.
|
||||
|
||||
UHID_GET_REPORT:
|
||||
This event is sent if the kernel driver wants to perform a GET_REPORT request
|
||||
on the control channeld as described in the HID specs. The report-type and
|
||||
on the control channel as described in the HID specs. The report-type and
|
||||
report-number are available in the payload.
|
||||
The kernel serializes GET_REPORT requests so there will never be two in
|
||||
parallel. However, if you fail to respond with a UHID_GET_REPORT_REPLY, the
|
||||
request might silently time out.
|
||||
Once you read a GET_REPORT request, you shall forward it to the hid device and
|
||||
remember the "id" field in the payload. Once your hid device responds to the
|
||||
Once you read a GET_REPORT request, you shall forward it to the HID device and
|
||||
remember the "id" field in the payload. Once your HID device responds to the
|
||||
GET_REPORT (or if it fails), you must send a UHID_GET_REPORT_REPLY to the
|
||||
kernel with the exact same "id" as in the request. If the request already
|
||||
timed out, the kernel will ignore the response silently. The "id" field is
|
||||
|
|
@ -184,7 +184,7 @@ UHID_GET_REPORT:
|
|||
|
||||
UHID_SET_REPORT:
|
||||
This is the SET_REPORT equivalent of UHID_GET_REPORT. On receipt, you shall
|
||||
send a SET_REPORT request to your hid device. Once it replies, you must tell
|
||||
send a SET_REPORT request to your HID device. Once it replies, you must tell
|
||||
the kernel about it via UHID_SET_REPORT_REPLY.
|
||||
The same restrictions as for UHID_GET_REPORT apply.
|
||||
|
||||
|
|
|
|||
|
|
@ -1029,7 +1029,7 @@ static DEFINE_MUTEX(dquirks_lock);
|
|||
/* Runtime ("dynamic") quirks manipulation functions */
|
||||
|
||||
/**
|
||||
* hid_exists_dquirk: find any dynamic quirks for a HID device
|
||||
* hid_exists_dquirk - find any dynamic quirks for a HID device
|
||||
* @hdev: the HID device to match
|
||||
*
|
||||
* Description:
|
||||
|
|
@ -1037,7 +1037,7 @@ static DEFINE_MUTEX(dquirks_lock);
|
|||
* the pointer to the relevant struct hid_device_id if found.
|
||||
* Must be called with a read lock held on dquirks_lock.
|
||||
*
|
||||
* Returns: NULL if no quirk found, struct hid_device_id * if found.
|
||||
* Return: NULL if no quirk found, struct hid_device_id * if found.
|
||||
*/
|
||||
static struct hid_device_id *hid_exists_dquirk(const struct hid_device *hdev)
|
||||
{
|
||||
|
|
@ -1061,7 +1061,7 @@ static struct hid_device_id *hid_exists_dquirk(const struct hid_device *hdev)
|
|||
|
||||
|
||||
/**
|
||||
* hid_modify_dquirk: add/replace a HID quirk
|
||||
* hid_modify_dquirk - add/replace a HID quirk
|
||||
* @id: the HID device to match
|
||||
* @quirks: the unsigned long quirks value to add/replace
|
||||
*
|
||||
|
|
@ -1070,7 +1070,7 @@ static struct hid_device_id *hid_exists_dquirk(const struct hid_device *hdev)
|
|||
* quirks value with what was provided. Otherwise, add the quirk
|
||||
* to the dynamic quirks list.
|
||||
*
|
||||
* Returns: 0 OK, -error on failure.
|
||||
* Return: 0 OK, -error on failure.
|
||||
*/
|
||||
static int hid_modify_dquirk(const struct hid_device_id *id,
|
||||
const unsigned long quirks)
|
||||
|
|
@ -1122,7 +1122,7 @@ static int hid_modify_dquirk(const struct hid_device_id *id,
|
|||
}
|
||||
|
||||
/**
|
||||
* hid_remove_all_dquirks: remove all runtime HID quirks from memory
|
||||
* hid_remove_all_dquirks - remove all runtime HID quirks from memory
|
||||
* @bus: bus to match against. Use HID_BUS_ANY if all need to be removed.
|
||||
*
|
||||
* Description:
|
||||
|
|
@ -1146,7 +1146,10 @@ static void hid_remove_all_dquirks(__u16 bus)
|
|||
}
|
||||
|
||||
/**
|
||||
* hid_quirks_init: apply HID quirks specified at module load time
|
||||
* hid_quirks_init - apply HID quirks specified at module load time
|
||||
* @quirks_param: array of quirks strings (vendor:product:quirks)
|
||||
* @bus: bus type
|
||||
* @count: number of quirks to check
|
||||
*/
|
||||
int hid_quirks_init(char **quirks_param, __u16 bus, int count)
|
||||
{
|
||||
|
|
@ -1177,7 +1180,7 @@ int hid_quirks_init(char **quirks_param, __u16 bus, int count)
|
|||
EXPORT_SYMBOL_GPL(hid_quirks_init);
|
||||
|
||||
/**
|
||||
* hid_quirks_exit: release memory associated with dynamic_quirks
|
||||
* hid_quirks_exit - release memory associated with dynamic_quirks
|
||||
* @bus: a bus to match against
|
||||
*
|
||||
* Description:
|
||||
|
|
@ -1194,14 +1197,14 @@ void hid_quirks_exit(__u16 bus)
|
|||
EXPORT_SYMBOL_GPL(hid_quirks_exit);
|
||||
|
||||
/**
|
||||
* hid_gets_squirk: return any static quirks for a HID device
|
||||
* hid_gets_squirk - return any static quirks for a HID device
|
||||
* @hdev: the HID device to match
|
||||
*
|
||||
* Description:
|
||||
* Given a HID device, return a pointer to the quirked hid_device_id entry
|
||||
* associated with that device.
|
||||
*
|
||||
* Returns: the quirks.
|
||||
* Return: the quirks.
|
||||
*/
|
||||
static unsigned long hid_gets_squirk(const struct hid_device *hdev)
|
||||
{
|
||||
|
|
@ -1225,13 +1228,13 @@ static unsigned long hid_gets_squirk(const struct hid_device *hdev)
|
|||
}
|
||||
|
||||
/**
|
||||
* hid_lookup_quirk: return any quirks associated with a HID device
|
||||
* hid_lookup_quirk - return any quirks associated with a HID device
|
||||
* @hdev: the HID device to look for
|
||||
*
|
||||
* Description:
|
||||
* Given a HID device, return any quirks associated with that device.
|
||||
*
|
||||
* Returns: an unsigned long quirks value.
|
||||
* Return: an unsigned long quirks value.
|
||||
*/
|
||||
unsigned long hid_lookup_quirk(const struct hid_device *hdev)
|
||||
{
|
||||
|
|
|
|||
|
|
@ -150,7 +150,7 @@ int sensor_hub_remove_callback(struct hid_sensor_hub_device *hsdev,
|
|||
* @info: return information about attribute after parsing report
|
||||
*
|
||||
* Parses report and returns the attribute information such as report id,
|
||||
* field index, units and exponet etc.
|
||||
* field index, units and exponent etc.
|
||||
*/
|
||||
int sensor_hub_input_get_attribute_info(struct hid_sensor_hub_device *hsdev,
|
||||
u8 type,
|
||||
|
|
@ -167,7 +167,7 @@ int sensor_hub_input_get_attribute_info(struct hid_sensor_hub_device *hsdev,
|
|||
* @is_signed: If true then fields < 32 bits will be sign-extended
|
||||
*
|
||||
* Issues a synchronous or asynchronous read request for an input attribute.
|
||||
* Returns data upto 32 bits.
|
||||
* Return: data up to 32 bits.
|
||||
*/
|
||||
|
||||
enum sensor_hub_read_flags {
|
||||
|
|
@ -205,8 +205,9 @@ int sensor_hub_set_feature(struct hid_sensor_hub_device *hsdev, u32 report_id,
|
|||
* @buffer: buffer to copy output
|
||||
*
|
||||
* Used to get a field in feature report. For example this can get polling
|
||||
* interval, sensitivity, activate/deactivate state. On success it returns
|
||||
* number of bytes copied to buffer. On failure, it returns value < 0.
|
||||
* interval, sensitivity, activate/deactivate state.
|
||||
* Return: On success, it returns the number of bytes copied to buffer.
|
||||
* On failure, it returns value < 0.
|
||||
*/
|
||||
int sensor_hub_get_feature(struct hid_sensor_hub_device *hsdev, u32 report_id,
|
||||
u32 field_index, int buffer_size, void *buffer);
|
||||
|
|
|
|||
|
|
@ -918,7 +918,7 @@ __u32 hid_field_extract(const struct hid_device *hid, __u8 *report,
|
|||
/**
|
||||
* hid_device_io_start - enable HID input during probe, remove
|
||||
*
|
||||
* @hid - the device
|
||||
* @hid: the device
|
||||
*
|
||||
* This should only be called during probe or remove and only be
|
||||
* called by the thread calling probe or remove. It will allow
|
||||
|
|
@ -936,7 +936,7 @@ static inline void hid_device_io_start(struct hid_device *hid) {
|
|||
/**
|
||||
* hid_device_io_stop - disable HID input during probe, remove
|
||||
*
|
||||
* @hid - the device
|
||||
* @hid: the device
|
||||
*
|
||||
* Should only be called after hid_device_io_start. It will prevent
|
||||
* incoming packets from going to the driver for the duration of
|
||||
|
|
@ -1010,6 +1010,13 @@ static inline void hid_map_usage(struct hid_input *hidinput,
|
|||
/**
|
||||
* hid_map_usage_clear - map usage input bits and clear the input bit
|
||||
*
|
||||
* @hidinput: hidinput which we are interested in
|
||||
* @usage: usage to fill in
|
||||
* @bit: pointer to input->{}bit (out parameter)
|
||||
* @max: maximal valid usage->code to consider later (out parameter)
|
||||
* @type: input event type (EV_KEY, EV_REL, ...)
|
||||
* @c: code which corresponds to this usage and type
|
||||
*
|
||||
* The same as hid_map_usage, except the @c bit is also cleared in supported
|
||||
* bits (@bit).
|
||||
*/
|
||||
|
|
@ -1084,7 +1091,7 @@ static inline void hid_hw_request(struct hid_device *hdev,
|
|||
* @rtype: HID report type
|
||||
* @reqtype: HID_REQ_GET_REPORT or HID_REQ_SET_REPORT
|
||||
*
|
||||
* @return: count of data transfered, negative if error
|
||||
* Return: count of data transferred, negative if error
|
||||
*
|
||||
* Same behavior as hid_hw_request, but with raw buffers instead.
|
||||
*/
|
||||
|
|
@ -1106,7 +1113,7 @@ static inline int hid_hw_raw_request(struct hid_device *hdev,
|
|||
* @buf: raw data to transfer
|
||||
* @len: length of buf
|
||||
*
|
||||
* @return: count of data transfered, negative if error
|
||||
* Return: count of data transferred, negative if error
|
||||
*/
|
||||
static inline int hid_hw_output_report(struct hid_device *hdev, __u8 *buf,
|
||||
size_t len)
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче