Lines Matching +full:write +full:- +full:to +full:- +full:read
1 .. SPDX-License-Identifier: GPL-2.0
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
14 It has a single root space IOSF Primary interface that supports transactions to/from touch devices.
16 bandwidth DMA services to the touch driver and transfers the HID report to host system main memory.
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).
29 -------------------------------
31 Below diagram illustrates the high-level architecture of THC software/hardware stack, which is fully
36 ----------------------------------------------
37 | +-----------------------------------+ |
39 | +-----------------------------------+ |
40 | +-----------------------------------+ |
41 | | HID Multi-touch Driver | |
42 | +-----------------------------------+ |
43 | +-----------------------------------+ |
45 | +-----------------------------------+ |
46 | +-----------------------------------+ |
48 | +-----------------------------------+ |
49 | +-----------------------------------+ |
51 | +-----------------------------------+ |
52 | +----------------+ +----------------+ |
54 | +----------------+ +----------------+ |
55 ----------------------------------------------
56 ----------------------------------------------
57 | +-----------------------------------+ |
59 | +-----------------------------------+ |
60 | +-----------------------------------+ |
62 | +-----------------------------------+ |
63 | +-----------------------------------+ |
65 | +-----------------------------------+ |
66 ----------------------------------------------
70 reports over the SPI/I2C bus to the THC Controller on the host.
76 accesses THC MMIO registers to configure and control THC hardware.
79 low-level driver that manages the THC Controller and implements HIDSPI/HIDI2C protocol.
83 ------------------------
86 ---------------------------------
88 | +---------------------------+ |
90 | +---------------------------+ |
91 | +---------------------------+ |
93 | +---------------------------+ |
94 +---------------+ | +------------+ +------------+ |
95 | System Memory +---+--+ DMA | | PIO | |
96 +---------------+ | +------------+ +------------+ |
97 | +---------------------------+ |
99 | +---------------------------+ |
100 | +------------+ +------------+ |
103 | +------------+ +------------+ |
104 ---------------------------------
109 MMIO Registers, which provide registers access for driver to configure and control THC hardware,
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.
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
122 the communication without driver involved, what driver needs to do is just configure the THC
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
133 ------------------
135 THC is exposed as "PCI Digitizer device" to the host. The PCI product and device IDs are
137 needs to update from generation to generation.
141 --------------------
148 When PORT_TYPE = 00b in MMIO registers, THC uses SPI interfaces to communicate with external
152 In Single IO mode, THC drives MOSI line to send data to Touch ICs, and receives data from Touch
156 also receives the data on those 4 lines. Driver needs to configure THC in different mode by
159 Beside IO mode, driver also needs to configure SPI bus speed. THC supports up to 42MHz SPI clock
162 For THC sending data to Touch IC, the data flow on SPI bus::
164 | --------------------THC sends---------------------------------|
169 | ---------THC Sends---------------||-----Touch IC sends--------|
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.
185 Interrupt line can be configured to either level triggered or edge triggered by setting MMIO
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.
192 --------------------------
194 This is a new feature introduced in Panther Lake platform, THC hardware allows driver to set
196 packet reading, THC hardware sequencer will first read incoming input packet size, then compare
199 - if input packet size <= max size, THC continues using input packet size to finish the reading
200 - if input packet size > max size, there is potential input data crash risk during
203 This feature is used to avoid data corruption which will cause RxDMA buffer overrun issue for
207 -------------------
209 Because of MCU performance limitation, some touch devices cannot de-assert interrupt pin
212 case, the delayed interrupt de-assertion will be recognized as a new interrupt signal by THC,
213 and causes THC to start an input report reading spuriously.
215 In order to avoid this situation, THC introduced interrupt delay new feature in Panther Lake
216 platform, where THC allows driver to set an interrupt delay. After this feature is enabled,
223 ----------
225 Opcode (operation code) is used to tell THC or Touch IC what the operation will be, such as PIO
226 read or PIO write.
228 When THC is configured to SPI mode, opcodes are used for determining the read/write IO mode.
234 0x0B Read Single I/O
235 0x02 Write Single I/O
236 0xBB Read Dual I/O
237 0xB2 Write Dual I/O
238 0xEB Read Quad I/O
239 0xE2 Write Quad I/O
242 In general, different touch IC has different OPCode definition. According to HIDSPI
243 protocol whitepaper, those OPCodes are defined in device ACPI table, and driver needs to
247 When THC is working in I2C mode, opcodes are used to tell THC what's the next PIO type:
248 I2C SubIP APB register read, I2C SubIP APB register write, I2C touch IC device read,
249 I2C touch IC device write, I2C touch IC device write followed by read.
251 Here are the THC pre-defined opcodes for I2C mode:
256 0x12 Read I2C SubIP APB internal registers 0h - FFh
257 0x13 Write I2C SubIP APB internal registers 0h - FFh
258 0x14 Read external Touch IC through I2C bus N/A
259 0x18 Write external Touch IC through I2C bus N/A
260 0x1C Write then read external Touch IC through I2C bus N/A
264 -------
266 THC provides a programmed I/O (PIO) access interface for the driver to access the touch IC's
267 configuration registers, or access I2C subIP's configuration registers. To use PIO to perform
268 I/O operations, driver should pre-program PIO control registers and PIO data registers and kick
269 off the sequencing cycle. THC uses different PIO opcodes to distinguish different PIO
270 operations (PIO read/write/write followed by read).
272 If there is a Sequencing Cycle In Progress and an attempt is made to program any of the control,
275 A status bit indicates when the cycle has completed allowing the driver to know when read results
276 can be checked and/or when to initiate a new command. If enabled, the cycle done assertion can
283 always in HID device descriptor which needs THC driver to read it out from HID Device (Touch IC).
284 So PIO typical use case is, before DMA initialization, write RESET command (PIO write), read
285 RESET response (PIO read or PIO write followed by read), write Power ON command (PIO write), read
286 device descriptor (PIO read).
288 For how to issue a PIO operation, here is the steps which driver needs follow:
290 - Program read/write data size in THC_SS_BC.
291 - Program I/O target address in THC_SW_SEQ_DATA0_ADDR.
292 - If write, program the write data in THC_SW_SEQ_DATA0..THC_SW_SEQ_DATAn.
293 - Program the PIO opcode in THC_SS_CMD.
294 - Set TSSGO = 1 to start the PIO write sequence.
295 - If THC_SS_CD_IE = 1, SW will receives a MSI when the PIO is completed.
296 - If read, read out the data in THC_SW_SEQ_DATA0..THC_SW_SEQ_DATAn.
299 -------
301 THC has 4 DMA channels: Read DMA1, Read DMA2, Write DMA and Software DMA.
303 3.3.1 Read DMA Channel
306 THC has two Read DMA engines: 1st RxDMA (RxDMA1) and 2nd RxDMA (RxDMA2). RxDMA1 is reserved for
311 software, THC will start auto-handling receiving logic.
313 For SPI mode, THC RxDMA sequence is: when Touch IC triggers a interrupt to THC, THC reads out
314 report header to identify what's the report type, and what's the report length, according to
315 above information, THC reads out report body to internal FIFO and start RxDMA coping the data
316 to system memory. After that, THC update interrupt cause register with report type, and update
317 RxDMA PRD table read pointer, then trigger a MSI interrupt to notify driver RxDMA finishing
321 with HIDSPI protocol, RxDMA only be used to receive input report. The sequence is, when Touch IC
322 triggers a interrupt to THC, THC first reads out 2 bytes from input report address to determine the
323 packet length, then use this packet length to start a DMA reading from input report address for
324 input report data. After that, THC update RxDMA PRD table read pointer, then trigger a MSI interrupt
325 to notify driver input report data is ready in system memory.
327 All above sequence is hardware automatically handled, all driver needs to do is configure RxDMA and
328 waiting for interrupt ready then read out the data from system memory.
333 THC supports a software triggered RxDMA mode to read the touch data from touch IC. This SW RxDMA
336 interrupt. It gives a flexibility to software driver to use RxDMA read Touch IC data in any time.
338 Before software starts a SW RxDMA, it shall stop the 1st and 2nd RxDMA, clear PRD read/write pointer
342 3.3.3 Write DMA Channel
345 THC has one write DMA engine, which can be used for sending data to Touch IC automatically.
346 According to HIDSPI and HIDI2C protocol, every time only one command can be sent to touch IC, and
347 before last command is completely handled, next command cannot be sent, THC write DMA engine only
350 What driver needs to do is, preparing PRD table and DMA buffer, then copy data to DMA buffer and
351 update PRD table with buffer address and buffer length, then start write DMA. THC will
352 automatically send the data to touch IC, and trigger a DMA completion interrupt once transferring
356 -------
363 In order to improve physical DMA memory usage, modern drivers trend to allocate a virtually
365 provide SGL (scatter gather list) APIs to support this usage.
367 THC uses PRD table (physical region descriptor) to support the corresponding OS kernel
368 SGL that describes the virtual to physical buffer mapping.
372 ------------------------ -------------- --------------
373 | PRD table base address +----+ PRD table #1 +-----+ PRD Entry #1 |
374 ------------------------ -------------- --------------
375 --------------
377 --------------
378 --------------
380 --------------
382 The read DMA engine supports multiple PRD tables held within a circular buffer that allow the THC
383 to support multiple data buffers from the Touch IC. This allows host SW to arm the Read DMA engine
384 with multiple buffers, allowing the Touch IC to send multiple data frames to the THC without SW
388 To simplify the design, SW assumes worst-case memory fragmentation. Therefore,each PRD table shall
389 contain the same number of PRD entries, allowing for a global register (per Touch IC) to hold the
390 number of PRD-entries per PRD table.
392 SW allocates up to 128 PRD tables per Read DMA engine as specified in the THC_M_PRT_RPRD_CNTRL.PCD
395 Max OS memory fragmentation will be at a 4KB boundary, thus to address 1MB of virtually contiguous
402 3.4.2 PRD Write pointer and read pointer
405 As PRD tables are organized as a Circular Buffer (CB), a read pointer and a write pointer for a CB
409 in a PRD entry. At this point HW increments the PRD read pointer. Thus, the read pointer points
410 to the PRD which the DMA engine is currently processing. This pointer rolls over once the circular
412 to 4 entries (0011b), then the read pointers will follow this pattern (HW is required to honor
415 The write pointer is updated by SW. The write pointer points to location in the DMA CB, where the
416 next PRD table is going to be stored. SW needs to ensure that this pointer rolls over once the
418 depth is equal to 5 entries (0100b), then the write pointers will follow this pattern (SW is
419 required to honor this behavior): 00h 01h 02h 03h 04h 80h 81h 82h 83h 84h 00h 01h ..
444 And one PRD table can include up to 256 PRD entries, as every entries is 4K bytes, so every
447 .. code-block:: c
454 up to 128 PRD tables (except write DMA, write DMA only has one PRD table). SW driver is responsible
455 to get max packet length from touch IC, and use this max packet length to create PRD entries for
465 --------------
467 - Call ACPI _RST method to reset Touch IC device.
468 - Read the reset response from TIC through PIO read.
469 - Issue a command to retrieve device descriptor from Touch IC through PIO write.
470 - Read the device descriptor from Touch IC through PIO read.
471 - If the device descriptor is valid, allocate DMA buffers and configure all DMA channels.
472 - Issue a command to retrieve report descriptor from Touch IC through DMA.
475 --------------------------
479 - Touch IC interrupts the THC Controller using an in-band THC interrupt.
480 - THC Sequencer reads the input report header by transmitting read approval as a signal
481 to the Touch IC to prepare for host to read from the device.
482 - THC Sequencer executes a Input Report Body Read operation corresponding to the value
484 - THC DMA engine begins fetching data from the THC Sequencer and writes to host memory
486 THC Sequencer signals all data has been read or the THC DMA Read Engine reaches the
488 - The THC Sequencer checks for the “Last Fragment Flag” bit in the Input Report Header.
490 - If the “Last Fragment Flag” bit is enabled the THC Sequencer enters End-of-Frame Processing.
494 - THC DMA engine increments the read pointer of the Read PRD CB, sets EOF interrupt status
496 - If THC EOF interrupt is enabled by the driver in the control register (THC_M_PRT_READ_DMA_CNTRL_2…
497 generates interrupt to software.
499 Sequence of steps to read data from RX DMA buffer:
501 - THC QuickSPI driver checks CB write Ptr and CB read Ptr to identify if any data frame in DMA
503 - THC QuickSPI driver gets first unprocessed PRD table.
504 - THC QuickSPI driver scans all PRD entries in this PRD table to calculate the total frame size.
505 - THC QuickSPI driver copies all frame data out.
506 - THC QuickSPI driver checks the data type according to input report body, and calls related
507 callbacks to process the data.
508 - THC QuickSPI driver updates write Ptr.
511 ---------------------------
515 - HID core calls raw_request callback with a request to THC QuickSPI driver.
516 - THC QuickSPI Driver converts request provided data into the output report packet and copies it
517 to THC's write DMA buffer.
518 - Start TxDMA to complete the write operation.
524 --------------
526 - Read device descriptor from Touch IC device through PIO write followed by read.
527 - If the device descriptor is valid, allocate DMA buffers and configure all DMA channels.
528 - Use PIO or TxDMA to write a SET_POWER request to TIC's command register, and check if the
529 write operation is successfully completed.
530 - Use PIO or TxDMA to write a RESET request to TIC's command register. If the write operation
532 - Use SWDMA to read report descriptor through TIC's report descriptor register.
535 --------------------------
539 - Touch IC asserts the interrupt indicating that it has an interrupt to send to HOST.
540 THC Sequencer issues a READ request over the I2C bus. The HIDI2C device returns the
542 - THC Sequencer continues the Read operation as per the size of data indicated in the
544 - THC DMA engine begins fetching data from the THC Sequencer and writes to host memory
546 plus the remaining data to RxDMA buffer. This process continues until the THC Sequencer
547 signals all data has been read or the THC DMA Read Engine reaches the end of it's last
549 - THC Sequencer enters End-of-Input Report Processing.
550 - If the device has no more input reports to send to the host, it de-asserts the interrupt
556 - THC DMA engine increments the read pointer of the Read PRD CB, sets EOF interrupt status
558 - If THC EOF interrupt is enabled by the driver in the control register
559 (THC_M_PRT_READ_DMA_CNTRL_2), generates interrupt to software.
561 Sequence of steps to read data from RX DMA buffer:
563 - THC QuickI2C driver checks CB write Ptr and CB read Ptr to identify if any data frame in DMA
565 - THC QuickI2C driver gets first unprocessed PRD table.
566 - THC QuickI2C driver scans all PRD entries in this PRD table to calculate the total frame size.
567 - THC QuickI2C driver copies all frame data out.
568 - THC QuickI2C driver call hid_input_report to send the input report content to HID core, which
571 - THC QuickI2C driver updates write Ptr.
574 ---------------------------
578 - HID core call THC QuickI2C raw_request callback.
579 - THC QuickI2C uses PIO or TXDMA to write a SET_REPORT request to TIC's command register. Report
580 type in SET_REPORT should be set to Output.
581 - THC QuickI2C programs TxDMA buffer with TX Data to be written to TIC's data register. The first
588 To debug THC, event tracing mechanism is used. To enable debug logs::
595 - HIDSPI: https://download.microsoft.com/download/c/a/0/ca07aef3-3e10-4022-b1e9-c98cea99465d/HidSpi…
596 - HIDI2C: https://download.microsoft.com/download/7/d/d/7dd44bb7-2a7a-4505-ac1c-7227d3d96d5b/hid-ov…