Documentation/hid/intel-thc-hid.rst

Source file repositories/reference/linux-study-clean/Documentation/hid/intel-thc-hid.rst

File Facts

System
Linux kernel
Corpus path
Documentation/hid/intel-thc-hid.rst
Extension
.rst
Size
29063 bytes
Lines
597
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

struct thc_prd_table {
        struct thc_prd_entry entries[PRD_ENTRIES_NUM];
   };

In general, every PRD table means one HID touch data packet. Every DMA engine can support
up to 128 PRD tables (except write DMA, write DMA only has one PRD table). SW driver is responsible
to get max packet length from touch IC, and use this max packet length to create PRD entries for
each PRD table.

4. HIDSPI support (QuickSPI)
============================

Intel THC is total compatible with HIDSPI protocol, THC HW sequenser can accelerate HIDSPI
protocol transferring.

4.1 Reset Flow
--------------

- Call ACPI _RST method to reset Touch IC device.
- Read the reset response from TIC through PIO read.
- Issue a command to retrieve device descriptor from Touch IC through PIO write.
- Read the device descriptor from Touch IC through PIO read.
- If the device descriptor is valid, allocate DMA buffers and configure all DMA channels.
- Issue a command to retrieve report descriptor from Touch IC through DMA.

4.2 Input Report Data Flow
--------------------------

Basic Flow:

- Touch IC interrupts the THC Controller using an in-band THC interrupt.
- THC Sequencer reads the input report header by transmitting read approval as a signal
  to the Touch IC to prepare for host to read from the device.
- THC Sequencer executes a Input Report Body Read operation corresponding to the value
  reflected in “Input Report Length” field of the Input Report Header.
- THC DMA engine begins fetching data from the THC Sequencer and writes to host memory
  at PRD entry 0 for the current CB PRD table entry. This process continues until the
  THC Sequencer signals all data has been read or the THC DMA Read Engine reaches the
  end of it's last PRD entry (or both).
- The THC Sequencer checks for the “Last Fragment Flag” bit in the Input Report Header.
  If it is clear, the THC Sequencer enters an idle state.
- If the “Last Fragment Flag” bit is enabled the THC Sequencer enters End-of-Frame Processing.

THC Sequencer End of Frame Processing:

- THC DMA engine increments the read pointer of the Read PRD CB, sets EOF interrupt status
  in RxDMA2 register (THC_M_PRT_READ_DMA_INT_STS_2).
- If THC EOF interrupt is enabled by the driver in the control register (THC_M_PRT_READ_DMA_CNTRL_2),
  generates interrupt to software.

Sequence of steps to read data from RX DMA buffer:

- THC QuickSPI driver checks CB write Ptr and CB read Ptr to identify if any data frame in DMA
  circular buffers.
- THC QuickSPI driver gets first unprocessed PRD table.
- THC QuickSPI driver scans all PRD entries in this PRD table to calculate the total frame size.
- THC QuickSPI driver copies all frame data out.
- THC QuickSPI driver checks the data type according to input report body, and calls related
  callbacks to process the data.
- THC QuickSPI driver updates write Ptr.

4.3 Output Report Data Flow
---------------------------

Generic Output Report Flow:

- HID core calls raw_request callback with a request to THC QuickSPI driver.
- THC QuickSPI Driver converts request provided data into the output report packet and copies it
  to THC's write DMA buffer.
- Start TxDMA to complete the write operation.

Annotation

Implementation Notes