tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
HID: THC: Add documentation
Add Documentation/hid/intel-thc-hid.rst file to provide hardware
and software detail for intel THC drivers.
Co-developed-by: Sun Xinpeng <xinpeng.sun@intel.com>
Signed-off-by: Sun Xinpeng <xinpeng.sun@intel.com>
Signed-off-by: Even Xu <even.xu@intel.com>
Reviewed-by: Srinivas Pandruvada <srinivas.pandruvada@linux.intel.com>
Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>
Reviewed-by: Mark Pearson <mpearson-lenovo@squebb.ca>
Tested-by: Aaron Ma <aaron.ma@canonical.com>
Signed-off-by: Jiri Kosina <jkosina@suse.com>
authored by
Even Xu
and committed by
Jiri Kosina
df3a78d8
2a770b49
+569
+1
Documentation/hid/index.rst
+1
Documentation/hid/index.rst
+568
Documentation/hid/intel-thc-hid.rst
+568
Documentation/hid/intel-thc-hid.rst
···
1
+
.. SPDX-License-Identifier: GPL-2.0
2
+
3
+
=================================
4
+
Intel Touch Host Controller (THC)
5
+
=================================
6
+
7
+
Touch Host Controller is the name of the IP block in PCH that interface with Touch Devices (ex:
8
+
touchscreen, touchpad etc.). It is comprised of 3 key functional blocks:
9
+
10
+
- A natively half-duplex Quad I/O capable SPI master
11
+
- Low latency I2C interface to support HIDI2C compliant devices
12
+
- A HW sequencer with RW DMA capability to system memory
13
+
14
+
It has a single root space IOSF Primary interface that supports transactions to/from touch devices.
15
+
Host driver configures and controls the touch devices over THC interface. THC provides high
16
+
bandwidth DMA services to the touch driver and transfers the HID report to host system main memory.
17
+
18
+
Hardware sequencer within the THC is responsible for transferring (via DMA) data from touch devices
19
+
into system memory. A ring buffer is used to avoid data loss due to asynchronous nature of data
20
+
consumption (by host) in relation to data production (by touch device via DMA).
21
+
22
+
Unlike other common SPI/I2C controllers, THC handles the HID device data interrupt and reset
23
+
signals directly.
24
+
25
+
1. Overview
26
+
===========
27
+
28
+
1.1 THC software/hardware stack
29
+
-------------------------------
30
+
31
+
Below diagram illustrates the high-level architecture of THC software/hardware stack, which is fully
32
+
capable of supporting HIDSPI/HIDI2C protocol in Linux OS.
33
+
34
+
::
35
+
36
+
----------------------------------------------
37
+
| +-----------------------------------+ |
38
+
| | Input Device | |
39
+
| +-----------------------------------+ |
40
+
| +-----------------------------------+ |
41
+
| | HID Multi-touch Driver | |
42
+
| +-----------------------------------+ |
43
+
| +-----------------------------------+ |
44
+
| | HID Core | |
45
+
| +-----------------------------------+ |
46
+
| +-----------------------------------+ |
47
+
| | THC QuickSPI/QuickI2C Driver | |
48
+
| +-----------------------------------+ |
49
+
| +-----------------------------------+ |
50
+
| | THC Hardware Driver | |
51
+
| +-----------------------------------+ |
52
+
| +----------------+ +----------------+ |
53
+
| SW | PCI Bus Driver | | ACPI Resource | |
54
+
| +----------------+ +----------------+ |
55
+
----------------------------------------------
56
+
----------------------------------------------
57
+
| +-----------------------------------+ |
58
+
| HW | PCI Bus | |
59
+
| +-----------------------------------+ |
60
+
| +-----------------------------------+ |
61
+
| | THC Controller | |
62
+
| +-----------------------------------+ |
63
+
| +-----------------------------------+ |
64
+
| | Touch IC | |
65
+
| +-----------------------------------+ |
66
+
----------------------------------------------
67
+
68
+
Touch IC (TIC), also as known as the Touch devices (touchscreen or touchpad). The discrete analog
69
+
components that sense and transfer either discrete touch data or heatmap data in the form of HID
70
+
reports over the SPI/I2C bus to the THC Controller on the host.
71
+
72
+
THC Host Controller, which is a PCI device HBA (host bus adapter), integrated into the PCH, that
73
+
serves as a bridge between the Touch ICs and the host.
74
+
75
+
THC Hardware Driver, provides THC hardware operation APIs for above QuickSPI/QuickI2C driver, it
76
+
accesses THC MMIO registers to configure and control THC hardware.
77
+
78
+
THC QuickSPI/QuickI2C driver, also as known as HIDSPI/HIDI2C driver, is registered as a HID
79
+
low-level driver that manages the THC Controller and implements HIDSPI/HIDI2C protocol.
80
+
81
+
82
+
1.2 THC hardware diagram
83
+
------------------------
84
+
Below diagram shows THC hardware components::
85
+
86
+
---------------------------------
87
+
| THC Controller |
88
+
| +---------------------------+ |
89
+
| | PCI Config Space | |
90
+
| +---------------------------+ |
91
+
| +---------------------------+ |
92
+
| + MMIO Registers | |
93
+
| +---------------------------+ |
94
+
+---------------+ | +------------+ +------------+ |
95
+
| System Memory +---+--+ DMA | | PIO | |
96
+
+---------------+ | +------------+ +------------+ |
97
+
| +---------------------------+ |
98
+
| | HW Sequencer | |
99
+
| +---------------------------+ |
100
+
| +------------+ +------------+ |
101
+
| | SPI/I2C | | GPIO | |
102
+
| | Controller | | Controller | |
103
+
| +------------+ +------------+ |
104
+
---------------------------------
105
+
106
+
As THC is exposed as a PCI devices, so it has standard PCI config space registers for PCI
107
+
enumeration and configuration.
108
+
109
+
MMIO Registers, which provide registers access for driver to configure and control THC hardware,
110
+
the registers include several categories: Interrupt status and control, DMA configure,
111
+
PIO (Programmed I/O, defined in section 3.2) status and control, SPI bus configure, I2C subIP
112
+
status and control, reset status and control...
113
+
114
+
THC provides two ways for driver to communicate with external Touch ICs: PIO and DMA.
115
+
PIO can let driver manually write/read data to/from Touch ICs, instead, THC DMA can
116
+
automatically write/read data without driver involved.
117
+
118
+
HW Sequencer includes THC major logic, it gets instruction from MMIO registers to control
119
+
SPI bus and I2C bus to finish a bus data transaction, it also can automatically handle
120
+
Touch ICs interrupt and start DMA receive/send data from/to Touch ICs according to interrupt
121
+
type. That means THC HW Sequencer understands HIDSPI/HIDI2C transfer protocol, and handle
122
+
the communication without driver involved, what driver needs to do is just configure the THC
123
+
properly, and prepare the formatted data packet or handle received data packet.
124
+
125
+
As THC supports HIDSPI/HIDI2C protocols, it has SPI controller and I2C subIP in it to expose
126
+
SPI bus and I2C bus. THC also integrates a GPIO controller to provide interrupt line support
127
+
and reset line support.
128
+
129
+
2. THC Hardware Interface
130
+
=========================
131
+
132
+
2.1 Host Interface
133
+
------------------
134
+
135
+
THC is exposed as "PCI Digitizer device" to the host. The PCI product and device IDs are
136
+
changed from different generations of processors. So the source code which enumerates drivers
137
+
needs to update from generation to generation.
138
+
139
+
140
+
2.2 Device Interface
141
+
--------------------
142
+
143
+
THC supports two types of bus for Touch IC connection: Enhanced SPI bus and I2C bus.
144
+
145
+
2.2.1 SPI Port
146
+
~~~~~~~~~~~~~~
147
+
148
+
When PORT_TYPE = 00b in MMIO registers, THC uses SPI interfaces to communicate with external
149
+
Touch IC. THC enhanced SPI Bus supports different SPI modes: standard Single IO mode,
150
+
Dual IO mode and Quad IO mode.
151
+
152
+
In Single IO mode, THC drives MOSI line to send data to Touch ICs, and receives data from Touch
153
+
ICs data from MISO line. In Dual IO mode, THC drivers MOSI and MISO both for data sending, and
154
+
also receives the data on both line. In Quad IO mode, there are other two lines (IO2 and IO3)
155
+
are added, THC drives MOSI (IO0), MISO (IO1), IO2 and IO3 at the same time for data sending, and
156
+
also receives the data on those 4 lines. Driver needs to configure THC in different mode by
157
+
setting different opcode.
158
+
159
+
Beside IO mode, driver also needs to configure SPI bus speed. THC supports up to 42MHz SPI clock
160
+
on Intel Lunar Lake platform.
161
+
162
+
For THC sending data to Touch IC, the data flow on SPI bus::
163
+
164
+
| --------------------THC sends---------------------------------|
165
+
<8Bits OPCode><24Bits Slave Address><Data><Data><Data>...........
166
+
167
+
For THC receiving data from Touch IC, the data flow on SPI bus::
168
+
169
+
| ---------THC Sends---------------||-----Touch IC sends--------|
170
+
<8Bits OPCode><24Bits Slave Address><Data><Data><Data>...........
171
+
172
+
2.2.2 I2C Port
173
+
~~~~~~~~~~~~~~
174
+
175
+
THC also integrates I2C controller in it, it's called I2C SubSystem. When PORT_TYPE = 01, THC
176
+
is configured to I2C mode. Comparing to SPI mode which can be configured through MMIO registers
177
+
directly, THC needs to use PIO read (by setting SubIP read opcode) to I2C subIP APB registers'
178
+
value and use PIO write (by setting SubIP write opcode) to do a write operation.
179
+
180
+
2.2.3 GPIO interface
181
+
~~~~~~~~~~~~~~~~~~~~
182
+
183
+
THC also includes two GPIO pins, one for interrupt and the other for device reset control.
184
+
185
+
Interrupt line can be configured to either level triggerred or edge triggerred by setting MMIO
186
+
Control register.
187
+
188
+
Reset line is controlled by BIOS (or EFI) through ACPI _RST method, driver needs to call this
189
+
device ACPI _RST method to reset touch IC during initialization.
190
+
191
+
3. High level concept
192
+
=====================
193
+
194
+
3.1 Opcode
195
+
----------
196
+
197
+
Opcode (operation code) is used to tell THC or Touch IC what the operation will be, such as PIO
198
+
read or PIO write.
199
+
200
+
When THC is configured to SPI mode, opcodes are used for determining the read/write IO mode.
201
+
There are some OPCode examples for SPI IO mode:
202
+
203
+
======= ==============================
204
+
opcode Corresponding SPI command
205
+
======= ==============================
206
+
0x0B Read Single I/O
207
+
0x02 Write Single I/O
208
+
0xBB Read Dual I/O
209
+
0xB2 Write Dual I/O
210
+
0xEB Read Quad I/O
211
+
0xE2 Write Quad I/O
212
+
======= ==============================
213
+
214
+
In general, different touch IC has different OPCode definition. According to HIDSPI
215
+
protocol whitepaper, those OPCodes are defined in device ACPI table, and driver needs to
216
+
query those information through OS ACPI APIs during driver initialization, then configures
217
+
THC MMIO OPCode registers with correct setting.
218
+
219
+
When THC is working in I2C mode, opcodes are used to tell THC what's the next PIO type:
220
+
I2C SubIP APB register read, I2C SubIP APB register write, I2C touch IC device read,
221
+
I2C touch IC device write, I2C touch IC device write followed by read.
222
+
223
+
Here are the THC pre-defined opcodes for I2C mode:
224
+
225
+
======= =================================================== ===========
226
+
opcode Corresponding I2C command Address
227
+
======= =================================================== ===========
228
+
0x12 Read I2C SubIP APB internal registers 0h - FFh
229
+
0x13 Write I2C SubIP APB internal registers 0h - FFh
230
+
0x14 Read external Touch IC through I2C bus N/A
231
+
0x18 Write external Touch IC through I2C bus N/A
232
+
0x1C Write then read external Touch IC through I2C bus N/A
233
+
======= =================================================== ===========
234
+
235
+
3.2 PIO
236
+
-------
237
+
238
+
THC provides a programmed I/O (PIO) access interface for the driver to access the touch IC's
239
+
configuration registers, or access I2C subIP's configuration registers. To use PIO to perform
240
+
I/O operations, driver should pre-program PIO control registers and PIO data registers and kick
241
+
off the sequencing cycle. THC uses different PIO opcodes to distinguish different PIO
242
+
operations (PIO read/write/write followed by read).
243
+
244
+
If there is a Sequencing Cycle In Progress and an attempt is made to program any of the control,
245
+
address, or data register the cycle is blocked and a sequence error will be encountered.
246
+
247
+
A status bit indicates when the cycle has completed allowing the driver to know when read results
248
+
can be checked and/or when to initiate a new command. If enabled, the cycle done assertion can
249
+
interrupt driver with an interrupt.
250
+
251
+
Because THC only has 16 FIFO registers for PIO, so all the data transfer through PIO shouldn't
252
+
exceed 64 bytes.
253
+
254
+
As DMA needs max packet size for transferring configuration, and the max packet size information
255
+
always in HID device descriptor which needs THC driver to read it out from HID Device (Touch IC).
256
+
So PIO typical use case is, before DMA initialization, write RESET command (PIO write), read
257
+
RESET response (PIO read or PIO write followed by read), write Power ON command (PIO write), read
258
+
device descriptor (PIO read).
259
+
260
+
For how to issue a PIO operation, here is the steps which driver needs follow:
261
+
262
+
- Program read/write data size in THC_SS_BC.
263
+
- Program I/O target address in THC_SW_SEQ_DATA0_ADDR.
264
+
- If write, program the write data in THC_SW_SEQ_DATA0..THC_SW_SEQ_DATAn.
265
+
- Program the PIO opcode in THC_SS_CMD.
266
+
- Set TSSGO = 1 to start the PIO write sequence.
267
+
- If THC_SS_CD_IE = 1, SW will receives a MSI when the PIO is completed.
268
+
- If read, read out the data in THC_SW_SEQ_DATA0..THC_SW_SEQ_DATAn.
269
+
270
+
3.3 DMA
271
+
-------
272
+
273
+
THC has 4 DMA channels: Read DMA1, Read DMA2, Write DMA and Software DMA.
274
+
275
+
3.3.1 Read DMA Channel
276
+
~~~~~~~~~~~~~~~~~~~~~~
277
+
278
+
THC has two Read DMA engines: 1st RxDMA (RxDMA1) and 2nd RxDMA (RxDMA2). RxDMA1 is reserved for
279
+
raw data mode. RxDMA2 is used for HID data mode and it is the RxDMA engine currently driver uses
280
+
for HID input report data retrieval.
281
+
282
+
RxDMA's typical use case is auto receiving the data from Touch IC. Once RxDMA is enabled by
283
+
software, THC will start auto-handling receiving logic.
284
+
285
+
For SPI mode, THC RxDMA sequence is: when Touch IC triggers a interrupt to THC, THC reads out
286
+
report header to identify what's the report type, and what's the report length, according to
287
+
above information, THC reads out report body to internal FIFO and start RxDMA coping the data
288
+
to system memory. After that, THC update interrupt cause register with report type, and update
289
+
RxDMA PRD table read pointer, then trigger a MSI interrupt to notify driver RxDMA finishing
290
+
data receiving.
291
+
292
+
For I2C mode, THC RxDMA's behavior is a little bit different, because of HIDI2C protocol difference
293
+
with HIDSPI protocol, RxDMA only be used to receive input report. The sequence is, when Touch IC
294
+
triggers a interrupt to THC, THC first reads out 2 bytes from input report address to determine the
295
+
packet length, then use this packet length to start a DMA reading from input report address for
296
+
input report data. After that, THC update RxDMA PRD table read pointer, then trigger a MSI interrupt
297
+
to notify driver input report data is ready in system memory.
298
+
299
+
All above sequence is hardware automatically handled, all driver needs to do is configure RxDMA and
300
+
waiting for interrupt ready then read out the data from system memory.
301
+
302
+
3.3.2 Software DMA channel
303
+
~~~~~~~~~~~~~~~~~~~~~~~~~~
304
+
305
+
THC supports a software triggerred RxDMA mode to read the touch data from touch IC. This SW RxDMA
306
+
is the 3rd THC RxDMA engine with the similar functionalities as the existing two RxDMAs, the only
307
+
difference is this SW RxDMA is triggerred by software, and RxDMA2 is triggerred by external Touch IC
308
+
interrupt. It gives a flexiblity to software driver to use RxDMA read Touch IC data in any time.
309
+
310
+
Before software starts a SW RxDMA, it shall stop the 1st and 2nd RxDMA, clear PRD read/write pointer
311
+
and quiesce the device interrupt (THC_DEVINT_QUIESCE_HW_STS = 1), other operations are the same with
312
+
RxDMA.
313
+
314
+
3.3.3 Write DMA Channel
315
+
~~~~~~~~~~~~~~~~~~~~~~~
316
+
317
+
THC has one write DMA engine, which can be used for sending data to Touch IC automatically.
318
+
According to HIDSPI and HIDI2C protocol, every time only one command can be sent to touch IC, and
319
+
before last command is completely handled, next command cannot be sent, THC write DMA engine only
320
+
supports single PRD table.
321
+
322
+
What driver needs to do is, preparing PRD table and DMA buffer, then copy data to DMA buffer and
323
+
update PRD table with buffer address and buffer length, then start write DMA. THC will
324
+
automatically send the data to touch IC, and trigger a DMA completion interrupt once transferring
325
+
is done.
326
+
327
+
3.4 PRD
328
+
-------
329
+
330
+
Physical Region Descriptor (PRD) provides the memory mapping description for THC DMAs.
331
+
332
+
3.4.1 PRD table and entry
333
+
~~~~~~~~~~~~~~~~~~~~~~~~~
334
+
335
+
In order to improve physical DMA memory usage, modern drivers trend to allocate a virtually
336
+
contiguous, but physically fragmented buffer of memory for each data buffer. Linux OS also
337
+
provide SGL (scatter gather list) APIs to support this usage.
338
+
339
+
THC uses PRD table (physical region descriptor) to support the corresponding OS kernel
340
+
SGL that describes the virtual to physical buffer mapping.
341
+
342
+
::
343
+
344
+
------------------------ -------------- --------------
345
+
| PRD table base address +----+ PRD table #1 +-----+ PRD Entry #1 |
346
+
------------------------ -------------- --------------
347
+
--------------
348
+
| PRD Entry #2 |
349
+
--------------
350
+
--------------
351
+
| PRD Entry #n |
352
+
--------------
353
+
354
+
The read DMA engine supports multiple PRD tables held within a circular buffer that allow the THC
355
+
to support multiple data buffers from the Touch IC. This allows host SW to arm the Read DMA engine
356
+
with multiple buffers, allowing the Touch IC to send multiple data frames to the THC without SW
357
+
interaction. This capability is required when the CPU processes touch frames slower than the
358
+
Touch IC can send them.
359
+
360
+
To simplify the design, SW assumes worst-case memory fragmentation. Therefore,each PRD table shall
361
+
contain the same number of PRD entries, allowing for a global register (per Touch IC) to hold the
362
+
number of PRD-entries per PRD table.
363
+
364
+
SW allocates up to 128 PRD tables per Read DMA engine as specified in the THC_M_PRT_RPRD_CNTRL.PCD
365
+
register field. The number of PRD tables should equal the number of data buffers.
366
+
367
+
Max OS memory fragmentation will be at a 4KB boundary, thus to address 1MB of virtually contiguous
368
+
memory 256 PRD entries are required for a single PRD Table. SW writes the number of PRD entries
369
+
for each PRD table in the THC_M_PRT_RPRD_CNTRL.PTEC register field. The PRD entry's length must be
370
+
multiple of 4KB except for the last entry in a PRD table.
371
+
372
+
SW allocates all the data buffers and PRD tables only once at host initialization.
373
+
374
+
3.4.2 PRD Write pointer and read pointer
375
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
376
+
377
+
As PRD tables are organized as a Circular Buffer (CB), a read pointer and a write pointer for a CB
378
+
are needed.
379
+
380
+
DMA HW consumes the PRD tables in the CB, one PRD entry at a time until the EOP bit is found set
381
+
in a PRD entry. At this point HW increments the PRD read pointer. Thus, the read pointer points
382
+
to the PRD which the DMA engine is currently processing. This pointer rolls over once the circular
383
+
buffer's depth has been traversed with bit[7] the Rollover bit. E.g. if the DMA CB depth is equal
384
+
to 4 entries (0011b), then the read pointers will follow this pattern (HW is required to honor
385
+
this behavior): 00h 01h 02h 03h 80h 81h 82h 83h 00h 01h ...
386
+
387
+
The write pointer is updated by SW. The write pointer points to location in the DMA CB, where the
388
+
next PRD table is going to be stored. SW needs to ensure that this pointer rolls over once the
389
+
circular buffer's depth has been traversed with Bit[7] as the rollover bit. E.g. if the DMA CB
390
+
depth is equal to 5 entries (0100b), then the write pointers will follow this pattern (SW is
391
+
required to honor this behavior): 00h 01h 02h 03h 04h 80h 81h 82h 83h 84h 00h 01h ..
392
+
393
+
3.4.3 PRD descriptor structure
394
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
395
+
396
+
Intel THC uses PRD entry descriptor for every PRD entry. Every PRD entry descriptor occupies
397
+
128 bits memories:
398
+
399
+
=================== ======== ===============================================
400
+
struct field bit(s) description
401
+
=================== ======== ===============================================
402
+
dest_addr 53..0 destination memory address, as every entry
403
+
is 4KB, ignore lowest 10 bits of address.
404
+
reserved1 54..62 reserved
405
+
int_on_completion 63 completion interrupt enable bit, if this bit
406
+
set it means THC will trigger a completion
407
+
interrupt. This bit is set by SW driver.
408
+
len 87..64 how many bytes of data in this entry.
409
+
end_of_prd 88 end of PRD table bit, if this bit is set,
410
+
it means this entry is last entry in this PRD
411
+
table. This bit is set by SW driver.
412
+
hw_status 90..89 HW status bits
413
+
reserved2 127..91 reserved
414
+
=================== ======== ===============================================
415
+
416
+
And one PRD table can include up to 256 PRD entries, as every entries is 4K bytes, so every
417
+
PRD table can describe 1M bytes memory.
418
+
419
+
.. code-block:: c
420
+
421
+
struct thc_prd_table {
422
+
struct thc_prd_entry entries[PRD_ENTRIES_NUM];
423
+
};
424
+
425
+
In general, every PRD table means one HID touch data packet. Every DMA engine can support
426
+
up to 128 PRD tables (except write DMA, write DMA only has one PRD table). SW driver is responsible
427
+
to get max packet length from touch IC, and use this max packet length to create PRD entries for
428
+
each PRD table.
429
+
430
+
4. HIDSPI support (QuickSPI)
431
+
============================
432
+
433
+
Intel THC is total compatible with HIDSPI protocol, THC HW sequenser can accelerate HIDSPI
434
+
protocol transferring.
435
+
436
+
4.1 Reset Flow
437
+
--------------
438
+
439
+
- Call ACPI _RST method to reset Touch IC device.
440
+
- Read the reset response from TIC through PIO read.
441
+
- Issue a command to retrieve device descriptor from Touch IC through PIO write.
442
+
- Read the device descriptor from Touch IC through PIO read.
443
+
- If the device descriptor is valid, allocate DMA buffers and configure all DMA channels.
444
+
- Issue a command to retrieve report descriptor from Touch IC through DMA.
445
+
446
+
4.2 Input Report Data Flow
447
+
--------------------------
448
+
449
+
Basic Flow:
450
+
451
+
- Touch IC interrupts the THC Controller using an in-band THC interrupt.
452
+
- THC Sequencer reads the input report header by transmitting read approval as a signal
453
+
to the Touch IC to prepare for host to read from the device.
454
+
- THC Sequencer executes a Input Report Body Read operation corresponding to the value
455
+
reflected in “Input Report Length” field of the Input Report Header.
456
+
- THC DMA engine begins fetching data from the THC Sequencer and writes to host memory
457
+
at PRD entry 0 for the current CB PRD table entry. This process continues until the
458
+
THC Sequencer signals all data has been read or the THC DMA Read Engine reaches the
459
+
end of it's last PRD entry (or both).
460
+
- The THC Sequencer checks for the “Last Fragment Flag” bit in the Input Report Header.
461
+
If it is clear, the THC Sequencer enters an idle state.
462
+
- If the “Last Fragment Flag” bit is enabled the THC Sequencer enters End-of-Frame Processing.
463
+
464
+
THC Sequencer End of Frame Processing:
465
+
466
+
- THC DMA engine increments the read pointer of the Read PRD CB, sets EOF interrupt status
467
+
in RxDMA2 register (THC_M_PRT_READ_DMA_INT_STS_2).
468
+
- If THC EOF interrupt is enabled by the driver in the control register (THC_M_PRT_READ_DMA_CNTRL_2),
469
+
generates interrupt to software.
470
+
471
+
Sequence of steps to read data from RX DMA buffer:
472
+
473
+
- THC QuickSPI driver checks CB write Ptr and CB read Ptr to identify if any data frame in DMA
474
+
circular buffers.
475
+
- THC QuickSPI driver gets first unprocessed PRD table.
476
+
- THC QuickSPI driver scans all PRD entries in this PRD table to calculate the total frame size.
477
+
- THC QuickSPI driver copies all frame data out.
478
+
- THC QuickSPI driver checks the data type according to input report body, and calls related
479
+
callbacks to process the data.
480
+
- THC QuickSPI driver updates write Ptr.
481
+
482
+
4.3 Output Report Data Flow
483
+
---------------------------
484
+
485
+
Generic Output Report Flow:
486
+
487
+
- HID core calls raw_request callback with a request to THC QuickSPI driver.
488
+
- THC QuickSPI Driver converts request provided data into the output report packet and copies it
489
+
to THC's write DMA buffer.
490
+
- Start TxDMA to complete the write operation.
491
+
492
+
5. HIDI2C support (QuickI2C)
493
+
============================
494
+
495
+
5.1 Reset Flow
496
+
--------------
497
+
498
+
- Read device descriptor from Touch IC device through PIO write followed by read.
499
+
- If the device descriptor is valid, allocate DMA buffers and configure all DMA channels.
500
+
- Use PIO or TxDMA to write a SET_POWER request to TIC's command register, and check if the
501
+
write operation is successfully completed.
502
+
- Use PIO or TxDMA to write a RESET request to TIC's command register. If the write operation
503
+
is successfully completed, wait for reset response from TIC.
504
+
- Use SWDMA to read report descriptor through TIC's report descriptor register.
505
+
506
+
5.2 Input Report Data Flow
507
+
--------------------------
508
+
509
+
Basic Flow:
510
+
511
+
- Touch IC asserts the interrupt indicating that it has an interrupt to send to HOST.
512
+
THC Sequencer issues a READ request over the I2C bus. The HIDI2C device returns the
513
+
first 2 bytes from the HIDI2C device which contains the length of the received data.
514
+
- THC Sequencer continues the Read operation as per the size of data indicated in the
515
+
length field.
516
+
- THC DMA engine begins fetching data from the THC Sequencer and writes to host memory
517
+
at PRD entry 0 for the current CB PRD table entry. THC writes 2Bytes for length field
518
+
plus the remaining data to RxDMA buffer. This process continues until the THC Sequencer
519
+
signals all data has been read or the THC DMA Read Engine reaches the end of it's last
520
+
PRD entry (or both).
521
+
- THC Sequencer enters End-of-Input Report Processing.
522
+
- If the device has no more input reports to send to the host, it de-asserts the interrupt
523
+
line. For any additional input reports, device keeps the interrupt line asserted and
524
+
steps 1 through 4 in the flow are repeated.
525
+
526
+
THC Sequencer End of Input Report Processing:
527
+
528
+
- THC DMA engine increments the read pointer of the Read PRD CB, sets EOF interrupt status
529
+
in RxDMA 2 register (THC_M_PRT_READ_DMA_INT_STS_2).
530
+
- If THC EOF interrupt is enabled by the driver in the control register
531
+
(THC_M_PRT_READ_DMA_CNTRL_2), generates interrupt to software.
532
+
533
+
Sequence of steps to read data from RX DMA buffer:
534
+
535
+
- THC QuickI2C driver checks CB write Ptr and CB read Ptr to identify if any data frame in DMA
536
+
circular buffers.
537
+
- THC QuickI2C driver gets first unprocessed PRD table.
538
+
- THC QuickI2C driver scans all PRD entries in this PRD table to calculate the total frame size.
539
+
- THC QuickI2C driver copies all frame data out.
540
+
- THC QuickI2C driver call hid_input_report to send the input report content to HID core, which
541
+
includes Report ID + Report Data Content (remove the length field from the original report
542
+
data).
543
+
- THC QuickI2C driver updates write Ptr.
544
+
545
+
5.3 Output Report Data Flow
546
+
---------------------------
547
+
548
+
Generic Output Report Flow:
549
+
550
+
- HID core call THC QuickI2C raw_request callback.
551
+
- THC QuickI2C uses PIO or TXDMA to write a SET_REPORT request to TIC's command register. Report
552
+
type in SET_REPORT should be set to Output.
553
+
- THC QuickI2C programs TxDMA buffer with TX Data to be written to TIC's data register. The first
554
+
2 bytes should indicate the length of the report followed by the report contents including
555
+
Report ID.
556
+
557
+
6. THC Debugging
558
+
================
559
+
560
+
To debug THC, event tracing mechanism is used. To enable debug logs::
561
+
562
+
echo 1 > /sys/kernel/debug/tracing/events/intel_thc/enable
563
+
cat /sys/kernel/debug/tracing/trace
564
+
565
+
7. Reference
566
+
============
567
+
- HIDSPI: https://download.microsoft.com/download/c/a/0/ca07aef3-3e10-4022-b1e9-c98cea99465d/HidSpiProtocolSpec.pdf
568
+
- HIDI2C: https://download.microsoft.com/download/7/d/d/7dd44bb7-2a7a-4505-ac1c-7227d3d96d5b/hid-over-i2c-protocol-spec-v1-0.docx