Skip to contentSkip to conversation

Add Intel Touch Host Controller drivers

PATCH In review Even Xu 6 participants 34 messages Jan 6, 2025 – May 14, 2025

Subsystems (3)
lore
Share & tools
lore

Even Xu

author maintainer
#0 lore raw

v4 cover Add Intel Touch Host Controller drivers

Intel Touch Host Controller (THC) is a new high performance input IP which can benefit HID device's data transaction, such as touch screen, touch pad, stylus.

THC IP now evoluates to V4, it can support 3 different modes: IPTS, HIDSPI and HIDI2C. Here are upgrade history:
- THC v1, for TGL/LKF, supports intel private IPTS (Intel Precise Touch and Stylus) protocol ( IPTS mode)
- THC v2, for ADL, adds industrial standard HID over SPI protocol support (HIDSPI mode)
- THC v3, for MTL, enhances HID over SPI mode
- THC v4, for LNL, adds inudstrial standard HID over I2C protocol support (HIDI2C mode)

Linux Surface community (https://github.com/linux-surface) already implemented IPTS mode. These patch series provides THC HIDSPI mode and THC HIDI2C mode support on Linux.

These patch series includes:
1. Document for THC hardware and software introduction.
2. Intel THC Hardware layer driver which provides control interfaces for protocol layer.
3. Intel QuickSPI (R) driver working as a HIDSPI device driver which implements HID over SPI protocol and flow.
4. Intel QuickI2C (R) driver working as a HIDI2C device driver which implements HID over I2C protocol and flow.

Change logs:
v4:
- Minor fix in documents
- Typo fixes in patch 6 & patch 7 commit descriptions

v3:
- Change tables in documents from literal block to table format
- Change symbol namespace to string literal according to patch:
commit cdd30ebb1b9f ("module: Convert symbol namespace to string literal")
- Refine Kconfig description
- Enhance Quickspi and Quicki2c driver by clearing THC hardware internal state before doing initialization to avoid BIOS impacts.
- A fix in Quicki2c driver when does set_report

v2:
- Fix document format issues
- Add THC device IDs for Intel Panther Lake (PTL) platform

Even Xu (13):
HID: THC: Add documentation
HID: intel-thc-hid: intel-thc: Add THC DMA interfaces
HID: intel-thc-hid: intel-thc: Add THC I2C config interfaces
HID: intel-thc-hid: intel-quickspi: Add THC QuickSPI driver hid layer
HID: intel-thc-hid: intel-quickspi: Add THC QuickSPI ACPI interfaces
HID: intel-thc-hid: intel-quickspi: Add HIDSPI protocol implementation
HID: intel-thc-hid: intel-quickspi: Add PM implementation
HID: intel-thc-hid: intel-quicki2c: Add THC QuickI2C driver skeleton
HID: intel-thc-hid: intel-quicki2c: Add THC QuickI2C driver hid layer
HID: intel-thc-hid: intel-quicki2c: Add THC QuickI2C ACPI interfaces
HID: intel-thc-hid: intel-quicki2c: Add HIDI2C protocol implementation
HID: intel-thc-hid: intel-quicki2c: Complete THC QuickI2C driver
HID: intel-thc-hid: intel-quicki2c: Add PM implementation

Xinpeng Sun (9):
HID: intel-thc-hid: Add basic THC driver skeleton
HID: intel-thc-hid: intel-thc: Add THC registers definition
HID: intel-thc-hid: intel-thc: Add THC PIO operation APIs
HID: intel-thc-hid: intel-thc: Add APIs for interrupt
HID: intel-thc-hid: intel-thc: Add THC LTR interfaces
HID: intel-thc-hid: intel-thc: Add THC interrupt handler
HID: intel-thc-hid: intel-thc: Add THC SPI config interfaces
HID: intel-thc-hid: intel-quickspi: Add THC QuickSPI driver skeleton
HID: intel-thc-hid: intel-quickspi: Complete THC QuickSPI driver

 Documentation/hid/index.rst                   |    1 +
 Documentation/hid/intel-thc-hid.rst           |  568 ++++++
 MAINTAINERS                                   |    6 +
 drivers/hid/Kconfig                           |    2 +
 drivers/hid/Makefile                          |    2 +
 drivers/hid/intel-thc-hid/Kconfig             |   42 +
 drivers/hid/intel-thc-hid/Makefile            |   22 +
 .../intel-quicki2c/pci-quicki2c.c             |  966 ++++++++++
 .../intel-quicki2c/quicki2c-dev.h             |  186 ++
 .../intel-quicki2c/quicki2c-hid.c             |  166 ++
 .../intel-quicki2c/quicki2c-hid.h             |   14 +
 .../intel-quicki2c/quicki2c-protocol.c        |  224 +++
 .../intel-quicki2c/quicki2c-protocol.h        |   20 +
 .../intel-quickspi/pci-quickspi.c             |  987 +++++++++++
 .../intel-quickspi/quickspi-dev.h             |  172 ++
 .../intel-quickspi/quickspi-hid.c             |  165 ++
 .../intel-quickspi/quickspi-hid.h             |   14 +
 .../intel-quickspi/quickspi-protocol.c        |  414 +++++
 .../intel-quickspi/quickspi-protocol.h        |   25 +
 .../intel-thc-hid/intel-thc/intel-thc-dev.c   | 1578 +++++++++++++++++
 .../intel-thc-hid/intel-thc/intel-thc-dev.h   |  116 ++
 .../intel-thc-hid/intel-thc/intel-thc-dma.c   |  969 ++++++++++
 .../intel-thc-hid/intel-thc/intel-thc-dma.h   |  146 ++
 .../intel-thc-hid/intel-thc/intel-thc-hw.h    |  881 +++++++++
 include/linux/hid-over-i2c.h                  |  117 ++
 include/linux/hid-over-spi.h                  |  155 ++
 26 files changed, 7958 insertions(+)
 create mode 100644 Documentation/hid/intel-thc-hid.rst
 create mode 100644 drivers/hid/intel-thc-hid/Kconfig
 create mode 100644 drivers/hid/intel-thc-hid/Makefile
 create mode 100644 drivers/hid/intel-thc-hid/intel-quicki2c/pci-quicki2c.c
 create mode 100644 drivers/hid/intel-thc-hid/intel-quicki2c/quicki2c-dev.h
 create mode 100644 drivers/hid/intel-thc-hid/intel-quicki2c/quicki2c-hid.c
 create mode 100644 drivers/hid/intel-thc-hid/intel-quicki2c/quicki2c-hid.h
 create mode 100644 drivers/hid/intel-thc-hid/intel-quicki2c/quicki2c-protocol.c
 create mode 100644 drivers/hid/intel-thc-hid/intel-quicki2c/quicki2c-protocol.h
 create mode 100644 drivers/hid/intel-thc-hid/intel-quickspi/pci-quickspi.c
 create mode 100644 drivers/hid/intel-thc-hid/intel-quickspi/quickspi-dev.h
 create mode 100644 drivers/hid/intel-thc-hid/intel-quickspi/quickspi-hid.c
 create mode 100644 drivers/hid/intel-thc-hid/intel-quickspi/quickspi-hid.h
 create mode 100644 drivers/hid/intel-thc-hid/intel-quickspi/quickspi-protocol.c
 create mode 100644 drivers/hid/intel-thc-hid/intel-quickspi/quickspi-protocol.h
 create mode 100644 drivers/hid/intel-thc-hid/intel-thc/intel-thc-dev.c
 create mode 100644 drivers/hid/intel-thc-hid/intel-thc/intel-thc-dev.h
 create mode 100644 drivers/hid/intel-thc-hid/intel-thc/intel-thc-dma.c
 create mode 100644 drivers/hid/intel-thc-hid/intel-thc/intel-thc-dma.h
 create mode 100644 drivers/hid/intel-thc-hid/intel-thc/intel-thc-hw.h
 create mode 100644 include/linux/hid-over-i2c.h
 create mode 100644 include/linux/hid-over-spi.h
Signature · 1 line
2.40.1
author maintainer
#1 lore raw

PATCH v4 1/22 HID: THC: Add documentation

Add Documentation/hid/intel-thc-hid.rst file to provide hardware and software detail for intel THC drivers.

---
 Documentation/hid/index.rst         |   1 +
 Documentation/hid/intel-thc-hid.rst | 568 ++++++++++++++++++++++++++++
 2 files changed, 569 insertions(+)
 create mode 100644 Documentation/hid/intel-thc-hid.rst
Documentation/hid/index.rst +1 -0
index af02cf7cfa82..baf156b44b58 100644
@@ -18,4 +18,5 @@ Human Interface Devices (HID)
 
    hid-alps
    intel-ish-hid
+   intel-thc-hid
    amd-sfh-hid
Documentation/hid/intel-thc-hid.rst new file +568 -0

568 lines not on this page · raw message

Signature · 1 line
2.40.1
#2 lore raw

Re: [PATCH v4 01/22] HID: THC: Add documentation

Quoted 11 lines · Even Xu

Add Documentation/hid/intel-thc-hid.rst file to provide hardware and software detail for intel THC drivers.

Reviewed-by Srinivas Pandruvada

<[email protected]>

---

Change logs are missing?
Also didn't receive any cover letter with any changes?

Thanks,
Srinivas

Quoted 789 lines

 Documentation/hid/index.rst         |   1 +
 Documentation/hid/intel-thc-hid.rst | 568
++++++++++++++++++++++++++++

 2 files changed, 569 insertions(+)

 create mode 100644 Documentation/hid/intel-thc-hid.rst

Documentation/hid/index.rst +0 -0
index af02cf7cfa82..baf156b44b58 100644
@@ -18,4 +18,5 @@ Human Interface Devices (HID)


    hid-alps
    intel-ish-hid
+   intel-thc-hid
    amd-sfh-hid

Documentation/hid/intel-thc-hid.rst new file +7 -0
new file mode 100644
index 000000000000..6c417205ac6a
@@ -0,0 +1,568 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=================================
+Intel Touch Host Controller (THC)
+=================================
+
+Touch Host Controller is the name of the IP block in PCH that

interface with Touch Devices (ex:
+touchscreen, touchpad etc.). It is comprised of 3 key functional blocks:

Documentation/hid/intel-thc-hid.rst new file +6 -0
+
+- A natively half-duplex Quad I/O capable SPI master
+- Low latency I2C interface to support HIDI2C compliant devices
+- A HW sequencer with RW DMA capability to system memory
+
+It has a single root space IOSF Primary interface that supports

transactions to/from touch devices.
+Host driver configures and controls the touch devices over THC interface. THC provides high
+bandwidth DMA services to the touch driver and transfers the HID report to host system main memory.

Documentation/hid/intel-thc-hid.rst new file +2 -0
+
+Hardware sequencer within the THC is responsible for transferring

(via DMA) data from touch devices
+into system memory. A ring buffer is used to avoid data loss due to asynchronous nature of data
+consumption (by host) in relation to data production (by touch device via DMA).

Documentation/hid/intel-thc-hid.rst new file +2 -0
+
+Unlike other common SPI/I2C controllers, THC handles the HID device

data interrupt and reset

Documentation/hid/intel-thc-hid.rst new file +9 -0
+signals directly.
+
+1. Overview
+===========
+
+1.1 THC software/hardware stack
+-------------------------------
+
+Below diagram illustrates the high-level architecture of THC

software/hardware stack, which is fully

Documentation/hid/intel-thc-hid.rst new file +37 -0
+capable of supporting HIDSPI/HIDI2C protocol in Linux OS.
+
+::
+
+  ----------------------------------------------
+ |      +-----------------------------------+   |
+ |      |           Input Device            |   |
+ |      +-----------------------------------+   |
+ |      +-----------------------------------+   |
+ |      |       HID Multi-touch Driver      |   |
+ |      +-----------------------------------+   |
+ |      +-----------------------------------+   |
+ |      |             HID Core              |   |
+ |      +-----------------------------------+   |
+ |      +-----------------------------------+   |
+ |      |    THC QuickSPI/QuickI2C Driver   |   |
+ |      +-----------------------------------+   |
+ |      +-----------------------------------+   |
+ |      |      THC Hardware Driver          |   |
+ |      +-----------------------------------+   |
+ |      +----------------+ +----------------+   |
+ |  SW  | PCI Bus Driver | | ACPI Resource  |   |
+ |      +----------------+ +----------------+   |
+  ----------------------------------------------
+  ----------------------------------------------
+ |      +-----------------------------------+   |
+ |  HW  |              PCI Bus              |   |
+ |      +-----------------------------------+   |
+ |      +-----------------------------------+   |
+ |      |           THC Controller          |   |
+ |      +-----------------------------------+   |
+ |      +-----------------------------------+   |
+ |      |              Touch IC             |   |
+ |      +-----------------------------------+   |
+  ----------------------------------------------
+
+Touch IC (TIC), also as known as the Touch devices (touchscreen or

touchpad). The discrete analog
+components that sense and transfer either discrete touch data or heatmap data in the form of HID

Documentation/hid/intel-thc-hid.rst new file +3 -0
+reports over the SPI/I2C bus to the THC Controller on the host.
+
+THC Host Controller, which is a PCI device HBA (host bus adapter),

integrated into the PCH, that

Documentation/hid/intel-thc-hid.rst new file +3 -0
+serves as a bridge between the Touch ICs and the host.
+
+THC Hardware Driver, provides THC hardware operation APIs for above

QuickSPI/QuickI2C driver, it

Documentation/hid/intel-thc-hid.rst new file +3 -0
+accesses THC MMIO registers to configure and control THC hardware.
+
+THC QuickSPI/QuickI2C driver, also as known as HIDSPI/HIDI2C driver,

is registered as a HID
+low-level driver that manages the THC Controller and implements HIDSPI/HIDI2C protocol.

Documentation/hid/intel-thc-hid.rst new file +27 -0
+
+
+1.2 THC hardware diagram
+------------------------
+Below diagram shows THC hardware components::
+
+                      ---------------------------------
+                     |          THC Controller         |
+                     |  +---------------------------+  |
+                     |  |     PCI Config Space      |  |
+                     |  +---------------------------+  |
+                     |  +---------------------------+  |
+                     |  +       MMIO Registers      |  |
+                     |  +---------------------------+  |
+ +---------------+   |  +------------+ +------------+  |
+ | System Memory +---+--+      DMA   | |   PIO      |  |
+ +---------------+   |  +------------+ +------------+  |
+                     |  +---------------------------+  |
+                     |  |       HW Sequencer        |  |
+                     |  +---------------------------+  |
+                     |  +------------+ +------------+  |
+                     |  |  SPI/I2C   | |    GPIO    |  |
+                     |  | Controller | | Controller |  |
+                     |  +------------+ +------------+  |
+                      ---------------------------------
+
+As THC is exposed as a PCI devices, so it has standard PCI config

space registers for PCI

Documentation/hid/intel-thc-hid.rst new file +3 -0
+enumeration and configuration.
+
+MMIO Registers, which provide registers access for driver to

configure and control THC hardware,
+the registers include several categories: Interrupt status and control, DMA configure,
+PIO (Programmed I/O, defined in section 3.2) status and control, SPI bus configure, I2C subIP

Documentation/hid/intel-thc-hid.rst new file +3 -0
+status and control, reset status and control...
+
+THC provides two ways for driver to communicate with external Touch

ICs: PIO and DMA.
+PIO can let driver manually write/read data to/from Touch ICs, instead, THC DMA can

Documentation/hid/intel-thc-hid.rst new file +3 -0
+automatically write/read data without driver involved.
+
+HW Sequencer includes THC major logic, it gets instruction from MMIO

registers to control
+SPI bus and I2C bus to finish a bus data transaction, it also can automatically handle
+Touch ICs interrupt and start DMA receive/send data from/to Touch ICs according to interrupt
+type. That means THC HW Sequencer understands HIDSPI/HIDI2C transfer protocol, and handle
+the communication without driver involved, what driver needs to do is just configure the THC
+properly, and prepare the formatted data packet or handle received data packet.

Documentation/hid/intel-thc-hid.rst new file +2 -0
+
+As THC supports HIDSPI/HIDI2C protocols, it has SPI controller and

I2C subIP in it to expose
+SPI bus and I2C bus. THC also integrates a GPIO controller to provide interrupt line support

Documentation/hid/intel-thc-hid.rst new file +9 -0
+and reset line support.
+
+2. THC Hardware Interface
+=========================
+
+2.1 Host Interface
+------------------
+
+THC is exposed as "PCI Digitizer device" to the host. The PCI

product and device IDs are
+changed from different generations of processors. So the source code which enumerates drivers

Documentation/hid/intel-thc-hid.rst new file +7 -0
+needs to update from generation to generation.
+
+
+2.2 Device Interface
+--------------------
+
+THC supports two types of bus for Touch IC connection: Enhanced SPI

bus and I2C bus.

Documentation/hid/intel-thc-hid.rst new file +5 -0
+
+2.2.1 SPI Port
+~~~~~~~~~~~~~~
+
+When PORT_TYPE = 00b in MMIO registers, THC uses SPI interfaces to

communicate with external
+Touch IC. THC enhanced SPI Bus supports different SPI modes:
standard Single IO mode,

Documentation/hid/intel-thc-hid.rst new file +3 -0
+Dual IO mode and Quad IO mode.
+
+In Single IO mode, THC drives MOSI line to send data to Touch ICs,

and receives data from Touch
+ICs data from MISO line. In Dual IO mode, THC drivers MOSI and MISO both for data sending, and
+also receives the data on both line. In Quad IO mode, there are other two lines (IO2 and IO3)
+are added, THC drives MOSI (IO0), MISO (IO1), IO2 and IO3 at the same time for data sending, and
+also receives the data on those 4 lines. Driver needs to configure THC in different mode by

Documentation/hid/intel-thc-hid.rst new file +3 -0
+setting different opcode.
+
+Beside IO mode, driver also needs to configure SPI bus speed. THC

supports up to 42MHz SPI clock

Documentation/hid/intel-thc-hid.rst new file +16 -0
+on Intel Lunar Lake platform.
+
+For THC sending data to Touch IC, the data flow on SPI bus::
+
+ | --------------------THC sends---------------------------------|
+ <8Bits OPCode><24Bits Slave Address><Data><Data><Data>...........
+
+For THC receiving data from Touch IC, the data flow on SPI bus::
+
+ | ---------THC Sends---------------||-----Touch IC sends--------|
+ <8Bits OPCode><24Bits Slave Address><Data><Data><Data>...........
+
+2.2.2 I2C Port
+~~~~~~~~~~~~~~
+
+THC also integrates I2C controller in it, it's called I2C SubSystem.

When PORT_TYPE = 01, THC
+is configured to I2C mode. Comparing to SPI mode which can be configured through MMIO registers
+directly, THC needs to use PIO read (by setting SubIP read opcode) to I2C subIP APB registers'
+value and use PIO write (by setting SubIP write opcode) to do a write operation.

Documentation/hid/intel-thc-hid.rst new file +5 -0
+
+2.2.3 GPIO interface
+~~~~~~~~~~~~~~~~~~~~
+
+THC also includes two GPIO pins, one for interrupt and the other for

device reset control.

Documentation/hid/intel-thc-hid.rst new file +2 -0
+
+Interrupt line can be configured to either level triggerred or edge

triggerred by setting MMIO

Documentation/hid/intel-thc-hid.rst new file +3 -0
+Control register.
+
+Reset line is controlled by BIOS (or EFI) through ACPI _RST method,

driver needs to call this

Documentation/hid/intel-thc-hid.rst new file +9 -0
+device ACPI _RST method to reset touch IC during initialization.
+
+3. High level concept
+=====================
+
+3.1 Opcode
+----------
+
+Opcode (operation code) is used to tell THC or Touch IC what the

operation will be, such as PIO

Documentation/hid/intel-thc-hid.rst new file +3 -0
+read or PIO write.
+
+When THC is configured to SPI mode, opcodes are used for determining

the read/write IO mode.

Documentation/hid/intel-thc-hid.rst new file +14 -0
+There are some OPCode examples for SPI IO mode:
+
+=======   ==============================
+opcode    Corresponding SPI command
+=======   ==============================
+0x0B      Read Single I/O
+0x02      Write Single I/O
+0xBB      Read Dual I/O
+0xB2      Write Dual I/O
+0xEB      Read Quad I/O
+0xE2      Write Quad I/O
+=======   ==============================
+
+In general, different touch IC has different OPCode definition.

According to HIDSPI
+protocol whitepaper, those OPCodes are defined in device ACPI table, and driver needs to
+query those information through OS ACPI APIs during driver initialization, then configures

Documentation/hid/intel-thc-hid.rst new file +3 -0
+THC MMIO OPCode registers with correct setting.
+
+When THC is working in I2C mode, opcodes are used to tell THC what's

the next PIO type:
+I2C SubIP APB register read, I2C SubIP APB register write, I2C touch IC device read,
+I2C touch IC device write, I2C touch IC device write followed by read.

Documentation/hid/intel-thc-hid.rst new file +4 -0
+
+Here are the THC pre-defined opcodes for I2C mode:
+
+=======   ===================================================  

===========
+opcode    Corresponding I2C command
Address
+=======   ===================================================
===========
+0x12      Read I2C SubIP APB internal registers                 0h - FFh
+0x13      Write I2C SubIP APB internal registers                0h - FFh
+0x14      Read external Touch IC through I2C bus                N/A +0x18      Write external Touch IC through I2C bus               N/A +0x1C      Write then read external Touch IC through I2C bus     N/A +=======   ===================================================
===========

Documentation/hid/intel-thc-hid.rst new file +5 -0
+
+3.2 PIO
+-------
+
+THC provides a programmed I/O (PIO) access interface for the driver

to access the touch IC's
+configuration registers, or access I2C subIP's configuration registers. To use PIO to perform
+I/O operations, driver should pre-program PIO control registers and PIO data registers and kick
+off the sequencing cycle. THC uses different PIO opcodes to distinguish different PIO

Documentation/hid/intel-thc-hid.rst new file +3 -0
+operations (PIO read/write/write followed by read).
+
+If there is a Sequencing Cycle In Progress and an attempt is made to

program any of the control,
+address, or data register the cycle is blocked and a sequence error will be encountered.

Documentation/hid/intel-thc-hid.rst new file +2 -0
+
+A status bit indicates when the cycle has completed allowing the

driver to know when read results
+can be checked and/or when to initiate a new command. If enabled, the cycle done assertion can

Documentation/hid/intel-thc-hid.rst new file +3 -0
+interrupt driver with an interrupt.
+
+Because THC only has 16 FIFO registers for PIO, so all the data

transfer through PIO shouldn't

Documentation/hid/intel-thc-hid.rst new file +3 -0
+exceed 64 bytes.
+
+As DMA needs max packet size for transferring configuration, and the

max packet size information
+always in HID device descriptor which needs THC driver to read it out from HID Device (Touch IC).
+So PIO typical use case is, before DMA initialization, write RESET command (PIO write), read
+RESET response (PIO read or PIO write followed by read), write Power ON command (PIO write), read

Documentation/hid/intel-thc-hid.rst new file +3 -0
+device descriptor (PIO read).
+
+For how to issue a PIO operation, here is the steps which driver

needs follow:
+

+- Program read/write data size in THC_SS_BC.
+- Program I/O target address in THC_SW_SEQ_DATA0_ADDR.
+- If write, program the write data in
THC_SW_SEQ_DATA0..THC_SW_SEQ_DATAn.
+- Program the PIO opcode in THC_SS_CMD.
+- Set TSSGO = 1 to start the PIO write sequence.
+- If THC_SS_CD_IE = 1, SW will receives a MSI when the PIO is

completed.
+- If read, read out the data in THC_SW_SEQ_DATA0..THC_SW_SEQ_DATAn.

Documentation/hid/intel-thc-hid.rst new file +5 -0
+
+3.3 DMA
+-------
+
+THC has 4 DMA channels: Read DMA1, Read DMA2, Write DMA and Software

DMA.

Documentation/hid/intel-thc-hid.rst new file +5 -0
+
+3.3.1 Read DMA Channel
+~~~~~~~~~~~~~~~~~~~~~~
+
+THC has two Read DMA engines: 1st RxDMA (RxDMA1) and 2nd RxDMA

(RxDMA2). RxDMA1 is reserved for
+raw data mode. RxDMA2 is used for HID data mode and it is the RxDMA engine currently driver uses

Documentation/hid/intel-thc-hid.rst new file +3 -0
+for HID input report data retrieval.
+
+RxDMA's typical use case is auto receiving the data from Touch IC.

Once RxDMA is enabled by

Documentation/hid/intel-thc-hid.rst new file +3 -0
+software, THC will start auto-handling receiving logic.
+
+For SPI mode, THC RxDMA sequence is: when Touch IC triggers a

interrupt to THC, THC reads out
+report header to identify what's the report type, and what's the report length, according to
+above information, THC reads out report body to internal FIFO and start RxDMA coping the data
+to system memory. After that, THC update interrupt cause register with report type, and update
+RxDMA PRD table read pointer, then trigger a MSI interrupt to notify driver RxDMA finishing

Documentation/hid/intel-thc-hid.rst new file +3 -0
+data receiving.
+
+For I2C mode, THC RxDMA's behavior is a little bit different,

because of HIDI2C protocol difference
+with HIDSPI protocol, RxDMA only be used to receive input report. The sequence is, when Touch IC
+triggers a interrupt to THC, THC first reads out 2 bytes from input report address to determine the
+packet length, then use this packet length to start a DMA reading from input report address for
+input report data. After that, THC update RxDMA PRD table read pointer, then trigger a MSI interrupt

Documentation/hid/intel-thc-hid.rst new file +3 -0
+to notify driver input report data is ready in system memory.
+
+All above sequence is hardware automatically handled, all driver

needs to do is configure RxDMA and
+waiting for interrupt ready then read out the data from system memory.

Documentation/hid/intel-thc-hid.rst new file +5 -0
+
+3.3.2 Software DMA channel
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+THC supports a software triggerred RxDMA mode to read the touch data

from touch IC. This SW RxDMA
+is the 3rd THC RxDMA engine with the similar functionalities as the existing two RxDMAs, the only
+difference is this SW RxDMA is triggerred by software, and RxDMA2 is triggerred by external Touch IC
+interrupt. It gives a flexiblity to software driver to use RxDMA read Touch IC data in any time.

Documentation/hid/intel-thc-hid.rst new file +2 -0
+
+Before software starts a SW RxDMA, it shall stop the 1st and 2nd

RxDMA, clear PRD read/write pointer
+and quiesce the device interrupt (THC_DEVINT_QUIESCE_HW_STS = 1), other operations are the same with

Documentation/hid/intel-thc-hid.rst new file +6 -0
+RxDMA.
+
+3.3.3 Write DMA Channel
+~~~~~~~~~~~~~~~~~~~~~~~
+
+THC has one write DMA engine, which can be used for sending data to

Touch IC automatically.
+According to HIDSPI and HIDI2C protocol, every time only one command can be sent to touch IC, and
+before last command is completely handled, next command cannot be sent, THC write DMA engine only

Documentation/hid/intel-thc-hid.rst new file +3 -0
+supports single PRD table.
+
+What driver needs to do is, preparing PRD table and DMA buffer, then

copy data to DMA buffer and
+update PRD table with buffer address and buffer length, then start write DMA. THC will
+automatically send the data to touch IC, and trigger a DMA completion interrupt once transferring

Documentation/hid/intel-thc-hid.rst new file +6 -0
+is done.
+
+3.4 PRD
+-------
+
+Physical Region Descriptor (PRD) provides the memory mapping

description for THC DMAs.

Documentation/hid/intel-thc-hid.rst new file +5 -0
+
+3.4.1 PRD table and entry
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In order to improve physical DMA memory usage, modern drivers trend

to allocate a virtually
+contiguous, but physically fragmented buffer of memory for each data buffer. Linux OS also

Documentation/hid/intel-thc-hid.rst new file +3 -0
+provide SGL (scatter gather list) APIs to support this usage.
+
+THC uses PRD table (physical region descriptor) to support the

corresponding OS kernel

Documentation/hid/intel-thc-hid.rst new file +15 -0
+SGL that describes the virtual to physical buffer mapping.
+
+::
+
+  ------------------------      --------------       --------------
+ | PRD table base address +----+ PRD table #1 +-----+ PRD Entry #1 |
+  ------------------------      --------------       --------------
+                                                     --------------
+                                                    | PRD Entry #2 |
+                                                     --------------
+                                                     --------------
+                                                    | PRD Entry #n |
+                                                     --------------
+
+The read DMA engine supports multiple PRD tables held within a

circular buffer that allow the THC
+to support multiple data buffers from the Touch IC. This allows host SW to arm the Read DMA engine
+with multiple buffers, allowing the Touch IC to send multiple data frames to the THC without SW
+interaction. This capability is required when the CPU processes touch frames slower than the

Documentation/hid/intel-thc-hid.rst new file +3 -0
+Touch IC can send them.
+
+To simplify the design, SW assumes worst-case memory fragmentation.

Therefore,each PRD table shall
+contain the same number of PRD entries, allowing for a global register (per Touch IC) to hold the

Documentation/hid/intel-thc-hid.rst new file +3 -0
+number of PRD-entries per PRD table.
+
+SW allocates up to 128 PRD tables per Read DMA engine as specified

in the THC_M_PRT_RPRD_CNTRL.PCD
+register field. The number of PRD tables should equal the number of data buffers.

Documentation/hid/intel-thc-hid.rst new file +2 -0
+
+Max OS memory fragmentation will be at a 4KB boundary, thus to

address 1MB of virtually contiguous
+memory 256 PRD entries are required for a single PRD Table. SW writes the number of PRD entries
+for each PRD table in the THC_M_PRT_RPRD_CNTRL.PTEC register field. The PRD entry's length must be

Documentation/hid/intel-thc-hid.rst new file +3 -0
+multiple of 4KB except for the last entry in a PRD table.
+
+SW allocates all the data buffers and PRD tables only once at host

initialization.

Documentation/hid/intel-thc-hid.rst new file +5 -0
+
+3.4.2 PRD Write pointer and read pointer
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+As PRD tables are organized as a Circular Buffer (CB), a read

pointer and a write pointer for a CB

Documentation/hid/intel-thc-hid.rst new file +3 -0
+are needed.
+
+DMA HW consumes the PRD tables in the CB, one PRD entry at a time

until the EOP bit is found set
+in a PRD entry. At this point HW increments the PRD read pointer. Thus, the read pointer points
+to the PRD which the DMA engine is currently processing. This pointer rolls over once the circular
+buffer's depth has been traversed with bit[7] the Rollover bit. E.g. if the DMA CB depth is equal
+to 4 entries (0011b), then the read pointers will follow this pattern (HW is required to honor

Documentation/hid/intel-thc-hid.rst new file +3 -0
+this behavior): 00h 01h 02h 03h 80h 81h 82h 83h 00h 01h ...
+
+The write pointer is updated by SW. The write pointer points to

location in the DMA CB, where the
+next PRD table is going to be stored. SW needs to ensure that this pointer rolls over once the
+circular buffer's depth has been traversed with Bit[7] as the rollover bit. E.g. if the DMA CB
+depth is equal to 5 entries (0100b), then the write pointers will follow this pattern (SW is
+required to honor this behavior): 00h 01h 02h 03h 04h 80h 81h 82h 83h 84h 00h 01h ..

Documentation/hid/intel-thc-hid.rst new file +5 -0
+
+3.4.3 PRD descriptor structure
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Intel THC uses PRD entry descriptor for every PRD entry. Every PRD

entry descriptor occupies
+128 bits memories:
+
+===================   ========
===============================================
+struct field          bit(s)     description +===================   ========
===============================================
+dest_addr             53..0      destination memory address, as every entry
+                                 is 4KB, ignore lowest 10 bits of address.

Documentation/hid/intel-thc-hid.rst new file +2 -0
+reserved1             54..62     reserved
+int_on_completion     63         completion interrupt enable bit, if

this bit
+                                 set it means THC will trigger a completion
+                                 interrupt. This bit is set by SW driver.
+len                   87..64     how many bytes of data in this entry.
+end_of_prd            88         end of PRD table bit, if this bit is set,
+                                 it means this entry is last entry in this PRD
+                                 table. This bit is set by SW driver.

Documentation/hid/intel-thc-hid.rst new file +3 -0
+hw_status             90..89     HW status bits
+reserved2             127..91    reserved
+===================   ========  

===============================================

Documentation/hid/intel-thc-hid.rst new file +2 -0
+
+And one PRD table can include up to 256 PRD entries, as every

entries is 4K bytes, so every

Documentation/hid/intel-thc-hid.rst new file +9 -0
+PRD table can describe 1M bytes memory.
+
+.. code-block:: c
+
+   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

Documentation/hid/intel-thc-hid.rst new file +6 -0
+each PRD table.
+
+4. HIDSPI support (QuickSPI)
+============================
+
+Intel THC is total compatible with HIDSPI protocol, THC HW sequenser

can accelerate HIDSPI

Documentation/hid/intel-thc-hid.rst new file +8 -0
+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.

Documentation/hid/intel-thc-hid.rst new file +7 -0
+
+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.

Documentation/hid/intel-thc-hid.rst new file +4 -0
+
+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.

Documentation/hid/intel-thc-hid.rst new file +4 -0
+
+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.

Documentation/hid/intel-thc-hid.rst new file +7 -0
+
+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.

Documentation/hid/intel-thc-hid.rst new file +8 -0
+
+5. HIDI2C support (QuickI2C)
+============================
+
+5.1 Reset Flow
+--------------
+
+- Read device descriptor from Touch IC device through PIO write

followed by read.
+- If the device descriptor is valid, allocate DMA buffers and configure all DMA channels.
+- Use PIO or TxDMA to write a SET_POWER request to TIC's command register, and check if the
+  write operation is successfully completed.
+- Use PIO or TxDMA to write a RESET request to TIC's command register. If the write operation
+  is successfully completed, wait for reset response from TIC. +- Use SWDMA to read report descriptor through TIC's report descriptor register.

Documentation/hid/intel-thc-hid.rst new file +7 -0
+
+5.2 Input Report Data Flow
+--------------------------
+
+Basic Flow:
+
+- Touch IC asserts the interrupt indicating that it has an interrupt

to send to HOST.
+  THC Sequencer issues a READ request over the I2C bus. The HIDI2C device returns the
+  first 2 bytes from the HIDI2C device which contains the length of the received data.
+- THC Sequencer continues the Read operation as per the size of data indicated in the
+  length field.
+- 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. THC writes 2Bytes for length field
+  plus the remaining data to RxDMA buffer. 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).

+- THC Sequencer enters End-of-Input Report Processing.
+- If the device has no more input reports to send to the host, it

de-asserts the interrupt
+  line. For any additional input reports, device keeps the interrupt line asserted and
+  steps 1 through 4 in the flow are repeated.

Documentation/hid/intel-thc-hid.rst new file +4 -0
+
+THC Sequencer End of Input Report Processing:
+
+- THC DMA engine increments the read pointer of the Read PRD CB,

sets EOF interrupt status
+  in RxDMA 2 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.

Documentation/hid/intel-thc-hid.rst new file +4 -0
+
+Sequence of steps to read data from RX DMA buffer:
+
+- THC QuickI2C driver checks CB write Ptr and CB read Ptr to

identify if any data frame in DMA
+  circular buffers.

+- THC QuickI2C driver gets first unprocessed PRD table.
+- THC QuickI2C driver scans all PRD entries in this PRD table to
calculate the total frame size.
+- THC QuickI2C driver copies all frame data out.
+- THC QuickI2C driver call hid_input_report to send the input report

content to HID core, which
+  includes Report ID + Report Data Content (remove the length field from the original report
+  data).
+- THC QuickI2C driver updates write Ptr.

Documentation/hid/intel-thc-hid.rst new file +8 -0
+
+5.3 Output Report Data Flow
+---------------------------
+
+Generic Output Report Flow:
+
+- HID core call THC QuickI2C raw_request callback.
+- THC QuickI2C uses PIO or TXDMA to write a SET_REPORT request to

TIC's command register. Report
+  type in SET_REPORT should be set to Output.
+- THC QuickI2C programs TxDMA buffer with TX Data to be written to TIC's data register. The first
+  2 bytes should indicate the length of the report followed by the report contents including
+  Report ID.

Documentation/hid/intel-thc-hid.rst new file +5 -0
+
+6. THC Debugging
+================
+
+To debug THC, event tracing mechanism is used. To enable debug

logs::

Documentation/hid/intel-thc-hid.rst new file +7 -0
+
+  echo 1 > /sys/kernel/debug/tracing/events/intel_thc/enable
+  cat /sys/kernel/debug/tracing/trace
+
+7. Reference
+============
+- HIDSPI:

https://download.microsoft.com/download/c/a/0/ca07aef3-3e10-4022-b1e9-c98cea99465d/HidSpiProtocolSpec.pdf
+- HIDI2C:
https://download.microsoft.com/download/7/d/d/7dd44bb7-2a7a-4505-ac1c-7227d3d96d5b/hid-over-i2c-protocol-spec-v1-0.docx

#3 lore raw

Re: [PATCH v4 01/22] HID: THC: Add documentation

Hi Srinivas,

As mentioned offline, the cover letter and version log are in v4 00/22.

Hi Aaron,

As far as I know, the issue you brought up at v3 only happens with Goodix devices. It's Goodix specific. Other devices don't have the issue. Wacom confirmed that with Wacom devices.

Can you work with the Lenovo team to confirm that so we can get this patchset accepted?

Thank you for your support,
Ping

Quoted 811 lines · srinivas pandruvada
Quoted 11 lines · Even Xu

Add Documentation/hid/intel-thc-hid.rst file to provide hardware and software detail for intel THC drivers.

Reviewed-by Srinivas Pandruvada

<[email protected]>

---

Change logs are missing?
Also didn't receive any cover letter with any changes?

Thanks,
Srinivas

Quoted 789 lines
 Documentation/hid/index.rst         |   1 +
 Documentation/hid/intel-thc-hid.rst | 568
++++++++++++++++++++++++++++
 2 files changed, 569 insertions(+)
 create mode 100644 Documentation/hid/intel-thc-hid.rst
Documentation/hid/index.rst +1 -0
index af02cf7cfa82..baf156b44b58 100644
@@ -18,4 +18,5 @@ Human Interface Devices (HID)
 
    hid-alps
    intel-ish-hid
+   intel-thc-hid
    amd-sfh-hid
Documentation/hid/intel-thc-hid.rst new file +7 -0
new file mode 100644
index 000000000000..6c417205ac6a
@@ -0,0 +1,568 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=================================
+Intel Touch Host Controller (THC)
+=================================
+
+Touch Host Controller is the name of the IP block in PCH that

interface with Touch Devices (ex:
+touchscreen, touchpad etc.). It is comprised of 3 key functional blocks:

Documentation/hid/intel-thc-hid.rst new file +6 -0
+
+- A natively half-duplex Quad I/O capable SPI master
+- Low latency I2C interface to support HIDI2C compliant devices
+- A HW sequencer with RW DMA capability to system memory
+
+It has a single root space IOSF Primary interface that supports

transactions to/from touch devices.
+Host driver configures and controls the touch devices over THC interface. THC provides high
+bandwidth DMA services to the touch driver and transfers the HID report to host system main memory.

Documentation/hid/intel-thc-hid.rst new file +2 -0
+
+Hardware sequencer within the THC is responsible for transferring

(via DMA) data from touch devices
+into system memory. A ring buffer is used to avoid data loss due to asynchronous nature of data
+consumption (by host) in relation to data production (by touch device via DMA).

Documentation/hid/intel-thc-hid.rst new file +2 -0
+
+Unlike other common SPI/I2C controllers, THC handles the HID device

data interrupt and reset

Documentation/hid/intel-thc-hid.rst new file +9 -0
+signals directly.
+
+1. Overview
+===========
+
+1.1 THC software/hardware stack
+-------------------------------
+
+Below diagram illustrates the high-level architecture of THC

software/hardware stack, which is fully

Documentation/hid/intel-thc-hid.rst new file +37 -0
+capable of supporting HIDSPI/HIDI2C protocol in Linux OS.
+
+::
+
+  ----------------------------------------------
+ |      +-----------------------------------+   |
+ |      |           Input Device            |   |
+ |      +-----------------------------------+   |
+ |      +-----------------------------------+   |
+ |      |       HID Multi-touch Driver      |   |
+ |      +-----------------------------------+   |
+ |      +-----------------------------------+   |
+ |      |             HID Core              |   |
+ |      +-----------------------------------+   |
+ |      +-----------------------------------+   |
+ |      |    THC QuickSPI/QuickI2C Driver   |   |
+ |      +-----------------------------------+   |
+ |      +-----------------------------------+   |
+ |      |      THC Hardware Driver          |   |
+ |      +-----------------------------------+   |
+ |      +----------------+ +----------------+   |
+ |  SW  | PCI Bus Driver | | ACPI Resource  |   |
+ |      +----------------+ +----------------+   |
+  ----------------------------------------------
+  ----------------------------------------------
+ |      +-----------------------------------+   |
+ |  HW  |              PCI Bus              |   |
+ |      +-----------------------------------+   |
+ |      +-----------------------------------+   |
+ |      |           THC Controller          |   |
+ |      +-----------------------------------+   |
+ |      +-----------------------------------+   |
+ |      |              Touch IC             |   |
+ |      +-----------------------------------+   |
+  ----------------------------------------------
+
+Touch IC (TIC), also as known as the Touch devices (touchscreen or

touchpad). The discrete analog
+components that sense and transfer either discrete touch data or heatmap data in the form of HID

Documentation/hid/intel-thc-hid.rst new file +3 -0
+reports over the SPI/I2C bus to the THC Controller on the host.
+
+THC Host Controller, which is a PCI device HBA (host bus adapter),

integrated into the PCH, that

Documentation/hid/intel-thc-hid.rst new file +3 -0
+serves as a bridge between the Touch ICs and the host.
+
+THC Hardware Driver, provides THC hardware operation APIs for above

QuickSPI/QuickI2C driver, it

Documentation/hid/intel-thc-hid.rst new file +3 -0
+accesses THC MMIO registers to configure and control THC hardware.
+
+THC QuickSPI/QuickI2C driver, also as known as HIDSPI/HIDI2C driver,

is registered as a HID
+low-level driver that manages the THC Controller and implements HIDSPI/HIDI2C protocol.

Documentation/hid/intel-thc-hid.rst new file +27 -0
+
+
+1.2 THC hardware diagram
+------------------------
+Below diagram shows THC hardware components::
+
+                      ---------------------------------
+                     |          THC Controller         |
+                     |  +---------------------------+  |
+                     |  |     PCI Config Space      |  |
+                     |  +---------------------------+  |
+                     |  +---------------------------+  |
+                     |  +       MMIO Registers      |  |
+                     |  +---------------------------+  |
+ +---------------+   |  +------------+ +------------+  |
+ | System Memory +---+--+      DMA   | |   PIO      |  |
+ +---------------+   |  +------------+ +------------+  |
+                     |  +---------------------------+  |
+                     |  |       HW Sequencer        |  |
+                     |  +---------------------------+  |
+                     |  +------------+ +------------+  |
+                     |  |  SPI/I2C   | |    GPIO    |  |
+                     |  | Controller | | Controller |  |
+                     |  +------------+ +------------+  |
+                      ---------------------------------
+
+As THC is exposed as a PCI devices, so it has standard PCI config

space registers for PCI

Documentation/hid/intel-thc-hid.rst new file +3 -0
+enumeration and configuration.
+
+MMIO Registers, which provide registers access for driver to

configure and control THC hardware,
+the registers include several categories: Interrupt status and control, DMA configure,
+PIO (Programmed I/O, defined in section 3.2) status and control, SPI bus configure, I2C subIP

Documentation/hid/intel-thc-hid.rst new file +3 -0
+status and control, reset status and control...
+
+THC provides two ways for driver to communicate with external Touch

ICs: PIO and DMA.
+PIO can let driver manually write/read data to/from Touch ICs, instead, THC DMA can

Documentation/hid/intel-thc-hid.rst new file +3 -0
+automatically write/read data without driver involved.
+
+HW Sequencer includes THC major logic, it gets instruction from MMIO

registers to control
+SPI bus and I2C bus to finish a bus data transaction, it also can automatically handle
+Touch ICs interrupt and start DMA receive/send data from/to Touch ICs according to interrupt
+type. That means THC HW Sequencer understands HIDSPI/HIDI2C transfer protocol, and handle
+the communication without driver involved, what driver needs to do is just configure the THC
+properly, and prepare the formatted data packet or handle received data packet.

Documentation/hid/intel-thc-hid.rst new file +2 -0
+
+As THC supports HIDSPI/HIDI2C protocols, it has SPI controller and

I2C subIP in it to expose
+SPI bus and I2C bus. THC also integrates a GPIO controller to provide interrupt line support

Documentation/hid/intel-thc-hid.rst new file +9 -0
+and reset line support.
+
+2. THC Hardware Interface
+=========================
+
+2.1 Host Interface
+------------------
+
+THC is exposed as "PCI Digitizer device" to the host. The PCI

product and device IDs are
+changed from different generations of processors. So the source code which enumerates drivers

Documentation/hid/intel-thc-hid.rst new file +7 -0
+needs to update from generation to generation.
+
+
+2.2 Device Interface
+--------------------
+
+THC supports two types of bus for Touch IC connection: Enhanced SPI

bus and I2C bus.

Documentation/hid/intel-thc-hid.rst new file +5 -0
+
+2.2.1 SPI Port
+~~~~~~~~~~~~~~
+
+When PORT_TYPE = 00b in MMIO registers, THC uses SPI interfaces to

communicate with external
+Touch IC. THC enhanced SPI Bus supports different SPI modes:
standard Single IO mode,

Documentation/hid/intel-thc-hid.rst new file +3 -0
+Dual IO mode and Quad IO mode.
+
+In Single IO mode, THC drives MOSI line to send data to Touch ICs,

and receives data from Touch
+ICs data from MISO line. In Dual IO mode, THC drivers MOSI and MISO both for data sending, and
+also receives the data on both line. In Quad IO mode, there are other two lines (IO2 and IO3)
+are added, THC drives MOSI (IO0), MISO (IO1), IO2 and IO3 at the same time for data sending, and
+also receives the data on those 4 lines. Driver needs to configure THC in different mode by

Documentation/hid/intel-thc-hid.rst new file +3 -0
+setting different opcode.
+
+Beside IO mode, driver also needs to configure SPI bus speed. THC

supports up to 42MHz SPI clock

Documentation/hid/intel-thc-hid.rst new file +16 -0
+on Intel Lunar Lake platform.
+
+For THC sending data to Touch IC, the data flow on SPI bus::
+
+ | --------------------THC sends---------------------------------|
+ <8Bits OPCode><24Bits Slave Address><Data><Data><Data>...........
+
+For THC receiving data from Touch IC, the data flow on SPI bus::
+
+ | ---------THC Sends---------------||-----Touch IC sends--------|
+ <8Bits OPCode><24Bits Slave Address><Data><Data><Data>...........
+
+2.2.2 I2C Port
+~~~~~~~~~~~~~~
+
+THC also integrates I2C controller in it, it's called I2C SubSystem.

When PORT_TYPE = 01, THC
+is configured to I2C mode. Comparing to SPI mode which can be configured through MMIO registers
+directly, THC needs to use PIO read (by setting SubIP read opcode) to I2C subIP APB registers'
+value and use PIO write (by setting SubIP write opcode) to do a write operation.

Documentation/hid/intel-thc-hid.rst new file +5 -0
+
+2.2.3 GPIO interface
+~~~~~~~~~~~~~~~~~~~~
+
+THC also includes two GPIO pins, one for interrupt and the other for

device reset control.

Documentation/hid/intel-thc-hid.rst new file +2 -0
+
+Interrupt line can be configured to either level triggerred or edge

triggerred by setting MMIO

Documentation/hid/intel-thc-hid.rst new file +3 -0
+Control register.
+
+Reset line is controlled by BIOS (or EFI) through ACPI _RST method,

driver needs to call this

Documentation/hid/intel-thc-hid.rst new file +9 -0
+device ACPI _RST method to reset touch IC during initialization.
+
+3. High level concept
+=====================
+
+3.1 Opcode
+----------
+
+Opcode (operation code) is used to tell THC or Touch IC what the

operation will be, such as PIO

Documentation/hid/intel-thc-hid.rst new file +3 -0
+read or PIO write.
+
+When THC is configured to SPI mode, opcodes are used for determining

the read/write IO mode.

Documentation/hid/intel-thc-hid.rst new file +14 -0
+There are some OPCode examples for SPI IO mode:
+
+=======   ==============================
+opcode    Corresponding SPI command
+=======   ==============================
+0x0B      Read Single I/O
+0x02      Write Single I/O
+0xBB      Read Dual I/O
+0xB2      Write Dual I/O
+0xEB      Read Quad I/O
+0xE2      Write Quad I/O
+=======   ==============================
+
+In general, different touch IC has different OPCode definition.

According to HIDSPI
+protocol whitepaper, those OPCodes are defined in device ACPI table, and driver needs to
+query those information through OS ACPI APIs during driver initialization, then configures

Documentation/hid/intel-thc-hid.rst new file +3 -0
+THC MMIO OPCode registers with correct setting.
+
+When THC is working in I2C mode, opcodes are used to tell THC what's

the next PIO type:
+I2C SubIP APB register read, I2C SubIP APB register write, I2C touch IC device read,
+I2C touch IC device write, I2C touch IC device write followed by read.

Documentation/hid/intel-thc-hid.rst new file +4 -0
+
+Here are the THC pre-defined opcodes for I2C mode:
+
+=======   ===================================================

===========
+opcode Corresponding I2C command
Address
+======= ===================================================
===========
+0x12 Read I2C SubIP APB internal registers 0h -
FFh
+0x13 Write I2C SubIP APB internal registers 0h -
FFh

+0x14      Read external Touch IC through I2C bus                N/A
+0x18      Write external Touch IC through I2C bus               N/A
+0x1C      Write then read external Touch IC through I2C bus     N/A
+=======   ===================================================

===========

Documentation/hid/intel-thc-hid.rst new file +5 -0
+
+3.2 PIO
+-------
+
+THC provides a programmed I/O (PIO) access interface for the driver

to access the touch IC's
+configuration registers, or access I2C subIP's configuration registers. To use PIO to perform
+I/O operations, driver should pre-program PIO control registers and PIO data registers and kick
+off the sequencing cycle. THC uses different PIO opcodes to distinguish different PIO

Documentation/hid/intel-thc-hid.rst new file +3 -0
+operations (PIO read/write/write followed by read).
+
+If there is a Sequencing Cycle In Progress and an attempt is made to

program any of the control,
+address, or data register the cycle is blocked and a sequence error will be encountered.

Documentation/hid/intel-thc-hid.rst new file +2 -0
+
+A status bit indicates when the cycle has completed allowing the

driver to know when read results
+can be checked and/or when to initiate a new command. If enabled, the cycle done assertion can

Documentation/hid/intel-thc-hid.rst new file +3 -0
+interrupt driver with an interrupt.
+
+Because THC only has 16 FIFO registers for PIO, so all the data

transfer through PIO shouldn't

Documentation/hid/intel-thc-hid.rst new file +3 -0
+exceed 64 bytes.
+
+As DMA needs max packet size for transferring configuration, and the

max packet size information
+always in HID device descriptor which needs THC driver to read it out from HID Device (Touch IC).
+So PIO typical use case is, before DMA initialization, write RESET command (PIO write), read
+RESET response (PIO read or PIO write followed by read), write Power ON command (PIO write), read

Documentation/hid/intel-thc-hid.rst new file +3 -0
+device descriptor (PIO read).
+
+For how to issue a PIO operation, here is the steps which driver

needs follow:
+

+- Program read/write data size in THC_SS_BC.
+- Program I/O target address in THC_SW_SEQ_DATA0_ADDR.
+- If write, program the write data in
THC_SW_SEQ_DATA0..THC_SW_SEQ_DATAn.
+- Program the PIO opcode in THC_SS_CMD.
+- Set TSSGO = 1 to start the PIO write sequence.
+- If THC_SS_CD_IE = 1, SW will receives a MSI when the PIO is

completed.
+- If read, read out the data in THC_SW_SEQ_DATA0..THC_SW_SEQ_DATAn.

Documentation/hid/intel-thc-hid.rst new file +5 -0
+
+3.3 DMA
+-------
+
+THC has 4 DMA channels: Read DMA1, Read DMA2, Write DMA and Software

DMA.

Documentation/hid/intel-thc-hid.rst new file +5 -0
+
+3.3.1 Read DMA Channel
+~~~~~~~~~~~~~~~~~~~~~~
+
+THC has two Read DMA engines: 1st RxDMA (RxDMA1) and 2nd RxDMA

(RxDMA2). RxDMA1 is reserved for
+raw data mode. RxDMA2 is used for HID data mode and it is the RxDMA engine currently driver uses

Documentation/hid/intel-thc-hid.rst new file +3 -0
+for HID input report data retrieval.
+
+RxDMA's typical use case is auto receiving the data from Touch IC.

Once RxDMA is enabled by

Documentation/hid/intel-thc-hid.rst new file +3 -0
+software, THC will start auto-handling receiving logic.
+
+For SPI mode, THC RxDMA sequence is: when Touch IC triggers a

interrupt to THC, THC reads out
+report header to identify what's the report type, and what's the report length, according to
+above information, THC reads out report body to internal FIFO and start RxDMA coping the data
+to system memory. After that, THC update interrupt cause register with report type, and update
+RxDMA PRD table read pointer, then trigger a MSI interrupt to notify driver RxDMA finishing

Documentation/hid/intel-thc-hid.rst new file +3 -0
+data receiving.
+
+For I2C mode, THC RxDMA's behavior is a little bit different,

because of HIDI2C protocol difference
+with HIDSPI protocol, RxDMA only be used to receive input report. The sequence is, when Touch IC
+triggers a interrupt to THC, THC first reads out 2 bytes from input report address to determine the
+packet length, then use this packet length to start a DMA reading from input report address for
+input report data. After that, THC update RxDMA PRD table read pointer, then trigger a MSI interrupt

Documentation/hid/intel-thc-hid.rst new file +3 -0
+to notify driver input report data is ready in system memory.
+
+All above sequence is hardware automatically handled, all driver

needs to do is configure RxDMA and
+waiting for interrupt ready then read out the data from system memory.

Documentation/hid/intel-thc-hid.rst new file +5 -0
+
+3.3.2 Software DMA channel
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+THC supports a software triggerred RxDMA mode to read the touch data

from touch IC. This SW RxDMA
+is the 3rd THC RxDMA engine with the similar functionalities as the existing two RxDMAs, the only
+difference is this SW RxDMA is triggerred by software, and RxDMA2 is triggerred by external Touch IC
+interrupt. It gives a flexiblity to software driver to use RxDMA read Touch IC data in any time.

Documentation/hid/intel-thc-hid.rst new file +2 -0
+
+Before software starts a SW RxDMA, it shall stop the 1st and 2nd

RxDMA, clear PRD read/write pointer
+and quiesce the device interrupt (THC_DEVINT_QUIESCE_HW_STS = 1), other operations are the same with

Documentation/hid/intel-thc-hid.rst new file +6 -0
+RxDMA.
+
+3.3.3 Write DMA Channel
+~~~~~~~~~~~~~~~~~~~~~~~
+
+THC has one write DMA engine, which can be used for sending data to

Touch IC automatically.
+According to HIDSPI and HIDI2C protocol, every time only one command can be sent to touch IC, and
+before last command is completely handled, next command cannot be sent, THC write DMA engine only

Documentation/hid/intel-thc-hid.rst new file +3 -0
+supports single PRD table.
+
+What driver needs to do is, preparing PRD table and DMA buffer, then

copy data to DMA buffer and
+update PRD table with buffer address and buffer length, then start write DMA. THC will
+automatically send the data to touch IC, and trigger a DMA completion interrupt once transferring

Documentation/hid/intel-thc-hid.rst new file +6 -0
+is done.
+
+3.4 PRD
+-------
+
+Physical Region Descriptor (PRD) provides the memory mapping

description for THC DMAs.

Documentation/hid/intel-thc-hid.rst new file +5 -0
+
+3.4.1 PRD table and entry
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In order to improve physical DMA memory usage, modern drivers trend

to allocate a virtually
+contiguous, but physically fragmented buffer of memory for each data buffer. Linux OS also

Documentation/hid/intel-thc-hid.rst new file +3 -0
+provide SGL (scatter gather list) APIs to support this usage.
+
+THC uses PRD table (physical region descriptor) to support the

corresponding OS kernel

Documentation/hid/intel-thc-hid.rst new file +15 -0
+SGL that describes the virtual to physical buffer mapping.
+
+::
+
+  ------------------------      --------------       --------------
+ | PRD table base address +----+ PRD table #1 +-----+ PRD Entry #1 |
+  ------------------------      --------------       --------------
+                                                     --------------
+                                                    | PRD Entry #2 |
+                                                     --------------
+                                                     --------------
+                                                    | PRD Entry #n |
+                                                     --------------
+
+The read DMA engine supports multiple PRD tables held within a

circular buffer that allow the THC
+to support multiple data buffers from the Touch IC. This allows host SW to arm the Read DMA engine
+with multiple buffers, allowing the Touch IC to send multiple data frames to the THC without SW
+interaction. This capability is required when the CPU processes touch frames slower than the

Documentation/hid/intel-thc-hid.rst new file +3 -0
+Touch IC can send them.
+
+To simplify the design, SW assumes worst-case memory fragmentation.

Therefore,each PRD table shall
+contain the same number of PRD entries, allowing for a global register (per Touch IC) to hold the

Documentation/hid/intel-thc-hid.rst new file +3 -0
+number of PRD-entries per PRD table.
+
+SW allocates up to 128 PRD tables per Read DMA engine as specified

in the THC_M_PRT_RPRD_CNTRL.PCD
+register field. The number of PRD tables should equal the number of data buffers.

Documentation/hid/intel-thc-hid.rst new file +2 -0
+
+Max OS memory fragmentation will be at a 4KB boundary, thus to

address 1MB of virtually contiguous
+memory 256 PRD entries are required for a single PRD Table. SW writes the number of PRD entries
+for each PRD table in the THC_M_PRT_RPRD_CNTRL.PTEC register field. The PRD entry's length must be

Documentation/hid/intel-thc-hid.rst new file +3 -0
+multiple of 4KB except for the last entry in a PRD table.
+
+SW allocates all the data buffers and PRD tables only once at host

initialization.

Documentation/hid/intel-thc-hid.rst new file +5 -0
+
+3.4.2 PRD Write pointer and read pointer
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+As PRD tables are organized as a Circular Buffer (CB), a read

pointer and a write pointer for a CB

Documentation/hid/intel-thc-hid.rst new file +3 -0
+are needed.
+
+DMA HW consumes the PRD tables in the CB, one PRD entry at a time

until the EOP bit is found set
+in a PRD entry. At this point HW increments the PRD read pointer. Thus, the read pointer points
+to the PRD which the DMA engine is currently processing. This pointer rolls over once the circular
+buffer's depth has been traversed with bit[7] the Rollover bit. E.g. if the DMA CB depth is equal
+to 4 entries (0011b), then the read pointers will follow this pattern (HW is required to honor

Documentation/hid/intel-thc-hid.rst new file +3 -0
+this behavior): 00h 01h 02h 03h 80h 81h 82h 83h 00h 01h ...
+
+The write pointer is updated by SW. The write pointer points to

location in the DMA CB, where the
+next PRD table is going to be stored. SW needs to ensure that this pointer rolls over once the
+circular buffer's depth has been traversed with Bit[7] as the rollover bit. E.g. if the DMA CB
+depth is equal to 5 entries (0100b), then the write pointers will follow this pattern (SW is
+required to honor this behavior): 00h 01h 02h 03h 04h 80h 81h 82h 83h 84h 00h 01h ..

Documentation/hid/intel-thc-hid.rst new file +5 -0
+
+3.4.3 PRD descriptor structure
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Intel THC uses PRD entry descriptor for every PRD entry. Every PRD

entry descriptor occupies
+128 bits memories:
+
+=================== ========
===============================================
+struct field bit(s) description
+=================== ========
===============================================
+dest_addr 53..0 destination memory address, as
every entry
+ is 4KB, ignore lowest 10 bits of
address.

Documentation/hid/intel-thc-hid.rst new file +2 -0
+reserved1             54..62     reserved
+int_on_completion     63         completion interrupt enable bit, if

this bit
+ set it means THC will trigger a
completion
+ interrupt. This bit is set by SW
driver.
+len 87..64 how many bytes of data in this
entry.
+end_of_prd 88 end of PRD table bit, if this bit
is set,
+ it means this entry is last entry
in this PRD
+ table. This bit is set by SW
driver.

Documentation/hid/intel-thc-hid.rst new file +3 -0
+hw_status             90..89     HW status bits
+reserved2             127..91    reserved
+===================   ========

===============================================

Documentation/hid/intel-thc-hid.rst new file +2 -0
+
+And one PRD table can include up to 256 PRD entries, as every

entries is 4K bytes, so every

Documentation/hid/intel-thc-hid.rst new file +9 -0
+PRD table can describe 1M bytes memory.
+
+.. code-block:: c
+
+   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

Documentation/hid/intel-thc-hid.rst new file +6 -0
+each PRD table.
+
+4. HIDSPI support (QuickSPI)
+============================
+
+Intel THC is total compatible with HIDSPI protocol, THC HW sequenser

can accelerate HIDSPI

Documentation/hid/intel-thc-hid.rst new file +8 -0
+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.

Documentation/hid/intel-thc-hid.rst new file +7 -0
+
+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.

Documentation/hid/intel-thc-hid.rst new file +4 -0
+
+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),

Documentation/hid/intel-thc-hid.rst new file +5 -0
+  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

Documentation/hid/intel-thc-hid.rst new file +9 -0
+  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

Documentation/hid/intel-thc-hid.rst new file +10 -0
+  to THC's write DMA buffer.
+- Start TxDMA to complete the write operation.
+
+5. HIDI2C support (QuickI2C)
+============================
+
+5.1 Reset Flow
+--------------
+
+- Read device descriptor from Touch IC device through PIO write

followed by read.
+- If the device descriptor is valid, allocate DMA buffers and configure all DMA channels.
+- Use PIO or TxDMA to write a SET_POWER request to TIC's command register, and check if the
+ write operation is successfully completed.
+- Use PIO or TxDMA to write a RESET request to TIC's command register. If the write operation
+ is successfully completed, wait for reset response from TIC. +- Use SWDMA to read report descriptor through TIC's report descriptor register.

Documentation/hid/intel-thc-hid.rst new file +7 -0
+
+5.2 Input Report Data Flow
+--------------------------
+
+Basic Flow:
+
+- Touch IC asserts the interrupt indicating that it has an interrupt

to send to HOST.
+ THC Sequencer issues a READ request over the I2C bus. The HIDI2C device returns the
+ first 2 bytes from the HIDI2C device which contains the length of the received data.
+- THC Sequencer continues the Read operation as per the size of data indicated in the
+ length field.
+- 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. THC writes 2Bytes for length field
+ plus the remaining data to RxDMA buffer. 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).

+- THC Sequencer enters End-of-Input Report Processing.
+- If the device has no more input reports to send to the host, it

de-asserts the interrupt
+ line. For any additional input reports, device keeps the interrupt line asserted and

Documentation/hid/intel-thc-hid.rst new file +5 -0
+  steps 1 through 4 in the flow are repeated.
+
+THC Sequencer End of Input Report Processing:
+
+- THC DMA engine increments the read pointer of the Read PRD CB,

sets EOF interrupt status
+ in RxDMA 2 register (THC_M_PRT_READ_DMA_INT_STS_2). +- If THC EOF interrupt is enabled by the driver in the control register

Documentation/hid/intel-thc-hid.rst new file +5 -0
+  (THC_M_PRT_READ_DMA_CNTRL_2), generates interrupt to software.
+
+Sequence of steps to read data from RX DMA buffer:
+
+- THC QuickI2C driver checks CB write Ptr and CB read Ptr to

identify if any data frame in DMA
+ circular buffers.

+- THC QuickI2C driver gets first unprocessed PRD table.
+- THC QuickI2C driver scans all PRD entries in this PRD table to
calculate the total frame size.
+- THC QuickI2C driver copies all frame data out.
+- THC QuickI2C driver call hid_input_report to send the input report

content to HID core, which
+ includes Report ID + Report Data Content (remove the length field from the original report

Documentation/hid/intel-thc-hid.rst new file +10 -0
+  data).
+- THC QuickI2C driver updates write Ptr.
+
+5.3 Output Report Data Flow
+---------------------------
+
+Generic Output Report Flow:
+
+- HID core call THC QuickI2C raw_request callback.
+- THC QuickI2C uses PIO or TXDMA to write a SET_REPORT request to

TIC's command register. Report
+ type in SET_REPORT should be set to Output.
+- THC QuickI2C programs TxDMA buffer with TX Data to be written to TIC's data register. The first
+ 2 bytes should indicate the length of the report followed by the report contents including

Documentation/hid/intel-thc-hid.rst new file +6 -0
+  Report ID.
+
+6. THC Debugging
+================
+
+To debug THC, event tracing mechanism is used. To enable debug

logs::

Documentation/hid/intel-thc-hid.rst new file +7 -0
+
+  echo 1 > /sys/kernel/debug/tracing/events/intel_thc/enable
+  cat /sys/kernel/debug/tracing/trace
+
+7. Reference
+============
+- HIDSPI:

https://download.microsoft.com/download/c/a/0/ca07aef3-3e10-4022-b1e9-c98cea99465d/HidSpiProtocolSpec.pdf
+- HIDI2C:
https://download.microsoft.com/download/7/d/d/7dd44bb7-2a7a-4505-ac1c-7227d3d96d5b/hid-over-i2c-protocol-spec-v1-0.docx

author maintainer
#4 lore raw

RE: [PATCH v4 01/22] HID: THC: Add documentation

hi, Aaron,

This issue was identified to Goodix touch firmware issue, it de-asserted interrupt line delayed. And Goodix engineer configured there were 10us delay at end of every touch event packet. They are working on it to modify the firmware for the fix.

Maybe you can get updated engineer firmware from Lenovo.

Thanks!

Best Regards,
Even Xu

Quoted 873 lines

-----Original Message-----
From: Ping Cheng <[email protected]>
Sent: Thursday, January 9, 2025 1:18 PM
To: srinivas pandruvada <[email protected]>; Aaron, Ma <[email protected]>; Ivan Delos Santos Julkarnain, Ameer <[email protected]>
Cc: Xu, Even <[email protected]>; [email protected]; [email protected]; [email protected]; [email protected]; [email protected]; mpearson- [email protected]; [email protected]; [email protected]; [email protected]; Sun, Xinpeng <[email protected]>
Subject: Re: [PATCH v4 01/22] HID: THC: Add documentation

Hi Srinivas,

As mentioned offline, the cover letter and version log are in v4 00/22.

Hi Aaron,

As far as I know, the issue you brought up at v3 only happens with Goodix devices. It's Goodix specific. Other devices don't have the issue. Wacom confirmed that with Wacom devices.

Can you work with the Lenovo team to confirm that so we can get this patchset accepted?

Thank you for your support,
Ping

Quoted 843 lines · srinivas pandruvada
Quoted 11 lines · Even Xu

Add Documentation/hid/intel-thc-hid.rst file to provide hardware and software detail for intel THC drivers.

Reviewed-by Srinivas Pandruvada

<[email protected]>

---

Change logs are missing?
Also didn't receive any cover letter with any changes?

Thanks,
Srinivas

Quoted 821 lines
 Documentation/hid/index.rst         |   1 +
 Documentation/hid/intel-thc-hid.rst | 568
++++++++++++++++++++++++++++
 2 files changed, 569 insertions(+)
 create mode 100644 Documentation/hid/intel-thc-hid.rst
(quoted diff) +0 -0

b/Documentation/hid/index.rst index af02cf7cfa82..baf156b44b58 100644

Documentation/hid/index.rst +1 -0
@@ -18,4 +18,5 @@ Human Interface Devices (HID)
 
    hid-alps
    intel-ish-hid
+   intel-thc-hid
    amd-sfh-hid
Documentation/hid/intel-thc-hid.rst new file +7 -0
new file mode 100644
index 000000000000..6c417205ac6a
@@ -0,0 +1,568 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=================================
+Intel Touch Host Controller (THC)
+=================================
+
+Touch Host Controller is the name of the IP block in PCH that

interface with Touch Devices (ex:
+touchscreen, touchpad etc.). It is comprised of 3 key functional blocks:

Documentation/hid/intel-thc-hid.rst new file +6 -0
+
+- A natively half-duplex Quad I/O capable SPI master
+- Low latency I2C interface to support HIDI2C compliant devices
+- A HW sequencer with RW DMA capability to system memory
+
+It has a single root space IOSF Primary interface that supports

transactions to/from touch devices.
+Host driver configures and controls the touch devices over THC interface. THC provides high
+bandwidth DMA services to the touch driver and transfers the HID report to host system main memory.

Documentation/hid/intel-thc-hid.rst new file +2 -0
+
+Hardware sequencer within the THC is responsible for transferring

(via DMA) data from touch devices
+into system memory. A ring buffer is used to avoid data loss due to asynchronous nature of data
+consumption (by host) in relation to data production (by touch device via DMA).

Documentation/hid/intel-thc-hid.rst new file +2 -0
+
+Unlike other common SPI/I2C controllers, THC handles the HID device

data interrupt and reset

Documentation/hid/intel-thc-hid.rst new file +9 -0
+signals directly.
+
+1. Overview
+===========
+
+1.1 THC software/hardware stack
+-------------------------------
+
+Below diagram illustrates the high-level architecture of THC

software/hardware stack, which is fully

Documentation/hid/intel-thc-hid.rst new file +37 -0
+capable of supporting HIDSPI/HIDI2C protocol in Linux OS.
+
+::
+
+  ----------------------------------------------
+ |      +-----------------------------------+   |
+ |      |           Input Device            |   |
+ |      +-----------------------------------+   |
+ |      +-----------------------------------+   |
+ |      |       HID Multi-touch Driver      |   |
+ |      +-----------------------------------+   |
+ |      +-----------------------------------+   |
+ |      |             HID Core              |   |
+ |      +-----------------------------------+   |
+ |      +-----------------------------------+   |
+ |      |    THC QuickSPI/QuickI2C Driver   |   |
+ |      +-----------------------------------+   |
+ |      +-----------------------------------+   |
+ |      |      THC Hardware Driver          |   |
+ |      +-----------------------------------+   |
+ |      +----------------+ +----------------+   |
+ |  SW  | PCI Bus Driver | | ACPI Resource  |   |
+ |      +----------------+ +----------------+   |
+  ----------------------------------------------
+  ----------------------------------------------
+ |      +-----------------------------------+   |
+ |  HW  |              PCI Bus              |   |
+ |      +-----------------------------------+   |
+ |      +-----------------------------------+   |
+ |      |           THC Controller          |   |
+ |      +-----------------------------------+   |
+ |      +-----------------------------------+   |
+ |      |              Touch IC             |   |
+ |      +-----------------------------------+   |
+  ----------------------------------------------
+
+Touch IC (TIC), also as known as the Touch devices (touchscreen or

touchpad). The discrete analog
+components that sense and transfer either discrete touch data or heatmap data in the form of HID

Documentation/hid/intel-thc-hid.rst new file +3 -0
+reports over the SPI/I2C bus to the THC Controller on the host.
+
+THC Host Controller, which is a PCI device HBA (host bus adapter),

integrated into the PCH, that

Documentation/hid/intel-thc-hid.rst new file +3 -0
+serves as a bridge between the Touch ICs and the host.
+
+THC Hardware Driver, provides THC hardware operation APIs for above

QuickSPI/QuickI2C driver, it

Documentation/hid/intel-thc-hid.rst new file +4 -0
+accesses THC MMIO registers to configure and control THC hardware.
+
+THC QuickSPI/QuickI2C driver, also as known as HIDSPI/HIDI2C
+driver,

is registered as a HID
+low-level driver that manages the THC Controller and implements HIDSPI/HIDI2C protocol.

Documentation/hid/intel-thc-hid.rst new file +27 -0
+
+
+1.2 THC hardware diagram
+------------------------
+Below diagram shows THC hardware components::
+
+                      ---------------------------------
+                     |          THC Controller         |
+                     |  +---------------------------+  |
+                     |  |     PCI Config Space      |  |
+                     |  +---------------------------+  |
+                     |  +---------------------------+  |
+                     |  +       MMIO Registers      |  |
+                     |  +---------------------------+  |
+ +---------------+   |  +------------+ +------------+  |
+ | System Memory +---+--+      DMA   | |   PIO      |  |
+ +---------------+   |  +------------+ +------------+  |
+                     |  +---------------------------+  |
+                     |  |       HW Sequencer        |  |
+                     |  +---------------------------+  |
+                     |  +------------+ +------------+  |
+                     |  |  SPI/I2C   | |    GPIO    |  |
+                     |  | Controller | | Controller |  |
+                     |  +------------+ +------------+  |
+                      ---------------------------------
+
+As THC is exposed as a PCI devices, so it has standard PCI config

space registers for PCI

Documentation/hid/intel-thc-hid.rst new file +3 -0
+enumeration and configuration.
+
+MMIO Registers, which provide registers access for driver to

configure and control THC hardware,
+the registers include several categories: Interrupt status and control, DMA configure,

Documentation/hid/intel-thc-hid.rst new file +2 -0
+PIO (Programmed I/O, defined in section 3.2) status and control,
+SPI

bus configure, I2C subIP

Documentation/hid/intel-thc-hid.rst new file +3 -0
+status and control, reset status and control...
+
+THC provides two ways for driver to communicate with external Touch

ICs: PIO and DMA.
+PIO can let driver manually write/read data to/from Touch ICs, instead, THC DMA can

Documentation/hid/intel-thc-hid.rst new file +4 -0
+automatically write/read data without driver involved.
+
+HW Sequencer includes THC major logic, it gets instruction from
+MMIO

registers to control
+SPI bus and I2C bus to finish a bus data transaction, it also can automatically handle
+Touch ICs interrupt and start DMA receive/send data from/to Touch ICs according to interrupt

Documentation/hid/intel-thc-hid.rst new file +2 -0
+type. That means THC HW Sequencer understands HIDSPI/HIDI2C
+transfer

protocol, and handle
+the communication without driver involved, what driver needs to do is just configure the THC
+properly, and prepare the formatted data packet or handle received data packet.

Documentation/hid/intel-thc-hid.rst new file +2 -0
+
+As THC supports HIDSPI/HIDI2C protocols, it has SPI controller and

I2C subIP in it to expose
+SPI bus and I2C bus. THC also integrates a GPIO controller to provide interrupt line support

Documentation/hid/intel-thc-hid.rst new file +9 -0
+and reset line support.
+
+2. THC Hardware Interface
+=========================
+
+2.1 Host Interface
+------------------
+
+THC is exposed as "PCI Digitizer device" to the host. The PCI

product and device IDs are

Documentation/hid/intel-thc-hid.rst new file +2 -0
+changed from different generations of processors. So the source
+code

which enumerates drivers

Documentation/hid/intel-thc-hid.rst new file +7 -0
+needs to update from generation to generation.
+
+
+2.2 Device Interface
+--------------------
+
+THC supports two types of bus for Touch IC connection: Enhanced SPI

bus and I2C bus.

Documentation/hid/intel-thc-hid.rst new file +5 -0
+
+2.2.1 SPI Port
+~~~~~~~~~~~~~~
+
+When PORT_TYPE = 00b in MMIO registers, THC uses SPI interfaces to

communicate with external
+Touch IC. THC enhanced SPI Bus supports different SPI modes:
standard Single IO mode,

Documentation/hid/intel-thc-hid.rst new file +3 -0
+Dual IO mode and Quad IO mode.
+
+In Single IO mode, THC drives MOSI line to send data to Touch ICs,

and receives data from Touch
+ICs data from MISO line. In Dual IO mode, THC drivers MOSI and MISO both for data sending, and
+also receives the data on both line. In Quad IO mode, there are other two lines (IO2 and IO3)
+are added, THC drives MOSI (IO0), MISO (IO1), IO2 and IO3 at the same time for data sending, and
+also receives the data on those 4 lines. Driver needs to configure THC in different mode by

Documentation/hid/intel-thc-hid.rst new file +3 -0
+setting different opcode.
+
+Beside IO mode, driver also needs to configure SPI bus speed. THC

supports up to 42MHz SPI clock

Documentation/hid/intel-thc-hid.rst new file +16 -0
+on Intel Lunar Lake platform.
+
+For THC sending data to Touch IC, the data flow on SPI bus::
+
+ | --------------------THC sends---------------------------------|
+ <8Bits OPCode><24Bits Slave Address><Data><Data><Data>...........
+
+For THC receiving data from Touch IC, the data flow on SPI bus::
+
+ | ---------THC Sends---------------||-----Touch IC sends--------|
+ <8Bits OPCode><24Bits Slave Address><Data><Data><Data>...........
+
+2.2.2 I2C Port
+~~~~~~~~~~~~~~
+
+THC also integrates I2C controller in it, it's called I2C SubSystem.

When PORT_TYPE = 01, THC
+is configured to I2C mode. Comparing to SPI mode which can be configured through MMIO registers
+directly, THC needs to use PIO read (by setting SubIP read opcode) to I2C subIP APB registers'
+value and use PIO write (by setting SubIP write opcode) to do a write operation.

Documentation/hid/intel-thc-hid.rst new file +6 -0
+
+2.2.3 GPIO interface
+~~~~~~~~~~~~~~~~~~~~
+
+THC also includes two GPIO pins, one for interrupt and the other
+for

device reset control.

Documentation/hid/intel-thc-hid.rst new file +2 -0
+
+Interrupt line can be configured to either level triggerred or edge

triggerred by setting MMIO

Documentation/hid/intel-thc-hid.rst new file +3 -0
+Control register.
+
+Reset line is controlled by BIOS (or EFI) through ACPI _RST method,

driver needs to call this

Documentation/hid/intel-thc-hid.rst new file +9 -0
+device ACPI _RST method to reset touch IC during initialization.
+
+3. High level concept
+=====================
+
+3.1 Opcode
+----------
+
+Opcode (operation code) is used to tell THC or Touch IC what the

operation will be, such as PIO

Documentation/hid/intel-thc-hid.rst new file +4 -0
+read or PIO write.
+
+When THC is configured to SPI mode, opcodes are used for
+determining

the read/write IO mode.

Documentation/hid/intel-thc-hid.rst new file +14 -0
+There are some OPCode examples for SPI IO mode:
+
+=======   ==============================
+opcode    Corresponding SPI command
+=======   ==============================
+0x0B      Read Single I/O
+0x02      Write Single I/O
+0xBB      Read Dual I/O
+0xB2      Write Dual I/O
+0xEB      Read Quad I/O
+0xE2      Write Quad I/O
+=======   ==============================
+
+In general, different touch IC has different OPCode definition.

According to HIDSPI

Documentation/hid/intel-thc-hid.rst new file +2 -0
+protocol whitepaper, those OPCodes are defined in device ACPI
+table,

and driver needs to
+query those information through OS ACPI APIs during driver initialization, then configures

Documentation/hid/intel-thc-hid.rst new file +4 -0
+THC MMIO OPCode registers with correct setting.
+
+When THC is working in I2C mode, opcodes are used to tell THC
+what's

the next PIO type:

Documentation/hid/intel-thc-hid.rst new file +2 -0
+I2C SubIP APB register read, I2C SubIP APB register write, I2C
+touch

IC device read,
+I2C touch IC device write, I2C touch IC device write followed by read.

Documentation/hid/intel-thc-hid.rst new file +4 -0
+
+Here are the THC pre-defined opcodes for I2C mode:
+
+=======   ===================================================

===========
+opcode Corresponding I2C command
Address
+======= ===================================================
===========
+0x12 Read I2C SubIP APB internal registers 0h -
FFh
+0x13 Write I2C SubIP APB internal registers 0h -
FFh

+0x14      Read external Touch IC through I2C bus                N/A
+0x18      Write external Touch IC through I2C bus               N/A
+0x1C      Write then read external Touch IC through I2C bus     N/A
+=======   ===================================================

===========

Documentation/hid/intel-thc-hid.rst new file +5 -0
+
+3.2 PIO
+-------
+
+THC provides a programmed I/O (PIO) access interface for the driver

to access the touch IC's
+configuration registers, or access I2C subIP's configuration registers. To use PIO to perform
+I/O operations, driver should pre-program PIO control registers and PIO data registers and kick
+off the sequencing cycle. THC uses different PIO opcodes to distinguish different PIO

Documentation/hid/intel-thc-hid.rst new file +4 -0
+operations (PIO read/write/write followed by read).
+
+If there is a Sequencing Cycle In Progress and an attempt is made
+to

program any of the control,
+address, or data register the cycle is blocked and a sequence error will be encountered.

Documentation/hid/intel-thc-hid.rst new file +2 -0
+
+A status bit indicates when the cycle has completed allowing the

driver to know when read results
+can be checked and/or when to initiate a new command. If enabled, the cycle done assertion can

Documentation/hid/intel-thc-hid.rst new file +3 -0
+interrupt driver with an interrupt.
+
+Because THC only has 16 FIFO registers for PIO, so all the data

transfer through PIO shouldn't

Documentation/hid/intel-thc-hid.rst new file +4 -0
+exceed 64 bytes.
+
+As DMA needs max packet size for transferring configuration, and
+the

max packet size information
+always in HID device descriptor which needs THC driver to read it out from HID Device (Touch IC).
+So PIO typical use case is, before DMA initialization, write RESET command (PIO write), read

Documentation/hid/intel-thc-hid.rst new file +2 -0
+RESET response (PIO read or PIO write followed by read), write
+Power

ON command (PIO write), read

Documentation/hid/intel-thc-hid.rst new file +3 -0
+device descriptor (PIO read).
+
+For how to issue a PIO operation, here is the steps which driver

needs follow:
+

+- Program read/write data size in THC_SS_BC.
+- Program I/O target address in THC_SW_SEQ_DATA0_ADDR.
+- If write, program the write data in
THC_SW_SEQ_DATA0..THC_SW_SEQ_DATAn.
+- Program the PIO opcode in THC_SS_CMD.
+- Set TSSGO = 1 to start the PIO write sequence.
+- If THC_SS_CD_IE = 1, SW will receives a MSI when the PIO is

completed.
+- If read, read out the data in THC_SW_SEQ_DATA0..THC_SW_SEQ_DATAn.

Documentation/hid/intel-thc-hid.rst new file +6 -0
+
+3.3 DMA
+-------
+
+THC has 4 DMA channels: Read DMA1, Read DMA2, Write DMA and
+Software

DMA.

Documentation/hid/intel-thc-hid.rst new file +5 -0
+
+3.3.1 Read DMA Channel
+~~~~~~~~~~~~~~~~~~~~~~
+
+THC has two Read DMA engines: 1st RxDMA (RxDMA1) and 2nd RxDMA

(RxDMA2). RxDMA1 is reserved for
+raw data mode. RxDMA2 is used for HID data mode and it is the RxDMA engine currently driver uses

Documentation/hid/intel-thc-hid.rst new file +3 -0
+for HID input report data retrieval.
+
+RxDMA's typical use case is auto receiving the data from Touch IC.

Once RxDMA is enabled by

Documentation/hid/intel-thc-hid.rst new file +3 -0
+software, THC will start auto-handling receiving logic.
+
+For SPI mode, THC RxDMA sequence is: when Touch IC triggers a

interrupt to THC, THC reads out
+report header to identify what's the report type, and what's the report length, according to
+above information, THC reads out report body to internal FIFO and start RxDMA coping the data
+to system memory. After that, THC update interrupt cause register with report type, and update

Documentation/hid/intel-thc-hid.rst new file +2 -0
+RxDMA PRD table read pointer, then trigger a MSI interrupt to
+notify

driver RxDMA finishing

Documentation/hid/intel-thc-hid.rst new file +3 -0
+data receiving.
+
+For I2C mode, THC RxDMA's behavior is a little bit different,

because of HIDI2C protocol difference
+with HIDSPI protocol, RxDMA only be used to receive input report. The sequence is, when Touch IC
+triggers a interrupt to THC, THC first reads out 2 bytes from input report address to determine the
+packet length, then use this packet length to start a DMA reading from input report address for
+input report data. After that, THC update RxDMA PRD table read pointer, then trigger a MSI interrupt

Documentation/hid/intel-thc-hid.rst new file +3 -0
+to notify driver input report data is ready in system memory.
+
+All above sequence is hardware automatically handled, all driver

needs to do is configure RxDMA and
+waiting for interrupt ready then read out the data from system memory.

Documentation/hid/intel-thc-hid.rst new file +6 -0
+
+3.3.2 Software DMA channel
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+THC supports a software triggerred RxDMA mode to read the touch
+data

from touch IC. This SW RxDMA
+is the 3rd THC RxDMA engine with the similar functionalities as the existing two RxDMAs, the only

Documentation/hid/intel-thc-hid.rst new file +2 -0
+difference is this SW RxDMA is triggerred by software, and RxDMA2
+is

triggerred by external Touch IC
+interrupt. It gives a flexiblity to software driver to use RxDMA read Touch IC data in any time.

Documentation/hid/intel-thc-hid.rst new file +2 -0
+
+Before software starts a SW RxDMA, it shall stop the 1st and 2nd

RxDMA, clear PRD read/write pointer
+and quiesce the device interrupt (THC_DEVINT_QUIESCE_HW_STS = 1), other operations are the same with

Documentation/hid/intel-thc-hid.rst new file +6 -0
+RxDMA.
+
+3.3.3 Write DMA Channel
+~~~~~~~~~~~~~~~~~~~~~~~
+
+THC has one write DMA engine, which can be used for sending data to

Touch IC automatically.

Documentation/hid/intel-thc-hid.rst new file +2 -0
+According to HIDSPI and HIDI2C protocol, every time only one
+command

can be sent to touch IC, and
+before last command is completely handled, next command cannot be sent, THC write DMA engine only

Documentation/hid/intel-thc-hid.rst new file +4 -0
+supports single PRD table.
+
+What driver needs to do is, preparing PRD table and DMA buffer,
+then

copy data to DMA buffer and
+update PRD table with buffer address and buffer length, then start write DMA. THC will
+automatically send the data to touch IC, and trigger a DMA completion interrupt once transferring

Documentation/hid/intel-thc-hid.rst new file +6 -0
+is done.
+
+3.4 PRD
+-------
+
+Physical Region Descriptor (PRD) provides the memory mapping

description for THC DMAs.

Documentation/hid/intel-thc-hid.rst new file +5 -0
+
+3.4.1 PRD table and entry
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In order to improve physical DMA memory usage, modern drivers trend

to allocate a virtually

Documentation/hid/intel-thc-hid.rst new file +2 -0
+contiguous, but physically fragmented buffer of memory for each
+data

buffer. Linux OS also

Documentation/hid/intel-thc-hid.rst new file +3 -0
+provide SGL (scatter gather list) APIs to support this usage.
+
+THC uses PRD table (physical region descriptor) to support the

corresponding OS kernel

Documentation/hid/intel-thc-hid.rst new file +16 -0
+SGL that describes the virtual to physical buffer mapping.
+
+::
+
+  ------------------------      --------------       --------------
+ | PRD table base address +----+ PRD table #1 +-----+ PRD Entry #1
+ | |
+  ------------------------      --------------       --------------
+                                                     --------------
+                                                    | PRD Entry #2 |
+                                                     --------------
+                                                     --------------
+                                                    | PRD Entry #n |
+                                                     --------------
+
+The read DMA engine supports multiple PRD tables held within a

circular buffer that allow the THC

Documentation/hid/intel-thc-hid.rst new file +2 -0
+to support multiple data buffers from the Touch IC. This allows
+host

SW to arm the Read DMA engine
+with multiple buffers, allowing the Touch IC to send multiple data frames to the THC without SW
+interaction. This capability is required when the CPU processes touch frames slower than the

Documentation/hid/intel-thc-hid.rst new file +3 -0
+Touch IC can send them.
+
+To simplify the design, SW assumes worst-case memory fragmentation.

Therefore,each PRD table shall
+contain the same number of PRD entries, allowing for a global register (per Touch IC) to hold the

Documentation/hid/intel-thc-hid.rst new file +3 -0
+number of PRD-entries per PRD table.
+
+SW allocates up to 128 PRD tables per Read DMA engine as specified

in the THC_M_PRT_RPRD_CNTRL.PCD
+register field. The number of PRD tables should equal the number of data buffers.

Documentation/hid/intel-thc-hid.rst new file +2 -0
+
+Max OS memory fragmentation will be at a 4KB boundary, thus to

address 1MB of virtually contiguous
+memory 256 PRD entries are required for a single PRD Table. SW writes the number of PRD entries
+for each PRD table in the THC_M_PRT_RPRD_CNTRL.PTEC register field. The PRD entry's length must be

Documentation/hid/intel-thc-hid.rst new file +3 -0
+multiple of 4KB except for the last entry in a PRD table.
+
+SW allocates all the data buffers and PRD tables only once at host

initialization.

Documentation/hid/intel-thc-hid.rst new file +5 -0
+
+3.4.2 PRD Write pointer and read pointer
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+As PRD tables are organized as a Circular Buffer (CB), a read

pointer and a write pointer for a CB

Documentation/hid/intel-thc-hid.rst new file +3 -0
+are needed.
+
+DMA HW consumes the PRD tables in the CB, one PRD entry at a time

until the EOP bit is found set
+in a PRD entry. At this point HW increments the PRD read pointer. Thus, the read pointer points
+to the PRD which the DMA engine is currently processing. This pointer rolls over once the circular
+buffer's depth has been traversed with bit[7] the Rollover bit. E.g. if the DMA CB depth is equal
+to 4 entries (0011b), then the read pointers will follow this pattern (HW is required to honor

Documentation/hid/intel-thc-hid.rst new file +3 -0
+this behavior): 00h 01h 02h 03h 80h 81h 82h 83h 00h 01h ...
+
+The write pointer is updated by SW. The write pointer points to

location in the DMA CB, where the
+next PRD table is going to be stored. SW needs to ensure that this pointer rolls over once the
+circular buffer's depth has been traversed with Bit[7] as the rollover bit. E.g. if the DMA CB
+depth is equal to 5 entries (0100b), then the write pointers will follow this pattern (SW is
+required to honor this behavior): 00h 01h 02h 03h 04h 80h 81h 82h 83h 84h 00h 01h ..

Documentation/hid/intel-thc-hid.rst new file +5 -0
+
+3.4.3 PRD descriptor structure
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Intel THC uses PRD entry descriptor for every PRD entry. Every PRD

entry descriptor occupies
+128 bits memories:
+
+=================== ========
===============================================
+struct field bit(s) description
+=================== ========
===============================================
+dest_addr 53..0 destination memory address, as
every entry
+ is 4KB, ignore lowest 10 bits of
address.

Documentation/hid/intel-thc-hid.rst new file +2 -0
+reserved1             54..62     reserved
+int_on_completion     63         completion interrupt enable bit, if

this bit
+ set it means THC will trigger a
completion
+ interrupt. This bit is set by SW
driver.
+len 87..64 how many bytes of data in this
entry.
+end_of_prd 88 end of PRD table bit, if this bit
is set,
+ it means this entry is last entry
in this PRD
+ table. This bit is set by SW
driver.

Documentation/hid/intel-thc-hid.rst new file +3 -0
+hw_status             90..89     HW status bits
+reserved2             127..91    reserved
+===================   ========

===============================================

Documentation/hid/intel-thc-hid.rst new file +2 -0
+
+And one PRD table can include up to 256 PRD entries, as every

entries is 4K bytes, so every

Documentation/hid/intel-thc-hid.rst new file +9 -0
+PRD table can describe 1M bytes memory.
+
+.. code-block:: c
+
+   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

Documentation/hid/intel-thc-hid.rst new file +7 -0
+each PRD table.
+
+4. HIDSPI support (QuickSPI)
+============================
+
+Intel THC is total compatible with HIDSPI protocol, THC HW
+sequenser

can accelerate HIDSPI

Documentation/hid/intel-thc-hid.rst new file +8 -0
+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.

Documentation/hid/intel-thc-hid.rst new file +7 -0
+
+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.

Documentation/hid/intel-thc-hid.rst new file +4 -0
+
+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),

Documentation/hid/intel-thc-hid.rst new file +5 -0
+  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

Documentation/hid/intel-thc-hid.rst new file +10 -0
+  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

Documentation/hid/intel-thc-hid.rst new file +10 -0
+  to THC's write DMA buffer.
+- Start TxDMA to complete the write operation.
+
+5. HIDI2C support (QuickI2C)
+============================
+
+5.1 Reset Flow
+--------------
+
+- Read device descriptor from Touch IC device through PIO write

followed by read.
+- If the device descriptor is valid, allocate DMA buffers and configure all DMA channels.
+- Use PIO or TxDMA to write a SET_POWER request to TIC's command register, and check if the
+ write operation is successfully completed.
+- Use PIO or TxDMA to write a RESET request to TIC's command register. If the write operation
+ is successfully completed, wait for reset response from TIC. +- Use SWDMA to read report descriptor through TIC's report descriptor register.

Documentation/hid/intel-thc-hid.rst new file +8 -0
+
+5.2 Input Report Data Flow
+--------------------------
+
+Basic Flow:
+
+- Touch IC asserts the interrupt indicating that it has an
+interrupt

to send to HOST.
+ THC Sequencer issues a READ request over the I2C bus. The HIDI2C device returns the
+ first 2 bytes from the HIDI2C device which contains the length of the received data.
+- THC Sequencer continues the Read operation as per the size of +data
indicated in the
+ length field.
+- 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. THC writes 2Bytes for length field
+ plus the remaining data to RxDMA buffer. 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).

+- THC Sequencer enters End-of-Input Report Processing.
+- If the device has no more input reports to send to the host, it

de-asserts the interrupt
+ line. For any additional input reports, device keeps the
+ interrupt
line asserted and

Documentation/hid/intel-thc-hid.rst new file +5 -0
+  steps 1 through 4 in the flow are repeated.
+
+THC Sequencer End of Input Report Processing:
+
+- THC DMA engine increments the read pointer of the Read PRD CB,

sets EOF interrupt status
+ in RxDMA 2 register (THC_M_PRT_READ_DMA_INT_STS_2). +- If THC EOF interrupt is enabled by the driver in the control register

Documentation/hid/intel-thc-hid.rst new file +5 -0
+  (THC_M_PRT_READ_DMA_CNTRL_2), generates interrupt to software.
+
+Sequence of steps to read data from RX DMA buffer:
+
+- THC QuickI2C driver checks CB write Ptr and CB read Ptr to

identify if any data frame in DMA
+ circular buffers.

+- THC QuickI2C driver gets first unprocessed PRD table.
+- THC QuickI2C driver scans all PRD entries in this PRD table to
calculate the total frame size.
+- THC QuickI2C driver copies all frame data out.
+- THC QuickI2C driver call hid_input_report to send the input

+report
content to HID core, which
+ includes Report ID + Report Data Content (remove the length field from the original report

Documentation/hid/intel-thc-hid.rst new file +10 -0
+  data).
+- THC QuickI2C driver updates write Ptr.
+
+5.3 Output Report Data Flow
+---------------------------
+
+Generic Output Report Flow:
+
+- HID core call THC QuickI2C raw_request callback.
+- THC QuickI2C uses PIO or TXDMA to write a SET_REPORT request to

TIC's command register. Report
+ type in SET_REPORT should be set to Output.
+- THC QuickI2C programs TxDMA buffer with TX Data to be written to TIC's data register. The first
+ 2 bytes should indicate the length of the report followed by the report contents including

Documentation/hid/intel-thc-hid.rst new file +6 -0
+  Report ID.
+
+6. THC Debugging
+================
+
+To debug THC, event tracing mechanism is used. To enable debug

logs::

Documentation/hid/intel-thc-hid.rst new file +7 -0
+
+  echo 1 > /sys/kernel/debug/tracing/events/intel_thc/enable
+  cat /sys/kernel/debug/tracing/trace
+
+7. Reference
+============
+- HIDSPI:

https://download.microsoft.com/download/c/a/0/ca07aef3-3e10-4022-b1e
9-c98cea99465d/HidSpiProtocolSpec.pdf
+- HIDI2C:
https://download.microsoft.com/download/7/d/d/7dd44bb7-2a7a-4505-ac1
c-7227d3d96d5b/hid-over-i2c-protocol-spec-v1-0.docx

Tested-by
#5 lore raw

Re: [PATCH v4 01/22] HID: THC: Add documentation

Hi Even and Ping,

Tested on Goodix and Wacom(include the enabling pci bus group in wacom driver), multitouch works (rotation and zoom in image viewer) fine on both touchscreen.

And Lenovo confirmed Goodix will provide new fw,
although no firmware from Goodix I can test, but root cause is not from THC driver.

I think the result of the test for this patchset is good.

Aaron

Quoted 886 lines · Even

hi, Aaron,

This issue was identified to Goodix touch firmware issue, it de-asserted interrupt line delayed. And Goodix engineer configured there were 10us delay at end of every touch event packet. They are working on it to modify the firmware for the fix.

Maybe you can get updated engineer firmware from Lenovo.

Thanks!

Best Regards,
Even Xu

Quoted 873 lines

-----Original Message-----
From: Ping Cheng <[email protected]>
Sent: Thursday, January 9, 2025 1:18 PM
To: srinivas pandruvada <[email protected]>; Aaron, Ma <[email protected]>; Ivan Delos Santos Julkarnain, Ameer <[email protected]>
Cc: Xu, Even <[email protected]>; [email protected]; [email protected]; [email protected]; [email protected]; [email protected]; mpearson- [email protected]; [email protected]; [email protected]; [email protected]; Sun, Xinpeng <[email protected]>
Subject: Re: [PATCH v4 01/22] HID: THC: Add documentation

Hi Srinivas,

As mentioned offline, the cover letter and version log are in v4 00/22.

Hi Aaron,

As far as I know, the issue you brought up at v3 only happens with Goodix devices. It's Goodix specific. Other devices don't have the issue. Wacom confirmed that with Wacom devices.

Can you work with the Lenovo team to confirm that so we can get this patchset accepted?

Thank you for your support,
Ping

Quoted 843 lines · srinivas pandruvada
Quoted 11 lines · Even Xu

Add Documentation/hid/intel-thc-hid.rst file to provide hardware and software detail for intel THC drivers.

Reviewed-by Srinivas Pandruvada

<[email protected]>

---

Change logs are missing?
Also didn't receive any cover letter with any changes?

Thanks,
Srinivas

Quoted 821 lines
  Documentation/hid/index.rst         |   1 +
  Documentation/hid/intel-thc-hid.rst | 568
++++++++++++++++++++++++++++
  2 files changed, 569 insertions(+)

create mode 100644 Documentation/hid/intel-thc-hid.rst

(quoted diff) +0 -0

b/Documentation/hid/index.rst index af02cf7cfa82..baf156b44b58 100644

Documentation/hid/index.rst +1 -0
@@ -18,4 +18,5 @@ Human Interface Devices (HID)
 
     hid-alps
     intel-ish-hid
+   intel-thc-hid
     amd-sfh-hid
Documentation/hid/intel-thc-hid.rst new file +7 -0
new file mode 100644
index 000000000000..6c417205ac6a
@@ -0,0 +1,568 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=================================
+Intel Touch Host Controller (THC)
+=================================
+
+Touch Host Controller is the name of the IP block in PCH that

interface with Touch Devices (ex:
+touchscreen, touchpad etc.). It is comprised of 3 key functional blocks:

Documentation/hid/intel-thc-hid.rst new file +6 -0
+
+- A natively half-duplex Quad I/O capable SPI master
+- Low latency I2C interface to support HIDI2C compliant devices
+- A HW sequencer with RW DMA capability to system memory
+
+It has a single root space IOSF Primary interface that supports

transactions to/from touch devices.
+Host driver configures and controls the touch devices over THC interface. THC provides high
+bandwidth DMA services to the touch driver and transfers the HID report to host system main memory.

Documentation/hid/intel-thc-hid.rst new file +2 -0
+
+Hardware sequencer within the THC is responsible for transferring

(via DMA) data from touch devices
+into system memory. A ring buffer is used to avoid data loss due to asynchronous nature of data
+consumption (by host) in relation to data production (by touch device via DMA).

Documentation/hid/intel-thc-hid.rst new file +2 -0
+
+Unlike other common SPI/I2C controllers, THC handles the HID device

data interrupt and reset

Documentation/hid/intel-thc-hid.rst new file +9 -0
+signals directly.
+
+1. Overview
+===========
+
+1.1 THC software/hardware stack
+-------------------------------
+
+Below diagram illustrates the high-level architecture of THC

software/hardware stack, which is fully

Documentation/hid/intel-thc-hid.rst new file +37 -0
+capable of supporting HIDSPI/HIDI2C protocol in Linux OS.
+
+::
+
+  ----------------------------------------------
+ |      +-----------------------------------+   |
+ |      |           Input Device            |   |
+ |      +-----------------------------------+   |
+ |      +-----------------------------------+   |
+ |      |       HID Multi-touch Driver      |   |
+ |      +-----------------------------------+   |
+ |      +-----------------------------------+   |
+ |      |             HID Core              |   |
+ |      +-----------------------------------+   |
+ |      +-----------------------------------+   |
+ |      |    THC QuickSPI/QuickI2C Driver   |   |
+ |      +-----------------------------------+   |
+ |      +-----------------------------------+   |
+ |      |      THC Hardware Driver          |   |
+ |      +-----------------------------------+   |
+ |      +----------------+ +----------------+   |
+ |  SW  | PCI Bus Driver | | ACPI Resource  |   |
+ |      +----------------+ +----------------+   |
+  ----------------------------------------------
+  ----------------------------------------------
+ |      +-----------------------------------+   |
+ |  HW  |              PCI Bus              |   |
+ |      +-----------------------------------+   |
+ |      +-----------------------------------+   |
+ |      |           THC Controller          |   |
+ |      +-----------------------------------+   |
+ |      +-----------------------------------+   |
+ |      |              Touch IC             |   |
+ |      +-----------------------------------+   |
+  ----------------------------------------------
+
+Touch IC (TIC), also as known as the Touch devices (touchscreen or

touchpad). The discrete analog
+components that sense and transfer either discrete touch data or heatmap data in the form of HID

Documentation/hid/intel-thc-hid.rst new file +3 -0
+reports over the SPI/I2C bus to the THC Controller on the host.
+
+THC Host Controller, which is a PCI device HBA (host bus adapter),

integrated into the PCH, that

Documentation/hid/intel-thc-hid.rst new file +3 -0
+serves as a bridge between the Touch ICs and the host.
+
+THC Hardware Driver, provides THC hardware operation APIs for above

QuickSPI/QuickI2C driver, it

Documentation/hid/intel-thc-hid.rst new file +4 -0
+accesses THC MMIO registers to configure and control THC hardware.
+
+THC QuickSPI/QuickI2C driver, also as known as HIDSPI/HIDI2C
+driver,

is registered as a HID
+low-level driver that manages the THC Controller and implements HIDSPI/HIDI2C protocol.

Documentation/hid/intel-thc-hid.rst new file +27 -0
+
+
+1.2 THC hardware diagram
+------------------------
+Below diagram shows THC hardware components::
+
+                      ---------------------------------
+                     |          THC Controller         |
+                     |  +---------------------------+  |
+                     |  |     PCI Config Space      |  |
+                     |  +---------------------------+  |
+                     |  +---------------------------+  |
+                     |  +       MMIO Registers      |  |
+                     |  +---------------------------+  |
+ +---------------+   |  +------------+ +------------+  |
+ | System Memory +---+--+      DMA   | |   PIO      |  |
+ +---------------+   |  +------------+ +------------+  |
+                     |  +---------------------------+  |
+                     |  |       HW Sequencer        |  |
+                     |  +---------------------------+  |
+                     |  +------------+ +------------+  |
+                     |  |  SPI/I2C   | |    GPIO    |  |
+                     |  | Controller | | Controller |  |
+                     |  +------------+ +------------+  |
+                      ---------------------------------
+
+As THC is exposed as a PCI devices, so it has standard PCI config

space registers for PCI

Documentation/hid/intel-thc-hid.rst new file +3 -0
+enumeration and configuration.
+
+MMIO Registers, which provide registers access for driver to

configure and control THC hardware,
+the registers include several categories: Interrupt status and control, DMA configure,

Documentation/hid/intel-thc-hid.rst new file +2 -0
+PIO (Programmed I/O, defined in section 3.2) status and control,
+SPI

bus configure, I2C subIP

Documentation/hid/intel-thc-hid.rst new file +3 -0
+status and control, reset status and control...
+
+THC provides two ways for driver to communicate with external Touch

ICs: PIO and DMA.
+PIO can let driver manually write/read data to/from Touch ICs, instead, THC DMA can

Documentation/hid/intel-thc-hid.rst new file +4 -0
+automatically write/read data without driver involved.
+
+HW Sequencer includes THC major logic, it gets instruction from
+MMIO

registers to control
+SPI bus and I2C bus to finish a bus data transaction, it also can automatically handle
+Touch ICs interrupt and start DMA receive/send data from/to Touch ICs according to interrupt

Documentation/hid/intel-thc-hid.rst new file +2 -0
+type. That means THC HW Sequencer understands HIDSPI/HIDI2C
+transfer

protocol, and handle
+the communication without driver involved, what driver needs to do is just configure the THC
+properly, and prepare the formatted data packet or handle received data packet.

Documentation/hid/intel-thc-hid.rst new file +2 -0
+
+As THC supports HIDSPI/HIDI2C protocols, it has SPI controller and

I2C subIP in it to expose
+SPI bus and I2C bus. THC also integrates a GPIO controller to provide interrupt line support

Documentation/hid/intel-thc-hid.rst new file +9 -0
+and reset line support.
+
+2. THC Hardware Interface
+=========================
+
+2.1 Host Interface
+------------------
+
+THC is exposed as "PCI Digitizer device" to the host. The PCI

product and device IDs are

Documentation/hid/intel-thc-hid.rst new file +2 -0
+changed from different generations of processors. So the source
+code

which enumerates drivers

Documentation/hid/intel-thc-hid.rst new file +7 -0
+needs to update from generation to generation.
+
+
+2.2 Device Interface
+--------------------
+
+THC supports two types of bus for Touch IC connection: Enhanced SPI

bus and I2C bus.

Documentation/hid/intel-thc-hid.rst new file +5 -0
+
+2.2.1 SPI Port
+~~~~~~~~~~~~~~
+
+When PORT_TYPE = 00b in MMIO registers, THC uses SPI interfaces to

communicate with external
+Touch IC. THC enhanced SPI Bus supports different SPI modes:
standard Single IO mode,

Documentation/hid/intel-thc-hid.rst new file +3 -0
+Dual IO mode and Quad IO mode.
+
+In Single IO mode, THC drives MOSI line to send data to Touch ICs,

and receives data from Touch
+ICs data from MISO line. In Dual IO mode, THC drivers MOSI and MISO both for data sending, and
+also receives the data on both line. In Quad IO mode, there are other two lines (IO2 and IO3)
+are added, THC drives MOSI (IO0), MISO (IO1), IO2 and IO3 at the same time for data sending, and
+also receives the data on those 4 lines. Driver needs to configure THC in different mode by

Documentation/hid/intel-thc-hid.rst new file +3 -0
+setting different opcode.
+
+Beside IO mode, driver also needs to configure SPI bus speed. THC

supports up to 42MHz SPI clock

Documentation/hid/intel-thc-hid.rst new file +16 -0
+on Intel Lunar Lake platform.
+
+For THC sending data to Touch IC, the data flow on SPI bus::
+
+ | --------------------THC sends---------------------------------|
+ <8Bits OPCode><24Bits Slave Address><Data><Data><Data>...........
+
+For THC receiving data from Touch IC, the data flow on SPI bus::
+
+ | ---------THC Sends---------------||-----Touch IC sends--------|
+ <8Bits OPCode><24Bits Slave Address><Data><Data><Data>...........
+
+2.2.2 I2C Port
+~~~~~~~~~~~~~~
+
+THC also integrates I2C controller in it, it's called I2C SubSystem.

When PORT_TYPE = 01, THC
+is configured to I2C mode. Comparing to SPI mode which can be configured through MMIO registers
+directly, THC needs to use PIO read (by setting SubIP read opcode) to I2C subIP APB registers'
+value and use PIO write (by setting SubIP write opcode) to do a write operation.

Documentation/hid/intel-thc-hid.rst new file +6 -0
+
+2.2.3 GPIO interface
+~~~~~~~~~~~~~~~~~~~~
+
+THC also includes two GPIO pins, one for interrupt and the other
+for

device reset control.

Documentation/hid/intel-thc-hid.rst new file +2 -0
+
+Interrupt line can be configured to either level triggerred or edge

triggerred by setting MMIO

Documentation/hid/intel-thc-hid.rst new file +3 -0
+Control register.
+
+Reset line is controlled by BIOS (or EFI) through ACPI _RST method,

driver needs to call this

Documentation/hid/intel-thc-hid.rst new file +9 -0
+device ACPI _RST method to reset touch IC during initialization.
+
+3. High level concept
+=====================
+
+3.1 Opcode
+----------
+
+Opcode (operation code) is used to tell THC or Touch IC what the

operation will be, such as PIO

Documentation/hid/intel-thc-hid.rst new file +4 -0
+read or PIO write.
+
+When THC is configured to SPI mode, opcodes are used for
+determining

the read/write IO mode.

Documentation/hid/intel-thc-hid.rst new file +14 -0
+There are some OPCode examples for SPI IO mode:
+
+=======   ==============================
+opcode    Corresponding SPI command
+=======   ==============================
+0x0B      Read Single I/O
+0x02      Write Single I/O
+0xBB      Read Dual I/O
+0xB2      Write Dual I/O
+0xEB      Read Quad I/O
+0xE2      Write Quad I/O
+=======   ==============================
+
+In general, different touch IC has different OPCode definition.

According to HIDSPI

Documentation/hid/intel-thc-hid.rst new file +2 -0
+protocol whitepaper, those OPCodes are defined in device ACPI
+table,

and driver needs to
+query those information through OS ACPI APIs during driver initialization, then configures

Documentation/hid/intel-thc-hid.rst new file +4 -0
+THC MMIO OPCode registers with correct setting.
+
+When THC is working in I2C mode, opcodes are used to tell THC
+what's

the next PIO type:

Documentation/hid/intel-thc-hid.rst new file +2 -0
+I2C SubIP APB register read, I2C SubIP APB register write, I2C
+touch

IC device read,
+I2C touch IC device write, I2C touch IC device write followed by read.

Documentation/hid/intel-thc-hid.rst new file +4 -0
+
+Here are the THC pre-defined opcodes for I2C mode:
+
+=======   ===================================================

===========
+opcode Corresponding I2C command
Address
+======= ===================================================
===========
+0x12 Read I2C SubIP APB internal registers 0h -
FFh
+0x13 Write I2C SubIP APB internal registers 0h -
FFh

+0x14      Read external Touch IC through I2C bus                N/A
+0x18      Write external Touch IC through I2C bus               N/A
+0x1C      Write then read external Touch IC through I2C bus     N/A
+=======   ===================================================

===========

Documentation/hid/intel-thc-hid.rst new file +5 -0
+
+3.2 PIO
+-------
+
+THC provides a programmed I/O (PIO) access interface for the driver

to access the touch IC's
+configuration registers, or access I2C subIP's configuration registers. To use PIO to perform
+I/O operations, driver should pre-program PIO control registers and PIO data registers and kick
+off the sequencing cycle. THC uses different PIO opcodes to distinguish different PIO

Documentation/hid/intel-thc-hid.rst new file +4 -0
+operations (PIO read/write/write followed by read).
+
+If there is a Sequencing Cycle In Progress and an attempt is made
+to

program any of the control,
+address, or data register the cycle is blocked and a sequence error will be encountered.

Documentation/hid/intel-thc-hid.rst new file +2 -0
+
+A status bit indicates when the cycle has completed allowing the

driver to know when read results
+can be checked and/or when to initiate a new command. If enabled, the cycle done assertion can

Documentation/hid/intel-thc-hid.rst new file +3 -0
+interrupt driver with an interrupt.
+
+Because THC only has 16 FIFO registers for PIO, so all the data

transfer through PIO shouldn't

Documentation/hid/intel-thc-hid.rst new file +4 -0
+exceed 64 bytes.
+
+As DMA needs max packet size for transferring configuration, and
+the

max packet size information
+always in HID device descriptor which needs THC driver to read it out from HID Device (Touch IC).
+So PIO typical use case is, before DMA initialization, write RESET command (PIO write), read

Documentation/hid/intel-thc-hid.rst new file +2 -0
+RESET response (PIO read or PIO write followed by read), write
+Power

ON command (PIO write), read

Documentation/hid/intel-thc-hid.rst new file +3 -0
+device descriptor (PIO read).
+
+For how to issue a PIO operation, here is the steps which driver

needs follow:
+

+- Program read/write data size in THC_SS_BC.
+- Program I/O target address in THC_SW_SEQ_DATA0_ADDR.
+- If write, program the write data in
THC_SW_SEQ_DATA0..THC_SW_SEQ_DATAn.
+- Program the PIO opcode in THC_SS_CMD.
+- Set TSSGO = 1 to start the PIO write sequence.
+- If THC_SS_CD_IE = 1, SW will receives a MSI when the PIO is

completed.
+- If read, read out the data in THC_SW_SEQ_DATA0..THC_SW_SEQ_DATAn.

Documentation/hid/intel-thc-hid.rst new file +6 -0
+
+3.3 DMA
+-------
+
+THC has 4 DMA channels: Read DMA1, Read DMA2, Write DMA and
+Software

DMA.

Documentation/hid/intel-thc-hid.rst new file +5 -0
+
+3.3.1 Read DMA Channel
+~~~~~~~~~~~~~~~~~~~~~~
+
+THC has two Read DMA engines: 1st RxDMA (RxDMA1) and 2nd RxDMA

(RxDMA2). RxDMA1 is reserved for
+raw data mode. RxDMA2 is used for HID data mode and it is the RxDMA engine currently driver uses

Documentation/hid/intel-thc-hid.rst new file +3 -0
+for HID input report data retrieval.
+
+RxDMA's typical use case is auto receiving the data from Touch IC.

Once RxDMA is enabled by

Documentation/hid/intel-thc-hid.rst new file +3 -0
+software, THC will start auto-handling receiving logic.
+
+For SPI mode, THC RxDMA sequence is: when Touch IC triggers a

interrupt to THC, THC reads out
+report header to identify what's the report type, and what's the report length, according to
+above information, THC reads out report body to internal FIFO and start RxDMA coping the data
+to system memory. After that, THC update interrupt cause register with report type, and update

Documentation/hid/intel-thc-hid.rst new file +2 -0
+RxDMA PRD table read pointer, then trigger a MSI interrupt to
+notify

driver RxDMA finishing

Documentation/hid/intel-thc-hid.rst new file +3 -0
+data receiving.
+
+For I2C mode, THC RxDMA's behavior is a little bit different,

because of HIDI2C protocol difference
+with HIDSPI protocol, RxDMA only be used to receive input report. The sequence is, when Touch IC
+triggers a interrupt to THC, THC first reads out 2 bytes from input report address to determine the
+packet length, then use this packet length to start a DMA reading from input report address for
+input report data. After that, THC update RxDMA PRD table read pointer, then trigger a MSI interrupt

Documentation/hid/intel-thc-hid.rst new file +3 -0
+to notify driver input report data is ready in system memory.
+
+All above sequence is hardware automatically handled, all driver

needs to do is configure RxDMA and
+waiting for interrupt ready then read out the data from system memory.

Documentation/hid/intel-thc-hid.rst new file +6 -0
+
+3.3.2 Software DMA channel
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+THC supports a software triggerred RxDMA mode to read the touch
+data

from touch IC. This SW RxDMA
+is the 3rd THC RxDMA engine with the similar functionalities as the existing two RxDMAs, the only

Documentation/hid/intel-thc-hid.rst new file +2 -0
+difference is this SW RxDMA is triggerred by software, and RxDMA2
+is

triggerred by external Touch IC
+interrupt. It gives a flexiblity to software driver to use RxDMA read Touch IC data in any time.

Documentation/hid/intel-thc-hid.rst new file +2 -0
+
+Before software starts a SW RxDMA, it shall stop the 1st and 2nd

RxDMA, clear PRD read/write pointer
+and quiesce the device interrupt (THC_DEVINT_QUIESCE_HW_STS = 1), other operations are the same with

Documentation/hid/intel-thc-hid.rst new file +6 -0
+RxDMA.
+
+3.3.3 Write DMA Channel
+~~~~~~~~~~~~~~~~~~~~~~~
+
+THC has one write DMA engine, which can be used for sending data to

Touch IC automatically.

Documentation/hid/intel-thc-hid.rst new file +2 -0
+According to HIDSPI and HIDI2C protocol, every time only one
+command

can be sent to touch IC, and
+before last command is completely handled, next command cannot be sent, THC write DMA engine only

Documentation/hid/intel-thc-hid.rst new file +4 -0
+supports single PRD table.
+
+What driver needs to do is, preparing PRD table and DMA buffer,
+then

copy data to DMA buffer and
+update PRD table with buffer address and buffer length, then start write DMA. THC will
+automatically send the data to touch IC, and trigger a DMA completion interrupt once transferring

Documentation/hid/intel-thc-hid.rst new file +6 -0
+is done.
+
+3.4 PRD
+-------
+
+Physical Region Descriptor (PRD) provides the memory mapping

description for THC DMAs.

Documentation/hid/intel-thc-hid.rst new file +5 -0
+
+3.4.1 PRD table and entry
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In order to improve physical DMA memory usage, modern drivers trend

to allocate a virtually

Documentation/hid/intel-thc-hid.rst new file +2 -0
+contiguous, but physically fragmented buffer of memory for each
+data

buffer. Linux OS also

Documentation/hid/intel-thc-hid.rst new file +3 -0
+provide SGL (scatter gather list) APIs to support this usage.
+
+THC uses PRD table (physical region descriptor) to support the

corresponding OS kernel

Documentation/hid/intel-thc-hid.rst new file +16 -0
+SGL that describes the virtual to physical buffer mapping.
+
+::
+
+  ------------------------      --------------       --------------
+ | PRD table base address +----+ PRD table #1 +-----+ PRD Entry #1
+ | |
+  ------------------------      --------------       --------------
+                                                     --------------
+                                                    | PRD Entry #2 |
+                                                     --------------
+                                                     --------------
+                                                    | PRD Entry #n |
+                                                     --------------
+
+The read DMA engine supports multiple PRD tables held within a

circular buffer that allow the THC

Documentation/hid/intel-thc-hid.rst new file +2 -0
+to support multiple data buffers from the Touch IC. This allows
+host

SW to arm the Read DMA engine
+with multiple buffers, allowing the Touch IC to send multiple data frames to the THC without SW
+interaction. This capability is required when the CPU processes touch frames slower than the

Documentation/hid/intel-thc-hid.rst new file +3 -0
+Touch IC can send them.
+
+To simplify the design, SW assumes worst-case memory fragmentation.

Therefore,each PRD table shall
+contain the same number of PRD entries, allowing for a global register (per Touch IC) to hold the

Documentation/hid/intel-thc-hid.rst new file +3 -0
+number of PRD-entries per PRD table.
+
+SW allocates up to 128 PRD tables per Read DMA engine as specified

in the THC_M_PRT_RPRD_CNTRL.PCD
+register field. The number of PRD tables should equal the number of data buffers.

Documentation/hid/intel-thc-hid.rst new file +2 -0
+
+Max OS memory fragmentation will be at a 4KB boundary, thus to

address 1MB of virtually contiguous
+memory 256 PRD entries are required for a single PRD Table. SW writes the number of PRD entries
+for each PRD table in the THC_M_PRT_RPRD_CNTRL.PTEC register field. The PRD entry's length must be

Documentation/hid/intel-thc-hid.rst new file +3 -0
+multiple of 4KB except for the last entry in a PRD table.
+
+SW allocates all the data buffers and PRD tables only once at host

initialization.

Documentation/hid/intel-thc-hid.rst new file +5 -0
+
+3.4.2 PRD Write pointer and read pointer
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+As PRD tables are organized as a Circular Buffer (CB), a read

pointer and a write pointer for a CB

Documentation/hid/intel-thc-hid.rst new file +3 -0
+are needed.
+
+DMA HW consumes the PRD tables in the CB, one PRD entry at a time

until the EOP bit is found set
+in a PRD entry. At this point HW increments the PRD read pointer. Thus, the read pointer points
+to the PRD which the DMA engine is currently processing. This pointer rolls over once the circular
+buffer's depth has been traversed with bit[7] the Rollover bit. E.g. if the DMA CB depth is equal
+to 4 entries (0011b), then the read pointers will follow this pattern (HW is required to honor

Documentation/hid/intel-thc-hid.rst new file +3 -0
+this behavior): 00h 01h 02h 03h 80h 81h 82h 83h 00h 01h ...
+
+The write pointer is updated by SW. The write pointer points to

location in the DMA CB, where the
+next PRD table is going to be stored. SW needs to ensure that this pointer rolls over once the
+circular buffer's depth has been traversed with Bit[7] as the rollover bit. E.g. if the DMA CB
+depth is equal to 5 entries (0100b), then the write pointers will follow this pattern (SW is
+required to honor this behavior): 00h 01h 02h 03h 04h 80h 81h 82h 83h 84h 00h 01h ..

Documentation/hid/intel-thc-hid.rst new file +5 -0
+
+3.4.3 PRD descriptor structure
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Intel THC uses PRD entry descriptor for every PRD entry. Every PRD

entry descriptor occupies
+128 bits memories:
+
+=================== ========
===============================================
+struct field bit(s) description
+=================== ========
===============================================
+dest_addr 53..0 destination memory address, as
every entry
+ is 4KB, ignore lowest 10 bits of
address.

Documentation/hid/intel-thc-hid.rst new file +2 -0
+reserved1             54..62     reserved
+int_on_completion     63         completion interrupt enable bit, if

this bit
+ set it means THC will trigger a
completion
+ interrupt. This bit is set by SW
driver.
+len 87..64 how many bytes of data in this
entry.
+end_of_prd 88 end of PRD table bit, if this bit
is set,
+ it means this entry is last entry
in this PRD
+ table. This bit is set by SW
driver.

Documentation/hid/intel-thc-hid.rst new file +3 -0
+hw_status             90..89     HW status bits
+reserved2             127..91    reserved
+===================   ========

===============================================

Documentation/hid/intel-thc-hid.rst new file +2 -0
+
+And one PRD table can include up to 256 PRD entries, as every

entries is 4K bytes, so every

Documentation/hid/intel-thc-hid.rst new file +9 -0
+PRD table can describe 1M bytes memory.
+
+.. code-block:: c
+
+   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

Documentation/hid/intel-thc-hid.rst new file +7 -0
+each PRD table.
+
+4. HIDSPI support (QuickSPI)
+============================
+
+Intel THC is total compatible with HIDSPI protocol, THC HW
+sequenser

can accelerate HIDSPI

Documentation/hid/intel-thc-hid.rst new file +8 -0
+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.

Documentation/hid/intel-thc-hid.rst new file +7 -0
+
+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.

Documentation/hid/intel-thc-hid.rst new file +4 -0
+
+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),

Documentation/hid/intel-thc-hid.rst new file +5 -0
+  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

Documentation/hid/intel-thc-hid.rst new file +10 -0
+  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

Documentation/hid/intel-thc-hid.rst new file +10 -0
+  to THC's write DMA buffer.
+- Start TxDMA to complete the write operation.
+
+5. HIDI2C support (QuickI2C)
+============================
+
+5.1 Reset Flow
+--------------
+
+- Read device descriptor from Touch IC device through PIO write

followed by read.
+- If the device descriptor is valid, allocate DMA buffers and configure all DMA channels.
+- Use PIO or TxDMA to write a SET_POWER request to TIC's command register, and check if the
+ write operation is successfully completed.
+- Use PIO or TxDMA to write a RESET request to TIC's command register. If the write operation
+ is successfully completed, wait for reset response from TIC. +- Use SWDMA to read report descriptor through TIC's report descriptor register.

Documentation/hid/intel-thc-hid.rst new file +8 -0
+
+5.2 Input Report Data Flow
+--------------------------
+
+Basic Flow:
+
+- Touch IC asserts the interrupt indicating that it has an
+interrupt

to send to HOST.
+ THC Sequencer issues a READ request over the I2C bus. The HIDI2C device returns the
+ first 2 bytes from the HIDI2C device which contains the length of the received data.
+- THC Sequencer continues the Read operation as per the size of +data
indicated in the
+ length field.
+- 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. THC writes 2Bytes for length field
+ plus the remaining data to RxDMA buffer. 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).

+- THC Sequencer enters End-of-Input Report Processing.
+- If the device has no more input reports to send to the host, it

de-asserts the interrupt
+ line. For any additional input reports, device keeps the
+ interrupt
line asserted and

Documentation/hid/intel-thc-hid.rst new file +5 -0
+  steps 1 through 4 in the flow are repeated.
+
+THC Sequencer End of Input Report Processing:
+
+- THC DMA engine increments the read pointer of the Read PRD CB,

sets EOF interrupt status
+ in RxDMA 2 register (THC_M_PRT_READ_DMA_INT_STS_2). +- If THC EOF interrupt is enabled by the driver in the control register

Documentation/hid/intel-thc-hid.rst new file +5 -0
+  (THC_M_PRT_READ_DMA_CNTRL_2), generates interrupt to software.
+
+Sequence of steps to read data from RX DMA buffer:
+
+- THC QuickI2C driver checks CB write Ptr and CB read Ptr to

identify if any data frame in DMA
+ circular buffers.

+- THC QuickI2C driver gets first unprocessed PRD table.
+- THC QuickI2C driver scans all PRD entries in this PRD table to
calculate the total frame size.
+- THC QuickI2C driver copies all frame data out.
+- THC QuickI2C driver call hid_input_report to send the input

+report
content to HID core, which
+ includes Report ID + Report Data Content (remove the length field from the original report

Documentation/hid/intel-thc-hid.rst new file +10 -0
+  data).
+- THC QuickI2C driver updates write Ptr.
+
+5.3 Output Report Data Flow
+---------------------------
+
+Generic Output Report Flow:
+
+- HID core call THC QuickI2C raw_request callback.
+- THC QuickI2C uses PIO or TXDMA to write a SET_REPORT request to

TIC's command register. Report
+ type in SET_REPORT should be set to Output.
+- THC QuickI2C programs TxDMA buffer with TX Data to be written to TIC's data register. The first
+ 2 bytes should indicate the length of the report followed by the report contents including

Documentation/hid/intel-thc-hid.rst new file +6 -0
+  Report ID.
+
+6. THC Debugging
+================
+
+To debug THC, event tracing mechanism is used. To enable debug

logs::

Documentation/hid/intel-thc-hid.rst new file +7 -0
+
+  echo 1 > /sys/kernel/debug/tracing/events/intel_thc/enable
+  cat /sys/kernel/debug/tracing/trace
+
+7. Reference
+============
+- HIDSPI:

https://download.microsoft.com/download/c/a/0/ca07aef3-3e10-4022-b1e
9-c98cea99465d/HidSpiProtocolSpec.pdf
+- HIDI2C:
https://download.microsoft.com/download/7/d/d/7dd44bb7-2a7a-4505-ac1
c-7227d3d96d5b/hid-over-i2c-protocol-spec-v1-0.docx

author maintainer
#6 lore raw

RE: [PATCH v4 01/22] HID: THC: Add documentation

Hi, Aaron,

Thanks for the testing and confirmation!

Best Regards,
Even Xu

Quoted 939 lines

-----Original Message-----
From: Aaron Ma <[email protected]>
Sent: Thursday, January 9, 2025 2:03 PM
To: Xu, Even <[email protected]>; Ping Cheng <[email protected]>; srinivas pandruvada <[email protected]>; Ivan Delos Santos Julkarnain, Ameer <[email protected]>
Cc: [email protected]; [email protected]; [email protected]; [email protected]; [email protected]; [email protected]; [email protected]; [email protected]; linux- [email protected]; Sun, Xinpeng <[email protected]>
Subject: Re: [PATCH v4 01/22] HID: THC: Add documentation

Hi Even and Ping,

Tested on Goodix and Wacom(include the enabling pci bus group in wacom driver), multitouch works (rotation and zoom in image viewer) fine on both touchscreen.

And Lenovo confirmed Goodix will provide new fw, although no firmware from Goodix I can test, but root cause is not from THC driver.

I think the result of the test for this patchset is good.

Aaron

Quoted 3 lines · Even

hi, Aaron,

This issue was identified to Goodix touch firmware issue, it de-asserted

interrupt line delayed.

Quoted 1 line

And Goodix engineer configured there were 10us delay at end of every touch

event packet.

Quoted 29 lines

They are working on it to modify the firmware for the fix.

Maybe you can get updated engineer firmware from Lenovo.

Thanks!

Best Regards,
Even Xu

Quoted 20 lines

-----Original Message-----
From: Ping Cheng <[email protected]>
Sent: Thursday, January 9, 2025 1:18 PM
To: srinivas pandruvada <[email protected]>; Aaron, Ma <[email protected]>; Ivan Delos Santos Julkarnain, Ameer <[email protected]>
Cc: Xu, Even <[email protected]>; [email protected]; [email protected]; [email protected]; [email protected]; [email protected]; mpearson- [email protected]; [email protected]; [email protected]; [email protected]; Sun, Xinpeng <[email protected]>
Subject: Re: [PATCH v4 01/22] HID: THC: Add documentation

Hi Srinivas,

As mentioned offline, the cover letter and version log are in v4 00/22.

Hi Aaron,

As far as I know, the issue you brought up at v3 only happens with Goodix

devices.

Quoted 875 lines
Quoted 875 lines

It's Goodix specific. Other devices don't have the issue. Wacom confirmed that with Wacom devices.

Can you work with the Lenovo team to confirm that so we can get this patchset accepted?

Thank you for your support,
Ping

Quoted 864 lines · srinivas pandruvada
Quoted 11 lines · Even Xu

Add Documentation/hid/intel-thc-hid.rst file to provide hardware and software detail for intel THC drivers.

Reviewed-by Srinivas Pandruvada

<[email protected]>

---

Change logs are missing?
Also didn't receive any cover letter with any changes?

Thanks,
Srinivas

Quoted 842 lines
  Documentation/hid/index.rst         |   1 +
  Documentation/hid/intel-thc-hid.rst | 568
++++++++++++++++++++++++++++
  2 files changed, 569 insertions(+)

create mode 100644 Documentation/hid/intel-thc-hid.rst

(quoted diff) +0 -0

b/Documentation/hid/index.rst index af02cf7cfa82..baf156b44b58 100644

Documentation/hid/index.rst +1 -0
@@ -18,4 +18,5 @@ Human Interface Devices (HID)
 
     hid-alps
     intel-ish-hid
+   intel-thc-hid
     amd-sfh-hid
Documentation/hid/intel-thc-hid.rst new file +7 -0
new file mode 100644
index 000000000000..6c417205ac6a
@@ -0,0 +1,568 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=================================
+Intel Touch Host Controller (THC)
+=================================
+
+Touch Host Controller is the name of the IP block in PCH that

interface with Touch Devices (ex:
+touchscreen, touchpad etc.). It is comprised of 3 key functional blocks:

Documentation/hid/intel-thc-hid.rst new file +6 -0
+
+- A natively half-duplex Quad I/O capable SPI master
+- Low latency I2C interface to support HIDI2C compliant devices
+- A HW sequencer with RW DMA capability to system memory
+
+It has a single root space IOSF Primary interface that supports

transactions to/from touch devices.
+Host driver configures and controls the touch devices over THC interface. THC provides high
+bandwidth DMA services to the touch driver and transfers the HID report to host system main memory.

Documentation/hid/intel-thc-hid.rst new file +2 -0
+
+Hardware sequencer within the THC is responsible for transferring

(via DMA) data from touch devices

Documentation/hid/intel-thc-hid.rst new file +2 -0
+into system memory. A ring buffer is used to avoid data loss due
+to

asynchronous nature of data
+consumption (by host) in relation to data production (by touch device via DMA).

Documentation/hid/intel-thc-hid.rst new file +3 -0
+
+Unlike other common SPI/I2C controllers, THC handles the HID
+device

data interrupt and reset

Documentation/hid/intel-thc-hid.rst new file +9 -0
+signals directly.
+
+1. Overview
+===========
+
+1.1 THC software/hardware stack
+-------------------------------
+
+Below diagram illustrates the high-level architecture of THC

software/hardware stack, which is fully

Documentation/hid/intel-thc-hid.rst new file +37 -0
+capable of supporting HIDSPI/HIDI2C protocol in Linux OS.
+
+::
+
+  ----------------------------------------------
+ |      +-----------------------------------+   |
+ |      |           Input Device            |   |
+ |      +-----------------------------------+   |
+ |      +-----------------------------------+   |
+ |      |       HID Multi-touch Driver      |   |
+ |      +-----------------------------------+   |
+ |      +-----------------------------------+   |
+ |      |             HID Core              |   |
+ |      +-----------------------------------+   |
+ |      +-----------------------------------+   |
+ |      |    THC QuickSPI/QuickI2C Driver   |   |
+ |      +-----------------------------------+   |
+ |      +-----------------------------------+   |
+ |      |      THC Hardware Driver          |   |
+ |      +-----------------------------------+   |
+ |      +----------------+ +----------------+   |
+ |  SW  | PCI Bus Driver | | ACPI Resource  |   |
+ |      +----------------+ +----------------+   |
+  ----------------------------------------------
+  ----------------------------------------------
+ |      +-----------------------------------+   |
+ |  HW  |              PCI Bus              |   |
+ |      +-----------------------------------+   |
+ |      +-----------------------------------+   |
+ |      |           THC Controller          |   |
+ |      +-----------------------------------+   |
+ |      +-----------------------------------+   |
+ |      |              Touch IC             |   |
+ |      +-----------------------------------+   |
+  ----------------------------------------------
+
+Touch IC (TIC), also as known as the Touch devices (touchscreen or

touchpad). The discrete analog
+components that sense and transfer either discrete touch data or heatmap data in the form of HID

Documentation/hid/intel-thc-hid.rst new file +3 -0
+reports over the SPI/I2C bus to the THC Controller on the host.
+
+THC Host Controller, which is a PCI device HBA (host bus adapter),

integrated into the PCH, that

Documentation/hid/intel-thc-hid.rst new file +4 -0
+serves as a bridge between the Touch ICs and the host.
+
+THC Hardware Driver, provides THC hardware operation APIs for
+above

QuickSPI/QuickI2C driver, it

Documentation/hid/intel-thc-hid.rst new file +4 -0
+accesses THC MMIO registers to configure and control THC hardware.
+
+THC QuickSPI/QuickI2C driver, also as known as HIDSPI/HIDI2C
+driver,

is registered as a HID
+low-level driver that manages the THC Controller and implements HIDSPI/HIDI2C protocol.

Documentation/hid/intel-thc-hid.rst new file +27 -0
+
+
+1.2 THC hardware diagram
+------------------------
+Below diagram shows THC hardware components::
+
+                      ---------------------------------
+                     |          THC Controller         |
+                     |  +---------------------------+  |
+                     |  |     PCI Config Space      |  |
+                     |  +---------------------------+  |
+                     |  +---------------------------+  |
+                     |  +       MMIO Registers      |  |
+                     |  +---------------------------+  |
+ +---------------+   |  +------------+ +------------+  |
+ | System Memory +---+--+      DMA   | |   PIO      |  |
+ +---------------+   |  +------------+ +------------+  |
+                     |  +---------------------------+  |
+                     |  |       HW Sequencer        |  |
+                     |  +---------------------------+  |
+                     |  +------------+ +------------+  |
+                     |  |  SPI/I2C   | |    GPIO    |  |
+                     |  | Controller | | Controller |  |
+                     |  +------------+ +------------+  |
+                      ---------------------------------
+
+As THC is exposed as a PCI devices, so it has standard PCI config

space registers for PCI

Documentation/hid/intel-thc-hid.rst new file +3 -0
+enumeration and configuration.
+
+MMIO Registers, which provide registers access for driver to

configure and control THC hardware,
+the registers include several categories: Interrupt status and control, DMA configure,

Documentation/hid/intel-thc-hid.rst new file +2 -0
+PIO (Programmed I/O, defined in section 3.2) status and control,
+SPI

bus configure, I2C subIP

Documentation/hid/intel-thc-hid.rst new file +4 -0
+status and control, reset status and control...
+
+THC provides two ways for driver to communicate with external
+Touch

ICs: PIO and DMA.
+PIO can let driver manually write/read data to/from Touch ICs, instead, THC DMA can

Documentation/hid/intel-thc-hid.rst new file +4 -0
+automatically write/read data without driver involved.
+
+HW Sequencer includes THC major logic, it gets instruction from
+MMIO

registers to control
+SPI bus and I2C bus to finish a bus data transaction, it also can automatically handle
+Touch ICs interrupt and start DMA receive/send data from/to Touch ICs according to interrupt

Documentation/hid/intel-thc-hid.rst new file +2 -0
+type. That means THC HW Sequencer understands HIDSPI/HIDI2C
+transfer

protocol, and handle
+the communication without driver involved, what driver needs to do is just configure the THC
+properly, and prepare the formatted data packet or handle received data packet.

Documentation/hid/intel-thc-hid.rst new file +2 -0
+
+As THC supports HIDSPI/HIDI2C protocols, it has SPI controller and

I2C subIP in it to expose
+SPI bus and I2C bus. THC also integrates a GPIO controller to provide interrupt line support

Documentation/hid/intel-thc-hid.rst new file +9 -0
+and reset line support.
+
+2. THC Hardware Interface
+=========================
+
+2.1 Host Interface
+------------------
+
+THC is exposed as "PCI Digitizer device" to the host. The PCI

product and device IDs are

Documentation/hid/intel-thc-hid.rst new file +2 -0
+changed from different generations of processors. So the source
+code

which enumerates drivers

Documentation/hid/intel-thc-hid.rst new file +8 -0
+needs to update from generation to generation.
+
+
+2.2 Device Interface
+--------------------
+
+THC supports two types of bus for Touch IC connection: Enhanced
+SPI

bus and I2C bus.

Documentation/hid/intel-thc-hid.rst new file +5 -0
+
+2.2.1 SPI Port
+~~~~~~~~~~~~~~
+
+When PORT_TYPE = 00b in MMIO registers, THC uses SPI interfaces to

communicate with external
+Touch IC. THC enhanced SPI Bus supports different SPI modes:
standard Single IO mode,

Documentation/hid/intel-thc-hid.rst new file +3 -0
+Dual IO mode and Quad IO mode.
+
+In Single IO mode, THC drives MOSI line to send data to Touch ICs,

and receives data from Touch

Documentation/hid/intel-thc-hid.rst new file +2 -0
+ICs data from MISO line. In Dual IO mode, THC drivers MOSI and
+MISO

both for data sending, and
+also receives the data on both line. In Quad IO mode, there are other two lines (IO2 and IO3)
+are added, THC drives MOSI (IO0), MISO (IO1), IO2 and IO3 at the same time for data sending, and
+also receives the data on those 4 lines. Driver needs to configure THC in different mode by

Documentation/hid/intel-thc-hid.rst new file +3 -0
+setting different opcode.
+
+Beside IO mode, driver also needs to configure SPI bus speed. THC

supports up to 42MHz SPI clock

Documentation/hid/intel-thc-hid.rst new file +16 -0
+on Intel Lunar Lake platform.
+
+For THC sending data to Touch IC, the data flow on SPI bus::
+
+ | --------------------THC sends---------------------------------|
+ <8Bits OPCode><24Bits Slave Address><Data><Data><Data>...........
+
+For THC receiving data from Touch IC, the data flow on SPI bus::
+
+ | ---------THC Sends---------------||-----Touch IC sends--------|
+ <8Bits OPCode><24Bits Slave Address><Data><Data><Data>...........
+
+2.2.2 I2C Port
+~~~~~~~~~~~~~~
+
+THC also integrates I2C controller in it, it's called I2C SubSystem.

When PORT_TYPE = 01, THC
+is configured to I2C mode. Comparing to SPI mode which can be configured through MMIO registers
+directly, THC needs to use PIO read (by setting SubIP read opcode) to I2C subIP APB registers'
+value and use PIO write (by setting SubIP write opcode) to do a write operation.

Documentation/hid/intel-thc-hid.rst new file +6 -0
+
+2.2.3 GPIO interface
+~~~~~~~~~~~~~~~~~~~~
+
+THC also includes two GPIO pins, one for interrupt and the other
+for

device reset control.

Documentation/hid/intel-thc-hid.rst new file +3 -0
+
+Interrupt line can be configured to either level triggerred or
+edge

triggerred by setting MMIO

Documentation/hid/intel-thc-hid.rst new file +4 -0
+Control register.
+
+Reset line is controlled by BIOS (or EFI) through ACPI _RST
+method,

driver needs to call this

Documentation/hid/intel-thc-hid.rst new file +9 -0
+device ACPI _RST method to reset touch IC during initialization.
+
+3. High level concept
+=====================
+
+3.1 Opcode
+----------
+
+Opcode (operation code) is used to tell THC or Touch IC what the

operation will be, such as PIO

Documentation/hid/intel-thc-hid.rst new file +4 -0
+read or PIO write.
+
+When THC is configured to SPI mode, opcodes are used for
+determining

the read/write IO mode.

Documentation/hid/intel-thc-hid.rst new file +14 -0
+There are some OPCode examples for SPI IO mode:
+
+=======   ==============================
+opcode    Corresponding SPI command
+=======   ==============================
+0x0B      Read Single I/O
+0x02      Write Single I/O
+0xBB      Read Dual I/O
+0xB2      Write Dual I/O
+0xEB      Read Quad I/O
+0xE2      Write Quad I/O
+=======   ==============================
+
+In general, different touch IC has different OPCode definition.

According to HIDSPI

Documentation/hid/intel-thc-hid.rst new file +2 -0
+protocol whitepaper, those OPCodes are defined in device ACPI
+table,

and driver needs to
+query those information through OS ACPI APIs during driver initialization, then configures

Documentation/hid/intel-thc-hid.rst new file +4 -0
+THC MMIO OPCode registers with correct setting.
+
+When THC is working in I2C mode, opcodes are used to tell THC
+what's

the next PIO type:

Documentation/hid/intel-thc-hid.rst new file +2 -0
+I2C SubIP APB register read, I2C SubIP APB register write, I2C
+touch

IC device read,
+I2C touch IC device write, I2C touch IC device write followed by read.

Documentation/hid/intel-thc-hid.rst new file +4 -0
+
+Here are the THC pre-defined opcodes for I2C mode:
+
+=======   ===================================================

===========
+opcode Corresponding I2C command
Address
+======= ===================================================
===========
+0x12 Read I2C SubIP APB internal registers 0h -
FFh
+0x13 Write I2C SubIP APB internal registers 0h -
FFh

+0x14      Read external Touch IC through I2C bus                N/A
+0x18      Write external Touch IC through I2C bus               N/A
+0x1C      Write then read external Touch IC through I2C bus     N/A
+=======   ===================================================

===========

Documentation/hid/intel-thc-hid.rst new file +6 -0
+
+3.2 PIO
+-------
+
+THC provides a programmed I/O (PIO) access interface for the
+driver

to access the touch IC's
+configuration registers, or access I2C subIP's configuration registers. To use PIO to perform

Documentation/hid/intel-thc-hid.rst new file +2 -0
+I/O operations, driver should pre-program PIO control registers
+and

PIO data registers and kick
+off the sequencing cycle. THC uses different PIO opcodes to distinguish different PIO

Documentation/hid/intel-thc-hid.rst new file +4 -0
+operations (PIO read/write/write followed by read).
+
+If there is a Sequencing Cycle In Progress and an attempt is made
+to

program any of the control,

Documentation/hid/intel-thc-hid.rst new file +2 -0
+address, or data register the cycle is blocked and a sequence
+error

will be encountered.

Documentation/hid/intel-thc-hid.rst new file +2 -0
+
+A status bit indicates when the cycle has completed allowing the

driver to know when read results
+can be checked and/or when to initiate a new command. If enabled, the cycle done assertion can

Documentation/hid/intel-thc-hid.rst new file +3 -0
+interrupt driver with an interrupt.
+
+Because THC only has 16 FIFO registers for PIO, so all the data

transfer through PIO shouldn't

Documentation/hid/intel-thc-hid.rst new file +4 -0
+exceed 64 bytes.
+
+As DMA needs max packet size for transferring configuration, and
+the

max packet size information
+always in HID device descriptor which needs THC driver to read it out from HID Device (Touch IC).
+So PIO typical use case is, before DMA initialization, write RESET command (PIO write), read

Documentation/hid/intel-thc-hid.rst new file +2 -0
+RESET response (PIO read or PIO write followed by read), write
+Power

ON command (PIO write), read

Documentation/hid/intel-thc-hid.rst new file +3 -0
+device descriptor (PIO read).
+
+For how to issue a PIO operation, here is the steps which driver

needs follow:
+

+- Program read/write data size in THC_SS_BC.
+- Program I/O target address in THC_SW_SEQ_DATA0_ADDR.
+- If write, program the write data in
THC_SW_SEQ_DATA0..THC_SW_SEQ_DATAn.
+- Program the PIO opcode in THC_SS_CMD.
+- Set TSSGO = 1 to start the PIO write sequence.
+- If THC_SS_CD_IE = 1, SW will receives a MSI when the PIO is

completed.
+- If read, read out the data in THC_SW_SEQ_DATA0..THC_SW_SEQ_DATAn.

Documentation/hid/intel-thc-hid.rst new file +6 -0
+
+3.3 DMA
+-------
+
+THC has 4 DMA channels: Read DMA1, Read DMA2, Write DMA and
+Software

DMA.

Documentation/hid/intel-thc-hid.rst new file +5 -0
+
+3.3.1 Read DMA Channel
+~~~~~~~~~~~~~~~~~~~~~~
+
+THC has two Read DMA engines: 1st RxDMA (RxDMA1) and 2nd RxDMA

(RxDMA2). RxDMA1 is reserved for

Documentation/hid/intel-thc-hid.rst new file +2 -0
+raw data mode. RxDMA2 is used for HID data mode and it is the
+RxDMA

engine currently driver uses

Documentation/hid/intel-thc-hid.rst new file +3 -0
+for HID input report data retrieval.
+
+RxDMA's typical use case is auto receiving the data from Touch IC.

Once RxDMA is enabled by

Documentation/hid/intel-thc-hid.rst new file +3 -0
+software, THC will start auto-handling receiving logic.
+
+For SPI mode, THC RxDMA sequence is: when Touch IC triggers a

interrupt to THC, THC reads out
+report header to identify what's the report type, and what's the report length, according to
+above information, THC reads out report body to internal FIFO and start RxDMA coping the data
+to system memory. After that, THC update interrupt cause register with report type, and update

Documentation/hid/intel-thc-hid.rst new file +2 -0
+RxDMA PRD table read pointer, then trigger a MSI interrupt to
+notify

driver RxDMA finishing

Documentation/hid/intel-thc-hid.rst new file +3 -0
+data receiving.
+
+For I2C mode, THC RxDMA's behavior is a little bit different,

because of HIDI2C protocol difference
+with HIDSPI protocol, RxDMA only be used to receive input report. The sequence is, when Touch IC

Documentation/hid/intel-thc-hid.rst new file +2 -0
+triggers a interrupt to THC, THC first reads out 2 bytes from
+input

report address to determine the
+packet length, then use this packet length to start a DMA reading from input report address for
+input report data. After that, THC update RxDMA PRD table read pointer, then trigger a MSI interrupt

Documentation/hid/intel-thc-hid.rst new file +3 -0
+to notify driver input report data is ready in system memory.
+
+All above sequence is hardware automatically handled, all driver

needs to do is configure RxDMA and
+waiting for interrupt ready then read out the data from system memory.

Documentation/hid/intel-thc-hid.rst new file +6 -0
+
+3.3.2 Software DMA channel
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+THC supports a software triggerred RxDMA mode to read the touch
+data

from touch IC. This SW RxDMA

Documentation/hid/intel-thc-hid.rst new file +2 -0
+is the 3rd THC RxDMA engine with the similar functionalities as
+the

existing two RxDMAs, the only

Documentation/hid/intel-thc-hid.rst new file +2 -0
+difference is this SW RxDMA is triggerred by software, and RxDMA2
+is

triggerred by external Touch IC
+interrupt. It gives a flexiblity to software driver to use RxDMA read Touch IC data in any time.

Documentation/hid/intel-thc-hid.rst new file +2 -0
+
+Before software starts a SW RxDMA, it shall stop the 1st and 2nd

RxDMA, clear PRD read/write pointer
+and quiesce the device interrupt (THC_DEVINT_QUIESCE_HW_STS = 1), other operations are the same with

Documentation/hid/intel-thc-hid.rst new file +7 -0
+RxDMA.
+
+3.3.3 Write DMA Channel
+~~~~~~~~~~~~~~~~~~~~~~~
+
+THC has one write DMA engine, which can be used for sending data
+to

Touch IC automatically.

Documentation/hid/intel-thc-hid.rst new file +2 -0
+According to HIDSPI and HIDI2C protocol, every time only one
+command

can be sent to touch IC, and
+before last command is completely handled, next command cannot be sent, THC write DMA engine only

Documentation/hid/intel-thc-hid.rst new file +4 -0
+supports single PRD table.
+
+What driver needs to do is, preparing PRD table and DMA buffer,
+then

copy data to DMA buffer and
+update PRD table with buffer address and buffer length, then start write DMA. THC will
+automatically send the data to touch IC, and trigger a DMA completion interrupt once transferring

Documentation/hid/intel-thc-hid.rst new file +6 -0
+is done.
+
+3.4 PRD
+-------
+
+Physical Region Descriptor (PRD) provides the memory mapping

description for THC DMAs.

Documentation/hid/intel-thc-hid.rst new file +6 -0
+
+3.4.1 PRD table and entry
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In order to improve physical DMA memory usage, modern drivers
+trend

to allocate a virtually

Documentation/hid/intel-thc-hid.rst new file +2 -0
+contiguous, but physically fragmented buffer of memory for each
+data

buffer. Linux OS also

Documentation/hid/intel-thc-hid.rst new file +3 -0
+provide SGL (scatter gather list) APIs to support this usage.
+
+THC uses PRD table (physical region descriptor) to support the

corresponding OS kernel

Documentation/hid/intel-thc-hid.rst new file +17 -0
+SGL that describes the virtual to physical buffer mapping.
+
+::
+
+  ------------------------      --------------       --------------
+ | PRD table base address +----+ PRD table #1 +-----+ PRD Entry #1
+ | |
+  ------------------------      --------------       --------------
+                                                     --------------
+                                                    | PRD Entry #2 |
+                                                     --------------
+                                                     --------------
+                                                    | PRD Entry #n |
+
+ --------------
+
+The read DMA engine supports multiple PRD tables held within a

circular buffer that allow the THC

Documentation/hid/intel-thc-hid.rst new file +2 -0
+to support multiple data buffers from the Touch IC. This allows
+host

SW to arm the Read DMA engine
+with multiple buffers, allowing the Touch IC to send multiple data frames to the THC without SW
+interaction. This capability is required when the CPU processes touch frames slower than the

Documentation/hid/intel-thc-hid.rst new file +3 -0
+Touch IC can send them.
+
+To simplify the design, SW assumes worst-case memory fragmentation.

Therefore,each PRD table shall
+contain the same number of PRD entries, allowing for a global register (per Touch IC) to hold the

Documentation/hid/intel-thc-hid.rst new file +3 -0
+number of PRD-entries per PRD table.
+
+SW allocates up to 128 PRD tables per Read DMA engine as specified

in the THC_M_PRT_RPRD_CNTRL.PCD

Documentation/hid/intel-thc-hid.rst new file +2 -0
+register field. The number of PRD tables should equal the number
+of

data buffers.

Documentation/hid/intel-thc-hid.rst new file +2 -0
+
+Max OS memory fragmentation will be at a 4KB boundary, thus to

address 1MB of virtually contiguous
+memory 256 PRD entries are required for a single PRD Table. SW writes the number of PRD entries
+for each PRD table in the THC_M_PRT_RPRD_CNTRL.PTEC register field. The PRD entry's length must be

Documentation/hid/intel-thc-hid.rst new file +3 -0
+multiple of 4KB except for the last entry in a PRD table.
+
+SW allocates all the data buffers and PRD tables only once at host

initialization.

Documentation/hid/intel-thc-hid.rst new file +5 -0
+
+3.4.2 PRD Write pointer and read pointer
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+As PRD tables are organized as a Circular Buffer (CB), a read

pointer and a write pointer for a CB

Documentation/hid/intel-thc-hid.rst new file +3 -0
+are needed.
+
+DMA HW consumes the PRD tables in the CB, one PRD entry at a time

until the EOP bit is found set
+in a PRD entry. At this point HW increments the PRD read pointer. Thus, the read pointer points
+to the PRD which the DMA engine is currently processing. This pointer rolls over once the circular
+buffer's depth has been traversed with bit[7] the Rollover bit. E.g. if the DMA CB depth is equal
+to 4 entries (0011b), then the read pointers will follow this pattern (HW is required to honor

Documentation/hid/intel-thc-hid.rst new file +3 -0
+this behavior): 00h 01h 02h 03h 80h 81h 82h 83h 00h 01h ...
+
+The write pointer is updated by SW. The write pointer points to

location in the DMA CB, where the
+next PRD table is going to be stored. SW needs to ensure that this pointer rolls over once the
+circular buffer's depth has been traversed with Bit[7] as the rollover bit. E.g. if the DMA CB
+depth is equal to 5 entries (0100b), then the write pointers will follow this pattern (SW is
+required to honor this behavior): 00h 01h 02h 03h 04h 80h 81h 82h 83h 84h 00h 01h ..

Documentation/hid/intel-thc-hid.rst new file +5 -0
+
+3.4.3 PRD descriptor structure
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Intel THC uses PRD entry descriptor for every PRD entry. Every PRD

entry descriptor occupies
+128 bits memories:
+
+=================== ========
===============================================
+struct field bit(s) description
+=================== ========
===============================================
+dest_addr 53..0 destination memory address, as
every entry
+ is 4KB, ignore lowest 10 bits of
address.

Documentation/hid/intel-thc-hid.rst new file +2 -0
+reserved1             54..62     reserved
+int_on_completion     63         completion interrupt enable bit, if

this bit
+ set it means THC will trigger a
completion
+ interrupt. This bit is set by SW
driver.
+len 87..64 how many bytes of data in this
entry.
+end_of_prd 88 end of PRD table bit, if this bit
is set,
+ it means this entry is last entry
in this PRD
+ table. This bit is set by SW
driver.

Documentation/hid/intel-thc-hid.rst new file +3 -0
+hw_status             90..89     HW status bits
+reserved2             127..91    reserved
+===================   ========

===============================================

Documentation/hid/intel-thc-hid.rst new file +2 -0
+
+And one PRD table can include up to 256 PRD entries, as every

entries is 4K bytes, so every

Documentation/hid/intel-thc-hid.rst new file +9 -0
+PRD table can describe 1M bytes memory.
+
+.. code-block:: c
+
+   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

Documentation/hid/intel-thc-hid.rst new file +7 -0
+each PRD table.
+
+4. HIDSPI support (QuickSPI)
+============================
+
+Intel THC is total compatible with HIDSPI protocol, THC HW
+sequenser

can accelerate HIDSPI

Documentation/hid/intel-thc-hid.rst new file +8 -0
+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.

Documentation/hid/intel-thc-hid.rst new file +7 -0
+
+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.

Documentation/hid/intel-thc-hid.rst new file +4 -0
+
+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),

Documentation/hid/intel-thc-hid.rst new file +5 -0
+  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

Documentation/hid/intel-thc-hid.rst new file +10 -0
+  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

Documentation/hid/intel-thc-hid.rst new file +10 -0
+  to THC's write DMA buffer.
+- Start TxDMA to complete the write operation.
+
+5. HIDI2C support (QuickI2C)
+============================
+
+5.1 Reset Flow
+--------------
+
+- Read device descriptor from Touch IC device through PIO write

followed by read.
+- If the device descriptor is valid, allocate DMA buffers and configure all DMA channels.
+- Use PIO or TxDMA to write a SET_POWER request to TIC's command register, and check if the
+ write operation is successfully completed.
+- Use PIO or TxDMA to write a RESET request to TIC's command register. If the write operation
+ is successfully completed, wait for reset response from TIC. +- Use SWDMA to read report descriptor through TIC's report descriptor register.

Documentation/hid/intel-thc-hid.rst new file +8 -0
+
+5.2 Input Report Data Flow
+--------------------------
+
+Basic Flow:
+
+- Touch IC asserts the interrupt indicating that it has an
+interrupt

to send to HOST.
+ THC Sequencer issues a READ request over the I2C bus. The HIDI2C device returns the
+ first 2 bytes from the HIDI2C device which contains the length
+ of
the received data.
+- THC Sequencer continues the Read operation as per the size of +data
indicated in the
+ length field.
+- 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. THC writes 2Bytes for length field
+ plus the remaining data to RxDMA buffer. 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).

+- THC Sequencer enters End-of-Input Report Processing.
+- If the device has no more input reports to send to the host, it

de-asserts the interrupt
+ line. For any additional input reports, device keeps the
+ interrupt
line asserted and

Documentation/hid/intel-thc-hid.rst new file +5 -0
+  steps 1 through 4 in the flow are repeated.
+
+THC Sequencer End of Input Report Processing:
+
+- THC DMA engine increments the read pointer of the Read PRD CB,

sets EOF interrupt status
+ in RxDMA 2 register (THC_M_PRT_READ_DMA_INT_STS_2). +- If THC EOF interrupt is enabled by the driver in the control register

Documentation/hid/intel-thc-hid.rst new file +5 -0
+  (THC_M_PRT_READ_DMA_CNTRL_2), generates interrupt to software.
+
+Sequence of steps to read data from RX DMA buffer:
+
+- THC QuickI2C driver checks CB write Ptr and CB read Ptr to

identify if any data frame in DMA
+ circular buffers.

+- THC QuickI2C driver gets first unprocessed PRD table.
+- THC QuickI2C driver scans all PRD entries in this PRD table to
calculate the total frame size.
+- THC QuickI2C driver copies all frame data out.
+- THC QuickI2C driver call hid_input_report to send the input

+report
content to HID core, which
+ includes Report ID + Report Data Content (remove the length
+ field
from the original report

Documentation/hid/intel-thc-hid.rst new file +10 -0
+  data).
+- THC QuickI2C driver updates write Ptr.
+
+5.3 Output Report Data Flow
+---------------------------
+
+Generic Output Report Flow:
+
+- HID core call THC QuickI2C raw_request callback.
+- THC QuickI2C uses PIO or TXDMA to write a SET_REPORT request to

TIC's command register. Report
+ type in SET_REPORT should be set to Output.
+- THC QuickI2C programs TxDMA buffer with TX Data to be written to TIC's data register. The first
+ 2 bytes should indicate the length of the report followed by the report contents including

Documentation/hid/intel-thc-hid.rst new file +6 -0
+  Report ID.
+
+6. THC Debugging
+================
+
+To debug THC, event tracing mechanism is used. To enable debug

logs::

Documentation/hid/intel-thc-hid.rst new file +7 -0
+
+  echo 1 > /sys/kernel/debug/tracing/events/intel_thc/enable
+  cat /sys/kernel/debug/tracing/trace
+
+7. Reference
+============
+- HIDSPI:

https://download.microsoft.com/download/c/a/0/ca07aef3-3e10-4022-b1
e 9-c98cea99465d/HidSpiProtocolSpec.pdf
+- HIDI2C:
https://download.microsoft.com/download/7/d/d/7dd44bb7-2a7a-4505-ac
1 c-7227d3d96d5b/hid-over-i2c-protocol-spec-v1-0.docx

author maintainer
#7 lore raw

PATCH v4 2/22 HID: intel-thc-hid: Add basic THC driver skeleton

In reply to Even Xu

From: Xinpeng Sun <[email protected]>

Create intel-thc-hid folder and add Kconfig and Makefile for THC drivers. Add basic THC device context structure, definitions and related initialization APIs for THC Hardware layer driver. Also initialize regmap struct for future THC registers access.

---
 MAINTAINERS                                   |   6 +
 drivers/hid/Kconfig                           |   2 +
 drivers/hid/Makefile                          |   2 +
 drivers/hid/intel-thc-hid/Kconfig             |  20 ++
 drivers/hid/intel-thc-hid/Makefile            |  11 +
 .../intel-thc-hid/intel-thc/intel-thc-dev.c   | 219 ++++++++++++++++++
 .../intel-thc-hid/intel-thc/intel-thc-dev.h   |  25 ++
 7 files changed, 285 insertions(+)
 create mode 100644 drivers/hid/intel-thc-hid/Kconfig
 create mode 100644 drivers/hid/intel-thc-hid/Makefile
 create mode 100644 drivers/hid/intel-thc-hid/intel-thc/intel-thc-dev.c
 create mode 100644 drivers/hid/intel-thc-hid/intel-thc/intel-thc-dev.h
MAINTAINERS +6 -0
index 17daa9ee9384..9465f2e89691 100644
@@ -11875,6 +11875,12 @@ S:	Maintained
 F:	arch/x86/include/asm/intel_telemetry.h
 F:	drivers/platform/x86/intel/telemetry/
 
+INTEL TOUCH HOST CONTROLLER (THC) DRIVER
+M:	Even Xu <[email protected]>
+M:	Xinpeng Sun <[email protected]>
+S:	Maintained
+F:	drivers/hid/intel-thc-hid/
+
 INTEL TPMI DRIVER
 M:	Srinivas Pandruvada <[email protected]>
 L:	[email protected]
drivers/hid/Kconfig +2 -0
index 4d2a89d65b65..c57927529f8a 100644
@@ -1386,4 +1386,6 @@ source "drivers/hid/amd-sfh-hid/Kconfig"
 
 source "drivers/hid/surface-hid/Kconfig"
 
+source "drivers/hid/intel-thc-hid/Kconfig"
+
 endif # HID_SUPPORT
drivers/hid/Makefile +2 -0
index 24de45f3677d..482b096eea28 100644
@@ -171,3 +171,5 @@ obj-$(INTEL_ISH_FIRMWARE_DOWNLOADER)	+= intel-ish-hid/
 obj-$(CONFIG_AMD_SFH_HID)       += amd-sfh-hid/
 
 obj-$(CONFIG_SURFACE_HID_CORE)  += surface-hid/
+
+obj-$(CONFIG_INTEL_THC_HID)     += intel-thc-hid/
drivers/hid/intel-thc-hid/Kconfig new file +20 -0
new file mode 100644
index 000000000000..dc7c5a23f0ad
@@ -0,0 +1,20 @@
+# SPDX-License-Identifier: GPL-2.0
+# Copyright (c) 2024, Intel Corporation.
+
+menu "Intel THC HID Support"
+	depends on X86_64 && PCI
+
+config INTEL_THC_HID
+	tristate "Intel Touch Host Controller"
+	select HID
+	help
+	  THC (Touch Host Controller) is the name of the IP block in PCH that
+	  interfaces with Touch Devices (ex: touchscreen, touchpad etc.). It
+	  is comprised of 3 key functional blocks: A natively half-duplex
+	  Quad I/O capable SPI master; a low latency I2C interface to support
+	  HIDI2C compliant devices; a hardware sequencer with Read/Write DMA
+	  capability to system memory.
+
+	  Say Y/M here if you want to support Intel THC. If unsure, say N.
+
+endmenu
drivers/hid/intel-thc-hid/Makefile new file +11 -0
new file mode 100644
index 000000000000..bebb60bedfeb
@@ -0,0 +1,11 @@
+# SPDX-License-Identifier: GPL-2.0
+#
+# Makefile - Intel Touch Host Controller (THC) drivers
+# Copyright (c) 2024, Intel Corporation.
+#
+#
+
+obj-$(CONFIG_INTEL_THC_HID) += intel-thc.o
+intel-thc-objs += intel-thc/intel-thc-dev.o
+
+ccflags-y += -I $(src)/intel-thc
drivers/hid/intel-thc-hid/intel-thc/intel-thc-dev.c new file +219 -0

219 lines not on this page · raw message

drivers/hid/intel-thc-hid/intel-thc/intel-thc-dev.h new file +25 -0
new file mode 100644
index 000000000000..7060f0a36cbd
@@ -0,0 +1,25 @@
+/* SPDX-License-Identifier: GPL-2.0 */
+/* Copyright (c) 2024 Intel Corporation */
+
+#ifndef _INTEL_THC_DEV_H_
+#define _INTEL_THC_DEV_H_
+
+#include <linux/cdev.h>
+
+#define THC_REGMAP_COMMON_OFFSET  0x10
+#define THC_REGMAP_MMIO_OFFSET    0x1000
+
+/**
+ * struct thc_device - THC private device struct
+ * @thc_regmap: MMIO regmap structure for accessing THC registers
+ * @mmio_addr: MMIO registers address
+ */
+struct thc_device {
+	struct device *dev;
+	struct regmap *thc_regmap;
+	void __iomem *mmio_addr;
+};
+
+struct thc_device *thc_dev_init(struct device *device, void __iomem *mem_addr);
+
+#endif /* _INTEL_THC_DEV_H_ */
Signature · 1 line
2.40.1
author maintainer
#8 lore raw

PATCH v4 3/22 HID: intel-thc-hid: intel-thc: Add THC registers definition

In reply to Even Xu

From: Xinpeng Sun <[email protected]>

Add THC Hardware register definitions and descriptions.

---
 .../intel-thc-hid/intel-thc/intel-thc-hw.h    | 639 ++++++++++++++++++
 1 file changed, 639 insertions(+)
 create mode 100644 drivers/hid/intel-thc-hid/intel-thc/intel-thc-hw.h
drivers/hid/intel-thc-hid/intel-thc/intel-thc-hw.h new file +639 -0
new file mode 100644
index 000000000000..8b3a962e7e64
@@ -0,0 +1,639 @@
+/* SPDX-License-Identifier: GPL-2.0 */
+/* Copyright (c) 2024 Intel Corporation */
+
+#ifndef _INTEL_THC_HW_H_
+#define _INTEL_THC_HW_H_
+
+#include <linux/bits.h>
+
+/* THC registers offset */
+/* Touch Host Controller Control Register */
+#define THC_M_PRT_CONTROL_OFFSET		0x1008
+/* THC SPI Bus Configuration Register */
+#define THC_M_PRT_SPI_CFG_OFFSET		0x1010
+/* THC SPI Bus Read Opcode Register */
+#define THC_M_PRT_SPI_ICRRD_OPCODE_OFFSET	0x1014
+/* THC SPI Bus Read Opcode Register */
+#define THC_M_PRT_SPI_DMARD_OPCODE_OFFSET	0x1018
+/* THC SPI Bus Write Opcode Register */
+#define THC_M_PRT_SPI_WR_OPCODE_OFFSET		0x101C
+/* THC Interrupt Enable Register */
+#define THC_M_PRT_INT_EN_OFFSET			0x1020
+/* THC Interrupt Status Register */
+#define THC_M_PRT_INT_STATUS_OFFSET		0x1024
+/* THC Error Cause Register */
+#define THC_M_PRT_ERR_CAUSE_OFFSET		0x1028
+/* THC SW sequencing Control */
+#define THC_M_PRT_SW_SEQ_CNTRL_OFFSET		0x1040
+/* THC SW sequencing Status */
+#define THC_M_PRT_SW_SEQ_STS_OFFSET		0x1044
+/* THC SW Sequencing Data DW0 or SPI Address Register */
+#define THC_M_PRT_SW_SEQ_DATA0_ADDR_OFFSET	0x1048
+/* THC SW sequencing Data DW1 */
+#define THC_M_PRT_SW_SEQ_DATA1_OFFSET		0x104C
+/* THC SW sequencing Data DW2 */
+#define THC_M_PRT_SW_SEQ_DATA2_OFFSET		0x1050
+/* THC SW sequencing Data DW3 */
+#define THC_M_PRT_SW_SEQ_DATA3_OFFSET		0x1054
+/* THC SW sequencing Data DW4 */
+#define THC_M_PRT_SW_SEQ_DATA4_OFFSET		0x1058
+/* THC SW sequencing Data DW5 */
+#define THC_M_PRT_SW_SEQ_DATA5_OFFSET		0x105C
+/* THC SW sequencing Data DW6 */
+#define THC_M_PRT_SW_SEQ_DATA6_OFFSET		0x1060
+/* THC SW sequencing Data DW7 */
+#define THC_M_PRT_SW_SEQ_DATA7_OFFSET		0x1064
+/* THC SW sequencing Data DW8 */
+#define THC_M_PRT_SW_SEQ_DATA8_OFFSET		0x1068
+/* THC SW sequencing Data DW9 */
+#define THC_M_PRT_SW_SEQ_DATA9_OFFSET		0x106C
+/* THC SW sequencing Data DW10 */
+#define THC_M_PRT_SW_SEQ_DATA10_OFFSET		0x1070
+/* THC SW sequencing Data DW11 */
+#define THC_M_PRT_SW_SEQ_DATA11_OFFSET		0x1074
+/* THC SW sequencing Data DW12 */
+#define THC_M_PRT_SW_SEQ_DATA12_OFFSET		0x1078
+/* THC SW sequencing Data DW13 */
+#define THC_M_PRT_SW_SEQ_DATA13_OFFSET		0x107C
+/* THC SW sequencing Data DW14 */
+#define THC_M_PRT_SW_SEQ_DATA14_OFFSET		0x1080
+/* THC SW sequencing Data DW15 */
+#define THC_M_PRT_SW_SEQ_DATA15_OFFSET		0x1084
+/* THC SW sequencing Data DW16 */
+#define THC_M_PRT_SW_SEQ_DATA16_OFFSET		0x1088
+/* THC Write PRD Base Address Register Low */
+#define THC_M_PRT_WPRD_BA_LOW_OFFSET		0x1090
+/* THC Write PRD Base Address Register High */
+#define THC_M_PRT_WPRD_BA_HI_OFFSET		0x1094
+/* THC Write DMA Control */
+#define THC_M_PRT_WRITE_DMA_CNTRL_OFFSET	0x1098
+/* THC Write Interrupt Status */
+#define THC_M_PRT_WRITE_INT_STS_OFFSET		0x109C
+/* THC Write DMA Error Register */
+#define THC_M_PRT_WRITE_DMA_ERR_OFFSET		0x10A0
+/* THC device address for the bulk write */
+#define THC_M_PRT_WR_BULK_ADDR_OFFSET		0x10B4
+/* THC Device Interrupt Cause Register Address */
+#define THC_M_PRT_DEV_INT_CAUSE_ADDR_OFFSET	0x10B8
+/* THC Device Interrupt Cause Register Value */
+#define THC_M_PRT_DEV_INT_CAUSE_REG_VAL_OFFSET	0x10BC
+/* THC TXDMA Frame Count */
+#define THC_M_PRT_TX_FRM_CNT_OFFSET		0x10E0
+/* THC TXDMA Packet Count */
+#define THC_M_PRT_TXDMA_PKT_CNT_OFFSET		0x10E4
+/* THC Device Interrupt Count on this port */
+#define THC_M_PRT_DEVINT_CNT_OFFSET		0x10E8
+/* Touch Device Interrupt Cause register Format Configuration Register 1 */
+#define THC_M_PRT_DEVINT_CFG_1_OFFSET		0x10EC
+/* Touch Device Interrupt Cause register Format Configuration Register 2 */
+#define THC_M_PRT_DEVINT_CFG_2_OFFSET		0x10F0
+/* THC Read PRD Base Address Low for the 1st RXDMA */
+#define THC_M_PRT_RPRD_BA_LOW_1_OFFSET		0x1100
+/* THC Read PRD Base Address High for the 1st RXDMA */
+#define THC_M_PRT_RPRD_BA_HI_1_OFFSET		0x1104
+/* THC Read PRD Control for the 1st RXDMA */
+#define THC_M_PRT_RPRD_CNTRL_1_OFFSET		0x1108
+/* THC Read DMA Control for the 1st RXDMA */
+#define THC_M_PRT_READ_DMA_CNTRL_1_OFFSET	0x110C
+/* THC Read Interrupt Status for the 1st RXDMA */
+#define THC_M_PRT_READ_DMA_INT_STS_1_OFFSET	0x1110
+/* THC Read DMA Error Register for the 1st RXDMA */
+#define THC_M_PRT_READ_DMA_ERR_1_OFFSET		0x1114
+/* Touch Sequencer GuC Tail Offset Address Low for the 1st RXDMA */
+#define THC_M_PRT_GUC_OFFSET_LOW_1_OFFSET	0x1118
+/* Touch Sequencer GuC Tail Offset Address High for the 1st RXDMA */
+#define THC_M_PRT_GUC_OFFSET_HI_1_OFFSET	0x111C
+/* Touch Host Controller GuC Work Queue Item Size for the 1st RXDMA */
+#define THC_M_PRT_GUC_WORKQ_ITEM_SZ_1_OFFSET	0x1120
+/* Touch Host Controller GuC Control register for the 1st RXDMA */
+#define THC_M_PRT_GUC_WORKQ_SZ_1_OFFSET		0x1124
+/* Touch Sequencer Control for the 1st DMA */
+#define THC_M_PRT_TSEQ_CNTRL_1_OFFSET		0x1128
+/* Touch Sequencer GuC Doorbell Address Low for the 1st RXDMA */
+#define THC_M_PRT_GUC_DB_ADDR_LOW_1_OFFSET	0x1130
+/* Touch Sequencer GuC Doorbell Address High for the 1st RXDMA */
+#define THC_M_PRT_GUC_DB_ADDR_HI_1_OFFSET	0x1134
+/* Touch Sequencer GuC Doorbell Data */
+#define THC_M_PRT_GUC_DB_DATA_1_OFFSET		0x1138
+/* Touch Sequencer GuC Tail Offset Initial Value for the 1st RXDMA */
+#define THC_M_PRT_GUC_OFFSET_INITVAL_1_OFFSET	0x1140
+/* THC Device Address for the bulk/touch data read for the 1st RXDMA */
+#define THC_M_PRT_RD_BULK_ADDR_1_OFFSET		0x1170
+/* THC Gfx/SW Doorbell Count from the 1st Stream RXDMA on this port */
+#define THC_M_PRT_DB_CNT_1_OFFSET		0x11A0
+/* THC Frame Count from the 1st Stream RXDMA on this port */
+#define THC_M_PRT_FRM_CNT_1_OFFSET		0x11A4
+/* THC Micro Frame Count from the 1st Stream RXDMA on this port */
+#define THC_M_PRT_UFRM_CNT_1_OFFSET		0x11A8
+/* THC Packet Count from the 1st Stream RXDMA on this port */
+#define THC_M_PRT_RXDMA_PKT_CNT_1_OFFSET	0x11AC
+/*
+ * THC Software Interrupt Count from the 1st Stream RXDMA
+ * on this port
+ */
+#define THC_M_PRT_SWINT_CNT_1_OFFSET		0x11B0
+/* Touch Sequencer Frame Drop Counter for the 1st RXDMA */
+#define THC_M_PRT_FRAME_DROP_CNT_1_OFFSET	0x11B4
+/* THC Coaescing 1 */
+#define THC_M_PRT_COALESCE_1_OFFSET		0x11B8
+/* THC Read PRD Base Address Low for the 2nd RXDMA */
+#define THC_M_PRT_RPRD_BA_LOW_2_OFFSET		0x1200
+/* THC Read PRD Base Address High for the 2nd RXDMA */
+#define THC_M_PRT_RPRD_BA_HI_2_OFFSET		0x1204
+/* THC Read PRD Control for the 2nd RXDMA */
+#define THC_M_PRT_RPRD_CNTRL_2_OFFSET		0x1208
+/* THC Read DMA Control for the 2nd RXDMA */
+#define THC_M_PRT_READ_DMA_CNTRL_2_OFFSET	0x120C
+/* THC Read Interrupt Status for the 2nd RXDMA */
+#define THC_M_PRT_READ_DMA_INT_STS_2_OFFSET	0x1210
+/* THC Read DMA Error Register for the 2nd RXDMA */
+#define THC_M_PRT_READ_DMA_ERR_2_OFFSET		0x1214
+/* Touch Sequencer GuC Tail Offset Address Low for the 2nd RXDMA */
+#define THC_M_PRT_GUC_OFFSET_LOW_2_OFFSET	0x1218
+/* Touch Sequencer GuC Tail Offset Address High for the 2nd RXDMA */
+#define THC_M_PRT_GUC_OFFSET_HI_2_OFFSET	0x121C
+/* Touch Host Controller GuC Work Queue Item Size for the 2nd RXDMA */
+#define THC_M_PRT_GUC_WORKQ_ITEM_SZ_2_OFFSET	0x1220
+/* Touch Host Controller GuC Control register for the 2nd RXDMA */
+#define THC_M_PRT_GUC_WORKQ_SZ_2_OFFSET		0x1224
+/* Touch Sequencer Control for the 2nd DMA */
+#define THC_M_PRT_TSEQ_CNTRL_2_OFFSET		0x1228
+/* Touch Sequencer GuC Doorbell Address Low for the 2nd RXDMA */
+#define THC_M_PRT_GUC_DB_ADDR_LOW_2_OFFSET	0x1230
+/* Touch Sequencer GuC Doorbell Address High for the 2nd RXDMA */
+#define THC_M_PRT_GUC_DB_ADDR_HI_2_OFFSET	0x1234
+/* Touch Sequencer GuC Doorbell Data for PRD2 */
+#define THC_M_PRT_GUC_DB_DATA_2_OFFSET		0x1238
+/* Touch Sequencer GuC Tail Offset Initial Value for the 2nd RXDMA */
+#define THC_M_PRT_GUC_OFFSET_INITVAL_2_OFFSET	0x1240
+/* THC Device Address for the bulk/touch data read for the 2nd RXDMA */
+#define THC_M_PRT_RD_BULK_ADDR_2_OFFSET		0x1270
+/* THC Gfx/SW Doorbell Count from the 2nd Stream RXDMA on this port */
+#define THC_M_PRT_DB_CNT_2_OFFSET		0x12A0
+/* THC Frame Count from the 2nd Stream RXDMA on this port */
+#define THC_M_PRT_FRM_CNT_2_OFFSET		0x12A4
+/* THC Micro Frame Count from the 2nd Stream RXDMA on this port */
+#define THC_M_PRT_UFRM_CNT_2_OFFSET		0x12A8
+/* THC Packet Count from the 2nd Stream RXDMA on this port */
+#define THC_M_PRT_RXDMA_PKT_CNT_2_OFFSET	0x12AC
+/*
+ * THC Software Interrupt Count from the 2nd Stream RXDMA
+ * on this port
+ */
+#define THC_M_PRT_SWINT_CNT_2_OFFSET		0x12B0
+/* Touch Sequencer Frame Drop Counter for the 2nd RXDMA */
+#define THC_M_PRT_FRAME_DROP_CNT_2_OFFSET	0x12B4
+/* THC Coaescing 2 */
+#define THC_M_PRT_COALESCE_2_OFFSET		0x12B8
+/* THC SPARE REGISTER */
+#define THC_M_PRT_SPARE_REG_OFFSET		0x12BC
+/* THC Read PRD Base Address Low for the SW RXDMA */
+#define THC_M_PRT_RPRD_BA_LOW_SW_OFFSET		0x12C0
+/* THC Read PRD Base Address High for the SW RXDMA */
+#define THC_M_PRT_RPRD_BA_HI_SW_OFFSET		0x12C4
+/* THC Read PRD Control for the SW RXDMA */
+#define THC_M_PRT_RPRD_CNTRL_SW_OFFSET		0x12C8
+/* THC Read DMA Control for the SW RXDMA */
+#define THC_M_PRT_READ_DMA_CNTRL_SW_OFFSET	0x12CC
+/* THC Read Interrupt Status for the SW RXDMA */
+#define THC_M_PRT_READ_DMA_INT_STS_SW_OFFSET	0x12D0
+/* Touch Sequencer Control for the SW DMA */
+#define THC_M_PRT_TSEQ_CNTRL_SW_OFFSET		0x12D4
+/* Address for the bulk read for SW DMA engine */
+#define THC_M_PRT_RD_BULK_ADDR_SW_OFFSET	0x12D8
+/* THC Frame Count from the SW RXDMA on this port */
+#define THC_M_PRT_FRM_CNT_SW_OFFSET		0x12DC
+/* THC Packet Count from the SW RXDMA on this port */
+#define THC_M_PRT_RXDMA_PKT_CNT_SW_OFFSET	0x12E0
+/* SW DMA PRD Table Length */
+#define THC_M_PRT_SW_DMA_PRD_TABLE_LEN_OFFSET	0x12E4
+/* THC timing based Frame/Interrupt caolescing control register for 1st RXDMA */
+#define THC_M_PRT_COALESCE_CNTRL_1_OFFSET	0x12E8
+/* THC timing based Frame/Interrupt caolescing control register for 2nd RXDMA */
+#define THC_M_PRT_COALESCE_CNTRL_2_OFFSET	0x12EC
+/* Touch Sequencer PRD Table Empty Counter for the 1st RXDMA */
+#define THC_M_PRT_PRD_EMPTY_CNT_1_OFFSET	0x12F0
+/* Touch Sequencer PRD Table Empty Counter for the 2nd RXDM */
+#define THC_M_PRT_PRD_EMPTY_CNT_2_OFFSET	0x12F4
+/* THC coalescing status to reflect the current coalescing FSM state for 1st RXDMA */
+#define THC_M_PRT_COALESCE_STS_1_OFFSET		0x12F8
+/* THC coalescing status to reflect the current coalescing FSM state for 2nd RXDMA */
+#define THC_M_PRT_COALESCE_STS_2_OFFSET		0x12FC
+/* THC Register for the SPI Port Duty Cycle Configuration */
+#define THC_M_PRT_SPI_DUTYC_CFG_OFFSET		0x1300
+/* THC Register for SW I2C Wtite Sequecning control */
+#define THC_M_PRT_SW_SEQ_I2C_WR_CNTRL_OFFSET	0x1304
+/* THC current Timestamp Register for RXDMA1 */
+#define THC_M_PRT_TIMESTAMP_1_OFFSET		0x1308
+/* THC current Timestamp Register for RXDMA2 */
+#define THC_M_PRT_TIMESTAMP_2_OFFSET		0x130C
+/* Current SYNC Event Timestamp Register */
+#define THC_M_PRT_SYNC_TIMESTAMP_OFFSET		0x1310
+/* THC Display Sync Register */
+#define THC_M_PRT_DISP_SYNC_OFFSET		0x1314
+/* THC Display Sync Register */
+#define THC_M_PRT_DISP_SYNC_2_OFFSET		0x1318
+/* THC Register for SW I2C Wtite Sequecning control */
+#define THC_M_PRT_I2C_CFG_OFFSET		0x131C
+
+/* THC register bits definition */
+#define TXN_ERR_INT_STS_BIT			BIT(28)
+#define TXN_FATAL_INT_STS_BIT			BIT(30)
+
+#define NONDMA_INT_STS_BIT			BIT(4)
+#define EOF_INT_STS_BIT				BIT(5)
+
+#define THC_CFG_DID_VID_VID		        GENMASK(15, 0)
+#define THC_CFG_DID_VID_DID		        GENMASK(31, 16)
+
+#define THC_CFG_STS_CMD_IOSE			BIT(0)
+#define THC_CFG_STS_CMD_MSE			BIT(1)
+#define THC_CFG_STS_CMD_BME			BIT(2)
+#define THC_CFG_STS_CMD_SPCYC			BIT(3)
+#define THC_CFG_STS_CMD_MWRIEN			BIT(4)
+#define THC_CFG_STS_CMD_VGAPS			BIT(5)
+#define THC_CFG_STS_CMD_PERRR			BIT(6)
+#define THC_CFG_STS_CMD_SERREN			BIT(8)
+#define THC_CFG_STS_CMD_FBTBEN			BIT(9)
+#define THC_CFG_STS_CMD_INTD			BIT(10)
+#define THC_CFG_STS_CMD_INTS			BIT(19)
+#define THC_CFG_STS_CMD_CAPL			BIT(20)
+#define THC_CFG_STS_CMD_MCAP			BIT(21)
+#define THC_CFG_STS_CMD_FBTBC			BIT(23)
+#define THC_CFG_STS_CMD_MDPE			BIT(24)
+#define THC_CFG_STS_CMD_DEVT			GENMASK(26, 25)
+#define THC_CFG_STS_CMD_STA			BIT(27)
+#define THC_CFG_STS_CMD_RTA			BIT(28)
+#define THC_CFG_STS_CMD_RMA			BIT(29)
+#define THC_CFG_STS_CMD_SSE			BIT(30)
+#define THC_CFG_STS_CMD_DPE			BIT(31)
+
+#define THC_CFG_CC_RID_RID			GENMASK(7, 0)
+#define THC_CFG_CC_RID_PI			GENMASK(15, 8)
+#define THC_CFG_CC_RID_SCC			GENMASK(23, 16)
+#define THC_CFG_CC_RID_BCC			GENMASK(31, 24)
+
+#define THC_CFG_BIST_HTYPE_LT_CLS_CLSZ		GENMASK(7, 0)
+#define THC_CFG_BIST_HTYPE_LT_CLS_LT		GENMASK(15, 8)
+#define THC_CFG_BIST_HTYPE_LT_CLS_HTYPE		GENMASK(22, 16)
+#define THC_CFG_BIST_HTYPE_LT_CLS_MFD		BIT(23)
+
+#define THC_CFG_BAR0_LOW_MEMSPACE		BIT(0)
+#define THC_CFG_BAR0_LOW_TYP			GENMASK(2, 1)
+#define THC_CFG_BAR0_LOW_PREFETCH		BIT(3)
+#define THC_CFG_BAR0_LOW_MEMSIZE		GENMASK(14, 4)
+#define THC_CFG_BAR0_LOW_MEMBAR			GENMASK(31, 15)
+#define THC_CFG_BAR0_HI_MEMBAR			GENMASK(31, 0)
+
+#define THC_CFG_SID_SVID_SSVID			GENMASK(15, 0)
+#define THC_CFG_SID_SVID_SSID			GENMASK(31, 16)
+
+#define THC_CFG_CAPP_CP				GENMASK(7, 0)
+
+#define THC_CFG_INT_ILINE			GENMASK(7, 0)
+#define THC_CFG_INT_IPIN			GENMASK(15, 8)
+
+#define THC_CFG_UR_STS_CTL_URRE			BIT(0)
+#define THC_CFG_UR_STS_CTL_URD			BIT(1)
+#define THC_CFG_UR_STS_CTL_FD			BIT(2)
+
+#define THC_CFG_MSIMC_MSINP_MSICID_CAPID	GENMASK(7, 0)
+#define THC_CFG_MSIMC_MSINP_MSICID_NXTP	        GENMASK(15, 8)
+#define THC_CFG_MSIMC_MSINP_MSICID_MSIE		BIT(16)
+#define THC_CFG_MSIMC_MSINP_MSICID_MMC	        GENMASK(19, 17)
+#define THC_CFG_MSIMC_MSINP_MSICID_MMEN	        GENMASK(22, 20)
+#define THC_CFG_MSIMC_MSINP_MSICID_XAC		BIT(23)
+#define THC_CFG_MSIMC_MSINP_MSICID_PVMC		BIT(24)
+#define THC_CFG_MSIMA_MADDR		        GENMASK(31, 2)
+#define THC_CFG_MSIMUA_MAUDDR		        GENMASK(31, 0)
+#define THC_CFG_MSIMD_MDAT			GENMASK(15, 0)
+
+#define THC_CFG_PMCAP_PMNP_PMCID_CAPP	        GENMASK(7, 0)
+#define THC_CFG_PMCAP_PMNP_PMCID_NXTP	        GENMASK(15, 8)
+#define THC_CFG_PMCAP_PMNP_PMCID_VER	        GENMASK(18, 16)
+#define THC_CFG_PMCAP_PMNP_PMCID_PMECLK		BIT(19)
+#define THC_CFG_PMCAP_PMNP_PMCID_DSI		BIT(21)
+#define THC_CFG_PMCAP_PMNP_PMCID_AUXC	        GENMASK(24, 22)
+#define THC_CFG_PMCAP_PMNP_PMCID_D1S		BIT(25)
+#define THC_CFG_PMCAP_PMNP_PMCID_D2S		BIT(26)
+#define THC_CFG_PMCAP_PMNP_PMCID_PMES	        GENMASK(31, 27)
+
+#define THC_CFG_PMD_PMCSRBSE_PMCSR_PWRST	GENMASK(1, 0)
+#define THC_CFG_PMD_PMCSRBSE_PMCSR_NSR		BIT(3)
+#define THC_CFG_PMD_PMCSRBSE_PMCSR_PMEEN	BIT(8)
+#define THC_CFG_PMD_PMCSRBSE_PMCSR_DSEL	        GENMASK(12, 9)
+#define THC_CFG_PMD_PMCSRBSE_PMCSR_DS	        GENMASK(14, 13)
+#define THC_CFG_PMD_PMCSRBSE_PMCSR_PMESTS	BIT(15)
+
+#define THC_CFG_DEVIDLE_CAPPID		        GENMASK(7, 0)
+#define THC_CFG_DEVIDLE_NCAPPP		        GENMASK(15, 8)
+#define THC_CFG_DEVIDLE_LENGTH		        GENMASK(23, 16)
+#define THC_CFG_DEVIDLE_REV		        GENMASK(27, 24)
+#define THC_CFG_DEVIDLE_VID		        GENMASK(31, 28)
+
+#define THC_CFG_VSHDR_VSECID		        GENMASK(15, 0)
+#define THC_CFG_VSHDR_VSECR		        GENMASK(19, 16)
+#define THC_CFG_VSHDR_VSECL		        GENMASK(31, 20)
+
+#define THC_CFG_SWLTRPTR_VALID			BIT(0)
+#define THC_CFG_SWLTRPTR_BARNUM		        GENMASK(3, 1)
+#define THC_CFG_SWLTRPTR_SWLTRLOC		GENMASK(31, 4)
+
+#define THC_CFG_DEVIDLEPTR_VALID		BIT(0)
+#define THC_CFG_DEVIDLEPTR_BARNUM		GENMASK(3, 1)
+#define THC_CFG_DEVIDLEPTR_DEVIDLELOC	        GENMASK(31, 4)
+#define THC_CFG_DEVIDLEPOL_POLV		        GENMASK(9, 0)
+#define THC_CFG_DEVIDLEPOL_POLS		        GENMASK(12, 10)
+
+#define THC_CFG_PCE_SPE				BIT(0)
+#define THC_CFG_PCE_I3E				BIT(1)
+#define THC_CFG_PCE_D3HE			BIT(2)
+#define THC_CFG_PCE_SE				BIT(3)
+#define THC_CFG_PCE_HAE				BIT(5)
+
+#define THC_CFG_MANID_PROC			GENMASK(7, 0)
+#define THC_CFG_MANID_MID			GENMASK(15, 8)
+#define THC_CFG_MANID_MSID			GENMASK(23, 16)
+#define THC_CFG_MANID_DOT			GENMASK(27, 24)
+
+#define THC_M_CMN_DEVIDLECTRL_CIP		BIT(0)
+#define THC_M_CMN_DEVIDLECTRL_IR		BIT(1)
+#define THC_M_CMN_DEVIDLECTRL_DEVIDLE		BIT(2)
+#define THC_M_CMN_DEVIDLECTRL_RR		BIT(3)
+#define THC_M_CMN_DEVIDLECTRL_IRC		BIT(4)
+
+#define THC_M_CMN_LTR_CTRL_OFFSET		0x14
+#define THC_M_CMN_LTR_CTRL_ACTIVE_LTR_REQ	BIT(0)
+#define THC_M_CMN_LTR_CTRL_ACTIVE_LTR_EN	BIT(1)
+#define THC_M_CMN_LTR_CTRL_LP_LTR_REQ		BIT(2)
+#define THC_M_CMN_LTR_CTRL_LP_LTR_EN		BIT(3)
+#define THC_M_CMN_LTR_CTRL_LP_LTR_SCALE	        GENMASK(6, 4)
+#define THC_M_CMN_LTR_CTRL_LP_LTR_VAL	        GENMASK(16, 7)
+#define THC_M_CMN_LTR_CTRL_ACT_LTR_SCALE	GENMASK(19, 17)
+#define THC_M_CMN_LTR_CTRL_ACT_LTR_VAL	        GENMASK(29, 20)
+#define THC_M_CMN_LTR_CTRL_LAST_LTR_SENT	GENMASK(31, 30)
+
+#define THC_M_PRT_CONTROL_TSFTRST		BIT(0)
+#define THC_M_PRT_CONTROL_THC_DEVINT_QUIESCE_EN	BIT(1)
+#define THC_M_PRT_CONTROL_THC_DEVINT_QUIESCE_HW_STS	BIT(2)
+#define THC_M_PRT_CONTROL_DEVRST		BIT(3)
+#define THC_M_PRT_CONTROL_THC_DRV_LOCK_EN	BIT(13)
+#define THC_M_PRT_CONTROL_THC_INSTANCE_INDEX	GENMASK(18, 16)
+#define THC_M_PRT_CONTROL_PORT_INDEX	        GENMASK(22, 20)
+#define THC_M_PRT_CONTROL_THC_ARB_POLICY	GENMASK(25, 24)
+#define THC_M_PRT_CONTROL_THC_BIOS_LOCK_EN	BIT(27)
+#define THC_M_PRT_CONTROL_PORT_SUPPORTED	BIT(28)
+#define THC_M_PRT_CONTROL_SPI_IO_RDY		BIT(29)
+#define THC_M_PRT_CONTROL_PORT_TYPE	        GENMASK(31, 30)
+
+#define THC_M_PRT_SPI_CFG_SPI_TRDC		GENMASK(1, 0)
+#define THC_M_PRT_SPI_CFG_SPI_TRMODE	        GENMASK(3, 2)
+#define THC_M_PRT_SPI_CFG_SPI_TCRF		GENMASK(6, 4)
+#define THC_M_PRT_SPI_CFG_SPI_RD_MPS	        GENMASK(15, 7)
+#define THC_M_PRT_SPI_CFG_SPI_TWMODE	        GENMASK(19, 18)
+#define THC_M_PRT_SPI_CFG_SPI_TCWF		GENMASK(22, 20)
+#define THC_M_PRT_SPI_CFG_SPI_LOW_FREQ_EN	BIT(23)
+#define THC_M_PRT_SPI_CFG_SPI_WR_MPS	        GENMASK(31, 24)
+
+#define THC_M_PRT_SPI_ICRRD_OPCODE_SPI_SIO	GENMASK(31, 24)
+#define THC_M_PRT_SPI_ICRRD_OPCODE_SPI_DIO	GENMASK(23, 16)
+#define THC_M_PRT_SPI_ICRRD_OPCODE_SPI_QIO	GENMASK(15, 8)
+
+#define THC_M_PRT_INT_EN_SIPE				BIT(0)
+#define THC_M_PRT_INT_EN_SBO				BIT(1)
+#define THC_M_PRT_INT_EN_SIDR				BIT(2)
+#define THC_M_PRT_INT_EN_SOFB				BIT(3)
+#define THC_M_PRT_INT_EN_INVLD_DEV_ENTRY_INT_EN		BIT(9)
+#define THC_M_PRT_INT_EN_FRAME_BABBLE_ERR_INT_EN	BIT(10)
+#define THC_M_PRT_INT_EN_BUF_OVRRUN_ERR_INT_EN		BIT(12)
+#define THC_M_PRT_INT_EN_PRD_ENTRY_ERR_INT_EN		BIT(13)
+#define THC_M_PRT_INT_EN_DISP_SYNC_EVT_INT_EN		BIT(14)
+#define THC_M_PRT_INT_EN_DEV_RAW_INT_EN			BIT(15)
+#define THC_M_PRT_INT_EN_FATAL_ERR_INT_EN		BIT(16)
+#define THC_M_PRT_INT_EN_THC_I2C_IC_RX_UNDER_INT_EN	BIT(17)
+#define THC_M_PRT_INT_EN_THC_I2C_IC_RX_OVER_INT_EN	BIT(18)
+#define THC_M_PRT_INT_EN_THC_I2C_IC_RX_FULL_INT_EN	BIT(19)
+#define THC_M_PRT_INT_EN_THC_I2C_IC_TX_OVER_INT_EN	BIT(20)
+#define THC_M_PRT_INT_EN_THC_I2C_IC_TX_EMPTY_INT_EN	BIT(21)
+#define THC_M_PRT_INT_EN_THC_I2C_IC_TX_ABRT_INT_EN	BIT(22)
+#define THC_M_PRT_INT_EN_THC_I2C_IC_SCL_STUCK_AT_LOW_DET_INT_EN	BIT(24)
+#define THC_M_PRT_INT_EN_THC_I2C_IC_STOP_DET_INT_EN	BIT(25)
+#define THC_M_PRT_INT_EN_THC_I2C_IC_START_DET_INT_EN	BIT(26)
+#define THC_M_PRT_INT_EN_THC_I2C_IC_MST_ON_HOLD_INT_EN	BIT(27)
+#define THC_M_PRT_INT_EN_TXN_ERR_INT_EN			BIT(29)
+#define THC_M_PRT_INT_EN_GBL_INT_EN			BIT(31)
+
+#define THC_M_PRT_INT_STATUS_DISP_SYNC_EVT_INT_STS		BIT(14)
+#define THC_M_PRT_INT_STATUS_DEV_RAW_INT_STS			BIT(15)
+#define THC_M_PRT_INT_STATUS_THC_I2C_IC_RX_UNDER_INT_STS	BIT(17)
+#define THC_M_PRT_INT_STATUS_THC_I2C_IC_RX_OVER_INT_STS		BIT(18)
+#define THC_M_PRT_INT_STATUS_THC_I2C_IC_RX_FULL_INT_STS		BIT(19)
+#define THC_M_PRT_INT_STATUS_THC_I2C_IC_TX_OVER_INT_STS		BIT(20)
+#define THC_M_PRT_INT_STATUS_THC_I2C_IC_TX_EMPTY_INT_STS	BIT(21)
+#define THC_M_PRT_INT_STATUS_THC_I2C_IC_TX_ABRT_INT_STS		BIT(22)
+#define THC_M_PRT_INT_STATUS_THC_I2C_IC_ACTIVITY_INT_STS	BIT(23)
+#define THC_M_PRT_INT_STATUS_THC_I2C_IC_SCL_STUCK_AT_LOW_INT_STS	BIT(24)
+#define THC_M_PRT_INT_STATUS_THC_I2C_IC_STOP_DET_INT_STS	BIT(25)
+#define THC_M_PRT_INT_STATUS_THC_I2C_IC_START_DET_INT_STS	BIT(26)
+#define THC_M_PRT_INT_STATUS_THC_I2C_IC_MST_ON_HOLD_INT_STS	BIT(27)
+#define THC_M_PRT_INT_STATUS_TXN_ERR_INT_STS			BIT(28)
+#define THC_M_PRT_INT_STATUS_FATAL_ERR_INT_STS			BIT(30)
+
+#define THC_M_PRT_ERR_CAUSE_INVLD_DEV_ENTRY	BIT(9)
+#define THC_M_PRT_ERR_CAUSE_FRAME_BABBLE_ERR	BIT(10)
+#define THC_M_PRT_ERR_CAUSE_BUF_OVRRUN_ERR	BIT(12)
+#define THC_M_PRT_ERR_CAUSE_PRD_ENTRY_ERR	BIT(13)
+#define THC_M_PRT_ERR_CAUSE_FATAL_ERR_CAUSE	GENMASK(23, 16)
+
+#define THC_M_PRT_SW_SEQ_CNTRL_TSSGO		BIT(0)
+#define THC_M_PRT_SW_SEQ_CNTRL_THC_SS_CD_IE	BIT(1)
+#define THC_M_PRT_SW_SEQ_CNTRL_THC_SS_CMD	GENMASK(15, 8)
+#define THC_M_PRT_SW_SEQ_CNTRL_THC_SS_BC	GENMASK(31, 16)
+#define THC_M_PRT_SW_SEQ_STS_TSSDONE		BIT(0)
+#define THC_M_PRT_SW_SEQ_STS_THC_SS_ERR		BIT(1)
+#define THC_M_PRT_SW_SEQ_STS_THC_SS_CIP		BIT(3)
+#define THC_M_PRT_SW_SEQ_DATA0_ADDR_THC_SW_SEQ_DATA0_ADDR	GENMASK(31, 0)
+#define THC_M_PRT_SW_SEQ_DATA1_THC_SW_SEQ_DATA1		        GENMASK(31, 0)
+
+#define THC_M_PRT_WPRD_BA_LOW_THC_M_PRT_WPRD_BA_LOW	        GENMASK(31, 12)
+#define THC_M_PRT_WPRD_BA_HI_THC_M_PRT_WPRD_BA_HI		GENMASK(31, 0)
+
+#define THC_M_PRT_WRITE_DMA_CNTRL_THC_WRDMA_START		BIT(0)
+#define THC_M_PRT_WRITE_DMA_CNTRL_THC_WRDMA_IE_IOC_ERROR	BIT(1)
+#define THC_M_PRT_WRITE_DMA_CNTRL_THC_WRDMA_IE_IOC		BIT(2)
+#define THC_M_PRT_WRITE_DMA_CNTRL_THC_WRDMA_IE_IOC_DMACPL	BIT(3)
+#define THC_M_PRT_WRITE_DMA_CNTRL_THC_WRDMA_UHS			BIT(23)
+#define THC_M_PRT_WRITE_DMA_CNTRL_THC_WRDMA_PTEC		GENMASK(31, 24)
+
+#define THC_M_PRT_WRITE_INT_STS_THC_WRDMA_CMPL_STATUS		BIT(0)
+#define THC_M_PRT_WRITE_INT_STS_THC_WRDMA_ERROR_STS		BIT(1)
+#define THC_M_PRT_WRITE_INT_STS_THC_WRDMA_IOC_STS		BIT(2)
+#define THC_M_PRT_WRITE_INT_STS_THC_WRDMA_ACTIVE		BIT(3)
+
+#define THC_M_PRT_WR_BULK_ADDR_THC_M_PRT_WR_BULK_ADDR	        GENMASK(31, 0)
+
+#define THC_M_PRT_DEV_INT_CAUSE_ADDR_THC_M_PRT_DEV_INT_CAUSE_ADDR	GENMASK(31, 0)
+#define THC_M_PRT_DEV_INT_CAUSE_REG_VAL_INTERRUPT_TYPE	        GENMASK(3, 0)
+#define THC_M_PRT_DEV_INT_CAUSE_REG_VAL_MICRO_FRAME_SIZE	GENMASK(23, 4)
+#define THC_M_PRT_DEV_INT_CAUSE_REG_VAL_BEGINNING_OF_FRAME	BIT(29)
+#define THC_M_PRT_DEV_INT_CAUSE_REG_VAL_END_OF_FRAME		BIT(30)
+#define THC_M_PRT_DEV_INT_CAUSE_REG_VAL_FRAME_TYPE		BIT(31)
+
+#define THC_M_PRT_TX_FRM_CNT_THC_M_PRT_TX_FRM_CNT		GENMASK(30, 0)
+#define THC_M_PRT_TX_FRM_CNT_THC_M_PRT_TX_FRM_CNT_RST		BIT(31)
+
+#define THC_M_PRT_TXDMA_PKT_CNT_THC_M_PRT_TXDMA_PKT_CNT	        GENMASK(30, 0)
+#define THC_M_PRT_TXDMA_PKT_CNT_THC_M_PRT_TXDMA_PKT_CNT_RST	BIT(31)
+
+#define THC_M_PRT_DEVINT_CNT_THC_M_PRT_DEVINT_CNT		GENMASK(30, 0)
+#define THC_M_PRT_DEVINT_CNT_THC_M_PRT_DEVINT_CNT_RST		BIT(31)
+
+#define THC_M_PRT_DEVINT_CFG_1_THC_M_PRT_INTTYP_OFFSET	        GENMASK(4, 0)
+#define THC_M_PRT_DEVINT_CFG_1_THC_M_PRT_INTTYP_LEN	        GENMASK(9, 5)
+#define THC_M_PRT_DEVINT_CFG_1_THC_M_PRT_EOF_OFFSET	        GENMASK(14, 10)
+#define THC_M_PRT_DEVINT_CFG_1_THC_M_PRT_SEND_ICR_US_EN		BIT(15)
+#define THC_M_PRT_DEVINT_CFG_1_THC_M_PRT_INTTYP_DATA_VAL	GENMASK(31, 16)
+
+#define THC_M_PRT_DEVINT_CFG_2_THC_M_PRT_UFSIZE_OFFSET	        GENMASK(4, 0)
+#define THC_M_PRT_DEVINT_CFG_2_THC_M_PRT_UFSIZE_LEN	        GENMASK(9, 5)
+#define THC_M_PRT_DEVINT_CFG_2_THC_M_PRT_UFSIZE_UNIT	        GENMASK(15, 12)
+#define THC_M_PRT_DEVINT_CFG_2_THC_M_PRT_FTYPE_IGNORE		BIT(16)
+#define THC_M_PRT_DEVINT_CFG_2_THC_M_PRT_FTYPE_VAL		BIT(17)
+#define THC_M_PRT_DEVINT_CFG_2_THC_M_PRT_RXDMA_ADDRINC_DIS	BIT(24)
+#define THC_M_PRT_DEVINT_CFG_2_THC_M_PRT_TXDMA_ADDRINC_DIS	BIT(25)
+#define THC_M_PRT_DEVINT_CFG_2_THC_M_PRT_RXDMA_PKT_STRM_EN	BIT(26)
+#define THC_M_PRT_DEVINT_CFG_2_THC_M_PRT_TXDMA_PKT_STRM_EN	BIT(27)
+#define THC_M_PRT_DEVINT_CFG_2_THC_M_PRT_DEVINT_POL		BIT(28)
+
+#define THC_M_PRT_RPRD_BA_LOW_1_THC_M_PRT_RPRD_BA_LOW	        GENMASK(31, 12)
+#define THC_M_PRT_RPRD_BA_HI_1_THC_M_PRT_RPRD_BA_HI	        GENMASK(31, 0)
+
+#define THC_M_PRT_RPRD_CNTRL_PCD		GENMASK(6, 0)
+#define THC_M_PRT_RPRD_CNTRL_PTEC		GENMASK(15, 8)
+#define THC_M_PRT_RPRD_CNTRL_PREFETCH_WM	GENMASK(19, 16)
+
+#define THC_M_PRT_READ_DMA_CNTRL_START		BIT(0)
+#define THC_M_PRT_READ_DMA_CNTRL_IE_ERROR	BIT(1)
+#define THC_M_PRT_READ_DMA_CNTRL_IE_IOC		BIT(2)
+#define THC_M_PRT_READ_DMA_CNTRL_IE_STALL	BIT(3)
+#define THC_M_PRT_READ_DMA_CNTRL_IE_NDDI	BIT(4)
+#define THC_M_PRT_READ_DMA_CNTRL_IE_EOF		BIT(5)
+#define THC_M_PRT_READ_DMA_CNTRL_IE_DMACPL	BIT(7)
+#define THC_M_PRT_READ_DMA_CNTRL_TPCRP	        GENMASK(15, 8)
+#define THC_M_PRT_READ_DMA_CNTRL_TPCWP	        GENMASK(23, 16)
+#define THC_M_PRT_READ_DMA_CNTRL_INT_SW_DMA_EN	BIT(28)
+#define THC_M_PRT_READ_DMA_CNTRL_SOO		BIT(29)
+#define THC_M_PRT_READ_DMA_CNTRL_UHS		BIT(30)
+#define THC_M_PRT_READ_DMA_CNTRL_TPCPR		BIT(31)
+
+#define THC_M_PRT_READ_DMA_INT_STS_DMACPL_STS	BIT(0)
+#define THC_M_PRT_READ_DMA_INT_STS_ERROR_STS	BIT(1)
+#define THC_M_PRT_READ_DMA_INT_STS_IOC_STS	BIT(2)
+#define THC_M_PRT_READ_DMA_INT_STS_STALL_STS	BIT(3)
+#define THC_M_PRT_READ_DMA_INT_STS_NONDMA_INT_STS	BIT(4)
+#define THC_M_PRT_READ_DMA_INT_STS_EOF_INT_STS	BIT(5)
+#define THC_M_PRT_READ_DMA_INT_STS_ACTIVE	BIT(8)
+
+#define THC_M_PRT_READ_DMA_ERR_1_DLERR		BIT(0)
+
+#define THC_M_PRT_GUC_OFFSET_LOW_1_THC_M_PRT_GUC_OFFSET_LOW	GENMASK(31, 3)
+#define THC_M_PRT_GUC_OFFSET_HI_1_THC_M_PRT_GUC_OFFSET_HI	GENMASK(31, 0)
+#define THC_M_PRT_GUC_WORKQ_ITEM_SZ_1_WORKQ_ITEM_SZ	        GENMASK(23, 0)
+#define THC_M_PRT_GUC_WORKQ_SZ_1_WORKQ_SZ       GENMASK(23, 0)
+#define THC_M_PRT_GUC_WORKQ_SZ_1_FCD	        GENMASK(27, 24)
+#define THC_M_PRT_GUC_WORKQ_SZ_1_GIC	        GENMASK(31, 28)
+
+#define THC_M_PRT_TSEQ_CNTRL_1_RGD		BIT(2)
+#define THC_M_PRT_TSEQ_CNTRL_1_EGP		BIT(3)
+#define THC_M_PRT_TSEQ_CNTRL_1_RTO		BIT(4)
+#define THC_M_PRT_TSEQ_CNTRL_1_EWOG		BIT(5)
+#define THC_M_PRT_TSEQ_CNTRL_1_RWOGC		BIT(6)
+#define THC_M_PRT_TSEQ_CNTRL_1_RX_DATA_FIFO_WR_WM		GENMASK(25, 16)
+#define THC_M_PRT_TSEQ_CNTRL_1_RESET_PREP_CHICKEN		BIT(30)
+#define THC_M_PRT_TSEQ_CNTRL_1_INT_EDG_DET_EN			BIT(31)
+
+#define THC_M_PRT_GUC_DB_ADDR_LOW_1_GUC_DB_ADDR_LOW	        GENMASK(31, 2)
+#define THC_M_PRT_GUC_DB_ADDR_HI_1_GUC_DB_ADDR_HI		GENMASK(31, 0)
+#define THC_M_PRT_GUC_DB_DATA_1_GUC_DB_DATA		        GENMASK(31, 0)
+#define THC_M_PRT_GUC_OFFSET_INITVAL_1_THC_M_PRT_GUC_OFFSET_INITVAL	GENMASK(31, 0)
+
+#define THC_M_PRT_RD_BULK_ADDR_1_THC_M_PRT_RD_BULK_ADDR	        GENMASK(31, 0)
+
+#define THC_M_PRT_DB_CNT_1_THC_M_PRT_DB_CNT		        GENMASK(30, 0)
+#define THC_M_PRT_DB_CNT_1_THC_M_PRT_DB_CNT_RST			BIT(31)
+
+#define THC_M_PRT_FRM_CNT_1_THC_M_PRT_FRM_CNT		        GENMASK(30, 0)
+#define THC_M_PRT_FRM_CNT_1_THC_M_PRT_FRM_CNT_RST		BIT(31)
+
+#define THC_M_PRT_UFRM_CNT_1_THC_M_PRT_UFRM_CNT		        GENMASK(30, 0)
+#define THC_M_PRT_UFRM_CNT_1_THC_M_PRT_UFRM_CNT_RST		BIT(31)
+
+#define THC_M_PRT_RXDMA_PKT_CNT_1_THC_M_PRT_RXDMA_PKT_CNT	GENMASK(30, 0)
+#define THC_M_PRT_RXDMA_PKT_CNT_1_THC_M_PRT_RXDMA_PKT_CNT_RST	BIT(31)
+
+#define THC_M_PRT_SWINT_CNT_1_THC_M_PRT_SWINT_CNT		GENMASK(30, 0)
+#define THC_M_PRT_SWINT_CNT_1_THC_M_PRT_SWINT_CNT_RST		BIT(31)
+
+#define THC_M_PRT_FRAME_DROP_CNT_1_NOFD			        GENMASK(30, 0)
+#define THC_M_PRT_FRAME_DROP_CNT_1_RFDC				BIT(31)
+
+#define THC_M_PRT_COALESCE_1_COALESCE_TIMEOUT		        GENMASK(6, 0)
+
+#define THC_M_PRT_RPRD_BA_LOW_2_THC_M_PRT_RPRD_BA_LOW	        GENMASK(31, 12)
+#define THC_M_PRT_RPRD_BA_HI_2_THC_M_PRT_RPRD_BA_HI	        GENMASK(31, 0)
+
+#define THC_M_PRT_READ_DMA_ERR_2_DLERR				BIT(0)
+
+#define THC_M_PRT_GUC_OFFSET_LOW_2_THC_M_PRT_GUC_OFFSET_LOW     GENMASK(31, 3)
+#define THC_M_PRT_GUC_OFFSET_HI_2_THC_M_PRT_GUC_OFFSET_HI	GENMASK(31, 0)
+
+#define THC_M_PRT_GUC_WORKQ_ITEM_SZ_2_WORKQ_ITEM_SZ	        GENMASK(23, 0)
+#define THC_M_PRT_GUC_WORKQ_SZ_2_WORKQ_SZ			GENMASK(23, 0)
+#define THC_M_PRT_GUC_WORKQ_SZ_2_FCD			        GENMASK(27, 24)
+#define THC_M_PRT_GUC_WORKQ_SZ_2_GIC			        GENMASK(31, 28)
+
+#define THC_M_PRT_TSEQ_CNTRL_2_RGD				BIT(2)
+#define THC_M_PRT_TSEQ_CNTRL_2_EGP				BIT(3)
+#define THC_M_PRT_TSEQ_CNTRL_2_RTO				BIT(4)
+
+#define THC_M_PRT_GUC_DB_ADDR_LOW_2_GUC_DB_ADDR_LOW	        GENMASK(31, 2)
+#define THC_M_PRT_GUC_DB_ADDR_HI_2_GUC_DB_ADDR_HI		GENMASK(31, 0)
+
+#define THC_M_PRT_GUC_DB_DATA_2_GUC_DB_DATA		        GENMASK(31, 0)
+
+#define THC_M_PRT_GUC_OFFSET_INITVAL_2_THC_M_PRT_GUC_OFFSET_INITVAL	GENMASK(31, 0)
+
+#define THC_M_PRT_RD_BULK_ADDR_2_THC_M_PRT_RD_BULK_ADDR	        GENMASK(31, 0)
+
+#define THC_M_PRT_DB_CNT_2_THC_M_PRT_DB_CNT		        GENMASK(30, 0)
+#define THC_M_PRT_DB_CNT_2_THC_M_PRT_DB_CNT_RST			BIT(31)
+
+#define THC_M_PRT_FRM_CNT_2_THC_M_PRT_FRM_CNT		        GENMASK(30, 0)
+#define THC_M_PRT_FRM_CNT_2_THC_M_PRT_FRM_CNT_RST		BIT(31)
+
+#define THC_M_PRT_UFRM_CNT_2_THC_M_PRT_UFRM_CNT		        GENMASK(30, 0)
+#define THC_M_PRT_UFRM_CNT_2_THC_M_PRT_UFRM_CNT_RST		BIT(31)
+
+#define THC_M_PRT_RXDMA_PKT_CNT_2_THC_M_PRT_RXDMA_PKT_CNT	GENMASK(30, 0)
+#define THC_M_PRT_RXDMA_PKT_CNT_2_THC_M_PRT_RXDMA_PKT_CNT_RST	BIT(31)
+
+#define THC_M_PRT_SWINT_CNT_2_THC_M_PRT_SWINT_CNT		GENMASK(30, 0)
+#define THC_M_PRT_SWINT_CNT_2_THC_M_PRT_SWINT_CNT_RST		BIT(31)
+
+#define THC_M_PRT_FRAME_DROP_CNT_2_NOFD			        GENMASK(30, 0)
+#define THC_M_PRT_FRAME_DROP_CNT_2_RFDC				BIT(31)
+
+#define THC_M_PRT_COALESCE_2_COALESCE_TIMEOUT		        GENMASK(6, 0)
+
+#define THC_M_PRT_SW_SEQ_I2C_WR_CNTRL_THC_I2C_RW_PIO_EN		BIT(23)
+#define THC_M_PRT_SW_SEQ_I2C_WR_CNTRL_THC_PIO_I2C_WBC	        GENMASK(31, 26)
+
+#define THC_M_PRT_RPRD_CNTRL_SW_THC_SWDMA_I2C_RX_DLEN_EN	BIT(23)
+#define THC_M_PRT_RPRD_CNTRL_SW_THC_SWDMA_I2C_WBC		GENMASK(31, 26)
+
+#define THC_M_PRT_PRD_EMPTY_CNT_1_RPTEC				BIT(31)
+#define THC_M_PRT_PRD_EMPTY_CNT_2_RPTEC				BIT(31)
+
+#define THC_M_PRT_SW_DMA_PRD_TABLE_LEN_THC_M_PRT_SW_DMA_PRD_TABLE_LEN	GENMASK(23, 0)
+
+#endif /* _INTEL_THC_HW_H_  */
Signature · 1 line
2.40.1
author maintainer
#9 lore raw

PATCH v4 4/22 HID: intel-thc-hid: intel-thc: Add THC PIO operation APIs

In reply to Even Xu

From: Xinpeng Sun <[email protected]>

THC PIO (programmed I/O) operations are very similar with general SPI/I2C read/write operation to access external slave device on the bus through internal FIFO.

THC PIO operations are split into 4 steps:
1. prepare: configure hardware with correct opcode, slave address, and fill the PIO FIFO
2. start: set start bit to issue a bus send/receive
3. wait: wait for bus sending/receiving completion
4. complete: check send/receive data in FIFO and return

---
 .../intel-thc-hid/intel-thc/intel-thc-dev.c   | 245 ++++++++++++++++++
 .../intel-thc-hid/intel-thc/intel-thc-dev.h   |  24 ++
 .../intel-thc-hid/intel-thc/intel-thc-hw.h    |  23 ++
 3 files changed, 292 insertions(+)
drivers/hid/intel-thc-hid/intel-thc/intel-thc-dev.c +245 -0
index de7a0ed38c25..397250c38ae7 100644
@@ -1,9 +1,11 @@
 /* SPDX-License-Identifier: GPL-2.0 */
 /* Copyright (c) 2024 Intel Corporation */
 
+#include <linux/bitfield.h>
 #include <linux/regmap.h>
 
 #include "intel-thc-dev.h"
+#include "intel-thc-hw.h"
 
 static int thc_regmap_read(void *context, unsigned int reg,
 			   unsigned int *val)
@@ -208,10 +210,253 @@ struct thc_device *thc_dev_init(struct device *device, void __iomem *mem_addr)
 
 	thc_clear_state(thc_dev);
 
+	mutex_init(&thc_dev->thc_bus_lock);
+
 	return thc_dev;
 }
 EXPORT_SYMBOL_NS_GPL(thc_dev_init, "INTEL_THC");
 
+static int prepare_pio(const struct thc_device *dev, const u8 pio_op,
+		       const u32 address, const u32 size)
+{
+	u32 sts, ctrl, addr, mask;
+
+	regmap_read(dev->thc_regmap, THC_M_PRT_SW_SEQ_STS_OFFSET, &sts);
+
+	/* Check if THC previous PIO still in progress */
+	if (sts & THC_M_PRT_SW_SEQ_STS_THC_SS_CIP) {
+		dev_err_once(dev->dev, "THC PIO is still busy!\n");
+		return -EBUSY;
+	}
+
+	/* Clear error bit and complete bit in state register */
+	sts |= THC_M_PRT_SW_SEQ_STS_THC_SS_ERR |
+	       THC_M_PRT_SW_SEQ_STS_TSSDONE;
+	regmap_write(dev->thc_regmap, THC_M_PRT_SW_SEQ_STS_OFFSET, sts);
+
+	/* Set PIO data size, opcode and interrupt capability */
+	ctrl = FIELD_PREP(THC_M_PRT_SW_SEQ_CNTRL_THC_SS_BC, size) |
+	       FIELD_PREP(THC_M_PRT_SW_SEQ_CNTRL_THC_SS_CMD, pio_op);
+	if (dev->pio_int_supported)
+		ctrl |= THC_M_PRT_SW_SEQ_CNTRL_THC_SS_CD_IE;
+
+	mask = THC_M_PRT_SW_SEQ_CNTRL_THC_SS_BC |
+	       THC_M_PRT_SW_SEQ_CNTRL_THC_SS_CMD |
+	       THC_M_PRT_SW_SEQ_CNTRL_THC_SS_CD_IE;
+	regmap_write_bits(dev->thc_regmap,
+			  THC_M_PRT_SW_SEQ_CNTRL_OFFSET, mask, ctrl);
+
+	/* Set PIO target address */
+	addr = FIELD_PREP(THC_M_PRT_SW_SEQ_DATA0_ADDR_THC_SW_SEQ_DATA0_ADDR, address);
+	mask = THC_M_PRT_SW_SEQ_DATA0_ADDR_THC_SW_SEQ_DATA0_ADDR;
+	regmap_write_bits(dev->thc_regmap,
+			  THC_M_PRT_SW_SEQ_DATA0_ADDR_OFFSET, mask, addr);
+	return 0;
+}
+
+static void pio_start(const struct thc_device *dev,
+		      u32 size_in_bytes, const u32 *buffer)
+{
+	if (size_in_bytes && buffer)
+		regmap_bulk_write(dev->thc_regmap, THC_M_PRT_SW_SEQ_DATA1_OFFSET,
+				  buffer, size_in_bytes / sizeof(u32));
+
+	/* Enable Start bit */
+	regmap_write_bits(dev->thc_regmap,
+			  THC_M_PRT_SW_SEQ_CNTRL_OFFSET,
+			  THC_M_PRT_SW_SEQ_CNTRL_TSSGO,
+			  THC_M_PRT_SW_SEQ_CNTRL_TSSGO);
+}
+
+static int pio_complete(const struct thc_device *dev,
+			u32 *buffer, u32 *size)
+{
+	u32 sts, ctrl;
+
+	regmap_read(dev->thc_regmap, THC_M_PRT_SW_SEQ_STS_OFFSET, &sts);
+	if (sts & THC_M_PRT_SW_SEQ_STS_THC_SS_ERR) {
+		dev_err_once(dev->dev, "PIO operation error\n");
+		return -EBUSY;
+	}
+
+	if (buffer && size) {
+		regmap_read(dev->thc_regmap, THC_M_PRT_SW_SEQ_CNTRL_OFFSET, &ctrl);
+		*size = FIELD_GET(THC_M_PRT_SW_SEQ_CNTRL_THC_SS_BC, ctrl);
+
+		regmap_bulk_read(dev->thc_regmap, THC_M_PRT_SW_SEQ_DATA1_OFFSET,
+				 buffer, *size / sizeof(u32));
+	}
+
+	sts |= THC_M_PRT_SW_SEQ_STS_THC_SS_ERR | THC_M_PRT_SW_SEQ_STS_TSSDONE;
+	regmap_write(dev->thc_regmap, THC_M_PRT_SW_SEQ_STS_OFFSET, sts);
+	return 0;
+}
+
+static int pio_wait(const struct thc_device *dev)
+{
+	u32 sts = 0;
+	int ret;
+
+	ret = regmap_read_poll_timeout(dev->thc_regmap, THC_M_PRT_SW_SEQ_STS_OFFSET, sts,
+				       !(sts & THC_M_PRT_SW_SEQ_STS_THC_SS_CIP ||
+				       !(sts & THC_M_PRT_SW_SEQ_STS_TSSDONE)),
+				       THC_REGMAP_POLLING_INTERVAL_US, THC_PIO_DONE_TIMEOUT_US);
+	if (ret)
+		dev_err_once(dev->dev, "Timeout while polling PIO operation done\n");
+
+	return ret;
+}
+
+/**
+ * thc_tic_pio_read - Read data from touch device by PIO
+ *
+ * @dev: The pointer of THC private device context
+ * @address: Slave address for the PIO operation
+ * @size: Expected read data size
+ * @actual_size: The pointer of the actual data size read from touch device
+ * @buffer: The pointer of data buffer to store the data read from touch device
+ *
+ * Return: 0 on success, other error codes on failed.
+ */
+int thc_tic_pio_read(struct thc_device *dev, const u32 address,
+		     const u32 size, u32 *actual_size, u32 *buffer)
+{
+	u8 opcode;
+	int ret;
+
+	if (size <= 0 || !actual_size || !buffer) {
+		dev_err(dev->dev, "Invalid input parameters, size %u, actual_size %p, buffer %p\n",
+			size, actual_size, buffer);
+		return -EINVAL;
+	}
+
+	if (mutex_lock_interruptible(&dev->thc_bus_lock))
+		return -EINTR;
+
+	opcode = (dev->port_type == THC_PORT_TYPE_SPI) ?
+		 THC_PIO_OP_SPI_TIC_READ : THC_PIO_OP_I2C_TIC_READ;
+
+	ret = prepare_pio(dev, opcode, address, size);
+	if (ret < 0)
+		goto end;
+
+	pio_start(dev, 0, NULL);
+
+	ret = pio_wait(dev);
+	if (ret < 0)
+		goto end;
+
+	ret = pio_complete(dev, buffer, actual_size);
+
+end:
+	mutex_unlock(&dev->thc_bus_lock);
+	return ret;
+}
+EXPORT_SYMBOL_NS_GPL(thc_tic_pio_read, "INTEL_THC");
+
+/**
+ * thc_tic_pio_write - Write data to touch device by PIO
+ *
+ * @dev: The pointer of THC private device context
+ * @address: Slave address for the PIO operation
+ * @size: PIO write data size
+ * @buffer: The pointer of the write data buffer
+ *
+ * Return: 0 on success, other error codes on failed.
+ */
+int thc_tic_pio_write(struct thc_device *dev, const u32 address,
+		      const u32 size, const u32 *buffer)
+{
+	u8 opcode;
+	int ret;
+
+	if (size <= 0 || !buffer) {
+		dev_err(dev->dev, "Invalid input parameters, size %u, buffer %p\n",
+			size, buffer);
+		return -EINVAL;
+	}
+
+	if (mutex_lock_interruptible(&dev->thc_bus_lock))
+		return -EINTR;
+
+	opcode = (dev->port_type == THC_PORT_TYPE_SPI) ?
+		 THC_PIO_OP_SPI_TIC_WRITE : THC_PIO_OP_I2C_TIC_WRITE;
+
+	ret = prepare_pio(dev, opcode, address, size);
+	if (ret < 0)
+		goto end;
+
+	pio_start(dev, size, buffer);
+
+	ret = pio_wait(dev);
+	if (ret < 0)
+		goto end;
+
+	ret = pio_complete(dev, NULL, NULL);
+
+end:
+	mutex_unlock(&dev->thc_bus_lock);
+	return ret;
+}
+EXPORT_SYMBOL_NS_GPL(thc_tic_pio_write, "INTEL_THC");
+
+/**
+ * thc_tic_pio_write_and_read - Write data followed by read data by PIO
+ *
+ * @dev: The pointer of THC private device context
+ * @address: Slave address for the PIO operation
+ * @write_size: PIO write data size
+ * @write_buffer: The pointer of the write data buffer
+ * @read_size: Expected PIO read data size
+ * @actual_size: The pointer of the actual read data size
+ * @read_buffer: The pointer of PIO read data buffer
+ *
+ * Return: 0 on success, other error codes on failed.
+ */
+int thc_tic_pio_write_and_read(struct thc_device *dev, const u32 address,
+			       const u32 write_size, const u32 *write_buffer,
+			       const u32 read_size, u32 *actual_size, u32 *read_buffer)
+{
+	u32 i2c_ctrl, mask;
+	int ret;
+
+	if (dev->port_type == THC_PORT_TYPE_SPI) {
+		dev_err(dev->dev, "SPI port type doesn't support pio write and read!");
+		return -EINVAL;
+	}
+
+	if (mutex_lock_interruptible(&dev->thc_bus_lock))
+		return -EINTR;
+
+	/* Config i2c PIO write and read sequence */
+	i2c_ctrl = FIELD_PREP(THC_M_PRT_SW_SEQ_I2C_WR_CNTRL_THC_PIO_I2C_WBC, write_size);
+	mask = THC_M_PRT_SW_SEQ_I2C_WR_CNTRL_THC_PIO_I2C_WBC;
+
+	regmap_write_bits(dev->thc_regmap, THC_M_PRT_SW_SEQ_I2C_WR_CNTRL_OFFSET,
+			  mask, i2c_ctrl);
+
+	regmap_write_bits(dev->thc_regmap, THC_M_PRT_SW_SEQ_I2C_WR_CNTRL_OFFSET,
+			  THC_M_PRT_SW_SEQ_I2C_WR_CNTRL_THC_I2C_RW_PIO_EN,
+			  THC_M_PRT_SW_SEQ_I2C_WR_CNTRL_THC_I2C_RW_PIO_EN);
+
+	ret = prepare_pio(dev, THC_PIO_OP_I2C_TIC_WRITE_AND_READ, address, read_size);
+	if (ret < 0)
+		goto end;
+
+	pio_start(dev, write_size, write_buffer);
+
+	ret = pio_wait(dev);
+	if (ret < 0)
+		goto end;
+
+	ret = pio_complete(dev, read_buffer, actual_size);
+
+end:
+	mutex_unlock(&dev->thc_bus_lock);
+	return ret;
+}
+EXPORT_SYMBOL_NS_GPL(thc_tic_pio_write_and_read, "INTEL_THC");
+
 MODULE_AUTHOR("Xinpeng Sun <[email protected]>");
 MODULE_AUTHOR("Even Xu <[email protected]>");
 
drivers/hid/intel-thc-hid/intel-thc/intel-thc-dev.h +24 -0
index 7060f0a36cbd..88a9f606a6a9 100644
@@ -5,21 +5,45 @@
 #define _INTEL_THC_DEV_H_
 
 #include <linux/cdev.h>
+#include <linux/mutex.h>
 
 #define THC_REGMAP_COMMON_OFFSET  0x10
 #define THC_REGMAP_MMIO_OFFSET    0x1000
 
+/*
+ * THC Port type
+ * @THC_PORT_TYPE_SPI: This port is used for HIDSPI
+ * @THC_PORT_TYPE_I2C: This port is used for HIDI2C
+ */
+enum thc_port_type {
+	THC_PORT_TYPE_SPI = 0,
+	THC_PORT_TYPE_I2C = 1,
+};
+
 /**
  * struct thc_device - THC private device struct
  * @thc_regmap: MMIO regmap structure for accessing THC registers
  * @mmio_addr: MMIO registers address
+ * @thc_bus_lock: mutex locker for THC config
+ * @port_type: port type of THC port instance
+ * @pio_int_supported: PIO interrupt supported flag
  */
 struct thc_device {
 	struct device *dev;
 	struct regmap *thc_regmap;
 	void __iomem *mmio_addr;
+	struct mutex thc_bus_lock;
+	enum thc_port_type port_type;
+	bool pio_int_supported;
 };
 
 struct thc_device *thc_dev_init(struct device *device, void __iomem *mem_addr);
+int thc_tic_pio_read(struct thc_device *dev, const u32 address,
+		     const u32 size, u32 *actual_size, u32 *buffer);
+int thc_tic_pio_write(struct thc_device *dev, const u32 address,
+		      const u32 size, const u32 *buffer);
+int thc_tic_pio_write_and_read(struct thc_device *dev, const u32 address,
+			       const u32 write_size, const u32 *write_buffer,
+			       const u32 read_size, u32 *actual_size, u32 *read_buffer);
 
 #endif /* _INTEL_THC_DEV_H_ */
drivers/hid/intel-thc-hid/intel-thc/intel-thc-hw.h +23 -0
index 8b3a962e7e64..60f5f657be62 100644
@@ -636,4 +636,27 @@
 
 #define THC_M_PRT_SW_DMA_PRD_TABLE_LEN_THC_M_PRT_SW_DMA_PRD_TABLE_LEN	GENMASK(23, 0)
 
+#define THC_REGMAP_POLLING_INTERVAL_US		10 /* 10us */
+#define THC_PIO_DONE_TIMEOUT_US			USEC_PER_SEC /* 1s */
+
+/*
+ * THC PIO opcode default value
+ * @THC_PIO_OP_SPI_TIC_READ: THC opcode for SPI PIO read
+ * @THC_PIO_OP_SPI_TIC_WRITE: THC opcode for SPI PIO write
+ * @THC_PIO_OP_I2C_SUBSYSTEM_READ: THC opcode for read I2C subsystem registers
+ * @THC_PIO_OP_I2C_SUBSYSTEM_WRITE: THC opcode for write I2C subsystem registers
+ * @THC_PIO_OP_I2C_TIC_READ: THC opcode for read I2C device
+ * @THC_PIO_OP_I2C_TIC_WRITE: THC opcode for write I2C device
+ * @THC_PIO_OP_I2C_TIC_WRITE_AND_READ: THC opcode for write followed by read I2C device
+ */
+enum thc_pio_opcode {
+	THC_PIO_OP_SPI_TIC_READ = 0x4,
+	THC_PIO_OP_SPI_TIC_WRITE = 0x6,
+	THC_PIO_OP_I2C_SUBSYSTEM_READ = 0x12,
+	THC_PIO_OP_I2C_SUBSYSTEM_WRITE = 0x13,
+	THC_PIO_OP_I2C_TIC_READ = 0x14,
+	THC_PIO_OP_I2C_TIC_WRITE = 0x18,
+	THC_PIO_OP_I2C_TIC_WRITE_AND_READ = 0x1C,
+};
+
 #endif /* _INTEL_THC_HW_H_  */
Signature · 1 line
2.40.1
author maintainer
#10 lore raw

PATCH v4 5/22 HID: intel-thc-hid: intel-thc: Add APIs for interrupt

In reply to Even Xu

From: Xinpeng Sun <[email protected]>

Add THC interrupt operation interfaces, such as interrupt configure, global interrupt enable/disable, external touch device GPIO interrupt quiesce and unquiesce.

---
 .../intel-thc-hid/intel-thc/intel-thc-dev.c   | 223 ++++++++++++++++++
 .../intel-thc-hid/intel-thc/intel-thc-dev.h   |   5 +
 .../intel-thc-hid/intel-thc/intel-thc-hw.h    |  17 ++
 3 files changed, 245 insertions(+)
drivers/hid/intel-thc-hid/intel-thc/intel-thc-dev.c +223 -0
index 397250c38ae7..e16810b2fb9d 100644
@@ -457,6 +457,229 @@ int thc_tic_pio_write_and_read(struct thc_device *dev, const u32 address,
 }
 EXPORT_SYMBOL_NS_GPL(thc_tic_pio_write_and_read, "INTEL_THC");
 
+/**
+ * thc_interrupt_config - Configure THC interrupts
+ *
+ * @dev: The pointer of THC private device context
+ */
+void thc_interrupt_config(struct thc_device *dev)
+{
+	u32 mbits, mask, r_dma_ctrl_1;
+
+	/* Clear Error reporting interrupt status bits */
+	mbits = THC_M_PRT_INT_STATUS_TXN_ERR_INT_STS |
+		THC_M_PRT_INT_STATUS_FATAL_ERR_INT_STS;
+	regmap_write_bits(dev->thc_regmap,
+			  THC_M_PRT_INT_STATUS_OFFSET,
+			  mbits, mbits);
+
+	/* Enable Error Reporting Interrupts */
+	mbits = THC_M_PRT_INT_EN_TXN_ERR_INT_EN |
+		THC_M_PRT_INT_EN_FATAL_ERR_INT_EN |
+		THC_M_PRT_INT_EN_BUF_OVRRUN_ERR_INT_EN;
+	regmap_write_bits(dev->thc_regmap,
+			  THC_M_PRT_INT_EN_OFFSET,
+			  mbits, mbits);
+
+	/* Clear PIO Interrupt status bits */
+	mbits = THC_M_PRT_SW_SEQ_STS_THC_SS_ERR |
+		THC_M_PRT_SW_SEQ_STS_TSSDONE;
+	regmap_write_bits(dev->thc_regmap,
+			  THC_M_PRT_SW_SEQ_STS_OFFSET,
+			  mbits, mbits);
+
+	/* Read Interrupts */
+	regmap_read(dev->thc_regmap,
+		    THC_M_PRT_READ_DMA_CNTRL_1_OFFSET,
+		    &r_dma_ctrl_1);
+	/* Disable RxDMA1 */
+	r_dma_ctrl_1 &= ~THC_M_PRT_READ_DMA_CNTRL_IE_EOF;
+	regmap_write(dev->thc_regmap,
+		     THC_M_PRT_READ_DMA_CNTRL_1_OFFSET,
+		     r_dma_ctrl_1);
+
+	/* Ack EOF Interrupt RxDMA1 */
+	mbits = THC_M_PRT_READ_DMA_INT_STS_EOF_INT_STS;
+	/* Ack NonDMA Interrupt */
+	mbits |= THC_M_PRT_READ_DMA_INT_STS_NONDMA_INT_STS;
+	regmap_write_bits(dev->thc_regmap,
+			  THC_M_PRT_READ_DMA_INT_STS_1_OFFSET,
+			  mbits, mbits);
+
+	/* Ack EOF Interrupt RxDMA2 */
+	regmap_write_bits(dev->thc_regmap,
+			  THC_M_PRT_READ_DMA_INT_STS_2_OFFSET,
+			  THC_M_PRT_READ_DMA_INT_STS_EOF_INT_STS,
+			  THC_M_PRT_READ_DMA_INT_STS_EOF_INT_STS);
+
+	/* Write Interrupts */
+	/* Disable TxDMA */
+	regmap_write_bits(dev->thc_regmap,
+			  THC_M_PRT_WRITE_DMA_CNTRL_OFFSET,
+			  THC_M_PRT_WRITE_DMA_CNTRL_THC_WRDMA_IE_IOC_DMACPL,
+			  0);
+
+	/* Clear TxDMA interrupt status bits */
+	mbits = THC_M_PRT_WRITE_INT_STS_THC_WRDMA_ERROR_STS;
+	mbits |=  THC_M_PRT_WRITE_INT_STS_THC_WRDMA_IOC_STS;
+	regmap_write_bits(dev->thc_regmap,
+			  THC_M_PRT_WRITE_INT_STS_OFFSET,
+			  mbits, mbits);
+
+	/* Enable Non-DMA device inband interrupt */
+	r_dma_ctrl_1 |= THC_M_PRT_READ_DMA_CNTRL_IE_NDDI;
+	regmap_write(dev->thc_regmap,
+		     THC_M_PRT_READ_DMA_CNTRL_1_OFFSET,
+		     r_dma_ctrl_1);
+
+	if (dev->port_type == THC_PORT_TYPE_SPI) {
+		/* Edge triggered interrupt */
+		regmap_write_bits(dev->thc_regmap, THC_M_PRT_TSEQ_CNTRL_1_OFFSET,
+				  THC_M_PRT_TSEQ_CNTRL_1_INT_EDG_DET_EN,
+				  THC_M_PRT_TSEQ_CNTRL_1_INT_EDG_DET_EN);
+	} else {
+		/* Level triggered interrupt */
+		regmap_write_bits(dev->thc_regmap, THC_M_PRT_TSEQ_CNTRL_1_OFFSET,
+				  THC_M_PRT_TSEQ_CNTRL_1_INT_EDG_DET_EN, 0);
+
+		mbits = THC_M_PRT_INT_EN_THC_I2C_IC_MST_ON_HOLD_INT_EN |
+			THC_M_PRT_INT_EN_THC_I2C_IC_SCL_STUCK_AT_LOW_DET_INT_EN |
+			THC_M_PRT_INT_EN_THC_I2C_IC_TX_ABRT_INT_EN |
+			THC_M_PRT_INT_EN_THC_I2C_IC_TX_OVER_INT_EN |
+			THC_M_PRT_INT_EN_THC_I2C_IC_RX_FULL_INT_EN |
+			THC_M_PRT_INT_EN_THC_I2C_IC_RX_OVER_INT_EN |
+			THC_M_PRT_INT_EN_THC_I2C_IC_RX_UNDER_INT_EN;
+		regmap_write_bits(dev->thc_regmap, THC_M_PRT_INT_EN_OFFSET,
+				  mbits, mbits);
+	}
+
+	thc_set_pio_interrupt_support(dev, false);
+
+	/* HIDSPI specific settings */
+	if (dev->port_type == THC_PORT_TYPE_SPI) {
+		mbits = FIELD_PREP(THC_M_PRT_DEVINT_CFG_1_THC_M_PRT_INTTYP_OFFSET,
+				   THC_BIT_OFFSET_INTERRUPT_TYPE) |
+			FIELD_PREP(THC_M_PRT_DEVINT_CFG_1_THC_M_PRT_INTTYP_LEN,
+				   THC_BIT_LENGTH_INTERRUPT_TYPE) |
+			FIELD_PREP(THC_M_PRT_DEVINT_CFG_1_THC_M_PRT_EOF_OFFSET,
+				   THC_BIT_OFFSET_LAST_FRAGMENT_FLAG) |
+			FIELD_PREP(THC_M_PRT_DEVINT_CFG_1_THC_M_PRT_INTTYP_DATA_VAL,
+				   THC_BITMASK_INVALID_TYPE_DATA);
+		mask = THC_M_PRT_DEVINT_CFG_1_THC_M_PRT_INTTYP_OFFSET |
+		       THC_M_PRT_DEVINT_CFG_1_THC_M_PRT_INTTYP_LEN |
+		       THC_M_PRT_DEVINT_CFG_1_THC_M_PRT_EOF_OFFSET |
+		       THC_M_PRT_DEVINT_CFG_1_THC_M_PRT_INTTYP_DATA_VAL;
+		regmap_write_bits(dev->thc_regmap, THC_M_PRT_DEVINT_CFG_1_OFFSET,
+				  mask, mbits);
+
+		mbits = FIELD_PREP(THC_M_PRT_DEVINT_CFG_2_THC_M_PRT_UFSIZE_OFFSET,
+				   THC_BIT_OFFSET_MICROFRAME_SIZE) |
+			FIELD_PREP(THC_M_PRT_DEVINT_CFG_2_THC_M_PRT_UFSIZE_LEN,
+				   THC_BIT_LENGTH_MICROFRAME_SIZE) |
+			FIELD_PREP(THC_M_PRT_DEVINT_CFG_2_THC_M_PRT_UFSIZE_UNIT,
+				   THC_UNIT_MICROFRAME_SIZE) |
+			THC_M_PRT_DEVINT_CFG_2_THC_M_PRT_FTYPE_IGNORE |
+			THC_M_PRT_DEVINT_CFG_2_THC_M_PRT_FTYPE_VAL;
+		mask = THC_M_PRT_DEVINT_CFG_2_THC_M_PRT_UFSIZE_OFFSET |
+		       THC_M_PRT_DEVINT_CFG_2_THC_M_PRT_UFSIZE_LEN |
+		       THC_M_PRT_DEVINT_CFG_2_THC_M_PRT_UFSIZE_UNIT |
+		       THC_M_PRT_DEVINT_CFG_2_THC_M_PRT_FTYPE_IGNORE |
+		       THC_M_PRT_DEVINT_CFG_2_THC_M_PRT_FTYPE_VAL;
+		regmap_write_bits(dev->thc_regmap, THC_M_PRT_DEVINT_CFG_2_OFFSET,
+				  mask, mbits);
+	}
+}
+EXPORT_SYMBOL_NS_GPL(thc_interrupt_config, "INTEL_THC");
+
+/**
+ * thc_int_trigger_type_select - Select THC interrupt trigger type
+ *
+ * @dev: the pointer of THC private device context
+ * @edge_trigger: determine the interrupt is edge triggered or level triggered
+ */
+void thc_int_trigger_type_select(struct thc_device *dev, bool edge_trigger)
+{
+	regmap_write_bits(dev->thc_regmap, THC_M_PRT_TSEQ_CNTRL_1_OFFSET,
+			  THC_M_PRT_TSEQ_CNTRL_1_INT_EDG_DET_EN,
+			  edge_trigger ? THC_M_PRT_TSEQ_CNTRL_1_INT_EDG_DET_EN : 0);
+}
+EXPORT_SYMBOL_NS_GPL(thc_int_trigger_type_select, "INTEL_THC");
+
+/**
+ * thc_interrupt_enable - Enable or disable THC interrupt
+ *
+ * @dev: the pointer of THC private device context
+ * @int_enable: the flag to control THC interrupt enable or disable
+ */
+void thc_interrupt_enable(struct thc_device *dev, bool int_enable)
+{
+	regmap_write_bits(dev->thc_regmap, THC_M_PRT_INT_EN_OFFSET,
+			  THC_M_PRT_INT_EN_GBL_INT_EN,
+			  int_enable ? THC_M_PRT_INT_EN_GBL_INT_EN : 0);
+}
+EXPORT_SYMBOL_NS_GPL(thc_interrupt_enable, "INTEL_THC");
+
+/**
+ * thc_interrupt_quiesce - Quiesce or unquiesce external touch device interrupt
+ *
+ * @dev: the pointer of THC private device context
+ * @int_quiesce: the flag to determine quiesce or unquiesce device interrupt
+ *
+ * Return: 0 on success, other error codes on failed
+ */
+int thc_interrupt_quiesce(const struct thc_device *dev, bool int_quiesce)
+{
+	u32 ctrl;
+	int ret;
+
+	regmap_read(dev->thc_regmap, THC_M_PRT_CONTROL_OFFSET, &ctrl);
+	if (!(ctrl & THC_M_PRT_CONTROL_THC_DEVINT_QUIESCE_EN) && !int_quiesce) {
+		dev_warn(dev->dev, "THC interrupt already unquiesce\n");
+		return 0;
+	}
+
+	if ((ctrl & THC_M_PRT_CONTROL_THC_DEVINT_QUIESCE_EN) && int_quiesce) {
+		dev_warn(dev->dev, "THC interrupt already quiesce\n");
+		return 0;
+	}
+
+	/* Quiesce device interrupt - Set quiesce bit and waiting for THC HW to ACK */
+	if (int_quiesce)
+		regmap_write_bits(dev->thc_regmap, THC_M_PRT_CONTROL_OFFSET,
+				  THC_M_PRT_CONTROL_THC_DEVINT_QUIESCE_EN,
+				  THC_M_PRT_CONTROL_THC_DEVINT_QUIESCE_EN);
+
+	ret = regmap_read_poll_timeout(dev->thc_regmap, THC_M_PRT_CONTROL_OFFSET, ctrl,
+				       ctrl & THC_M_PRT_CONTROL_THC_DEVINT_QUIESCE_HW_STS,
+				       THC_REGMAP_POLLING_INTERVAL_US, THC_QUIESCE_EN_TIMEOUT_US);
+	if (ret) {
+		dev_err_once(dev->dev,
+			     "Timeout while waiting THC idle, target quiesce state = %s\n",
+			     int_quiesce ? "true" : "false");
+		return ret;
+	}
+
+	/* Unquiesce device interrupt - Clear the quiesce bit */
+	if (!int_quiesce)
+		regmap_write_bits(dev->thc_regmap, THC_M_PRT_CONTROL_OFFSET,
+				  THC_M_PRT_CONTROL_THC_DEVINT_QUIESCE_EN, 0);
+
+	return 0;
+}
+EXPORT_SYMBOL_NS_GPL(thc_interrupt_quiesce, "INTEL_THC");
+
+/**
+ * thc_set_pio_interrupt_support - Determine PIO interrupt is supported or not
+ *
+ * @dev: The pointer of THC private device context
+ * @supported: The flag to determine enabling PIO interrupt or not
+ */
+void thc_set_pio_interrupt_support(struct thc_device *dev, bool supported)
+{
+	dev->pio_int_supported = supported;
+}
+EXPORT_SYMBOL_NS_GPL(thc_set_pio_interrupt_support, "INTEL_THC");
+
 MODULE_AUTHOR("Xinpeng Sun <[email protected]>");
 MODULE_AUTHOR("Even Xu <[email protected]>");
 
drivers/hid/intel-thc-hid/intel-thc/intel-thc-dev.h +5 -0
index 88a9f606a6a9..bef48c25c195 100644
@@ -45,5 +45,10 @@ int thc_tic_pio_write(struct thc_device *dev, const u32 address,
 int thc_tic_pio_write_and_read(struct thc_device *dev, const u32 address,
 			       const u32 write_size, const u32 *write_buffer,
 			       const u32 read_size, u32 *actual_size, u32 *read_buffer);
+void thc_interrupt_config(struct thc_device *dev);
+void thc_int_trigger_type_select(struct thc_device *dev, bool edge_trigger);
+void thc_interrupt_enable(struct thc_device *dev, bool int_enable);
+void thc_set_pio_interrupt_support(struct thc_device *dev, bool supported);
+int thc_interrupt_quiesce(const struct thc_device *dev, bool int_quiesce);
 
 #endif /* _INTEL_THC_DEV_H_ */
drivers/hid/intel-thc-hid/intel-thc/intel-thc-hw.h +17 -0
index 60f5f657be62..093c36fb5e1f 100644
@@ -639,6 +639,23 @@
 #define THC_REGMAP_POLLING_INTERVAL_US		10 /* 10us */
 #define THC_PIO_DONE_TIMEOUT_US			USEC_PER_SEC /* 1s */
 
+/* Default configures for HIDSPI */
+#define THC_BIT_OFFSET_INTERRUPT_TYPE		4
+/* input_report_type is 4 bits for HIDSPI */
+#define THC_BIT_LENGTH_INTERRUPT_TYPE		4
+/* Last fragment indicator is bit 15 for HIDSPI */
+#define THC_BIT_OFFSET_LAST_FRAGMENT_FLAG	22
+#define THC_BIT_OFFSET_MICROFRAME_SIZE		8
+/* input_report_length is 14 bits for HIDSPI */
+#define THC_BIT_LENGTH_MICROFRAME_SIZE		14
+/* MFS unit in power of 2 */
+#define THC_UNIT_MICROFRAME_SIZE		2
+#define THC_BITMASK_INTERRUPT_TYPE_DATA		1
+#define THC_BITMASK_INVALID_TYPE_DATA		2
+
+/* Interrupt Quiesce default timeout value */
+#define THC_QUIESCE_EN_TIMEOUT_US		USEC_PER_SEC /* 1s */
+
 /*
  * THC PIO opcode default value
  * @THC_PIO_OP_SPI_TIC_READ: THC opcode for SPI PIO read
Signature · 1 line
2.40.1
author maintainer
#11 lore raw

PATCH v4 6/22 HID: intel-thc-hid: intel-thc: Add THC DMA interfaces

In reply to Even Xu

As THC PIO only has 64 bytes FIFO length, THC DMAs are introduced to send/receive large data packets.

THC has three types of DMA channels: Read DMA channel (RxDMA), Write DMA channel (TxDMA) and Software DMA (SWDMA).

In addition to basic DMA functions, THC RxDMA also includes an auto hardware sequence which can handle external touch device's interrupt automatically without software involved. THC RxDMA channel usually is used for handling touch input reports.

THC TxDMA is very similar with general IO TxDMA, and usually is used for sending command/request to exteranl touch device.

THC SWDMA can perform read, write followed by read operation according to different configurations. Unlike RxDMA triggered by bus activity, SWDMA can be triggered by SW driver at any time, for example:
- Retrieving an input report without interrupt
- Sending command followed by reading response

THC DMA operation flow includes 4 steps:
1. Allocate DMA buffers
2. Configure opcode, fill PRD table with DMA buffers, enable DMA channel
3. Wait for completion, read out DMA buffers and update buffer pointers
4. Stop DMA and release DMA buffers

THC Hardware layer driver provides APIs for all above DMA Steps.

---
 drivers/hid/intel-thc-hid/Makefile            |   1 +
 .../intel-thc-hid/intel-thc/intel-thc-dev.c   |   8 +
 .../intel-thc-hid/intel-thc/intel-thc-dev.h   |  18 +
 .../intel-thc-hid/intel-thc/intel-thc-dma.c   | 969 ++++++++++++++++++
 .../intel-thc-hid/intel-thc/intel-thc-dma.h   | 146 +++
 5 files changed, 1142 insertions(+)
 create mode 100644 drivers/hid/intel-thc-hid/intel-thc/intel-thc-dma.c
 create mode 100644 drivers/hid/intel-thc-hid/intel-thc/intel-thc-dma.h
drivers/hid/intel-thc-hid/Makefile +1 -0
index bebb60bedfeb..b9709cc5e9eb 100644
@@ -7,5 +7,6 @@
 
 obj-$(CONFIG_INTEL_THC_HID) += intel-thc.o
 intel-thc-objs += intel-thc/intel-thc-dev.o
+intel-thc-objs += intel-thc/intel-thc-dma.o
 
 ccflags-y += -I $(src)/intel-thc
drivers/hid/intel-thc-hid/intel-thc/intel-thc-dev.c +8 -0
index e16810b2fb9d..4cb9ceaf395c 100644
@@ -211,6 +211,14 @@ struct thc_device *thc_dev_init(struct device *device, void __iomem *mem_addr)
 	thc_clear_state(thc_dev);
 
 	mutex_init(&thc_dev->thc_bus_lock);
+	init_waitqueue_head(&thc_dev->write_complete_wait);
+	init_waitqueue_head(&thc_dev->swdma_complete_wait);
+
+	thc_dev->dma_ctx = thc_dma_init(thc_dev);
+	if (!thc_dev->dma_ctx) {
+		dev_err_once(device, "DMA context init failed\n");
+		return ERR_PTR(-ENOMEM);
+	}
 
 	return thc_dev;
 }
drivers/hid/intel-thc-hid/intel-thc/intel-thc-dev.h +18 -0
index bef48c25c195..f775b972b4f5 100644
@@ -6,6 +6,9 @@
 
 #include <linux/cdev.h>
 #include <linux/mutex.h>
+#include <linux/workqueue.h>
+
+#include "intel-thc-dma.h"
 
 #define THC_REGMAP_COMMON_OFFSET  0x10
 #define THC_REGMAP_MMIO_OFFSET    0x1000
@@ -27,6 +30,12 @@ enum thc_port_type {
  * @thc_bus_lock: mutex locker for THC config
  * @port_type: port type of THC port instance
  * @pio_int_supported: PIO interrupt supported flag
+ * @dma_ctx: DMA specific data
+ * @write_complete_wait: signal event for DMA write complete
+ * @swdma_complete_wait: signal event for SWDMA sequence complete
+ * @write_done: bool value that indicates if DMA write is done
+ * @swdma_done: bool value that indicates if SWDMA swquence is done
+ * @perf_limit: the delay between read operation and write operation
  */
 struct thc_device {
 	struct device *dev;
@@ -35,6 +44,15 @@ struct thc_device {
 	struct mutex thc_bus_lock;
 	enum thc_port_type port_type;
 	bool pio_int_supported;
+
+	struct thc_dma_context *dma_ctx;
+
+	wait_queue_head_t write_complete_wait;
+	wait_queue_head_t swdma_complete_wait;
+	bool write_done;
+	bool swdma_done;
+
+	u32 perf_limit;
 };
 
 struct thc_device *thc_dev_init(struct device *device, void __iomem *mem_addr);
drivers/hid/intel-thc-hid/intel-thc/intel-thc-dma.c new file +969 -0

969 lines not on this page · raw message

drivers/hid/intel-thc-hid/intel-thc/intel-thc-dma.h new file +146 -0

146 lines not on this page · raw message

Signature · 1 line
2.40.1
author maintainer
#12 lore raw

PATCH v4 7/22 HID: intel-thc-hid: intel-thc: Add THC LTR interfaces

In reply to Even Xu

From: Xinpeng Sun <[email protected]>

THC supports LTR configuration and runtimely mode switching. There are two LTR modes: Active LTR and Low Power LTR.

THC hardware layer provides APIs for LTR configuration and mode switching.

---
 .../intel-thc-hid/intel-thc/intel-thc-dev.c   | 114 ++++++++++++++++++
 .../intel-thc-hid/intel-thc/intel-thc-dev.h   |   3 +
 .../intel-thc-hid/intel-thc/intel-thc-hw.h    |  21 ++++
 3 files changed, 138 insertions(+)
drivers/hid/intel-thc-hid/intel-thc/intel-thc-dev.c +114 -0
index 4cb9ceaf395c..f09832016d9c 100644
@@ -688,6 +688,120 @@ void thc_set_pio_interrupt_support(struct thc_device *dev, bool supported)
 }
 EXPORT_SYMBOL_NS_GPL(thc_set_pio_interrupt_support, "INTEL_THC");
 
+/**
+ * thc_ltr_config - Configure THC Latency Tolerance Reporting(LTR) settings
+ *
+ * @dev: The pointer of THC private device context
+ * @active_ltr_us: active LTR value, unit is us
+ * @lp_ltr_us: low power LTR value, unit is us
+ */
+void thc_ltr_config(struct thc_device *dev, u32 active_ltr_us, u32 lp_ltr_us)
+{
+	u32 active_ltr_scale, lp_ltr_scale, ltr_ctrl, ltr_mask, orig, tmp;
+
+	if (active_ltr_us >= THC_LTR_MIN_VAL_SCALE_3 &&
+	    active_ltr_us < THC_LTR_MAX_VAL_SCALE_3) {
+		active_ltr_scale = THC_LTR_SCALE_3;
+		active_ltr_us = active_ltr_us >> 5;
+	} else if (active_ltr_us >= THC_LTR_MIN_VAL_SCALE_4 &&
+		   active_ltr_us < THC_LTR_MAX_VAL_SCALE_4) {
+		active_ltr_scale = THC_LTR_SCALE_4;
+		active_ltr_us = active_ltr_us >> 10;
+	} else if (active_ltr_us >= THC_LTR_MIN_VAL_SCALE_5 &&
+		   active_ltr_us < THC_LTR_MAX_VAL_SCALE_5) {
+		active_ltr_scale = THC_LTR_SCALE_5;
+		active_ltr_us = active_ltr_us >> 15;
+	} else {
+		active_ltr_scale = THC_LTR_SCALE_2;
+	}
+
+	if (lp_ltr_us >= THC_LTR_MIN_VAL_SCALE_3 &&
+	    lp_ltr_us < THC_LTR_MAX_VAL_SCALE_3) {
+		lp_ltr_scale = THC_LTR_SCALE_3;
+		lp_ltr_us = lp_ltr_us >> 5;
+	} else if (lp_ltr_us >= THC_LTR_MIN_VAL_SCALE_4 &&
+		   lp_ltr_us < THC_LTR_MAX_VAL_SCALE_4) {
+		lp_ltr_scale = THC_LTR_SCALE_4;
+		lp_ltr_us = lp_ltr_us >> 10;
+	} else if (lp_ltr_us >= THC_LTR_MIN_VAL_SCALE_5 &&
+		   lp_ltr_us < THC_LTR_MAX_VAL_SCALE_5) {
+		lp_ltr_scale = THC_LTR_SCALE_5;
+		lp_ltr_us = lp_ltr_us >> 15;
+	} else {
+		lp_ltr_scale = THC_LTR_SCALE_2;
+	}
+
+	regmap_read(dev->thc_regmap, THC_M_CMN_LTR_CTRL_OFFSET, &orig);
+	ltr_ctrl = FIELD_PREP(THC_M_CMN_LTR_CTRL_ACT_LTR_VAL, active_ltr_us) |
+		   FIELD_PREP(THC_M_CMN_LTR_CTRL_ACT_LTR_SCALE, active_ltr_scale) |
+		   THC_M_CMN_LTR_CTRL_ACTIVE_LTR_REQ |
+		   THC_M_CMN_LTR_CTRL_ACTIVE_LTR_EN |
+		   FIELD_PREP(THC_M_CMN_LTR_CTRL_LP_LTR_VAL, lp_ltr_us) |
+		   FIELD_PREP(THC_M_CMN_LTR_CTRL_LP_LTR_SCALE, lp_ltr_scale) |
+		   THC_M_CMN_LTR_CTRL_LP_LTR_REQ;
+
+	ltr_mask = THC_M_CMN_LTR_CTRL_ACT_LTR_VAL |
+		   THC_M_CMN_LTR_CTRL_ACT_LTR_SCALE |
+		   THC_M_CMN_LTR_CTRL_ACTIVE_LTR_REQ |
+		   THC_M_CMN_LTR_CTRL_ACTIVE_LTR_EN |
+		   THC_M_CMN_LTR_CTRL_LP_LTR_VAL |
+		   THC_M_CMN_LTR_CTRL_LP_LTR_SCALE |
+		   THC_M_CMN_LTR_CTRL_LP_LTR_REQ |
+		   THC_M_CMN_LTR_CTRL_LP_LTR_EN;
+
+	tmp = orig & ~ltr_mask;
+	tmp |= ltr_ctrl & ltr_mask;
+
+	regmap_write(dev->thc_regmap, THC_M_CMN_LTR_CTRL_OFFSET, tmp);
+}
+EXPORT_SYMBOL_NS_GPL(thc_ltr_config, "INTEL_THC");
+
+/**
+ * thc_change_ltr_mode - Change THC LTR mode
+ *
+ * @dev: The pointer of THC private device context
+ * @ltr_mode: LTR mode(active or low power)
+ */
+void thc_change_ltr_mode(struct thc_device *dev, u32 ltr_mode)
+{
+	if (ltr_mode == THC_LTR_MODE_ACTIVE) {
+		regmap_write_bits(dev->thc_regmap, THC_M_CMN_LTR_CTRL_OFFSET,
+				  THC_M_CMN_LTR_CTRL_LP_LTR_EN, 0);
+		regmap_write_bits(dev->thc_regmap, THC_M_CMN_LTR_CTRL_OFFSET,
+				  THC_M_CMN_LTR_CTRL_ACTIVE_LTR_EN,
+				  THC_M_CMN_LTR_CTRL_ACTIVE_LTR_EN);
+		return;
+	}
+
+	regmap_write_bits(dev->thc_regmap, THC_M_CMN_LTR_CTRL_OFFSET,
+			  THC_M_CMN_LTR_CTRL_ACTIVE_LTR_EN, 0);
+	regmap_write_bits(dev->thc_regmap, THC_M_CMN_LTR_CTRL_OFFSET,
+			  THC_M_CMN_LTR_CTRL_LP_LTR_EN,
+			  THC_M_CMN_LTR_CTRL_LP_LTR_EN);
+}
+EXPORT_SYMBOL_NS_GPL(thc_change_ltr_mode, "INTEL_THC");
+
+/**
+ * thc_ltr_unconfig - Unconfigure THC Latency Tolerance Reporting(LTR) settings
+ *
+ * @dev: The pointer of THC private device context
+ */
+void thc_ltr_unconfig(struct thc_device *dev)
+{
+	u32 ltr_ctrl, bits_clear;
+
+	regmap_read(dev->thc_regmap, THC_M_CMN_LTR_CTRL_OFFSET, &ltr_ctrl);
+	bits_clear = THC_M_CMN_LTR_CTRL_LP_LTR_EN |
+			THC_M_CMN_LTR_CTRL_ACTIVE_LTR_EN |
+			THC_M_CMN_LTR_CTRL_LP_LTR_REQ |
+			THC_M_CMN_LTR_CTRL_ACTIVE_LTR_REQ;
+
+	ltr_ctrl &= ~bits_clear;
+
+	regmap_write(dev->thc_regmap, THC_M_CMN_LTR_CTRL_OFFSET, ltr_ctrl);
+}
+EXPORT_SYMBOL_NS_GPL(thc_ltr_unconfig, "INTEL_THC");
+
 MODULE_AUTHOR("Xinpeng Sun <[email protected]>");
 MODULE_AUTHOR("Even Xu <[email protected]>");
 
drivers/hid/intel-thc-hid/intel-thc/intel-thc-dev.h +3 -0
index f775b972b4f5..c25f2fd57c76 100644
@@ -68,5 +68,8 @@ void thc_int_trigger_type_select(struct thc_device *dev, bool edge_trigger);
 void thc_interrupt_enable(struct thc_device *dev, bool int_enable);
 void thc_set_pio_interrupt_support(struct thc_device *dev, bool supported);
 int thc_interrupt_quiesce(const struct thc_device *dev, bool int_quiesce);
+void thc_ltr_config(struct thc_device *dev, u32 active_ltr_us, u32 lp_ltr_us);
+void thc_change_ltr_mode(struct thc_device *dev, u32 ltr_mode);
+void thc_ltr_unconfig(struct thc_device *dev);
 
 #endif /* _INTEL_THC_DEV_H_ */
drivers/hid/intel-thc-hid/intel-thc/intel-thc-hw.h +21 -0
index 093c36fb5e1f..fb9c60f87666 100644
@@ -656,6 +656,27 @@
 /* Interrupt Quiesce default timeout value */
 #define THC_QUIESCE_EN_TIMEOUT_US		USEC_PER_SEC /* 1s */
 
+/* LTR definition */
+/*
+ * THC uses scale to calculate final LTR value.
+ * Scale is geometric progression of 2^5 step, starting from 2^0.
+ * For example, THC_LTR_SCALE_2(2) means 2^(5 * 2) = 1024, unit is ns.
+ */
+#define THC_LTR_SCALE_0				0
+#define THC_LTR_SCALE_1				1
+#define THC_LTR_SCALE_2				2
+#define THC_LTR_SCALE_3				3
+#define THC_LTR_SCALE_4				4
+#define THC_LTR_SCALE_5				5
+#define THC_LTR_MODE_ACTIVE			0
+#define THC_LTR_MODE_LP				1
+#define THC_LTR_MIN_VAL_SCALE_3			BIT(10)
+#define THC_LTR_MAX_VAL_SCALE_3			BIT(15)
+#define THC_LTR_MIN_VAL_SCALE_4			BIT(15)
+#define THC_LTR_MAX_VAL_SCALE_4			BIT(20)
+#define THC_LTR_MIN_VAL_SCALE_5			BIT(20)
+#define THC_LTR_MAX_VAL_SCALE_5			BIT(25)
+
 /*
  * THC PIO opcode default value
  * @THC_PIO_OP_SPI_TIC_READ: THC opcode for SPI PIO read
Signature · 1 line
2.40.1
author maintainer
#13 lore raw

PATCH v4 8/22 HID: intel-thc-hid: intel-thc: Add THC interrupt handler

In reply to Even Xu

From: Xinpeng Sun <[email protected]>

Add common interrupt handler to clear interrupt status and return interrupt type to caller for future handling.

---
 .../intel-thc-hid/intel-thc/intel-thc-dev.c   | 259 ++++++++++++++++++
 .../intel-thc-hid/intel-thc/intel-thc-dev.h   |  27 ++
 2 files changed, 286 insertions(+)
drivers/hid/intel-thc-hid/intel-thc/intel-thc-dev.c +259 -0
index f09832016d9c..99dbaeef041c 100644
@@ -802,6 +802,265 @@ void thc_ltr_unconfig(struct thc_device *dev)
 }
 EXPORT_SYMBOL_NS_GPL(thc_ltr_unconfig, "INTEL_THC");
 
+/**
+ * thc_int_cause_read - Read interrupt cause register value
+ *
+ * @dev: The pointer of THC private device context
+ *
+ * Return: The interrupt cause register value
+ */
+u32 thc_int_cause_read(struct thc_device *dev)
+{
+	u32 int_cause;
+
+	regmap_read(dev->thc_regmap,
+		    THC_M_PRT_DEV_INT_CAUSE_REG_VAL_OFFSET, &int_cause);
+
+	return int_cause;
+}
+EXPORT_SYMBOL_NS_GPL(thc_int_cause_read, "INTEL_THC");
+
+static void thc_print_txn_error_cause(const struct thc_device *dev)
+{
+	bool known_error = false;
+	u32 cause = 0;
+
+	regmap_read(dev->thc_regmap, THC_M_PRT_ERR_CAUSE_OFFSET, &cause);
+
+	if (cause & THC_M_PRT_ERR_CAUSE_PRD_ENTRY_ERR) {
+		dev_err(dev->dev, "TXN Error: Invalid PRD Entry\n");
+		known_error = true;
+	}
+	if (cause & THC_M_PRT_ERR_CAUSE_BUF_OVRRUN_ERR) {
+		dev_err(dev->dev, "TXN Error: THC Buffer Overrun\n");
+		known_error = true;
+	}
+	if (cause & THC_M_PRT_ERR_CAUSE_FRAME_BABBLE_ERR) {
+		dev_err(dev->dev, "TXN Error: Frame Babble\n");
+		known_error = true;
+	}
+	if (cause & THC_M_PRT_ERR_CAUSE_INVLD_DEV_ENTRY) {
+		dev_err(dev->dev, "TXN Error: Invalid Device Register Setting\n");
+		known_error = true;
+	}
+
+	/* Clear interrupt status bits */
+	regmap_write(dev->thc_regmap, THC_M_PRT_ERR_CAUSE_OFFSET, cause);
+
+	if (!known_error)
+		dev_err(dev->dev, "TXN Error does not match any known value: 0x%X\n",
+			cause);
+}
+
+/**
+ * thc_interrupt_handler - Handle THC interrupts
+ *
+ * THC interrupts include several types: external touch device (TIC) non-DMA
+ * interrupts, PIO completion interrupts, DMA interrtups, I2C subIP raw
+ * interrupts and error interrupts.
+ *
+ * This is a help function for interrupt processing, it detects interrupt
+ * type, clear the interrupt status bit and return the interrupt type to caller
+ * for future processing.
+ *
+ * @dev: The pointer of THC private device context
+ *
+ * Return: The combined flag for interrupt type
+ */
+int thc_interrupt_handler(struct thc_device *dev)
+{
+	u32 read_sts_1, read_sts_2, read_sts_sw, write_sts;
+	u32 int_sts, err_cause, seq_cntrl, seq_sts;
+	int interrupt_type = 0;
+
+	regmap_read(dev->thc_regmap,
+		    THC_M_PRT_READ_DMA_INT_STS_1_OFFSET, &read_sts_1);
+
+	if (read_sts_1 & THC_M_PRT_READ_DMA_INT_STS_NONDMA_INT_STS) {
+		dev_dbg(dev->dev, "THC non-DMA device interrupt\n");
+
+		regmap_write(dev->thc_regmap, THC_M_PRT_READ_DMA_INT_STS_1_OFFSET,
+			     NONDMA_INT_STS_BIT);
+
+		interrupt_type |= BIT(THC_NONDMA_INT);
+
+		return interrupt_type;
+	}
+
+	regmap_read(dev->thc_regmap, THC_M_PRT_INT_STATUS_OFFSET, &int_sts);
+
+	if (int_sts & THC_M_PRT_INT_STATUS_TXN_ERR_INT_STS) {
+		dev_err(dev->dev, "THC transaction error, int_sts: 0x%08X\n", int_sts);
+		thc_print_txn_error_cause(dev);
+
+		regmap_write(dev->thc_regmap, THC_M_PRT_INT_STATUS_OFFSET,
+			     TXN_ERR_INT_STS_BIT);
+
+		interrupt_type |= BIT(THC_TXN_ERR_INT);
+
+		return interrupt_type;
+	}
+
+	regmap_read(dev->thc_regmap, THC_M_PRT_ERR_CAUSE_OFFSET, &err_cause);
+	regmap_read(dev->thc_regmap,
+		    THC_M_PRT_READ_DMA_INT_STS_2_OFFSET, &read_sts_2);
+
+	if (err_cause & THC_M_PRT_ERR_CAUSE_BUF_OVRRUN_ERR ||
+	    read_sts_1 & THC_M_PRT_READ_DMA_INT_STS_STALL_STS ||
+	    read_sts_2 & THC_M_PRT_READ_DMA_INT_STS_STALL_STS) {
+		dev_err(dev->dev, "Buffer overrun or RxDMA engine stalled!\n");
+		thc_print_txn_error_cause(dev);
+
+		regmap_write(dev->thc_regmap, THC_M_PRT_READ_DMA_INT_STS_2_OFFSET,
+			     THC_M_PRT_READ_DMA_INT_STS_STALL_STS);
+		regmap_write(dev->thc_regmap, THC_M_PRT_READ_DMA_INT_STS_1_OFFSET,
+			     THC_M_PRT_READ_DMA_INT_STS_STALL_STS);
+		regmap_write(dev->thc_regmap, THC_M_PRT_ERR_CAUSE_OFFSET,
+			     THC_M_PRT_ERR_CAUSE_BUF_OVRRUN_ERR);
+
+		interrupt_type |= BIT(THC_TXN_ERR_INT);
+
+		return interrupt_type;
+	}
+
+	if (int_sts & THC_M_PRT_INT_STATUS_FATAL_ERR_INT_STS) {
+		dev_err_once(dev->dev, "THC FATAL error, int_sts: 0x%08X\n", int_sts);
+
+		regmap_write(dev->thc_regmap, THC_M_PRT_INT_STATUS_OFFSET,
+			     TXN_FATAL_INT_STS_BIT);
+
+		interrupt_type |= BIT(THC_FATAL_ERR_INT);
+
+		return interrupt_type;
+	}
+
+	regmap_read(dev->thc_regmap,
+		    THC_M_PRT_SW_SEQ_CNTRL_OFFSET, &seq_cntrl);
+	regmap_read(dev->thc_regmap,
+		    THC_M_PRT_SW_SEQ_STS_OFFSET, &seq_sts);
+
+	if (seq_cntrl & THC_M_PRT_SW_SEQ_CNTRL_THC_SS_CD_IE &&
+	    seq_sts & THC_M_PRT_SW_SEQ_STS_TSSDONE) {
+		dev_dbg(dev->dev, "THC_SS_CD_IE and TSSDONE are set\n");
+		interrupt_type |= BIT(THC_PIO_DONE_INT);
+	}
+
+	if (read_sts_1 & THC_M_PRT_READ_DMA_INT_STS_EOF_INT_STS) {
+		dev_dbg(dev->dev, "Got RxDMA1 Read Interrupt\n");
+
+		regmap_write(dev->thc_regmap,
+			     THC_M_PRT_READ_DMA_INT_STS_1_OFFSET, read_sts_1);
+
+		interrupt_type |= BIT(THC_RXDMA1_INT);
+	}
+
+	if (read_sts_2 & THC_M_PRT_READ_DMA_INT_STS_EOF_INT_STS) {
+		dev_dbg(dev->dev, "Got RxDMA2 Read Interrupt\n");
+
+		regmap_write(dev->thc_regmap,
+			     THC_M_PRT_READ_DMA_INT_STS_2_OFFSET, read_sts_2);
+
+		interrupt_type |= BIT(THC_RXDMA2_INT);
+	}
+
+	regmap_read(dev->thc_regmap,
+		    THC_M_PRT_READ_DMA_INT_STS_SW_OFFSET, &read_sts_sw);
+
+	if (read_sts_sw & THC_M_PRT_READ_DMA_INT_STS_DMACPL_STS) {
+		dev_dbg(dev->dev, "Got SwDMA Read Interrupt\n");
+
+		regmap_write(dev->thc_regmap,
+			     THC_M_PRT_READ_DMA_INT_STS_SW_OFFSET, read_sts_sw);
+
+		dev->swdma_done = true;
+		wake_up_interruptible(&dev->swdma_complete_wait);
+
+		interrupt_type |= BIT(THC_SWDMA_INT);
+	}
+
+	regmap_read(dev->thc_regmap,
+		    THC_M_PRT_WRITE_INT_STS_OFFSET, &write_sts);
+
+	if (write_sts & THC_M_PRT_WRITE_INT_STS_THC_WRDMA_CMPL_STATUS) {
+		dev_dbg(dev->dev, "Got TxDMA Write complete Interrupt\n");
+
+		regmap_write(dev->thc_regmap,
+			     THC_M_PRT_WRITE_INT_STS_OFFSET, write_sts);
+
+		dev->write_done = true;
+		wake_up_interruptible(&dev->write_complete_wait);
+
+		interrupt_type |= BIT(THC_TXDMA_INT);
+	}
+
+	if (int_sts & THC_M_PRT_INT_STATUS_DEV_RAW_INT_STS) {
+		regmap_write(dev->thc_regmap, THC_M_PRT_INT_STATUS_OFFSET,
+			     THC_M_PRT_INT_STATUS_DEV_RAW_INT_STS);
+		interrupt_type |= BIT(THC_I2CSUBIP_INT);
+	}
+	if (int_sts & THC_M_PRT_INT_STATUS_THC_I2C_IC_RX_UNDER_INT_STS) {
+		regmap_write(dev->thc_regmap, THC_M_PRT_INT_STATUS_OFFSET,
+			     THC_M_PRT_INT_STATUS_THC_I2C_IC_RX_UNDER_INT_STS);
+		interrupt_type |= BIT(THC_I2CSUBIP_INT);
+	}
+	if (int_sts & THC_M_PRT_INT_STATUS_THC_I2C_IC_RX_OVER_INT_STS) {
+		regmap_write(dev->thc_regmap, THC_M_PRT_INT_STATUS_OFFSET,
+			     THC_M_PRT_INT_STATUS_THC_I2C_IC_RX_OVER_INT_STS);
+		interrupt_type |= BIT(THC_I2CSUBIP_INT);
+	}
+	if (int_sts & THC_M_PRT_INT_STATUS_THC_I2C_IC_RX_FULL_INT_STS) {
+		regmap_write(dev->thc_regmap, THC_M_PRT_INT_STATUS_OFFSET,
+			     THC_M_PRT_INT_STATUS_THC_I2C_IC_RX_FULL_INT_STS);
+		interrupt_type |= BIT(THC_I2CSUBIP_INT);
+	}
+	if (int_sts & THC_M_PRT_INT_STATUS_THC_I2C_IC_TX_OVER_INT_STS) {
+		regmap_write(dev->thc_regmap, THC_M_PRT_INT_STATUS_OFFSET,
+			     THC_M_PRT_INT_STATUS_THC_I2C_IC_TX_OVER_INT_STS);
+		interrupt_type |= BIT(THC_I2CSUBIP_INT);
+	}
+	if (int_sts & THC_M_PRT_INT_STATUS_THC_I2C_IC_TX_EMPTY_INT_STS) {
+		regmap_write(dev->thc_regmap, THC_M_PRT_INT_STATUS_OFFSET,
+			     THC_M_PRT_INT_STATUS_THC_I2C_IC_TX_EMPTY_INT_STS);
+		interrupt_type |= BIT(THC_I2CSUBIP_INT);
+	}
+	if (int_sts & THC_M_PRT_INT_STATUS_THC_I2C_IC_TX_ABRT_INT_STS) {
+		regmap_write(dev->thc_regmap, THC_M_PRT_INT_STATUS_OFFSET,
+			     THC_M_PRT_INT_STATUS_THC_I2C_IC_TX_ABRT_INT_STS);
+		interrupt_type |= BIT(THC_I2CSUBIP_INT);
+	}
+	if (int_sts & THC_M_PRT_INT_STATUS_THC_I2C_IC_ACTIVITY_INT_STS) {
+		regmap_write(dev->thc_regmap, THC_M_PRT_INT_STATUS_OFFSET,
+			     THC_M_PRT_INT_STATUS_THC_I2C_IC_ACTIVITY_INT_STS);
+		interrupt_type |= BIT(THC_I2CSUBIP_INT);
+	}
+	if (int_sts & THC_M_PRT_INT_STATUS_THC_I2C_IC_SCL_STUCK_AT_LOW_INT_STS) {
+		regmap_write(dev->thc_regmap, THC_M_PRT_INT_STATUS_OFFSET,
+			     THC_M_PRT_INT_STATUS_THC_I2C_IC_SCL_STUCK_AT_LOW_INT_STS);
+		interrupt_type |= BIT(THC_I2CSUBIP_INT);
+	}
+	if (int_sts & THC_M_PRT_INT_STATUS_THC_I2C_IC_STOP_DET_INT_STS) {
+		regmap_write(dev->thc_regmap, THC_M_PRT_INT_STATUS_OFFSET,
+			     THC_M_PRT_INT_STATUS_THC_I2C_IC_STOP_DET_INT_STS);
+		interrupt_type |= BIT(THC_I2CSUBIP_INT);
+	}
+	if (int_sts & THC_M_PRT_INT_STATUS_THC_I2C_IC_START_DET_INT_STS) {
+		regmap_write(dev->thc_regmap, THC_M_PRT_INT_STATUS_OFFSET,
+			     THC_M_PRT_INT_STATUS_THC_I2C_IC_START_DET_INT_STS);
+		interrupt_type |= BIT(THC_I2CSUBIP_INT);
+	}
+	if (int_sts & THC_M_PRT_INT_STATUS_THC_I2C_IC_MST_ON_HOLD_INT_STS) {
+		regmap_write(dev->thc_regmap, THC_M_PRT_INT_STATUS_OFFSET,
+			     THC_M_PRT_INT_STATUS_THC_I2C_IC_MST_ON_HOLD_INT_STS);
+		interrupt_type |= BIT(THC_I2CSUBIP_INT);
+	}
+
+	if (!interrupt_type)
+		interrupt_type |= BIT(THC_UNKNOWN_INT);
+
+	return interrupt_type;
+}
+EXPORT_SYMBOL_NS_GPL(thc_interrupt_handler, "INTEL_THC");
+
 MODULE_AUTHOR("Xinpeng Sun <[email protected]>");
 MODULE_AUTHOR("Even Xu <[email protected]>");
 
drivers/hid/intel-thc-hid/intel-thc/intel-thc-dev.h +27 -0
index c25f2fd57c76..d34fab243fdc 100644
@@ -23,6 +23,31 @@ enum thc_port_type {
 	THC_PORT_TYPE_I2C = 1,
 };
 
+/**
+ * THC interrupt flag
+ * @THC_NONDMA_INT: THC non-DMA interrupt
+ * @THC_RXDMA1_INT: THC RxDMA1 interrupt
+ * @THC_RXDMA2_INT: THC RxDMA2 interrupt
+ * @THC_SWDMA_INT: THC SWDMA interrupt
+ * @THC_TXDMA_INT: THC TXDMA interrupt
+ * @THC_PIO_DONE_INT: THC PIO complete interrupt
+ * @THC_I2CSUBIP_INT: THC I2C subsystem interrupt
+ * @THC_TXN_ERR_INT: THC transfer error interrupt
+ * @THC_FATAL_ERR_INT: THC fatal error interrupt
+ */
+enum thc_int_type {
+	THC_NONDMA_INT = 0,
+	THC_RXDMA1_INT = 1,
+	THC_RXDMA2_INT = 2,
+	THC_SWDMA_INT = 3,
+	THC_TXDMA_INT = 4,
+	THC_PIO_DONE_INT = 5,
+	THC_I2CSUBIP_INT = 6,
+	THC_TXN_ERR_INT = 7,
+	THC_FATAL_ERR_INT = 8,
+	THC_UNKNOWN_INT
+};
+
 /**
  * struct thc_device - THC private device struct
  * @thc_regmap: MMIO regmap structure for accessing THC registers
@@ -71,5 +96,7 @@ int thc_interrupt_quiesce(const struct thc_device *dev, bool int_quiesce);
 void thc_ltr_config(struct thc_device *dev, u32 active_ltr_us, u32 lp_ltr_us);
 void thc_change_ltr_mode(struct thc_device *dev, u32 ltr_mode);
 void thc_ltr_unconfig(struct thc_device *dev);
+u32 thc_int_cause_read(struct thc_device *dev);
+int thc_interrupt_handler(struct thc_device *dev);
 
 #endif /* _INTEL_THC_DEV_H_ */
Signature · 1 line
2.40.1
author maintainer
#14 lore raw

PATCH v4 9/22 HID: intel-thc-hid: intel-thc: Add THC SPI config interfaces

In reply to Even Xu

From: Xinpeng Sun <[email protected]>

Add SPI bus related APIs to configure SPI operation parameters, such as port type, bus frequency, bus IO mode, read/write OPcode, and slave register addresses.

---
 .../intel-thc-hid/intel-thc/intel-thc-dev.c   | 229 ++++++++++++++++++
 .../intel-thc-hid/intel-thc/intel-thc-dev.h   |   7 +
 .../intel-thc-hid/intel-thc/intel-thc-hw.h    |  52 ++++
 3 files changed, 288 insertions(+)
drivers/hid/intel-thc-hid/intel-thc/intel-thc-dev.c +229 -0
index 99dbaeef041c..8a439eb120b5 100644
@@ -1061,6 +1061,235 @@ int thc_interrupt_handler(struct thc_device *dev)
 }
 EXPORT_SYMBOL_NS_GPL(thc_interrupt_handler, "INTEL_THC");
 
+/**
+ * thc_port_select - Set THC port type
+ *
+ * @dev: The pointer of THC private device context
+ * @port_type: THC port type to use for current device
+ *
+ * Return: 0 on success, other error codes on failed.
+ */
+int thc_port_select(struct thc_device *dev, enum thc_port_type port_type)
+{
+	u32 ctrl, mask;
+
+	if (port_type == THC_PORT_TYPE_SPI) {
+		dev_dbg(dev->dev, "Set THC port type to SPI\n");
+		dev->port_type = THC_PORT_TYPE_SPI;
+
+		/* Enable delay of CS assertion and set to default value */
+		ctrl = THC_M_PRT_SPI_DUTYC_CFG_SPI_CSA_CK_DELAY_EN |
+		       FIELD_PREP(THC_M_PRT_SPI_DUTYC_CFG_SPI_CSA_CK_DELAY_VAL,
+				  THC_CSA_CK_DELAY_VAL_DEFAULT);
+		mask = THC_M_PRT_SPI_DUTYC_CFG_SPI_CSA_CK_DELAY_EN |
+		       THC_M_PRT_SPI_DUTYC_CFG_SPI_CSA_CK_DELAY_VAL;
+		regmap_write_bits(dev->thc_regmap, THC_M_PRT_SPI_DUTYC_CFG_OFFSET,
+				  mask, ctrl);
+	} else if (port_type == THC_PORT_TYPE_I2C) {
+		dev_dbg(dev->dev, "Set THC port type to I2C\n");
+		dev->port_type = THC_PORT_TYPE_I2C;
+
+		/* Set THC transition arbitration policy to frame boundary for I2C */
+		ctrl = FIELD_PREP(THC_M_PRT_CONTROL_THC_ARB_POLICY,
+				  THC_ARB_POLICY_FRAME_BOUNDARY);
+		mask = THC_M_PRT_CONTROL_THC_ARB_POLICY;
+
+		regmap_write_bits(dev->thc_regmap, THC_M_PRT_CONTROL_OFFSET, mask, ctrl);
+	} else {
+		dev_err(dev->dev, "unsupported THC port type: %d\n", port_type);
+		return -EINVAL;
+	}
+
+	ctrl = FIELD_PREP(THC_M_PRT_CONTROL_PORT_TYPE, port_type);
+	mask = THC_M_PRT_CONTROL_PORT_TYPE;
+
+	regmap_write_bits(dev->thc_regmap, THC_M_PRT_CONTROL_OFFSET, mask, ctrl);
+
+	return 0;
+}
+EXPORT_SYMBOL_NS_GPL(thc_port_select, "INTEL_THC");
+
+#define THC_SPI_FREQUENCY_7M	7812500
+#define THC_SPI_FREQUENCY_15M	15625000
+#define THC_SPI_FREQUENCY_17M	17857100
+#define THC_SPI_FREQUENCY_20M	20833000
+#define THC_SPI_FREQUENCY_25M	25000000
+#define THC_SPI_FREQUENCY_31M	31250000
+#define THC_SPI_FREQUENCY_41M	41666700
+
+#define THC_SPI_LOW_FREQUENCY	THC_SPI_FREQUENCY_17M
+
+static u8 thc_get_spi_freq_div_val(struct thc_device *dev, u32 spi_freq_val)
+{
+	int frequency[] = {
+		THC_SPI_FREQUENCY_7M,
+		THC_SPI_FREQUENCY_15M,
+		THC_SPI_FREQUENCY_17M,
+		THC_SPI_FREQUENCY_20M,
+		THC_SPI_FREQUENCY_25M,
+		THC_SPI_FREQUENCY_31M,
+		THC_SPI_FREQUENCY_41M,
+	};
+	u8 frequency_div[] = {
+		THC_SPI_FRQ_DIV_2,
+		THC_SPI_FRQ_DIV_1,
+		THC_SPI_FRQ_DIV_7,
+		THC_SPI_FRQ_DIV_6,
+		THC_SPI_FRQ_DIV_5,
+		THC_SPI_FRQ_DIV_4,
+		THC_SPI_FRQ_DIV_3,
+	};
+	int size = ARRAY_SIZE(frequency);
+	u32 closest_freq;
+	u8 freq_div;
+	int i;
+
+	for (i = size - 1; i >= 0; i--)
+		if ((int)spi_freq_val - frequency[i] >= 0)
+			break;
+
+	if (i < 0) {
+		dev_err_once(dev->dev, "Not supported SPI frequency %d\n", spi_freq_val);
+		return THC_SPI_FRQ_RESERVED;
+	}
+
+	closest_freq = frequency[i];
+	freq_div = frequency_div[i];
+
+	dev_dbg(dev->dev,
+		"Setting SPI frequency: spi_freq_val = %u, Closest freq = %u\n",
+		spi_freq_val, closest_freq);
+
+	return freq_div;
+}
+
+/**
+ * thc_spi_read_config - Configure SPI bus read attributes
+ *
+ * @dev: The pointer of THC private device context
+ * @spi_freq_val: SPI read frequecy value
+ * @io_mode: SPI read IO mode
+ * @opcode: Read opcode
+ * @spi_rd_mps: SPI read max packet size
+ *
+ * Return: 0 on success, other error codes on failed.
+ */
+int thc_spi_read_config(struct thc_device *dev, u32 spi_freq_val,
+			u32 io_mode, u32 opcode, u32 spi_rd_mps)
+{
+	bool is_low_freq = false;
+	u32 cfg, mask;
+	u8 freq_div;
+
+	freq_div = thc_get_spi_freq_div_val(dev, spi_freq_val);
+	if (freq_div == THC_SPI_FRQ_RESERVED)
+		return -EINVAL;
+
+	if (spi_freq_val < THC_SPI_LOW_FREQUENCY)
+		is_low_freq = true;
+
+	cfg = FIELD_PREP(THC_M_PRT_SPI_CFG_SPI_TCRF, freq_div) |
+	      FIELD_PREP(THC_M_PRT_SPI_CFG_SPI_TRMODE, io_mode) |
+	      (is_low_freq ? THC_M_PRT_SPI_CFG_SPI_LOW_FREQ_EN : 0) |
+	      FIELD_PREP(THC_M_PRT_SPI_CFG_SPI_RD_MPS, spi_rd_mps);
+	mask = THC_M_PRT_SPI_CFG_SPI_TCRF |
+	       THC_M_PRT_SPI_CFG_SPI_TRMODE |
+	       THC_M_PRT_SPI_CFG_SPI_LOW_FREQ_EN |
+	       THC_M_PRT_SPI_CFG_SPI_RD_MPS;
+
+	regmap_write_bits(dev->thc_regmap,
+			  THC_M_PRT_SPI_CFG_OFFSET, mask, cfg);
+
+	if (io_mode == THC_QUAD_IO)
+		opcode = FIELD_PREP(THC_M_PRT_SPI_ICRRD_OPCODE_SPI_QIO, opcode);
+	else if (io_mode == THC_DUAL_IO)
+		opcode = FIELD_PREP(THC_M_PRT_SPI_ICRRD_OPCODE_SPI_DIO, opcode);
+	else
+		opcode = FIELD_PREP(THC_M_PRT_SPI_ICRRD_OPCODE_SPI_SIO, opcode);
+
+	regmap_write(dev->thc_regmap, THC_M_PRT_SPI_ICRRD_OPCODE_OFFSET, opcode);
+	regmap_write(dev->thc_regmap, THC_M_PRT_SPI_DMARD_OPCODE_OFFSET, opcode);
+
+	return 0;
+}
+EXPORT_SYMBOL_NS_GPL(thc_spi_read_config, "INTEL_THC");
+
+/**
+ * thc_spi_write_config - Configure SPI bus write attributes
+ *
+ * @dev: The pointer of THC private device context
+ * @spi_freq_val: SPI write frequecy value
+ * @io_mode: SPI write IO mode
+ * @opcode: Write opcode
+ * @spi_wr_mps: SPI write max packet size
+ * @perf_limit: Performance limitation in unit of 10us
+ *
+ * Return: 0 on success, other error codes on failed.
+ */
+int thc_spi_write_config(struct thc_device *dev, u32 spi_freq_val,
+			 u32 io_mode, u32 opcode, u32 spi_wr_mps,
+			 u32 perf_limit)
+{
+	bool is_low_freq = false;
+	u32 cfg, mask;
+	u8 freq_div;
+
+	freq_div = thc_get_spi_freq_div_val(dev, spi_freq_val);
+	if (freq_div == THC_SPI_FRQ_RESERVED)
+		return -EINVAL;
+
+	if (spi_freq_val < THC_SPI_LOW_FREQUENCY)
+		is_low_freq = true;
+
+	cfg = FIELD_PREP(THC_M_PRT_SPI_CFG_SPI_TCWF, freq_div) |
+	      FIELD_PREP(THC_M_PRT_SPI_CFG_SPI_TWMODE, io_mode) |
+	      (is_low_freq ? THC_M_PRT_SPI_CFG_SPI_LOW_FREQ_EN : 0) |
+	      FIELD_PREP(THC_M_PRT_SPI_CFG_SPI_WR_MPS, spi_wr_mps);
+	mask = THC_M_PRT_SPI_CFG_SPI_TCWF |
+	       THC_M_PRT_SPI_CFG_SPI_TWMODE |
+	       THC_M_PRT_SPI_CFG_SPI_LOW_FREQ_EN |
+	       THC_M_PRT_SPI_CFG_SPI_WR_MPS;
+
+	regmap_write_bits(dev->thc_regmap,
+			  THC_M_PRT_SPI_CFG_OFFSET, mask, cfg);
+
+	if (io_mode == THC_QUAD_IO)
+		opcode = FIELD_PREP(THC_M_PRT_SPI_ICRRD_OPCODE_SPI_QIO, opcode);
+	else if (io_mode == THC_DUAL_IO)
+		opcode = FIELD_PREP(THC_M_PRT_SPI_ICRRD_OPCODE_SPI_DIO, opcode);
+	else
+		opcode = FIELD_PREP(THC_M_PRT_SPI_ICRRD_OPCODE_SPI_SIO, opcode);
+
+	regmap_write(dev->thc_regmap, THC_M_PRT_SPI_WR_OPCODE_OFFSET, opcode);
+
+	dev->perf_limit = perf_limit;
+
+	return 0;
+}
+EXPORT_SYMBOL_NS_GPL(thc_spi_write_config, "INTEL_THC");
+
+/**
+ * thc_spi_input_output_address_config - Configure SPI input and output addresses
+ *
+ * @dev: the pointer of THC private device context
+ * @input_hdr_addr: input report header address
+ * @input_bdy_addr: input report body address
+ * @output_addr: output report address
+ */
+void thc_spi_input_output_address_config(struct thc_device *dev, u32 input_hdr_addr,
+					 u32 input_bdy_addr, u32 output_addr)
+{
+	regmap_write(dev->thc_regmap,
+		     THC_M_PRT_DEV_INT_CAUSE_ADDR_OFFSET, input_hdr_addr);
+	regmap_write(dev->thc_regmap,
+		     THC_M_PRT_RD_BULK_ADDR_1_OFFSET, input_bdy_addr);
+	regmap_write(dev->thc_regmap,
+		     THC_M_PRT_RD_BULK_ADDR_2_OFFSET, input_bdy_addr);
+	regmap_write(dev->thc_regmap,
+		     THC_M_PRT_WR_BULK_ADDR_OFFSET, output_addr);
+}
+EXPORT_SYMBOL_NS_GPL(thc_spi_input_output_address_config, "INTEL_THC");
+
 MODULE_AUTHOR("Xinpeng Sun <[email protected]>");
 MODULE_AUTHOR("Even Xu <[email protected]>");
 
drivers/hid/intel-thc-hid/intel-thc/intel-thc-dev.h +7 -0
index d34fab243fdc..925355f19bae 100644
@@ -98,5 +98,12 @@ void thc_change_ltr_mode(struct thc_device *dev, u32 ltr_mode);
 void thc_ltr_unconfig(struct thc_device *dev);
 u32 thc_int_cause_read(struct thc_device *dev);
 int thc_interrupt_handler(struct thc_device *dev);
+int thc_port_select(struct thc_device *dev, enum thc_port_type port_type);
+int thc_spi_read_config(struct thc_device *dev, u32 spi_freq_val,
+			u32 io_mode, u32 opcode, u32 spi_rd_mps);
+int thc_spi_write_config(struct thc_device *dev, u32 spi_freq_val,
+			 u32 io_mode, u32 opcode, u32 spi_wr_mps, u32 perf_limit);
+void thc_spi_input_output_address_config(struct thc_device *dev, u32 input_hdr_addr,
+					 u32 input_bdy_addr, u32 output_addr);
 
 #endif /* _INTEL_THC_DEV_H_ */
drivers/hid/intel-thc-hid/intel-thc/intel-thc-hw.h +52 -0

62 lines not on this page · raw message

Signature · 1 line
2.40.1
author maintainer
#15 lore raw

PATCH v4 10/22 HID: intel-thc-hid: intel-thc: Add THC I2C config interfaces

In reply to Even Xu

Add I2C bus related APIs to initialize I2C sub-system parameters, such as bus speed, slave address, address bit. As I2C sub-system hasn't auto register save and restore support, provide APIs to do it manually.

---
 .../intel-thc-hid/intel-thc/intel-thc-dev.c   | 281 ++++++++++++++++++
 .../intel-thc-hid/intel-thc/intel-thc-dev.h   |   7 +
 .../intel-thc-hid/intel-thc/intel-thc-hw.h    | 129 ++++++++
 3 files changed, 417 insertions(+)
drivers/hid/intel-thc-hid/intel-thc/intel-thc-dev.c +281 -0
index 8a439eb120b5..92a1dbe9a928 100644
@@ -1290,6 +1290,287 @@ void thc_spi_input_output_address_config(struct thc_device *dev, u32 input_hdr_a
 }
 EXPORT_SYMBOL_NS_GPL(thc_spi_input_output_address_config, "INTEL_THC");
 
+static int thc_i2c_subip_pio_read(struct thc_device *dev, const u32 address,
+				  u32 *size, u32 *buffer)
+{
+	int ret;
+
+	if (!size || *size == 0 || !buffer) {
+		dev_err(dev->dev, "Invalid input parameters, size %p, buffer %p\n",
+			size, buffer);
+		return -EINVAL;
+	}
+
+	if (mutex_lock_interruptible(&dev->thc_bus_lock))
+		return -EINTR;
+
+	ret = prepare_pio(dev, THC_PIO_OP_I2C_SUBSYSTEM_READ, address, *size);
+	if (ret < 0)
+		goto end;
+
+	pio_start(dev, 0, NULL);
+
+	ret = pio_wait(dev);
+	if (ret < 0)
+		goto end;
+
+	ret = pio_complete(dev, buffer, size);
+	if (ret < 0)
+		goto end;
+
+end:
+	mutex_unlock(&dev->thc_bus_lock);
+
+	if (ret)
+		dev_err_once(dev->dev, "Read THC I2C SubIP register failed %d, offset %u\n",
+			     ret, address);
+
+	return ret;
+}
+
+static int thc_i2c_subip_pio_write(struct thc_device *dev, const u32 address,
+				   const u32 size, const u32 *buffer)
+{
+	int ret;
+
+	if (size == 0 || !buffer) {
+		dev_err(dev->dev, "Invalid input parameters, size %u, buffer %p\n",
+			size, buffer);
+		return -EINVAL;
+	}
+
+	if (mutex_lock_interruptible(&dev->thc_bus_lock))
+		return -EINTR;
+
+	ret = prepare_pio(dev, THC_PIO_OP_I2C_SUBSYSTEM_WRITE, address, size);
+	if (ret < 0)
+		goto end;
+
+	pio_start(dev, size, buffer);
+
+	ret = pio_wait(dev);
+	if (ret < 0)
+		goto end;
+
+	ret = pio_complete(dev, NULL, NULL);
+	if (ret < 0)
+		goto end;
+
+end:
+	mutex_unlock(&dev->thc_bus_lock);
+
+	if (ret)
+		dev_err_once(dev->dev, "Write THC I2C SubIP register failed %d, offset %u\n",
+			     ret, address);
+
+	return ret;
+}
+
+#define I2C_SUBIP_CON_DEFAULT		0x663
+#define I2C_SUBIP_INT_MASK_DEFAULT	0x7FFF
+#define I2C_SUBIP_RX_TL_DEFAULT		62
+#define I2C_SUBIP_TX_TL_DEFAULT		0
+#define I2C_SUBIP_DMA_TDLR_DEFAULT	7
+#define I2C_SUBIP_DMA_RDLR_DEFAULT	7
+
+static int thc_i2c_subip_set_speed(struct thc_device *dev, const u32 speed,
+				   const u32 hcnt, const u32 lcnt)
+{
+	u32 hcnt_offset, lcnt_offset;
+	u32 val;
+	int ret;
+
+	switch (speed) {
+	case THC_I2C_STANDARD:
+		hcnt_offset = THC_I2C_IC_SS_SCL_HCNT_OFFSET;
+		lcnt_offset = THC_I2C_IC_SS_SCL_LCNT_OFFSET;
+		break;
+
+	case THC_I2C_FAST_AND_PLUS:
+		hcnt_offset = THC_I2C_IC_FS_SCL_HCNT_OFFSET;
+		lcnt_offset = THC_I2C_IC_FS_SCL_LCNT_OFFSET;
+		break;
+
+	case THC_I2C_HIGH_SPEED:
+		hcnt_offset = THC_I2C_IC_HS_SCL_HCNT_OFFSET;
+		lcnt_offset = THC_I2C_IC_HS_SCL_LCNT_OFFSET;
+		break;
+
+	default:
+		dev_err_once(dev->dev, "Unsupported i2c speed %d\n", speed);
+		ret = -EINVAL;
+		return ret;
+	}
+
+	ret = thc_i2c_subip_pio_write(dev, hcnt_offset, sizeof(u32), &hcnt);
+	if (ret < 0)
+		return ret;
+
+	ret = thc_i2c_subip_pio_write(dev, lcnt_offset, sizeof(u32), &lcnt);
+	if (ret < 0)
+		return ret;
+
+	val = I2C_SUBIP_CON_DEFAULT & ~THC_I2C_IC_CON_SPEED;
+	val |= FIELD_PREP(THC_I2C_IC_CON_SPEED, speed);
+	ret = thc_i2c_subip_pio_write(dev, THC_I2C_IC_CON_OFFSET, sizeof(u32), &val);
+	if (ret < 0)
+		return ret;
+
+	return 0;
+}
+
+static u32 i2c_subip_regs[] = {
+	THC_I2C_IC_CON_OFFSET,
+	THC_I2C_IC_TAR_OFFSET,
+	THC_I2C_IC_INTR_MASK_OFFSET,
+	THC_I2C_IC_RX_TL_OFFSET,
+	THC_I2C_IC_TX_TL_OFFSET,
+	THC_I2C_IC_DMA_CR_OFFSET,
+	THC_I2C_IC_DMA_TDLR_OFFSET,
+	THC_I2C_IC_DMA_RDLR_OFFSET,
+	THC_I2C_IC_SS_SCL_HCNT_OFFSET,
+	THC_I2C_IC_SS_SCL_LCNT_OFFSET,
+	THC_I2C_IC_FS_SCL_HCNT_OFFSET,
+	THC_I2C_IC_FS_SCL_LCNT_OFFSET,
+	THC_I2C_IC_HS_SCL_HCNT_OFFSET,
+	THC_I2C_IC_HS_SCL_LCNT_OFFSET,
+	THC_I2C_IC_ENABLE_OFFSET,
+};
+
+/**
+ * thc_i2c_subip_init - Initialize and configure THC I2C subsystem
+ *
+ * @dev: The pointer of THC private device context
+ * @target_address: Slave address of touch device (TIC)
+ * @speed: I2C bus frequency speed mode
+ * @hcnt: I2C clock SCL high count
+ * @lcnt: I2C clock SCL low count
+ *
+ * Return: 0 on success, other error codes on failed.
+ */
+int thc_i2c_subip_init(struct thc_device *dev, const u32 target_address,
+		       const u32 speed, const u32 hcnt, const u32 lcnt)
+{
+	u32 read_size = sizeof(u32);
+	u32 val;
+	int ret;
+
+	ret = thc_i2c_subip_pio_read(dev, THC_I2C_IC_ENABLE_OFFSET, &read_size, &val);
+	if (ret < 0)
+		return ret;
+
+	val &= ~THC_I2C_IC_ENABLE_ENABLE;
+	ret = thc_i2c_subip_pio_write(dev, THC_I2C_IC_ENABLE_OFFSET, sizeof(u32), &val);
+	if (ret < 0)
+		return ret;
+
+	ret = thc_i2c_subip_pio_read(dev, THC_I2C_IC_TAR_OFFSET, &read_size, &val);
+	if (ret < 0)
+		return ret;
+
+	val &= ~THC_I2C_IC_TAR_IC_TAR;
+	val |= FIELD_PREP(THC_I2C_IC_TAR_IC_TAR, target_address);
+	ret = thc_i2c_subip_pio_write(dev, THC_I2C_IC_TAR_OFFSET, sizeof(u32), &val);
+	if (ret < 0)
+		return ret;
+
+	ret = thc_i2c_subip_set_speed(dev, speed, hcnt, lcnt);
+	if (ret < 0)
+		return ret;
+
+	val = I2C_SUBIP_INT_MASK_DEFAULT;
+	ret = thc_i2c_subip_pio_write(dev, THC_I2C_IC_INTR_MASK_OFFSET, sizeof(u32), &val);
+	if (ret < 0)
+		return ret;
+
+	val = I2C_SUBIP_RX_TL_DEFAULT;
+	ret = thc_i2c_subip_pio_write(dev, THC_I2C_IC_RX_TL_OFFSET, sizeof(u32), &val);
+	if (ret < 0)
+		return ret;
+
+	val = I2C_SUBIP_TX_TL_DEFAULT;
+	ret = thc_i2c_subip_pio_write(dev, THC_I2C_IC_TX_TL_OFFSET, sizeof(u32), &val);
+	if (ret < 0)
+		return ret;
+
+	val = THC_I2C_IC_DMA_CR_RDMAE | THC_I2C_IC_DMA_CR_TDMAE;
+	ret = thc_i2c_subip_pio_write(dev, THC_I2C_IC_DMA_CR_OFFSET, sizeof(u32), &val);
+	if (ret < 0)
+		return ret;
+
+	val = I2C_SUBIP_DMA_TDLR_DEFAULT;
+	ret = thc_i2c_subip_pio_write(dev, THC_I2C_IC_DMA_TDLR_OFFSET, sizeof(u32), &val);
+	if (ret < 0)
+		return ret;
+
+	val = I2C_SUBIP_DMA_RDLR_DEFAULT;
+	ret = thc_i2c_subip_pio_write(dev, THC_I2C_IC_DMA_RDLR_OFFSET, sizeof(u32), &val);
+	if (ret < 0)
+		return ret;
+
+	ret = thc_i2c_subip_pio_read(dev, THC_I2C_IC_ENABLE_OFFSET, &read_size, &val);
+	if (ret < 0)
+		return ret;
+
+	val |= THC_I2C_IC_ENABLE_ENABLE;
+	ret = thc_i2c_subip_pio_write(dev, THC_I2C_IC_ENABLE_OFFSET, sizeof(u32), &val);
+	if (ret < 0)
+		return ret;
+
+	dev->i2c_subip_regs = devm_kzalloc(dev->dev, sizeof(i2c_subip_regs), GFP_KERNEL);
+	if (!dev->i2c_subip_regs)
+		return PTR_ERR(dev->i2c_subip_regs);
+
+	return 0;
+}
+EXPORT_SYMBOL_NS_GPL(thc_i2c_subip_init, "INTEL_THC");
+
+/**
+ * thc_i2c_subip_regs_save - Save THC I2C sub-subsystem register values to THC device context
+ *
+ * @dev: The pointer of THC private device context
+ *
+ * Return: 0 on success, other error codes on failed.
+ */
+int thc_i2c_subip_regs_save(struct thc_device *dev)
+{
+	int ret;
+	u32 read_size = sizeof(u32);
+
+	for (int i = 0; i < ARRAY_SIZE(i2c_subip_regs); i++) {
+		ret = thc_i2c_subip_pio_read(dev, i2c_subip_regs[i],
+					     &read_size, (u32 *)&dev->i2c_subip_regs + i);
+		if (ret < 0)
+			return ret;
+	}
+
+	return 0;
+}
+EXPORT_SYMBOL_NS_GPL(thc_i2c_subip_regs_save, "INTEL_THC");
+
+/**
+ * thc_i2c_subip_regs_restore - Restore THC I2C subsystem registers from THC device context
+ *
+ * @dev: The pointer of THC private device context
+ *
+ * Return: 0 on success, other error codes on failed.
+ */
+int thc_i2c_subip_regs_restore(struct thc_device *dev)
+{
+	int ret;
+	u32 write_size = sizeof(u32);
+
+	for (int i = 0; i < ARRAY_SIZE(i2c_subip_regs); i++) {
+		ret = thc_i2c_subip_pio_write(dev, i2c_subip_regs[i],
+					      write_size, (u32 *)&dev->i2c_subip_regs + i);
+		if (ret < 0)
+			return ret;
+	}
+
+	return 0;
+}
+EXPORT_SYMBOL_NS_GPL(thc_i2c_subip_regs_restore, "INTEL_THC");
+
 MODULE_AUTHOR("Xinpeng Sun <[email protected]>");
 MODULE_AUTHOR("Even Xu <[email protected]>");
 
drivers/hid/intel-thc-hid/intel-thc/intel-thc-dev.h +7 -0
index 925355f19bae..0517fee2c668 100644
@@ -61,6 +61,7 @@ enum thc_int_type {
  * @write_done: bool value that indicates if DMA write is done
  * @swdma_done: bool value that indicates if SWDMA swquence is done
  * @perf_limit: the delay between read operation and write operation
+ * @i2c_subip_regs: the copy of THC I2C sub-system registers for resuming restore
  */
 struct thc_device {
 	struct device *dev;
@@ -78,6 +79,8 @@ struct thc_device {
 	bool swdma_done;
 
 	u32 perf_limit;
+
+	u32 *i2c_subip_regs;
 };
 
 struct thc_device *thc_dev_init(struct device *device, void __iomem *mem_addr);
@@ -105,5 +108,9 @@ int thc_spi_write_config(struct thc_device *dev, u32 spi_freq_val,
 			 u32 io_mode, u32 opcode, u32 spi_wr_mps, u32 perf_limit);
 void thc_spi_input_output_address_config(struct thc_device *dev, u32 input_hdr_addr,
 					 u32 input_bdy_addr, u32 output_addr);
+int thc_i2c_subip_init(struct thc_device *dev, const u32 target_address,
+		       const u32 speed, const u32 hcnt, const u32 lcnt);
+int thc_i2c_subip_regs_save(struct thc_device *dev);
+int thc_i2c_subip_regs_restore(struct thc_device *dev);
 
 #endif /* _INTEL_THC_DEV_H_ */
drivers/hid/intel-thc-hid/intel-thc/intel-thc-hw.h +129 -0

133 lines not on this page · raw message

Signature · 1 line
2.40.1
author maintainer
#16 lore raw

PATCH v4 11/22 HID: intel-thc-hid: intel-quickspi: Add THC QuickSPI driver skeleton

In reply to Even Xu

From: Xinpeng Sun <[email protected]>

Create intel-quickspi folder and add Kconfig and Makefile for THC QuickSPI driver. Add basic device structure, definitions and probe/remove functions for QuickSPI driver.

---
 drivers/hid/intel-thc-hid/Kconfig             |  11 +
 drivers/hid/intel-thc-hid/Makefile            |   3 +
 .../intel-quickspi/pci-quickspi.c             | 287 ++++++++++++++++++
 .../intel-quickspi/quickspi-dev.h             |  61 ++++
 4 files changed, 362 insertions(+)
 create mode 100644 drivers/hid/intel-thc-hid/intel-quickspi/pci-quickspi.c
 create mode 100644 drivers/hid/intel-thc-hid/intel-quickspi/quickspi-dev.h
drivers/hid/intel-thc-hid/Kconfig +11 -0
index dc7c5a23f0ad..25a3729df92a 100644
@@ -17,4 +17,15 @@ config INTEL_THC_HID
 
 	  Say Y/M here if you want to support Intel THC. If unsure, say N.
 
+config INTEL_QUICKSPI
+	tristate "Intel QuickSPI driver based on Intel Touch Host Controller"
+	depends on INTEL_THC_HID
+	help
+	  Intel QuickSPI, based on Touch Host Controller (THC), implements
+	  HIDSPI (HID over SPI) protocol. It configures THC to work at SPI
+	  mode, and controls THC hardware sequencer to accelerate HIDSPI
+	  transaction flow.
+
+	  Say Y/M here if you want to support Intel QuickSPI. If unsure, say N.
+
 endmenu
drivers/hid/intel-thc-hid/Makefile +3 -0
index b9709cc5e9eb..7669739a39b7 100644
@@ -9,4 +9,7 @@ obj-$(CONFIG_INTEL_THC_HID) += intel-thc.o
 intel-thc-objs += intel-thc/intel-thc-dev.o
 intel-thc-objs += intel-thc/intel-thc-dma.o
 
+obj-$(CONFIG_INTEL_QUICKSPI) += intel-quickspi.o
+intel-quickspi-objs += intel-quickspi/pci-quickspi.o
+
 ccflags-y += -I $(src)/intel-thc
drivers/hid/intel-thc-hid/intel-quickspi/pci-quickspi.c new file +287 -0

287 lines not on this page · raw message

drivers/hid/intel-thc-hid/intel-quickspi/quickspi-dev.h new file +61 -0

61 lines not on this page · raw message

Signature · 1 line
2.40.1
author maintainer
#17 lore raw

PATCH v4 12/22 HID: intel-thc-hid: intel-quickspi: Add THC QuickSPI driver hid layer

In reply to Even Xu

Add HID Low level driver callbacks and hid probe function to register QucikSPI as a HID driver, and external touch device as a HID device.

---
 drivers/hid/intel-thc-hid/Makefile            |   1 +
 .../intel-quickspi/quickspi-dev.h             |  11 ++
 .../intel-quickspi/quickspi-hid.c             | 142 ++++++++++++++++++
 .../intel-quickspi/quickspi-hid.h             |  14 ++
 include/linux/hid-over-spi.h                  |  37 +++++
 5 files changed, 205 insertions(+)
 create mode 100644 drivers/hid/intel-thc-hid/intel-quickspi/quickspi-hid.c
 create mode 100644 drivers/hid/intel-thc-hid/intel-quickspi/quickspi-hid.h
 create mode 100644 include/linux/hid-over-spi.h
drivers/hid/intel-thc-hid/Makefile +1 -0
index 7669739a39b7..4dd9e815021d 100644
@@ -11,5 +11,6 @@ intel-thc-objs += intel-thc/intel-thc-dma.o
 
 obj-$(CONFIG_INTEL_QUICKSPI) += intel-quickspi.o
 intel-quickspi-objs += intel-quickspi/pci-quickspi.o
+intel-quickspi-objs += intel-quickspi/quickspi-hid.o
 
 ccflags-y += -I $(src)/intel-thc
drivers/hid/intel-thc-hid/intel-quickspi/quickspi-dev.h +11 -0
index cffc859efa19..335b32363d7f 100644
@@ -4,6 +4,8 @@
 #ifndef _QUICKSPI_DEV_H_
 #define _QUICKSPI_DEV_H_
 
+#include <linux/hid-over-spi.h>
+
 #define PCI_DEVICE_ID_INTEL_THC_MTL_DEVICE_ID_SPI_PORT1		0x7E49
 #define PCI_DEVICE_ID_INTEL_THC_MTL_DEVICE_ID_SPI_PORT2		0x7E4B
 #define PCI_DEVICE_ID_INTEL_THC_LNL_DEVICE_ID_SPI_PORT1		0xA849
@@ -38,24 +40,33 @@ struct quickspi_driver_data {
 struct device;
 struct pci_dev;
 struct thc_device;
+struct hid_device;
 
 /**
  * struct quickspi_device -  THC QuickSpi device struct
  * @dev: point to kernel device
  * @pdev: point to PCI device
  * @thc_hw: point to THC device
+ * @hid_dev: point to hid device
  * @driver_data: point to quickspi specific driver data
  * @state: THC SPI device state
  * @mem_addr: MMIO memory address
+ * @dev_desc: device descriptor for HIDSPI protocol
+ * @report_descriptor: store a copy of device report descriptor
  */
 struct quickspi_device {
 	struct device *dev;
 	struct pci_dev *pdev;
 	struct thc_device *thc_hw;
+	struct hid_device *hid_dev;
 	struct quickspi_driver_data *driver_data;
 	enum quickspi_dev_state state;
 
 	void __iomem *mem_addr;
+
+	struct hidspi_dev_descriptor dev_desc;
+
+	u8 *report_descriptor;
 };
 
 #endif /* _QUICKSPI_DEV_H_ */
drivers/hid/intel-thc-hid/intel-quickspi/quickspi-hid.c new file +142 -0

142 lines not on this page · raw message

drivers/hid/intel-thc-hid/intel-quickspi/quickspi-hid.h new file +14 -0
new file mode 100644
index 000000000000..f640fa876a40
@@ -0,0 +1,14 @@
+/* SPDX-License-Identifier: GPL-2.0 */
+/* Copyright (c) 2024 Intel Corporation */
+
+#ifndef _QUICKSPI_HID_H_
+#define _QUICKSPI_HID_H_
+
+struct quickspi_device;
+
+int quickspi_hid_send_report(struct quickspi_device *qsdev,
+			     void *data, size_t data_size);
+int quickspi_hid_probe(struct quickspi_device *qsdev);
+void quickspi_hid_remove(struct quickspi_device *qsdev);
+
+#endif /* _QUICKSPI_HID_H_ */
include/linux/hid-over-spi.h new file +37 -0
new file mode 100644
index 000000000000..ddbe41c5d8fd
@@ -0,0 +1,37 @@
+/* SPDX-License-Identifier: GPL-2.0 */
+/* Copyright 2024 Intel Corporation */
+
+#ifndef _HID_OVER_SPI_H_
+#define _HID_OVER_SPI_H_
+
+/**
+ * struct hidspi_dev_descriptor - HIDSPI device descriptor definition
+ * @dev_desc_len: The length of the complete device descriptor, fixed to 0x18 (24).
+ * @bcd_ver: The version number of the HIDSPI protocol supported.
+ *           In binary coded decimal (BCD) format. Must be fixed to 0x0300.
+ * @rep_desc_len: The length of the report descriptor
+ * @max_input_len: The length of the largest possible HID input (or feature) report
+ * @max_output_len: The length of the largest output (or feature) report
+ * @max_frag_len: The length of the largest fragment, where a fragment represents
+ *                the body of an input report.
+ * @vendor_id: Device manufacturers vendor ID
+ * @product_id: Device unique model/product ID
+ * @version_id: Device’s unique version
+ * @flags: Specify flags for the device’s operation
+ * @reserved: Reserved and should be 0
+ */
+struct hidspi_dev_descriptor {
+	__le16 dev_desc_len;
+	__le16 bcd_ver;
+	__le16 rep_desc_len;
+	__le16 max_input_len;
+	__le16 max_output_len;
+	__le16 max_frag_len;
+	__le16 vendor_id;
+	__le16 product_id;
+	__le16 version_id;
+	__le16 flags;
+	__le32 reserved;
+};
+
+#endif /* _HID_OVER_SPI_H_ */
Signature · 1 line
2.40.1
author maintainer
#18 lore raw

PATCH v4 13/22 HID: intel-thc-hid: intel-quickspi: Add THC QuickSPI ACPI interfaces

In reply to Even Xu

Add functions to query QuickSPI ACPI DSD parameters and provide APIs for DSM method accessing.

---
 .../intel-quickspi/pci-quickspi.c             | 189 ++++++++++++++++++
 .../intel-quickspi/quickspi-dev.h             |  54 +++++
 2 files changed, 243 insertions(+)
drivers/hid/intel-thc-hid/intel-quickspi/pci-quickspi.c +189 -0
index a997c9a570d4..7df2d00c3b22 100644
@@ -1,6 +1,8 @@
 /* SPDX-License-Identifier: GPL-2.0 */
 /* Copyright (c) 2024 Intel Corporation */
 
+#include <linux/acpi.h>
+#include <linux/bitfield.h>
 #include <linux/device.h>
 #include <linux/dma-mapping.h>
 #include <linux/err.h>
@@ -9,6 +11,7 @@
 #include <linux/pci.h>
 
 #include "intel-thc-dev.h"
+#include "intel-thc-hw.h"
 
 #include "quickspi-dev.h"
 
@@ -24,6 +27,186 @@ struct quickspi_driver_data ptl = {
 	.max_packet_size_value = MAX_PACKET_SIZE_VALUE_LNL,
 };
 
+/* THC QuickSPI ACPI method to get device properties */
+/* HIDSPI Method: {6e2ac436-0fcf-41af-a265-b32a220dcfab} */
+static guid_t hidspi_guid =
+	GUID_INIT(0x6e2ac436, 0x0fcf, 0x41af, 0xa2, 0x65, 0xb3, 0x2a,
+		  0x22, 0x0d, 0xcf, 0xab);
+
+/* QuickSpi Method: {300D35b7-ac20-413e-8e9c-92e4dafd0afe} */
+static guid_t thc_quickspi_guid =
+	GUID_INIT(0x300d35b7, 0xac20, 0x413e, 0x8e, 0x9c, 0x92, 0xe4,
+		  0xda, 0xfd, 0x0a, 0xfe);
+
+/* Platform Method: {84005682-5b71-41a4-0x8d668130f787a138} */
+static guid_t thc_platform_guid =
+	GUID_INIT(0x84005682, 0x5b71, 0x41a4, 0x8d, 0x66, 0x81, 0x30,
+		  0xf7, 0x87, 0xa1, 0x38);
+
+/**
+ * thc_acpi_get_property - Query device ACPI parameter
+ *
+ * @adev: point to ACPI device
+ * @guid: ACPI method's guid
+ * @rev: ACPI method's revision
+ * @func: ACPI method's function number
+ * @type: ACPI parameter's data type
+ * @prop_buf: point to return buffer
+ *
+ * This is a helper function for device to query its ACPI parameters.
+ *
+ * Return: 0 if successful or ENODEV on failed.
+ */
+static int thc_acpi_get_property(struct acpi_device *adev, const guid_t *guid,
+				 u64 rev, u64 func, acpi_object_type type, void *prop_buf)
+{
+	acpi_handle handle = acpi_device_handle(adev);
+	union acpi_object *obj;
+
+	obj = acpi_evaluate_dsm_typed(handle, guid, rev, func, NULL, type);
+	if (!obj) {
+		acpi_handle_err(handle,
+				"Error _DSM call failed, rev: %llu, func: %llu, type: %u\n",
+				rev, func, type);
+		return -ENODEV;
+	}
+
+	if (type == ACPI_TYPE_INTEGER)
+		*(u32 *)prop_buf = (u32)obj->integer.value;
+	else if (type == ACPI_TYPE_BUFFER)
+		memcpy(prop_buf, obj->buffer.pointer, obj->buffer.length);
+
+	ACPI_FREE(obj);
+
+	return 0;
+}
+
+/**
+ * quickspi_get_acpi_resources - Query all quickspi devices' ACPI parameters
+ *
+ * @qsdev: point to quickspi device
+ *
+ * This function gets all quickspi devices' ACPI resource.
+ *
+ * Return: 0 if successful or error code on failed.
+ */
+static int quickspi_get_acpi_resources(struct quickspi_device *qsdev)
+{
+	struct acpi_device *adev = ACPI_COMPANION(qsdev->dev);
+	int ret = -EINVAL;
+
+	if (!adev) {
+		dev_err(qsdev->dev, "no valid ACPI companion\n");
+		return ret;
+	}
+
+	qsdev->acpi_dev = adev;
+
+	ret = thc_acpi_get_property(adev, &hidspi_guid,
+				    ACPI_QUICKSPI_REVISION_NUM,
+				    ACPI_QUICKSPI_FUNC_NUM_INPUT_REP_HDR_ADDR,
+				    ACPI_TYPE_INTEGER,
+				    &qsdev->input_report_hdr_addr);
+	if (ret)
+		return ret;
+
+	ret = thc_acpi_get_property(adev, &hidspi_guid,
+				    ACPI_QUICKSPI_REVISION_NUM,
+				    ACPI_QUICKSPI_FUNC_NUM_INPUT_REP_BDY_ADDR,
+				    ACPI_TYPE_INTEGER,
+				    &qsdev->input_report_bdy_addr);
+	if (ret)
+		return ret;
+
+	ret = thc_acpi_get_property(adev, &hidspi_guid,
+				    ACPI_QUICKSPI_REVISION_NUM,
+				    ACPI_QUICKSPI_FUNC_NUM_OUTPUT_REP_ADDR,
+				    ACPI_TYPE_INTEGER,
+				    &qsdev->output_report_addr);
+	if (ret)
+		return ret;
+
+	ret = thc_acpi_get_property(adev, &hidspi_guid,
+				    ACPI_QUICKSPI_REVISION_NUM,
+				    ACPI_QUICKSPI_FUNC_NUM_READ_OPCODE,
+				    ACPI_TYPE_BUFFER,
+				    &qsdev->spi_read_opcode);
+	if (ret)
+		return ret;
+
+	ret = thc_acpi_get_property(adev, &hidspi_guid,
+				    ACPI_QUICKSPI_REVISION_NUM,
+				    ACPI_QUICKSPI_FUNC_NUM_WRITE_OPCODE,
+				    ACPI_TYPE_BUFFER,
+				    &qsdev->spi_write_opcode);
+	if (ret)
+		return ret;
+
+	ret = thc_acpi_get_property(adev, &hidspi_guid,
+				    ACPI_QUICKSPI_REVISION_NUM,
+				    ACPI_QUICKSPI_FUNC_NUM_IO_MODE,
+				    ACPI_TYPE_INTEGER,
+				    &qsdev->spi_read_io_mode);
+	if (ret)
+		return ret;
+
+	if (qsdev->spi_read_io_mode & SPI_WRITE_IO_MODE)
+		qsdev->spi_write_io_mode = FIELD_GET(SPI_IO_MODE_OPCODE, qsdev->spi_read_io_mode);
+	else
+		qsdev->spi_write_io_mode = THC_SINGLE_IO;
+
+	qsdev->spi_read_io_mode = FIELD_GET(SPI_IO_MODE_OPCODE, qsdev->spi_read_io_mode);
+
+	ret = thc_acpi_get_property(adev, &thc_quickspi_guid,
+				    ACPI_QUICKSPI_REVISION_NUM,
+				    ACPI_QUICKSPI_FUNC_NUM_CONNECTION_SPEED,
+				    ACPI_TYPE_INTEGER,
+				    &qsdev->spi_freq_val);
+	if (ret)
+		return ret;
+
+	ret = thc_acpi_get_property(adev, &thc_quickspi_guid,
+				    ACPI_QUICKSPI_REVISION_NUM,
+				    ACPI_QUICKSPI_FUNC_NUM_LIMIT_PACKET_SIZE,
+				    ACPI_TYPE_INTEGER,
+				    &qsdev->limit_packet_size);
+	if (ret)
+		return ret;
+
+	if (qsdev->limit_packet_size || !qsdev->driver_data)
+		qsdev->spi_packet_size = DEFAULT_MIN_PACKET_SIZE_VALUE;
+	else
+		qsdev->spi_packet_size = qsdev->driver_data->max_packet_size_value;
+
+	ret = thc_acpi_get_property(adev, &thc_quickspi_guid,
+				    ACPI_QUICKSPI_REVISION_NUM,
+				    ACPI_QUICKSPI_FUNC_NUM_PERFORMANCE_LIMIT,
+				    ACPI_TYPE_INTEGER,
+				    &qsdev->performance_limit);
+	if (ret)
+		return ret;
+
+	qsdev->performance_limit = FIELD_GET(PERFORMANCE_LIMITATION, qsdev->performance_limit);
+
+	ret = thc_acpi_get_property(adev, &thc_platform_guid,
+				    ACPI_QUICKSPI_REVISION_NUM,
+				    ACPI_QUICKSPI_FUNC_NUM_ACTIVE_LTR,
+				    ACPI_TYPE_INTEGER,
+				    &qsdev->active_ltr_val);
+	if (ret)
+		return ret;
+
+	ret = thc_acpi_get_property(adev, &thc_platform_guid,
+				    ACPI_QUICKSPI_REVISION_NUM,
+				    ACPI_QUICKSPI_FUNC_NUM_LP_LTR,
+				    ACPI_TYPE_INTEGER,
+				    &qsdev->low_power_ltr_val);
+	if (ret)
+		return ret;
+
+	return 0;
+}
+
 /**
  * quickspi_irq_quick_handler - The ISR of the quickspi driver
  *
@@ -113,6 +296,12 @@ static struct quickspi_device *quickspi_dev_init(struct pci_dev *pdev, void __io
 		return ERR_PTR(ret);
 	}
 
+	ret = quickspi_get_acpi_resources(qsdev);
+	if (ret) {
+		dev_err(dev, "Get ACPI resources failed, ret = %d\n", ret);
+		return ERR_PTR(ret);
+	}
+
 	thc_interrupt_config(qsdev->thc_hw);
 
 	thc_interrupt_enable(qsdev->thc_hw, true);
drivers/hid/intel-thc-hid/intel-quickspi/quickspi-dev.h +54 -0

88 lines not on this page · raw message

Signature · 1 line
2.40.1
author maintainer
#19 lore raw

PATCH v4 14/22 HID: intel-thc-hid: intel-quickspi: Add HIDSPI protocol implementation

In reply to Even Xu

Intel QuickSPI driver uses THC hardware to accelerate HID over SPI (HIDSPI) protocol flow.

This patch implements all data flows described in HID over SPI protocol SPEC by using THC hardware layer APIs.

HID over SPI SPEC:
https://www.microsoft.com/download/details.aspx?id=103325

---
 drivers/hid/intel-thc-hid/Makefile            |   1 +
 .../intel-quickspi/quickspi-dev.h             |  38 ++
 .../intel-quickspi/quickspi-hid.c             |  17 +-
 .../intel-quickspi/quickspi-protocol.c        | 411 ++++++++++++++++++
 .../intel-quickspi/quickspi-protocol.h        |  25 ++
 include/linux/hid-over-spi.h                  | 118 +++++
 6 files changed, 609 insertions(+), 1 deletion(-)
 create mode 100644 drivers/hid/intel-thc-hid/intel-quickspi/quickspi-protocol.c
 create mode 100644 drivers/hid/intel-thc-hid/intel-quickspi/quickspi-protocol.h
drivers/hid/intel-thc-hid/Makefile +1 -0
index 4dd9e815021d..2dba4db70c33 100644
@@ -12,5 +12,6 @@ intel-thc-objs += intel-thc/intel-thc-dma.o
 obj-$(CONFIG_INTEL_QUICKSPI) += intel-quickspi.o
 intel-quickspi-objs += intel-quickspi/pci-quickspi.o
 intel-quickspi-objs += intel-quickspi/quickspi-hid.o
+intel-quickspi-objs += intel-quickspi/quickspi-protocol.o
 
 ccflags-y += -I $(src)/intel-thc
drivers/hid/intel-thc-hid/intel-quickspi/quickspi-dev.h +38 -0
index deb24dd1a0fa..c5257378c1e9 100644
@@ -4,7 +4,12 @@
 #ifndef _QUICKSPI_DEV_H_
 #define _QUICKSPI_DEV_H_
 
+#include <linux/bits.h>
 #include <linux/hid-over-spi.h>
+#include <linux/sizes.h>
+#include <linux/wait.h>
+
+#include "quickspi-protocol.h"
 
 #define PCI_DEVICE_ID_INTEL_THC_MTL_DEVICE_ID_SPI_PORT1		0x7E49
 #define PCI_DEVICE_ID_INTEL_THC_MTL_DEVICE_ID_SPI_PORT2		0x7E4B
@@ -92,6 +97,21 @@ struct acpi_device;
  * @active_ltr_val: THC active LTR value
  * @low_power_ltr_val: THC low power LTR value
  * @report_descriptor: store a copy of device report descriptor
+ * @input_buf: store a copy of latest input report data
+ * @report_buf: store a copy of latest input/output report packet from set/get feature
+ * @report_len: the length of input/output report packet
+ * @reset_ack_wq: workqueue for waiting reset response from device
+ * @reset_ack: indicate reset response received or not
+ * @nondma_int_received_wq: workqueue for waiting THC non-DMA interrupt
+ * @nondma_int_received: indicate THC non-DMA interrupt received or not
+ * @report_desc_got_wq: workqueue for waiting device report descriptor
+ * @report_desc_got: indicate device report descritor received or not
+ * @set_power_on_wq: workqueue for waiting set power on response from device
+ * @set_power_on: indicate set power on response received or not
+ * @get_feature_cmpl_wq: workqueue for waiting get feature response from device
+ * @get_feature_cmpl: indicate get feature received or not
+ * @set_feature_cmpl_wq: workqueue for waiting set feature to device
+ * @set_feature_cmpl: indicate set feature send complete or not
  */
 struct quickspi_device {
 	struct device *dev;
@@ -121,6 +141,24 @@ struct quickspi_device {
 	u32 low_power_ltr_val;
 
 	u8 *report_descriptor;
+	u8 *input_buf;
+	u8 *report_buf;
+	u32 report_len;
+
+	wait_queue_head_t reset_ack_wq;
+	bool reset_ack;
+
+	wait_queue_head_t nondma_int_received_wq;
+	bool nondma_int_received;
+
+	wait_queue_head_t report_desc_got_wq;
+	bool report_desc_got;
+
+	wait_queue_head_t get_report_cmpl_wq;
+	bool get_report_cmpl;
+
+	wait_queue_head_t set_report_cmpl_wq;
+	bool set_report_cmpl;
 };
 
 #endif /* _QUICKSPI_DEV_H_ */
drivers/hid/intel-thc-hid/intel-quickspi/quickspi-hid.c +16 -1
index eae53a749a38..2553d4b42b51 100644
@@ -51,7 +51,22 @@ static int quickspi_hid_raw_request(struct hid_device *hid,
 				    __u8 *buf, size_t len,
 				    unsigned char rtype, int reqtype)
 {
-	return 0;
+	struct quickspi_device *qsdev = hid->driver_data;
+	int ret = 0;
+
+	switch (reqtype) {
+	case HID_REQ_GET_REPORT:
+		ret = quickspi_get_report(qsdev, rtype, reportnum, buf);
+		break;
+	case HID_REQ_SET_REPORT:
+		ret = quickspi_set_report(qsdev, rtype, reportnum, buf, len);
+		break;
+	default:
+		dev_err_once(qsdev->dev, "Not supported request type %d\n", reqtype);
+		break;
+	}
+
+	return ret;
 }
 
 static int quickspi_hid_power(struct hid_device *hid, int lvl)
drivers/hid/intel-thc-hid/intel-quickspi/quickspi-protocol.c new file +411 -0

411 lines not on this page · raw message

drivers/hid/intel-thc-hid/intel-quickspi/quickspi-protocol.h new file +25 -0
new file mode 100644
index 000000000000..775e29c1ed13
@@ -0,0 +1,25 @@
+/* SPDX-License-Identifier: GPL-2.0 */
+/* Copyright (c) 2024 Intel Corporation */
+
+#ifndef _QUICKSPI_PROTOCOL_H_
+#define _QUICKSPI_PROTOCOL_H_
+
+#include <linux/hid-over-spi.h>
+
+#define QUICKSPI_ACK_WAIT_TIMEOUT    5
+
+struct quickspi_device;
+
+void quickspi_handle_input_data(struct quickspi_device *qsdev, u32 buf_len);
+int quickspi_get_report(struct quickspi_device *qsdev, u8 report_type,
+			unsigned int report_id, void *buf);
+int quickspi_set_report(struct quickspi_device *qsdev, u8 report_type,
+			unsigned int report_id, void *buf, u32 buf_len);
+int quickspi_get_report_descriptor(struct quickspi_device *qsdev);
+
+int quickspi_set_power(struct quickspi_device *qsdev,
+		       enum hidspi_power_state power_state);
+
+int reset_tic(struct quickspi_device *qsdev);
+
+#endif /* _QUICKSPI_PROTOCOL_H_ */
include/linux/hid-over-spi.h +118 -0

128 lines not on this page · raw message

Signature · 1 line
2.40.1
author maintainer
#20 lore raw

PATCH v4 15/22 HID: intel-thc-hid: intel-quickspi: Complete THC QuickSPI driver

In reply to Even Xu

From: Xinpeng Sun <[email protected]>

Fully implement QuickSPI driver probe/remove callbacks, interrupt handler, integrate HIDSPI protocol, enumerate HID device and register HID device.

---
 .../intel-quickspi/pci-quickspi.c             | 265 ++++++++++++++++++
 .../intel-quickspi/quickspi-protocol.c        |   3 +
 2 files changed, 268 insertions(+)
drivers/hid/intel-thc-hid/intel-quickspi/pci-quickspi.c +265 -0
index 7df2d00c3b22..cc92e1a30411 100644
@@ -14,6 +14,8 @@
 #include "intel-thc-hw.h"
 
 #include "quickspi-dev.h"
+#include "quickspi-hid.h"
+#include "quickspi-protocol.h"
 
 struct quickspi_driver_data mtl = {
 	.max_packet_size_value = MAX_PACKET_SIZE_VALUE_MTL,
@@ -228,6 +230,37 @@ static irqreturn_t quickspi_irq_quick_handler(int irq, void *dev_id)
 	return IRQ_WAKE_THREAD;
 }
 
+/**
+ * try_recover - Try to recovery THC and Device
+ * @qsdev: pointer to quickspi device
+ *
+ * This function is a error handler, called when fatal error happens.
+ * It try to reset Touch Device and re-configure THC to recovery
+ * transferring between Device and THC.
+ *
+ * Return: 0 if successful or error code on failed.
+ */
+static int try_recover(struct quickspi_device *qsdev)
+{
+	int ret;
+
+	ret = reset_tic(qsdev);
+	if (ret) {
+		dev_err(qsdev->dev, "Reset touch device failed, ret = %d\n", ret);
+		return ret;
+	}
+
+	thc_dma_unconfigure(qsdev->thc_hw);
+
+	ret = thc_dma_configure(qsdev->thc_hw);
+	if (ret) {
+		dev_err(qsdev->dev, "Re-configure THC DMA failed, ret = %d\n", ret);
+		return ret;
+	}
+
+	return 0;
+}
+
 /**
  * quickspi_irq_thread_handler - IRQ thread handler of quickspi driver
  *
@@ -239,15 +272,52 @@ static irqreturn_t quickspi_irq_quick_handler(int irq, void *dev_id)
 static irqreturn_t quickspi_irq_thread_handler(int irq, void *dev_id)
 {
 	struct quickspi_device *qsdev = dev_id;
+	size_t input_len;
+	int read_finished = 0;
+	int err_recover = 0;
 	int int_mask;
+	int ret;
 
 	if (qsdev->state == QUICKSPI_DISABLED)
 		return IRQ_HANDLED;
 
 	int_mask = thc_interrupt_handler(qsdev->thc_hw);
 
+	if (int_mask & BIT(THC_FATAL_ERR_INT) || int_mask & BIT(THC_TXN_ERR_INT)) {
+		err_recover = 1;
+		goto end;
+	}
+
+	if (int_mask & BIT(THC_NONDMA_INT)) {
+		if (qsdev->state == QUICKSPI_RESETING) {
+			qsdev->reset_ack = true;
+			wake_up_interruptible(&qsdev->reset_ack_wq);
+		} else {
+			qsdev->nondma_int_received = true;
+			wake_up_interruptible(&qsdev->nondma_int_received_wq);
+		}
+	}
+
+	if (int_mask & BIT(THC_RXDMA2_INT)) {
+		while (!read_finished) {
+			ret = thc_rxdma_read(qsdev->thc_hw, THC_RXDMA2, qsdev->input_buf,
+					     &input_len, &read_finished);
+			if (ret) {
+				err_recover = 1;
+				goto end;
+			}
+
+			quickspi_handle_input_data(qsdev, input_len);
+		}
+	}
+
+end:
 	thc_interrupt_enable(qsdev->thc_hw, true);
 
+	if (err_recover)
+		if (try_recover(qsdev))
+			qsdev->state = QUICKSPI_DISABLED;
+
 	return IRQ_HANDLED;
 }
 
@@ -280,8 +350,15 @@ static struct quickspi_device *quickspi_dev_init(struct pci_dev *pdev, void __io
 	qsdev->pdev = pdev;
 	qsdev->dev = dev;
 	qsdev->mem_addr = mem_addr;
+	qsdev->state = QUICKSPI_DISABLED;
 	qsdev->driver_data = (struct quickspi_driver_data *)id->driver_data;
 
+	init_waitqueue_head(&qsdev->reset_ack_wq);
+	init_waitqueue_head(&qsdev->nondma_int_received_wq);
+	init_waitqueue_head(&qsdev->report_desc_got_wq);
+	init_waitqueue_head(&qsdev->get_report_cmpl_wq);
+	init_waitqueue_head(&qsdev->set_report_cmpl_wq);
+
 	/* thc hw init */
 	qsdev->thc_hw = thc_dev_init(qsdev->dev, qsdev->mem_addr);
 	if (IS_ERR(qsdev->thc_hw)) {
@@ -290,6 +367,10 @@ static struct quickspi_device *quickspi_dev_init(struct pci_dev *pdev, void __io
 		return ERR_PTR(ret);
 	}
 
+	ret = thc_interrupt_quiesce(qsdev->thc_hw, true);
+	if (ret)
+		return ERR_PTR(ret);
+
 	ret = thc_port_select(qsdev->thc_hw, THC_PORT_TYPE_SPI);
 	if (ret) {
 		dev_err(dev, "Failed to select THC port, ret = %d.\n", ret);
@@ -302,10 +383,43 @@ static struct quickspi_device *quickspi_dev_init(struct pci_dev *pdev, void __io
 		return ERR_PTR(ret);
 	}
 
+	/* THC config for input/output address */
+	thc_spi_input_output_address_config(qsdev->thc_hw,
+					    qsdev->input_report_hdr_addr,
+					    qsdev->input_report_bdy_addr,
+					    qsdev->output_report_addr);
+
+	/* THC config for spi read operation */
+	ret = thc_spi_read_config(qsdev->thc_hw, qsdev->spi_freq_val,
+				  qsdev->spi_read_io_mode,
+				  qsdev->spi_read_opcode,
+				  qsdev->spi_packet_size);
+	if (ret) {
+		dev_err(dev, "thc_spi_read_config failed, ret = %d\n", ret);
+		return ERR_PTR(ret);
+	}
+
+	/* THC config for spi write operation */
+	ret = thc_spi_write_config(qsdev->thc_hw, qsdev->spi_freq_val,
+				   qsdev->spi_write_io_mode,
+				   qsdev->spi_write_opcode,
+				   qsdev->spi_packet_size,
+				   qsdev->performance_limit);
+	if (ret) {
+		dev_err(dev, "thc_spi_write_config failed, ret = %d\n", ret);
+		return ERR_PTR(ret);
+	}
+
+	thc_ltr_config(qsdev->thc_hw,
+		       qsdev->active_ltr_val,
+		       qsdev->low_power_ltr_val);
+
 	thc_interrupt_config(qsdev->thc_hw);
 
 	thc_interrupt_enable(qsdev->thc_hw, true);
 
+	qsdev->state = QUICKSPI_INITED;
+
 	return qsdev;
 }
 
@@ -319,6 +433,103 @@ static struct quickspi_device *quickspi_dev_init(struct pci_dev *pdev, void __io
 static void quickspi_dev_deinit(struct quickspi_device *qsdev)
 {
 	thc_interrupt_enable(qsdev->thc_hw, false);
+	thc_ltr_unconfig(qsdev->thc_hw);
+
+	qsdev->state = QUICKSPI_DISABLED;
+}
+
+/**
+ * quickspi_dma_init - Configure THC DMA for quickspi device
+ * @qsdev: pointer to the quickspi device structure
+ *
+ * This function uses TIC's parameters(such as max input length, max output
+ * length) to allocate THC DMA buffers and configure THC DMA engines.
+ *
+ * Return: 0 if successful or error code on failed.
+ */
+static int quickspi_dma_init(struct quickspi_device *qsdev)
+{
+	int ret;
+
+	ret = thc_dma_set_max_packet_sizes(qsdev->thc_hw, 0,
+					   le16_to_cpu(qsdev->dev_desc.max_input_len),
+					   le16_to_cpu(qsdev->dev_desc.max_output_len),
+					   0);
+	if (ret)
+		return ret;
+
+	ret = thc_dma_allocate(qsdev->thc_hw);
+	if (ret) {
+		dev_err(qsdev->dev, "Allocate THC DMA buffer failed, ret = %d\n", ret);
+		return ret;
+	}
+
+	/* Enable RxDMA */
+	ret = thc_dma_configure(qsdev->thc_hw);
+	if (ret) {
+		dev_err(qsdev->dev, "Configure THC DMA failed, ret = %d\n", ret);
+		thc_dma_unconfigure(qsdev->thc_hw);
+		thc_dma_release(qsdev->thc_hw);
+		return ret;
+	}
+
+	return ret;
+}
+
+/**
+ * quickspi_dma_deinit - Release THC DMA for quickspi device
+ * @qsdev: pointer to the quickspi device structure
+ *
+ * Stop THC DMA engines and release all DMA buffers.
+ *
+ */
+static void quickspi_dma_deinit(struct quickspi_device *qsdev)
+{
+	thc_dma_unconfigure(qsdev->thc_hw);
+	thc_dma_release(qsdev->thc_hw);
+}
+
+/**
+ * quickspi_alloc_report_buf - Alloc report buffers
+ * @qsdev: pointer to the quickspi device structure
+ *
+ * Allocate report descriptor buffer, it will be used for restore TIC HID
+ * report descriptor.
+ *
+ * Allocate input report buffer, it will be used for receive HID input report
+ * data from TIC.
+ *
+ * Allocate output report buffer, it will be used for store HID output report,
+ * such as set feature.
+ *
+ * Return: 0 if successful or error code on failed.
+ */
+static int quickspi_alloc_report_buf(struct quickspi_device *qsdev)
+{
+	size_t max_report_len;
+	size_t max_input_len;
+
+	qsdev->report_descriptor = devm_kzalloc(qsdev->dev,
+						le16_to_cpu(qsdev->dev_desc.rep_desc_len),
+						GFP_KERNEL);
+	if (!qsdev->report_descriptor)
+		return -ENOMEM;
+
+	max_input_len = max(le16_to_cpu(qsdev->dev_desc.rep_desc_len),
+			    le16_to_cpu(qsdev->dev_desc.max_input_len));
+
+	qsdev->input_buf = devm_kzalloc(qsdev->dev, max_input_len, GFP_KERNEL);
+	if (!qsdev->input_buf)
+		return -ENOMEM;
+
+	max_report_len = max(le16_to_cpu(qsdev->dev_desc.max_output_len),
+			     le16_to_cpu(qsdev->dev_desc.max_input_len));
+
+	qsdev->report_buf = devm_kzalloc(qsdev->dev, max_report_len, GFP_KERNEL);
+	if (!qsdev->report_buf)
+		return -ENOMEM;
+
+	return 0;
 }
 
 /*
@@ -327,6 +538,18 @@ static void quickspi_dev_deinit(struct quickspi_device *qsdev)
  * @pdev: point to pci device
  * @id: point to pci_device_id structure
  *
+ * This function initializes THC and HIDSPI device, the flow is:
+ * - do THC pci device initialization
+ * - query HIDSPI ACPI parameters
+ * - configure THC to HIDSPI mode
+ * - go through HIDSPI enumeration flow
+ *   |- reset HIDSPI device
+ *   |- read device descriptor
+ * - enable THC interrupt and DMA
+ * - read report descriptor
+ * - register HID device
+ * - enable runtime power management
+ *
  * Return 0 if success or error code on failure.
  */
 static int quickspi_probe(struct pci_dev *pdev,
@@ -390,8 +613,44 @@ static int quickspi_probe(struct pci_dev *pdev,
 		goto dev_deinit;
 	}
 
+	ret = reset_tic(qsdev);
+	if (ret) {
+		dev_err(&pdev->dev, "Reset Touch Device failed, ret = %d\n", ret);
+		goto dev_deinit;
+	}
+
+	ret = quickspi_alloc_report_buf(qsdev);
+	if (ret) {
+		dev_err(&pdev->dev, "Alloc report buffers failed, ret= %d\n", ret);
+		goto dev_deinit;
+	}
+
+	ret = quickspi_dma_init(qsdev);
+	if (ret) {
+		dev_err(&pdev->dev, "Setup THC DMA failed, ret= %d\n", ret);
+		goto dev_deinit;
+	}
+
+	ret = quickspi_get_report_descriptor(qsdev);
+	if (ret) {
+		dev_err(&pdev->dev, "Get report descriptor failed, ret = %d\n", ret);
+		goto dma_deinit;
+	}
+
+	ret = quickspi_hid_probe(qsdev);
+	if (ret) {
+		dev_err(&pdev->dev, "Failed to register HID device, ret = %d\n", ret);
+		goto dma_deinit;
+	}
+
+	qsdev->state = QUICKSPI_ENABLED;
+
+	dev_dbg(&pdev->dev, "QuickSPI probe success\n");
+
 	return 0;
 
+dma_deinit:
+	quickspi_dma_deinit(qsdev);
 dev_deinit:
 	quickspi_dev_deinit(qsdev);
 unmap_io_region:
@@ -418,6 +677,9 @@ static void quickspi_remove(struct pci_dev *pdev)
 	if (!qsdev)
 		return;
 
+	quickspi_hid_remove(qsdev);
+	quickspi_dma_deinit(qsdev);
+
 	quickspi_dev_deinit(qsdev);
 
 	pcim_iounmap_regions(pdev, BIT(0));
@@ -441,6 +703,9 @@ static void quickspi_shutdown(struct pci_dev *pdev)
 	if (!qsdev)
 		return;
 
+	/* Must stop DMA before reboot to avoid DMA entering into unknown state */
+	quickspi_dma_deinit(qsdev);
+
 	quickspi_dev_deinit(qsdev);
 }
 
drivers/hid/intel-thc-hid/intel-quickspi/quickspi-protocol.c +3 -0
index ba28b82da385..7373238ceb18 100644
@@ -225,6 +225,9 @@ void quickspi_handle_input_data(struct quickspi_device *qsdev, u32 buf_len)
 		break;
 
 	case DATA:
+		if (qsdev->state != QUICKSPI_ENABLED)
+			return;
+
 		if (input_len > le16_to_cpu(qsdev->dev_desc.max_input_len)) {
 			dev_err_once(qsdev->dev, "Unexpected too large input report length: %u\n",
 				     input_len);
Signature · 1 line
2.40.1
author maintainer
#21 lore raw

PATCH v4 16/22 HID: intel-thc-hid: intel-quickspi: Add PM implementation

In reply to Even Xu

Implement THC QuickSPI driver power management callbacks.

---
 .../intel-quickspi/pci-quickspi.c             | 246 ++++++++++++++++++
 .../intel-quickspi/quickspi-dev.h             |   8 +
 .../intel-quickspi/quickspi-hid.c             |   8 +
 3 files changed, 262 insertions(+)
drivers/hid/intel-thc-hid/intel-quickspi/pci-quickspi.c +246 -0
index cc92e1a30411..4641e818dfa4 100644
@@ -9,6 +9,7 @@
 #include <linux/interrupt.h>
 #include <linux/irqreturn.h>
 #include <linux/pci.h>
+#include <linux/pm_runtime.h>
 
 #include "intel-thc-dev.h"
 #include "intel-thc-hw.h"
@@ -281,6 +282,10 @@ static irqreturn_t quickspi_irq_thread_handler(int irq, void *dev_id)
 	if (qsdev->state == QUICKSPI_DISABLED)
 		return IRQ_HANDLED;
 
+	ret = pm_runtime_resume_and_get(qsdev->dev);
+	if (ret)
+		return IRQ_HANDLED;
+
 	int_mask = thc_interrupt_handler(qsdev->thc_hw);
 
 	if (int_mask & BIT(THC_FATAL_ERR_INT) || int_mask & BIT(THC_TXN_ERR_INT)) {
@@ -318,6 +323,9 @@ static irqreturn_t quickspi_irq_thread_handler(int irq, void *dev_id)
 		if (try_recover(qsdev))
 			qsdev->state = QUICKSPI_DISABLED;
 
+	pm_runtime_mark_last_busy(qsdev->dev);
+	pm_runtime_put_autosuspend(qsdev->dev);
+
 	return IRQ_HANDLED;
 }
 
@@ -645,6 +653,13 @@ static int quickspi_probe(struct pci_dev *pdev,
 
 	qsdev->state = QUICKSPI_ENABLED;
 
+	/* Enable runtime power management */
+	pm_runtime_use_autosuspend(qsdev->dev);
+	pm_runtime_set_autosuspend_delay(qsdev->dev, DEFAULT_AUTO_SUSPEND_DELAY_MS);
+	pm_runtime_mark_last_busy(qsdev->dev);
+	pm_runtime_put_noidle(qsdev->dev);
+	pm_runtime_put_autosuspend(qsdev->dev);
+
 	dev_dbg(&pdev->dev, "QuickSPI probe success\n");
 
 	return 0;
@@ -680,6 +695,8 @@ static void quickspi_remove(struct pci_dev *pdev)
 	quickspi_hid_remove(qsdev);
 	quickspi_dma_deinit(qsdev);
 
+	pm_runtime_get_noresume(qsdev->dev);
+
 	quickspi_dev_deinit(qsdev);
 
 	pcim_iounmap_regions(pdev, BIT(0));
@@ -709,6 +726,234 @@ static void quickspi_shutdown(struct pci_dev *pdev)
 	quickspi_dev_deinit(qsdev);
 }
 
+static int quickspi_suspend(struct device *device)
+{
+	struct pci_dev *pdev = to_pci_dev(device);
+	struct quickspi_device *qsdev;
+	int ret;
+
+	qsdev = pci_get_drvdata(pdev);
+	if (!qsdev)
+		return -ENODEV;
+
+	ret = quickspi_set_power(qsdev, HIDSPI_SLEEP);
+	if (ret)
+		return ret;
+
+	ret = thc_interrupt_quiesce(qsdev->thc_hw, true);
+	if (ret)
+		return ret;
+
+	thc_interrupt_enable(qsdev->thc_hw, false);
+
+	thc_dma_unconfigure(qsdev->thc_hw);
+
+	return 0;
+}
+
+static int quickspi_resume(struct device *device)
+{
+	struct pci_dev *pdev = to_pci_dev(device);
+	struct quickspi_device *qsdev;
+	int ret;
+
+	qsdev = pci_get_drvdata(pdev);
+	if (!qsdev)
+		return -ENODEV;
+
+	ret = thc_port_select(qsdev->thc_hw, THC_PORT_TYPE_SPI);
+	if (ret)
+		return ret;
+
+	thc_interrupt_config(qsdev->thc_hw);
+
+	thc_interrupt_enable(qsdev->thc_hw, true);
+
+	ret = thc_dma_configure(qsdev->thc_hw);
+	if (ret)
+		return ret;
+
+	ret = thc_interrupt_quiesce(qsdev->thc_hw, false);
+	if (ret)
+		return ret;
+
+	ret = quickspi_set_power(qsdev, HIDSPI_ON);
+	if (ret)
+		return ret;
+
+	return 0;
+}
+
+static int quickspi_freeze(struct device *device)
+{
+	struct pci_dev *pdev = to_pci_dev(device);
+	struct quickspi_device *qsdev;
+	int ret;
+
+	qsdev = pci_get_drvdata(pdev);
+	if (!qsdev)
+		return -ENODEV;
+
+	ret = thc_interrupt_quiesce(qsdev->thc_hw, true);
+	if (ret)
+		return ret;
+
+	thc_interrupt_enable(qsdev->thc_hw, false);
+
+	thc_dma_unconfigure(qsdev->thc_hw);
+
+	return 0;
+}
+
+static int quickspi_thaw(struct device *device)
+{
+	struct pci_dev *pdev = to_pci_dev(device);
+	struct quickspi_device *qsdev;
+	int ret;
+
+	qsdev = pci_get_drvdata(pdev);
+	if (!qsdev)
+		return -ENODEV;
+
+	ret = thc_dma_configure(qsdev->thc_hw);
+	if (ret)
+		return ret;
+
+	thc_interrupt_enable(qsdev->thc_hw, true);
+
+	ret = thc_interrupt_quiesce(qsdev->thc_hw, false);
+	if (ret)
+		return ret;
+
+	return 0;
+}
+
+static int quickspi_poweroff(struct device *device)
+{
+	struct pci_dev *pdev = to_pci_dev(device);
+	struct quickspi_device *qsdev;
+	int ret;
+
+	qsdev = pci_get_drvdata(pdev);
+	if (!qsdev)
+		return -ENODEV;
+
+	ret = thc_interrupt_quiesce(qsdev->thc_hw, true);
+	if (ret)
+		return ret;
+
+	thc_interrupt_enable(qsdev->thc_hw, false);
+
+	thc_ltr_unconfig(qsdev->thc_hw);
+
+	quickspi_dma_deinit(qsdev);
+
+	return 0;
+}
+
+static int quickspi_restore(struct device *device)
+{
+	struct pci_dev *pdev = to_pci_dev(device);
+	struct quickspi_device *qsdev;
+	int ret;
+
+	qsdev = pci_get_drvdata(pdev);
+	if (!qsdev)
+		return -ENODEV;
+
+	ret = thc_interrupt_quiesce(qsdev->thc_hw, true);
+	if (ret)
+		return ret;
+
+	/* Reconfig THC HW when back from hibernate */
+	ret = thc_port_select(qsdev->thc_hw, THC_PORT_TYPE_SPI);
+	if (ret)
+		return ret;
+
+	thc_spi_input_output_address_config(qsdev->thc_hw,
+					    qsdev->input_report_hdr_addr,
+					    qsdev->input_report_bdy_addr,
+					    qsdev->output_report_addr);
+
+	ret = thc_spi_read_config(qsdev->thc_hw, qsdev->spi_freq_val,
+				  qsdev->spi_read_io_mode,
+				  qsdev->spi_read_opcode,
+				  qsdev->spi_packet_size);
+	if (ret)
+		return ret;
+
+	ret = thc_spi_write_config(qsdev->thc_hw, qsdev->spi_freq_val,
+				   qsdev->spi_write_io_mode,
+				   qsdev->spi_write_opcode,
+				   qsdev->spi_packet_size,
+				   qsdev->performance_limit);
+	if (ret)
+		return ret;
+
+	thc_interrupt_config(qsdev->thc_hw);
+
+	thc_interrupt_enable(qsdev->thc_hw, true);
+
+	/* TIC may lose power, needs go through reset flow */
+	ret = reset_tic(qsdev);
+	if (ret)
+		return ret;
+
+	ret = thc_dma_configure(qsdev->thc_hw);
+	if (ret)
+		return ret;
+
+	thc_ltr_config(qsdev->thc_hw,
+		       qsdev->active_ltr_val,
+		       qsdev->low_power_ltr_val);
+
+	thc_change_ltr_mode(qsdev->thc_hw, THC_LTR_MODE_ACTIVE);
+
+	return 0;
+}
+
+static int quickspi_runtime_suspend(struct device *device)
+{
+	struct pci_dev *pdev = to_pci_dev(device);
+	struct quickspi_device *qsdev;
+
+	qsdev = pci_get_drvdata(pdev);
+	if (!qsdev)
+		return -ENODEV;
+
+	thc_change_ltr_mode(qsdev->thc_hw, THC_LTR_MODE_LP);
+
+	pci_save_state(pdev);
+
+	return 0;
+}
+
+static int quickspi_runtime_resume(struct device *device)
+{
+	struct pci_dev *pdev = to_pci_dev(device);
+	struct quickspi_device *qsdev;
+
+	qsdev = pci_get_drvdata(pdev);
+	if (!qsdev)
+		return -ENODEV;
+
+	thc_change_ltr_mode(qsdev->thc_hw, THC_LTR_MODE_ACTIVE);
+
+	return 0;
+}
+
+static const struct dev_pm_ops quickspi_pm_ops = {
+	.suspend = quickspi_suspend,
+	.resume = quickspi_resume,
+	.freeze = quickspi_freeze,
+	.thaw = quickspi_thaw,
+	.poweroff = quickspi_poweroff,
+	.restore = quickspi_restore,
+	.runtime_suspend = quickspi_runtime_suspend,
+	.runtime_resume = quickspi_runtime_resume,
+	.runtime_idle = NULL,
+};
+
 static const struct pci_device_id quickspi_pci_tbl[] = {
 	{PCI_DEVICE_DATA(INTEL, THC_MTL_DEVICE_ID_SPI_PORT1, &mtl), },
 	{PCI_DEVICE_DATA(INTEL, THC_MTL_DEVICE_ID_SPI_PORT2, &mtl), },
@@ -728,6 +973,7 @@ static struct pci_driver quickspi_driver = {
 	.probe = quickspi_probe,
 	.remove = quickspi_remove,
 	.shutdown = quickspi_shutdown,
+	.driver.pm = &quickspi_pm_ops,
 	.driver.probe_type = PROBE_PREFER_ASYNCHRONOUS,
 };
 
drivers/hid/intel-thc-hid/intel-quickspi/quickspi-dev.h +8 -0
index c5257378c1e9..75179bb26767 100644
@@ -47,6 +47,14 @@
 #define MAX_PACKET_SIZE_VALUE_MTL			128
 #define MAX_PACKET_SIZE_VALUE_LNL			256
 
+/*
+ * THC uses runtime auto suspend to dynamically switch between THC active LTR
+ * and low power LTR to save CPU power.
+ * Default value is 5000ms, that means if no touch event in this time, THC will
+ * change to low power LTR mode.
+ */
+#define DEFAULT_AUTO_SUSPEND_DELAY_MS			5000
+
 enum quickspi_dev_state {
 	QUICKSPI_NONE,
 	QUICKSPI_RESETING,
drivers/hid/intel-thc-hid/intel-quickspi/quickspi-hid.c +8 -0
index 2553d4b42b51..ad52e402c28a 100644
@@ -3,6 +3,7 @@
 
 #include <linux/hid.h>
 #include <linux/input.h>
+#include <linux/pm_runtime.h>
 
 #include "quickspi-dev.h"
 #include "quickspi-hid.h"
@@ -54,6 +55,10 @@ static int quickspi_hid_raw_request(struct hid_device *hid,
 	struct quickspi_device *qsdev = hid->driver_data;
 	int ret = 0;
 
+	ret = pm_runtime_resume_and_get(qsdev->dev);
+	if (ret)
+		return ret;
+
 	switch (reqtype) {
 	case HID_REQ_GET_REPORT:
 		ret = quickspi_get_report(qsdev, rtype, reportnum, buf);
@@ -66,6 +71,9 @@ static int quickspi_hid_raw_request(struct hid_device *hid,
 		break;
 	}
 
+	pm_runtime_mark_last_busy(qsdev->dev);
+	pm_runtime_put_autosuspend(qsdev->dev);
+
 	return ret;
 }
 
Signature · 1 line
2.40.1
author maintainer
#22 lore raw

PATCH v4 17/22 HID: intel-thc-hid: intel-quicki2c: Add THC QuickI2C driver skeleton

In reply to Even Xu

Create intel-quicki2c folder and add Kconfig and Makefile for THC QuickI2C driver. Add basic device structure, definitions and probe/remove functions for QuickI2C driver.

---
 drivers/hid/intel-thc-hid/Kconfig             |  11 +
 drivers/hid/intel-thc-hid/Makefile            |   3 +
 .../intel-quicki2c/pci-quicki2c.c             | 270 ++++++++++++++++++
 .../intel-quicki2c/quicki2c-dev.h             |  48 ++++
 4 files changed, 332 insertions(+)
 create mode 100644 drivers/hid/intel-thc-hid/intel-quicki2c/pci-quicki2c.c
 create mode 100644 drivers/hid/intel-thc-hid/intel-quicki2c/quicki2c-dev.h
drivers/hid/intel-thc-hid/Kconfig +11 -0
index 25a3729df92a..84c2db881bf4 100644
@@ -28,4 +28,15 @@ config INTEL_QUICKSPI
 
 	  Say Y/M here if you want to support Intel QuickSPI. If unsure, say N.
 
+config INTEL_QUICKI2C
+	tristate "Intel QuickI2C driver based on Intel Touch Host Controller"
+	depends on INTEL_THC_HID
+	help
+	  Intel QuickI2C, uses Touch Host Controller (THC) hardware, implements
+	  HIDI2C (HID over I2C) protocol. It configures THC to work in I2C
+	  mode, and controls THC hardware sequencer to accelerate HIDI2C
+	  transaction flow.
+
+	  Say Y/M here if you want to support Intel QuickI2C. If unsure, say N.
+
 endmenu
drivers/hid/intel-thc-hid/Makefile +3 -0
index 2dba4db70c33..4d4f02e1c415 100644
@@ -14,4 +14,7 @@ intel-quickspi-objs += intel-quickspi/pci-quickspi.o
 intel-quickspi-objs += intel-quickspi/quickspi-hid.o
 intel-quickspi-objs += intel-quickspi/quickspi-protocol.o
 
+obj-$(CONFIG_INTEL_QUICKI2C) += intel-quicki2c.o
+intel-quicki2c-objs += intel-quicki2c/pci-quicki2c.o
+
 ccflags-y += -I $(src)/intel-thc
drivers/hid/intel-thc-hid/intel-quicki2c/pci-quicki2c.c new file +270 -0

270 lines not on this page · raw message

drivers/hid/intel-thc-hid/intel-quicki2c/quicki2c-dev.h new file +48 -0

48 lines not on this page · raw message

Signature · 1 line
2.40.1
author maintainer
#23 lore raw

PATCH v4 18/22 HID: intel-thc-hid: intel-quicki2c: Add THC QuickI2C driver hid layer

In reply to Even Xu

Add HID Low level driver callbacks and hid probe function to register QucikI2C as a HID driver, and external touch device as a HID device.

---
 drivers/hid/intel-thc-hid/Makefile            |   1 +
 .../intel-quicki2c/quicki2c-dev.h             |  11 ++
 .../intel-quicki2c/quicki2c-hid.c             | 142 ++++++++++++++++++
 .../intel-quicki2c/quicki2c-hid.h             |  14 ++
 include/linux/hid-over-i2c.h                  |  44 ++++++
 5 files changed, 212 insertions(+)
 create mode 100644 drivers/hid/intel-thc-hid/intel-quicki2c/quicki2c-hid.c
 create mode 100644 drivers/hid/intel-thc-hid/intel-quicki2c/quicki2c-hid.h
 create mode 100644 include/linux/hid-over-i2c.h
drivers/hid/intel-thc-hid/Makefile +1 -0
index 4d4f02e1c415..91bde6d6aa14 100644
@@ -16,5 +16,6 @@ intel-quickspi-objs += intel-quickspi/quickspi-protocol.o
 
 obj-$(CONFIG_INTEL_QUICKI2C) += intel-quicki2c.o
 intel-quicki2c-objs += intel-quicki2c/pci-quicki2c.o
+intel-quicki2c-objs += intel-quicki2c/quicki2c-hid.o
 
 ccflags-y += -I $(src)/intel-thc
drivers/hid/intel-thc-hid/intel-quicki2c/quicki2c-dev.h +11 -0
index 90c4ffe5ccfa..9e2a863d8135 100644
@@ -4,6 +4,8 @@
 #ifndef _QUICKI2C_DEV_H_
 #define _QUICKI2C_DEV_H_
 
+#include <linux/hid-over-i2c.h>
+
 #define THC_LNL_DEVICE_ID_I2C_PORT1	0xA848
 #define THC_LNL_DEVICE_ID_I2C_PORT2	0xA84A
 #define THC_PTL_H_DEVICE_ID_I2C_PORT1	0xE348
@@ -26,23 +28,32 @@ enum quicki2c_dev_state {
 struct device;
 struct pci_dev;
 struct thc_device;
+struct hid_device;
 
 /**
  * struct quicki2c_device -  THC QuickI2C device struct
  * @dev: point to kernel device
  * @pdev: point to PCI device
  * @thc_hw: point to THC device
+ * @hid_dev: point to hid device
  * @driver_data: point to quicki2c specific driver data
  * @state: THC I2C device state
  * @mem_addr: MMIO memory address
+ * @dev_desc: device descriptor for HIDI2C protocol
+ * @report_descriptor: store a copy of device report descriptor
  */
 struct quicki2c_device {
 	struct device *dev;
 	struct pci_dev *pdev;
 	struct thc_device *thc_hw;
+	struct hid_device *hid_dev;
 	enum quicki2c_dev_state state;
 
 	void __iomem *mem_addr;
+
+	struct hidi2c_dev_descriptor dev_desc;
+
+	u8 *report_descriptor;
 };
 
 #endif /* _QUICKI2C_DEV_H_ */
drivers/hid/intel-thc-hid/intel-quicki2c/quicki2c-hid.c new file +142 -0

142 lines not on this page · raw message

drivers/hid/intel-thc-hid/intel-quicki2c/quicki2c-hid.h new file +14 -0
new file mode 100644
index 000000000000..e80df5f339fe
@@ -0,0 +1,14 @@
+/* SPDX-License-Identifier: GPL-2.0 */
+/* Copyright (c) 2024 Intel Corporation */
+
+#ifndef _QUICKI2C_HID_H_
+#define _QUICKI2C_HID_H_
+
+struct quicki2c_device;
+
+int quicki2c_hid_send_report(struct quicki2c_device *qcdev,
+			     void *data, size_t data_size);
+int quicki2c_hid_probe(struct quicki2c_device *qcdev);
+void quicki2c_hid_remove(struct quicki2c_device *qcdev);
+
+#endif /* _QUICKI2C_HID_H_ */
include/linux/hid-over-i2c.h new file +44 -0

44 lines not on this page · raw message

Signature · 1 line
2.40.1
author maintainer
#24 lore raw

PATCH v4 19/22 HID: intel-thc-hid: intel-quicki2c: Add THC QuickI2C ACPI interfaces

In reply to Even Xu

Add functions to query QuickI2C ACPI DSM/DSD parameters and use these APIs to access all QuickI2C ACPI resources.

---
 .../intel-quicki2c/pci-quicki2c.c             | 190 ++++++++++++++++++
 .../intel-quicki2c/quicki2c-dev.h             | 107 ++++++++++
 2 files changed, 297 insertions(+)
drivers/hid/intel-thc-hid/intel-quicki2c/pci-quicki2c.c +190 -0
index 3919ae3e1400..a8b35d40f3b9 100644
@@ -1,6 +1,7 @@
 /* SPDX-License-Identifier: GPL-2.0 */
 /* Copyright (c) 2024 Intel Corporation */
 
+#include <linux/acpi.h>
 #include <linux/device.h>
 #include <linux/dma-mapping.h>
 #include <linux/err.h>
@@ -9,9 +10,185 @@
 #include <linux/pci.h>
 
 #include "intel-thc-dev.h"
+#include "intel-thc-hw.h"
 
 #include "quicki2c-dev.h"
 
+/* THC QuickI2C ACPI method to get device properties */
+/* HIDI2C device method */
+static guid_t i2c_hid_guid =
+	GUID_INIT(0x3cdff6f7, 0x4267, 0x4555, 0xad, 0x05, 0xb3, 0x0a, 0x3d, 0x89, 0x38, 0xde);
+
+/* platform method */
+static guid_t thc_platform_guid =
+	GUID_INIT(0x84005682, 0x5b71, 0x41a4, 0x8d, 0x66, 0x81, 0x30, 0xf7, 0x87, 0xa1, 0x38);
+
+/**
+ * quicki2c_acpi_get_dsm_property - Query device ACPI DSM parameter
+ *
+ * @adev: point to ACPI device
+ * @guid: ACPI method's guid
+ * @rev: ACPI method's revision
+ * @func: ACPI method's function number
+ * @type: ACPI parameter's data type
+ * @prop_buf: point to return buffer
+ *
+ * This is a helper function for device to query its ACPI DSM parameters.
+ *
+ * Return: 0 if success or ENODEV on failed.
+ */
+static int quicki2c_acpi_get_dsm_property(struct acpi_device *adev, const guid_t *guid,
+					  u64 rev, u64 func, acpi_object_type type, void *prop_buf)
+{
+	acpi_handle handle = acpi_device_handle(adev);
+	union acpi_object *obj;
+
+	obj = acpi_evaluate_dsm_typed(handle, guid, rev, func, NULL, type);
+	if (!obj) {
+		acpi_handle_err(handle,
+				"Error _DSM call failed, rev: %d, func: %d, type: %d\n",
+				(int)rev, (int)func, (int)type);
+		return -ENODEV;
+	}
+
+	if (type == ACPI_TYPE_INTEGER)
+		*(u32 *)prop_buf = (u32)obj->integer.value;
+	else if (type == ACPI_TYPE_BUFFER)
+		memcpy(prop_buf, obj->buffer.pointer, obj->buffer.length);
+
+	ACPI_FREE(obj);
+
+	return 0;
+}
+
+/**
+ * quicki2c_acpi_get_dsd_property - Query device ACPI DSD parameter
+ *
+ * @adev: point to ACPI device
+ * @dsd_method_name: ACPI method's property name
+ * @type: ACPI parameter's data type
+ * @prop_buf: point to return buffer
+ *
+ * This is a helper function for device to query its ACPI DSD parameters.
+ *
+ * Return: 0 if success or ENODEV on failed.
+ */
+static int quicki2c_acpi_get_dsd_property(struct acpi_device *adev, acpi_string dsd_method_name,
+					  acpi_object_type type, void *prop_buf)
+{
+	acpi_handle handle = acpi_device_handle(adev);
+	struct acpi_buffer buffer = { ACPI_ALLOCATE_BUFFER, NULL };
+	union acpi_object obj = { .type = type };
+	struct acpi_object_list arg_list = {
+		.count = 1,
+		.pointer = &obj,
+	};
+	union acpi_object *ret_obj;
+	acpi_status status;
+
+	status = acpi_evaluate_object(handle, dsd_method_name, &arg_list, &buffer);
+	if (ACPI_FAILURE(status)) {
+		acpi_handle_err(handle,
+				"Can't evaluate %s method: %d\n", dsd_method_name, status);
+		return -ENODEV;
+	}
+
+	ret_obj = buffer.pointer;
+
+	memcpy(prop_buf, ret_obj->buffer.pointer, ret_obj->buffer.length);
+
+	return 0;
+}
+
+/**
+ * quicki2c_get_acpi_resources - Query all quicki2c devices' ACPI parameters
+ *
+ * @qcdev: point to quicki2c device
+ *
+ * This function gets all quicki2c devices' ACPI resource.
+ *
+ * Return: 0 if success or error code on failed.
+ */
+static int quicki2c_get_acpi_resources(struct quicki2c_device *qcdev)
+{
+	struct acpi_device *adev = ACPI_COMPANION(qcdev->dev);
+	struct quicki2c_subip_acpi_parameter i2c_param;
+	struct quicki2c_subip_acpi_config i2c_config;
+	int ret = -EINVAL;
+
+	if (!adev) {
+		dev_err(qcdev->dev, "Invalid acpi device pointer\n");
+		return ret;
+	}
+
+	qcdev->acpi_dev = adev;
+
+	ret = quicki2c_acpi_get_dsm_property(adev, &i2c_hid_guid,
+					     QUICKI2C_ACPI_REVISION_NUM,
+					     QUICKI2C_ACPI_FUNC_NUM_HID_DESC_ADDR,
+					     ACPI_TYPE_INTEGER,
+					     &qcdev->hid_desc_addr);
+	if (ret)
+		return ret;
+
+	ret = quicki2c_acpi_get_dsm_property(adev, &thc_platform_guid,
+					     QUICKI2C_ACPI_REVISION_NUM,
+					     QUICKI2C_ACPI_FUNC_NUM_ACTIVE_LTR_VAL,
+					     ACPI_TYPE_INTEGER,
+					     &qcdev->active_ltr_val);
+	if (ret)
+		return ret;
+
+	ret = quicki2c_acpi_get_dsm_property(adev, &thc_platform_guid,
+					     QUICKI2C_ACPI_REVISION_NUM,
+					     QUICKI2C_ACPI_FUNC_NUM_LP_LTR_VAL,
+					     ACPI_TYPE_INTEGER,
+					     &qcdev->low_power_ltr_val);
+	if (ret)
+		return ret;
+
+	ret = quicki2c_acpi_get_dsd_property(adev, QUICKI2C_ACPI_METHOD_NAME_ICRS,
+					     ACPI_TYPE_BUFFER, &i2c_param);
+	if (ret)
+		return ret;
+
+	if (i2c_param.addressing_mode != HIDI2C_ADDRESSING_MODE_7BIT)
+		return -EOPNOTSUPP;
+
+	qcdev->i2c_slave_addr = i2c_param.device_address;
+
+	ret = quicki2c_acpi_get_dsd_property(adev, QUICKI2C_ACPI_METHOD_NAME_ISUB,
+					     ACPI_TYPE_BUFFER, &i2c_config);
+	if (ret)
+		return ret;
+
+	if (i2c_param.connection_speed > 0 &&
+	    i2c_param.connection_speed <= QUICKI2C_SUBIP_STANDARD_MODE_MAX_SPEED) {
+		qcdev->i2c_speed_mode = THC_I2C_STANDARD;
+		qcdev->i2c_clock_hcnt = i2c_config.SMHX;
+		qcdev->i2c_clock_lcnt = i2c_config.SMLX;
+	} else if (i2c_param.connection_speed > QUICKI2C_SUBIP_STANDARD_MODE_MAX_SPEED &&
+		   i2c_param.connection_speed <= QUICKI2C_SUBIP_FAST_MODE_MAX_SPEED) {
+		qcdev->i2c_speed_mode = THC_I2C_FAST_AND_PLUS;
+		qcdev->i2c_clock_hcnt = i2c_config.FMHX;
+		qcdev->i2c_clock_lcnt = i2c_config.FMLX;
+	} else if (i2c_param.connection_speed > QUICKI2C_SUBIP_FAST_MODE_MAX_SPEED &&
+		   i2c_param.connection_speed <= QUICKI2C_SUBIP_FASTPLUS_MODE_MAX_SPEED) {
+		qcdev->i2c_speed_mode = THC_I2C_FAST_AND_PLUS;
+		qcdev->i2c_clock_hcnt = i2c_config.FPHX;
+		qcdev->i2c_clock_lcnt = i2c_config.FPLX;
+	} else if (i2c_param.connection_speed > QUICKI2C_SUBIP_FASTPLUS_MODE_MAX_SPEED &&
+		   i2c_param.connection_speed <= QUICKI2C_SUBIP_HIGH_SPEED_MODE_MAX_SPEED) {
+		qcdev->i2c_speed_mode = THC_I2C_HIGH_SPEED;
+		qcdev->i2c_clock_hcnt = i2c_config.HMHX;
+		qcdev->i2c_clock_lcnt = i2c_config.HMLX;
+	} else {
+		return -EOPNOTSUPP;
+	}
+
+	return 0;
+}
+
 /**
  * quicki2c_irq_quick_handler - The ISR of the quicki2c driver
  *
@@ -92,12 +269,25 @@ static struct quicki2c_device *quicki2c_dev_init(struct pci_dev *pdev, void __io
 		return ERR_PTR(ret);
 	}
 
+	ret = quicki2c_get_acpi_resources(qcdev);
+	if (ret) {
+		dev_err_once(dev, "Get ACPI resources failed, ret = %d\n", ret);
+		return ERR_PTR(ret);
+	}
+
 	ret = thc_port_select(qcdev->thc_hw, THC_PORT_TYPE_I2C);
 	if (ret) {
 		dev_err_once(dev, "Failed to select THC port, ret = %d.\n", ret);
 		return ERR_PTR(ret);
 	}
 
+	ret = thc_i2c_subip_init(qcdev->thc_hw, qcdev->i2c_slave_addr,
+				 qcdev->i2c_speed_mode,
+				 qcdev->i2c_clock_hcnt,
+				 qcdev->i2c_clock_lcnt);
+	if (ret)
+		return ERR_PTR(ret);
+
 	thc_interrupt_config(qcdev->thc_hw);
 
 	thc_interrupt_enable(qcdev->thc_hw, true);
drivers/hid/intel-thc-hid/intel-quicki2c/quicki2c-dev.h +107 -0

144 lines not on this page · raw message

Signature · 1 line
2.40.1
author maintainer
#25 lore raw

PATCH v4 20/22 HID: intel-thc-hid: intel-quicki2c: Add HIDI2C protocol implementation

In reply to Even Xu

Intel QuickI2C driver uses THC hardware to accelerate HID over I2C (HIDI2C) protocol flow.

This patch implements all data flows described in HID over I2C protocol SPEC by using THC hardware layer APIs.

HID over I2C SPEC:
https://learn.microsoft.com/en-us/previous-versions/windows/hardware/design/dn642101(v=vs.85)

---
 drivers/hid/intel-thc-hid/Makefile            |   1 +
 .../intel-quicki2c/quicki2c-dev.h             |   6 +
 .../intel-quicki2c/quicki2c-hid.c             |  18 +-
 .../intel-quicki2c/quicki2c-protocol.c        | 197 ++++++++++++++++++
 .../intel-quicki2c/quicki2c-protocol.h        |  19 ++
 include/linux/hid-over-i2c.h                  |  73 +++++++
 6 files changed, 313 insertions(+), 1 deletion(-)
 create mode 100644 drivers/hid/intel-thc-hid/intel-quicki2c/quicki2c-protocol.c
 create mode 100644 drivers/hid/intel-thc-hid/intel-quicki2c/quicki2c-protocol.h
drivers/hid/intel-thc-hid/Makefile +1 -0
index 91bde6d6aa14..6f762d87af07 100644
@@ -17,5 +17,6 @@ intel-quickspi-objs += intel-quickspi/quickspi-protocol.o
 obj-$(CONFIG_INTEL_QUICKI2C) += intel-quicki2c.o
 intel-quicki2c-objs += intel-quicki2c/pci-quicki2c.o
 intel-quicki2c-objs += intel-quicki2c/quicki2c-hid.o
+intel-quicki2c-objs += intel-quicki2c/quicki2c-protocol.o
 
 ccflags-y += -I $(src)/intel-thc
drivers/hid/intel-thc-hid/intel-quicki2c/quicki2c-dev.h +6 -0
index 60cb736bd5e5..d6ad731120ce 100644
@@ -138,6 +138,9 @@ struct acpi_device;
  * @i2c_clock_hcnt: I2C CLK high period time (unit in cycle count)
  * @i2c_clock_lcnt: I2C CLK low period time (unit in cycle count)
  * @report_descriptor: store a copy of device report descriptor
+ * @input_buf: store a copy of latest input report data
+ * @report_buf: store a copy of latest input/output report packet from set/get feature
+ * @report_len: the length of input/output report packet
  */
 struct quicki2c_device {
 	struct device *dev;
@@ -161,6 +164,9 @@ struct quicki2c_device {
 	u32 i2c_clock_lcnt;
 
 	u8 *report_descriptor;
+	u8 *input_buf;
+	u8 *report_buf;
+	u32 report_len;
 };
 
 #endif /* _QUICKI2C_DEV_H_ */
drivers/hid/intel-thc-hid/intel-quicki2c/quicki2c-hid.c +17 -1
index 4236603f3f76..e8e6f10b7952 100644
@@ -6,6 +6,7 @@
 
 #include "quicki2c-dev.h"
 #include "quicki2c-hid.h"
+#include "quicki2c-protocol.h"
 
 /**
  * quicki2c_hid_parse() - HID core parse() callback
@@ -51,7 +52,22 @@ static int quicki2c_hid_raw_request(struct hid_device *hid,
 				    __u8 *buf, size_t len,
 				    unsigned char rtype, int reqtype)
 {
-	return 0;
+	struct quicki2c_device *qcdev = hid->driver_data;
+	int ret = 0;
+
+	switch (reqtype) {
+	case HID_REQ_GET_REPORT:
+		ret = quicki2c_get_report(qcdev, rtype, reportnum, buf, len);
+		break;
+	case HID_REQ_SET_REPORT:
+		ret = quicki2c_set_report(qcdev, rtype, reportnum, buf, len);
+		break;
+	default:
+		dev_err(qcdev->dev, "Not supported request type %d\n", reqtype);
+		break;
+	}
+
+	return ret;
 }
 
 static int quicki2c_hid_power(struct hid_device *hid, int lvl)
drivers/hid/intel-thc-hid/intel-quicki2c/quicki2c-protocol.c new file +197 -0

197 lines not on this page · raw message

drivers/hid/intel-thc-hid/intel-quicki2c/quicki2c-protocol.h new file +19 -0
new file mode 100644
index 000000000000..3a0d66c7d9ef
@@ -0,0 +1,19 @@
+/* SPDX-License-Identifier: GPL-2.0 */
+/* Copyright (c) 2024 Intel Corporation */
+
+#ifndef _QUICKI2C_PROTOCOL_H_
+#define _QUICKI2C_PROTOCOL_H_
+
+#include <linux/hid-over-i2c.h>
+
+struct quicki2c_device;
+
+int quicki2c_set_power(struct quicki2c_device *qcdev, enum hidi2c_power_state power_state);
+int quicki2c_get_report(struct quicki2c_device *qcdev, u8 report_type,
+			unsigned int reportnum, void *buf, u32 buf_len);
+int quicki2c_set_report(struct quicki2c_device *qcdev, u8 report_type,
+			unsigned int reportnum, void *buf, u32 buf_len);
+int quicki2c_get_device_descriptor(struct quicki2c_device *qcdev);
+int quicki2c_get_report_descriptor(struct quicki2c_device *qcdev);
+
+#endif /* _QUICKI2C_PROTOCOL_H_ */
include/linux/hid-over-i2c.h +73 -0

86 lines not on this page · raw message

Signature · 1 line
2.40.1
author maintainer
#26 lore raw

PATCH v4 21/22 HID: intel-thc-hid: intel-quicki2c: Complete THC QuickI2C driver

In reply to Even Xu

Fully implement QuickI2C driver probe/remove callbacks, interrupt handler, integrate HIDI2C protocol, enumerate HID device and register HID device.

---
 .../intel-quicki2c/pci-quicki2c.c             | 273 ++++++++++++++++++
 .../intel-quicki2c/quicki2c-dev.h             |   6 +
 .../intel-quicki2c/quicki2c-protocol.c        |  27 ++
 .../intel-quicki2c/quicki2c-protocol.h        |   1 +
 4 files changed, 307 insertions(+)
drivers/hid/intel-thc-hid/intel-quicki2c/pci-quicki2c.c +273 -0
index a8b35d40f3b9..d417972ae9b0 100644
@@ -8,11 +8,14 @@
 #include <linux/interrupt.h>
 #include <linux/irqreturn.h>
 #include <linux/pci.h>
+#include <linux/sizes.h>
 
 #include "intel-thc-dev.h"
 #include "intel-thc-hw.h"
 
 #include "quicki2c-dev.h"
+#include "quicki2c-hid.h"
+#include "quicki2c-protocol.h"
 
 /* THC QuickI2C ACPI method to get device properties */
 /* HIDI2C device method */
@@ -210,6 +213,69 @@ static irqreturn_t quicki2c_irq_quick_handler(int irq, void *dev_id)
 	return IRQ_WAKE_THREAD;
 }
 
+/**
+ * try_recover - Try to recovery THC and Device
+ * @qcdev: pointer to quicki2c device
+ *
+ * This function is a error handler, called when fatal error happens.
+ * It try to reset Touch Device and re-configure THC to recovery
+ * transferring between Device and THC.
+ *
+ * Return: 0 if successful or error code on failed
+ */
+static int try_recover(struct quicki2c_device *qcdev)
+{
+	int ret;
+
+	thc_dma_unconfigure(qcdev->thc_hw);
+
+	ret = thc_dma_configure(qcdev->thc_hw);
+	if (ret) {
+		dev_err(qcdev->dev, "Reconfig DMA failed\n");
+		return ret;
+	}
+
+	return 0;
+}
+
+static int handle_input_report(struct quicki2c_device *qcdev)
+{
+	struct hidi2c_report_packet *pkt = (struct hidi2c_report_packet *)qcdev->input_buf;
+	int rx_dma_finished = 0;
+	size_t report_len;
+	int ret;
+
+	while (!rx_dma_finished) {
+		ret = thc_rxdma_read(qcdev->thc_hw, THC_RXDMA2,
+				     (u8 *)pkt, &report_len,
+				     &rx_dma_finished);
+		if (ret)
+			return ret;
+
+		if (!pkt->len) {
+			if (qcdev->state == QUICKI2C_RESETING) {
+				qcdev->reset_ack = true;
+				wake_up(&qcdev->reset_ack_wq);
+
+				qcdev->state = QUICKI2C_RESETED;
+			} else {
+				dev_warn(qcdev->dev, "unexpected DIR happen\n");
+			}
+
+			continue;
+		}
+
+		/* discard samples before driver probe complete */
+		if (qcdev->state != QUICKI2C_ENABLED)
+			continue;
+
+		quicki2c_hid_send_report(qcdev, pkt->data,
+					 HIDI2C_DATA_LEN(le16_to_cpu(pkt->len)));
+	}
+
+	return 0;
+}
+
 /**
  * quicki2c_irq_thread_handler - IRQ thread handler of quicki2c driver
  *
@@ -221,6 +287,7 @@ static irqreturn_t quicki2c_irq_quick_handler(int irq, void *dev_id)
 static irqreturn_t quicki2c_irq_thread_handler(int irq, void *dev_id)
 {
 	struct quicki2c_device *qcdev = dev_id;
+	int err_recover = 0;
 	int int_mask;
 
 	if (qcdev->state == QUICKI2C_DISABLED)
@@ -228,8 +295,25 @@ static irqreturn_t quicki2c_irq_thread_handler(int irq, void *dev_id)
 
 	int_mask = thc_interrupt_handler(qcdev->thc_hw);
 
+	if (int_mask & BIT(THC_FATAL_ERR_INT) || int_mask & BIT(THC_TXN_ERR_INT) ||
+	    int_mask & BIT(THC_UNKNOWN_INT)) {
+		err_recover = 1;
+		goto exit;
+	}
+
+	if (int_mask & BIT(THC_RXDMA2_INT)) {
+		err_recover = handle_input_report(qcdev);
+		if (err_recover)
+			goto exit;
+	}
+
+exit:
 	thc_interrupt_enable(qcdev->thc_hw, true);
 
+	if (err_recover)
+		if (try_recover(qcdev))
+			qcdev->state = QUICKI2C_DISABLED;
+
 	return IRQ_HANDLED;
 }
 
@@ -260,6 +344,9 @@ static struct quicki2c_device *quicki2c_dev_init(struct pci_dev *pdev, void __io
 	qcdev->pdev = pdev;
 	qcdev->dev = dev;
 	qcdev->mem_addr = mem_addr;
+	qcdev->state = QUICKI2C_DISABLED;
+
+	init_waitqueue_head(&qcdev->reset_ack_wq);
 
 	/* thc hw init */
 	qcdev->thc_hw = thc_dev_init(qcdev->dev, qcdev->mem_addr);
@@ -275,6 +362,10 @@ static struct quicki2c_device *quicki2c_dev_init(struct pci_dev *pdev, void __io
 		return ERR_PTR(ret);
 	}
 
+	ret = thc_interrupt_quiesce(qcdev->thc_hw, true);
+	if (ret)
+		return ERR_PTR(ret);
+
 	ret = thc_port_select(qcdev->thc_hw, THC_PORT_TYPE_I2C);
 	if (ret) {
 		dev_err_once(dev, "Failed to select THC port, ret = %d.\n", ret);
@@ -288,10 +379,14 @@ static struct quicki2c_device *quicki2c_dev_init(struct pci_dev *pdev, void __io
 	if (ret)
 		return ERR_PTR(ret);
 
+	thc_int_trigger_type_select(qcdev->thc_hw, false);
+
 	thc_interrupt_config(qcdev->thc_hw);
 
 	thc_interrupt_enable(qcdev->thc_hw, true);
 
+	qcdev->state = QUICKI2C_INITED;
+
 	return qcdev;
 }
 
@@ -305,6 +400,114 @@ static struct quicki2c_device *quicki2c_dev_init(struct pci_dev *pdev, void __io
 static void quicki2c_dev_deinit(struct quicki2c_device *qcdev)
 {
 	thc_interrupt_enable(qcdev->thc_hw, false);
+	thc_ltr_unconfig(qcdev->thc_hw);
+
+	qcdev->state = QUICKI2C_DISABLED;
+}
+
+/**
+ * quicki2c_dma_init - Configure THC DMA for quicki2c device
+ * @qcdev: pointer to the quicki2c device structure
+ *
+ * This function uses TIC's parameters(such as max input length, max output
+ * length) to allocate THC DMA buffers and configure THC DMA engines.
+ *
+ * Return: 0 if success or error code on failed.
+ */
+static int quicki2c_dma_init(struct quicki2c_device *qcdev)
+{
+	size_t swdma_max_len;
+	int ret;
+
+	swdma_max_len = max(le16_to_cpu(qcdev->dev_desc.max_input_len),
+			    le16_to_cpu(qcdev->dev_desc.report_desc_len));
+
+	ret = thc_dma_set_max_packet_sizes(qcdev->thc_hw, 0,
+					   le16_to_cpu(qcdev->dev_desc.max_input_len),
+					   le16_to_cpu(qcdev->dev_desc.max_output_len),
+					   swdma_max_len);
+	if (ret)
+		return ret;
+
+	ret = thc_dma_allocate(qcdev->thc_hw);
+	if (ret) {
+		dev_err(qcdev->dev, "Allocate THC DMA buffer failed, ret = %d\n", ret);
+		return ret;
+	}
+
+	/* Enable RxDMA */
+	ret = thc_dma_configure(qcdev->thc_hw);
+	if (ret) {
+		dev_err(qcdev->dev, "Configure THC DMA failed, ret = %d\n", ret);
+		thc_dma_unconfigure(qcdev->thc_hw);
+		thc_dma_release(qcdev->thc_hw);
+		return ret;
+	}
+
+	return ret;
+}
+
+/**
+ * quicki2c_dma_deinit - Release THC DMA for quicki2c device
+ * @qcdev: pointer to the quicki2c device structure
+ *
+ * Stop THC DMA engines and release all DMA buffers.
+ *
+ */
+static void quicki2c_dma_deinit(struct quicki2c_device *qcdev)
+{
+	thc_dma_unconfigure(qcdev->thc_hw);
+	thc_dma_release(qcdev->thc_hw);
+}
+
+/**
+ * quicki2c_alloc_report_buf - Alloc report buffers
+ * @qcdev: pointer to the quicki2c device structure
+ *
+ * Allocate report descriptor buffer, it will be used for restore TIC HID
+ * report descriptor.
+ *
+ * Allocate input report buffer, it will be used for receive HID input report
+ * data from TIC.
+ *
+ * Allocate output report buffer, it will be used for store HID output report,
+ * such as set feature.
+ *
+ * Return: 0 if success or error code on failed.
+ */
+static int quicki2c_alloc_report_buf(struct quicki2c_device *qcdev)
+{
+	size_t max_report_len;
+
+	qcdev->report_descriptor = devm_kzalloc(qcdev->dev,
+						le16_to_cpu(qcdev->dev_desc.report_desc_len),
+						GFP_KERNEL);
+	if (!qcdev->report_descriptor)
+		return -ENOMEM;
+
+	/*
+	 * Some HIDI2C devices don't declare input/output max length correctly,
+	 * give default 4K buffer to avoid DMA buffer overrun.
+	 */
+	max_report_len = max(le16_to_cpu(qcdev->dev_desc.max_input_len), SZ_4K);
+
+	qcdev->input_buf = devm_kzalloc(qcdev->dev, max_report_len, GFP_KERNEL);
+	if (!qcdev->input_buf)
+		return -ENOMEM;
+
+	if (!le16_to_cpu(qcdev->dev_desc.max_output_len))
+		qcdev->dev_desc.max_output_len = cpu_to_le16(SZ_4K);
+
+	max_report_len = max(le16_to_cpu(qcdev->dev_desc.max_output_len),
+			     max_report_len);
+
+	qcdev->report_buf = devm_kzalloc(qcdev->dev, max_report_len, GFP_KERNEL);
+	if (!qcdev->report_buf)
+		return -ENOMEM;
+
+	qcdev->report_len = max_report_len;
+
+	return 0;
 }
 
 /*
@@ -313,6 +516,18 @@ static void quicki2c_dev_deinit(struct quicki2c_device *qcdev)
  * @pdev: point to pci device
  * @id: point to pci_device_id structure
  *
+ * This function initializes THC and HIDI2C device, the flow is:
+ * - do THC pci device initialization
+ * - query HIDI2C ACPI parameters
+ * - configure THC to HIDI2C mode
+ * - go through HIDI2C enumeration flow
+ *   |- read device descriptor
+ *   |- reset HIDI2C device
+ * - enable THC interrupt and DMA
+ * - read report descriptor
+ * - register HID device
+ * - enable runtime power management
+ *
  * Return 0 if success or error code on failed.
  */
 static int quicki2c_probe(struct pci_dev *pdev,
@@ -376,8 +591,60 @@ static int quicki2c_probe(struct pci_dev *pdev,
 		goto dev_deinit;
 	}
 
+	ret = quicki2c_get_device_descriptor(qcdev);
+	if (ret) {
+		dev_err(&pdev->dev, "Get device descriptor failed, ret = %d\n", ret);
+		goto dev_deinit;
+	}
+
+	ret = quicki2c_alloc_report_buf(qcdev);
+	if (ret) {
+		dev_err(&pdev->dev, "Alloc report buffers failed, ret= %d\n", ret);
+		goto dev_deinit;
+	}
+
+	ret = quicki2c_dma_init(qcdev);
+	if (ret) {
+		dev_err(&pdev->dev, "Setup THC DMA failed, ret= %d\n", ret);
+		goto dev_deinit;
+	}
+
+	ret = thc_interrupt_quiesce(qcdev->thc_hw, false);
+	if (ret)
+		goto dev_deinit;
+
+	ret = quicki2c_set_power(qcdev, HIDI2C_ON);
+	if (ret) {
+		dev_err(&pdev->dev, "Set Power On command failed, ret= %d\n", ret);
+		goto dev_deinit;
+	}
+
+	ret = quicki2c_reset(qcdev);
+	if (ret) {
+		dev_err(&pdev->dev, "Reset HIDI2C device failed, ret= %d\n", ret);
+		goto dev_deinit;
+	}
+
+	ret = quicki2c_get_report_descriptor(qcdev);
+	if (ret) {
+		dev_err(&pdev->dev, "Get report descriptor failed, ret = %d\n", ret);
+		goto dma_deinit;
+	}
+
+	ret = quicki2c_hid_probe(qcdev);
+	if (ret) {
+		dev_err(&pdev->dev, "Failed to register HID device, ret = %d\n", ret);
+		goto dma_deinit;
+	}
+
+	qcdev->state = QUICKI2C_ENABLED;
+
+	dev_dbg(&pdev->dev, "QuickI2C probe success\n");
+
 	return 0;
 
+dma_deinit:
+	quicki2c_dma_deinit(qcdev);
 dev_deinit:
 	quicki2c_dev_deinit(qcdev);
 unmap_io_region:
@@ -404,6 +671,9 @@ static void quicki2c_remove(struct pci_dev *pdev)
 	if (!qcdev)
 		return;
 
+	quicki2c_hid_remove(qcdev);
+	quicki2c_dma_deinit(qcdev);
+
 	quicki2c_dev_deinit(qcdev);
 
 	pcim_iounmap_regions(pdev, BIT(0));
@@ -427,6 +697,9 @@ static void quicki2c_shutdown(struct pci_dev *pdev)
 	if (!qcdev)
 		return;
 
+	/* Must stop DMA before reboot to avoid DMA entering into unknown state */
+	quicki2c_dma_deinit(qcdev);
+
 	quicki2c_dev_deinit(qcdev);
 }
 
drivers/hid/intel-thc-hid/intel-quicki2c/quicki2c-dev.h +6 -0
index d6ad731120ce..0fdac6ba1b04 100644
@@ -5,6 +5,7 @@
 #define _QUICKI2C_DEV_H_
 
 #include <linux/hid-over-i2c.h>
+#include <linux/workqueue.h>
 
 #define THC_LNL_DEVICE_ID_I2C_PORT1	0xA848
 #define THC_LNL_DEVICE_ID_I2C_PORT2	0xA84A
@@ -141,6 +142,8 @@ struct acpi_device;
  * @input_buf: store a copy of latest input report data
  * @report_buf: store a copy of latest input/output report packet from set/get feature
  * @report_len: the length of input/output report packet
+ * @reset_ack_wq: workqueue for waiting reset response from device
+ * @reset_ack: indicate reset response received or not
  */
 struct quicki2c_device {
 	struct device *dev;
@@ -167,6 +170,9 @@ struct quicki2c_device {
 	u8 *input_buf;
 	u8 *report_buf;
 	u32 report_len;
+
+	wait_queue_head_t reset_ack_wq;
+	bool reset_ack;
 };
 
 #endif /* _QUICKI2C_DEV_H_ */
drivers/hid/intel-thc-hid/intel-quicki2c/quicki2c-protocol.c +27 -0
index 0540003c221e..f493df0d5dc4 100644
@@ -195,3 +195,30 @@ int quicki2c_set_report(struct quicki2c_device *qcdev, u8 report_type,
 
 	return buf_len;
 }
+
+#define HIDI2C_RESET_TIMEOUT		5
+
+int quicki2c_reset(struct quicki2c_device *qcdev)
+{
+	int ret;
+
+	qcdev->reset_ack = false;
+	qcdev->state = QUICKI2C_RESETING;
+
+	ret = write_cmd_to_txdma(qcdev, HIDI2C_RESET, HIDI2C_RESERVED, 0, NULL, 0);
+	if (ret) {
+		dev_err_once(qcdev->dev, "Send reset command failed, ret %d\n", ret);
+		return ret;
+	}
+
+	ret = wait_event_interruptible_timeout(qcdev->reset_ack_wq, qcdev->reset_ack,
+					       HIDI2C_RESET_TIMEOUT * HZ);
+	if (ret <= 0 || !qcdev->reset_ack) {
+		dev_err_once(qcdev->dev,
+			     "Wait reset response timed out ret:%d timeout:%ds\n",
+			     ret, HIDI2C_RESET_TIMEOUT);
+		return -ETIMEDOUT;
+	}
+
+	return 0;
+}
drivers/hid/intel-thc-hid/intel-quicki2c/quicki2c-protocol.h +1 -0
index 3a0d66c7d9ef..bf4908cce59c 100644
@@ -15,5 +15,6 @@ int quicki2c_set_report(struct quicki2c_device *qcdev, u8 report_type,
 			unsigned int reportnum, void *buf, u32 buf_len);
 int quicki2c_get_device_descriptor(struct quicki2c_device *qcdev);
 int quicki2c_get_report_descriptor(struct quicki2c_device *qcdev);
+int quicki2c_reset(struct quicki2c_device *qcdev);
 
 #endif /* _QUICKI2C_PROTOCOL_H_ */
Signature · 1 line
2.40.1
author maintainer
#27 lore raw

PATCH v4 22/22 HID: intel-thc-hid: intel-quicki2c: Add PM implementation

In reply to Even Xu

Implement THC QuickI2C driver power management callbacks.

---
 .../intel-quicki2c/pci-quicki2c.c             | 233 ++++++++++++++++++
 .../intel-quicki2c/quicki2c-dev.h             |   8 +
 .../intel-quicki2c/quicki2c-hid.c             |   8 +
 3 files changed, 249 insertions(+)
drivers/hid/intel-thc-hid/intel-quicki2c/pci-quicki2c.c +233 -0
index d417972ae9b0..b56c72124821 100644
@@ -9,6 +9,7 @@
 #include <linux/irqreturn.h>
 #include <linux/pci.h>
 #include <linux/sizes.h>
+#include <linux/pm_runtime.h>
 
 #include "intel-thc-dev.h"
 #include "intel-thc-hw.h"
@@ -289,10 +290,15 @@ static irqreturn_t quicki2c_irq_thread_handler(int irq, void *dev_id)
 	struct quicki2c_device *qcdev = dev_id;
 	int err_recover = 0;
 	int int_mask;
+	int ret;
 
 	if (qcdev->state == QUICKI2C_DISABLED)
 		return IRQ_HANDLED;
 
+	ret = pm_runtime_resume_and_get(qcdev->dev);
+	if (ret)
+		return IRQ_HANDLED;
+
 	int_mask = thc_interrupt_handler(qcdev->thc_hw);
 
 	if (int_mask & BIT(THC_FATAL_ERR_INT) || int_mask & BIT(THC_TXN_ERR_INT) ||
@@ -314,6 +320,9 @@ static irqreturn_t quicki2c_irq_thread_handler(int irq, void *dev_id)
 		if (try_recover(qcdev))
 			qcdev->state = QUICKI2C_DISABLED;
 
+	pm_runtime_mark_last_busy(qcdev->dev);
+	pm_runtime_put_autosuspend(qcdev->dev);
+
 	return IRQ_HANDLED;
 }
 
@@ -639,6 +648,13 @@ static int quicki2c_probe(struct pci_dev *pdev,
 
 	qcdev->state = QUICKI2C_ENABLED;
 
+	/* Enable runtime power management */
+	pm_runtime_use_autosuspend(qcdev->dev);
+	pm_runtime_set_autosuspend_delay(qcdev->dev, DEFAULT_AUTO_SUSPEND_DELAY_MS);
+	pm_runtime_mark_last_busy(qcdev->dev);
+	pm_runtime_put_noidle(qcdev->dev);
+	pm_runtime_put_autosuspend(qcdev->dev);
+
 	dev_dbg(&pdev->dev, "QuickI2C probe success\n");
 
 	return 0;
@@ -674,6 +690,8 @@ static void quicki2c_remove(struct pci_dev *pdev)
 	quicki2c_hid_remove(qcdev);
 	quicki2c_dma_deinit(qcdev);
 
+	pm_runtime_get_noresume(qcdev->dev);
+
 	quicki2c_dev_deinit(qcdev);
 
 	pcim_iounmap_regions(pdev, BIT(0));
@@ -703,6 +721,220 @@ static void quicki2c_shutdown(struct pci_dev *pdev)
 	quicki2c_dev_deinit(qcdev);
 }
 
+static int quicki2c_suspend(struct device *device)
+{
+	struct pci_dev *pdev = to_pci_dev(device);
+	struct quicki2c_device *qcdev;
+	int ret;
+
+	qcdev = pci_get_drvdata(pdev);
+	if (!qcdev)
+		return -ENODEV;
+
+	/*
+	 * As I2C is THC subsystem, no register auto save/restore support,
+	 * need driver to do that explicitly for every D3 case.
+	 */
+	ret = thc_i2c_subip_regs_save(qcdev->thc_hw);
+	if (ret)
+		return ret;
+
+	ret = thc_interrupt_quiesce(qcdev->thc_hw, true);
+	if (ret)
+		return ret;
+
+	thc_interrupt_enable(qcdev->thc_hw, false);
+
+	thc_dma_unconfigure(qcdev->thc_hw);
+
+	return 0;
+}
+
+static int quicki2c_resume(struct device *device)
+{
+	struct pci_dev *pdev = to_pci_dev(device);
+	struct quicki2c_device *qcdev;
+	int ret;
+
+	qcdev = pci_get_drvdata(pdev);
+	if (!qcdev)
+		return -ENODEV;
+
+	ret = thc_port_select(qcdev->thc_hw, THC_PORT_TYPE_I2C);
+	if (ret)
+		return ret;
+
+	ret = thc_i2c_subip_regs_restore(qcdev->thc_hw);
+	if (ret)
+		return ret;
+
+	thc_interrupt_config(qcdev->thc_hw);
+
+	thc_interrupt_enable(qcdev->thc_hw, true);
+
+	ret = thc_dma_configure(qcdev->thc_hw);
+	if (ret)
+		return ret;
+
+	ret = thc_interrupt_quiesce(qcdev->thc_hw, false);
+	if (ret)
+		return ret;
+
+	return 0;
+}
+
+static int quicki2c_freeze(struct device *device)
+{
+	struct pci_dev *pdev = to_pci_dev(device);
+	struct quicki2c_device *qcdev;
+	int ret;
+
+	qcdev = pci_get_drvdata(pdev);
+	if (!qcdev)
+		return -ENODEV;
+
+	ret = thc_interrupt_quiesce(qcdev->thc_hw, true);
+	if (ret)
+		return ret;
+
+	thc_interrupt_enable(qcdev->thc_hw, false);
+
+	thc_dma_unconfigure(qcdev->thc_hw);
+
+	return 0;
+}
+
+static int quicki2c_thaw(struct device *device)
+{
+	struct pci_dev *pdev = to_pci_dev(device);
+	struct quicki2c_device *qcdev;
+	int ret;
+
+	qcdev = pci_get_drvdata(pdev);
+	if (!qcdev)
+		return -ENODEV;
+
+	ret = thc_dma_configure(qcdev->thc_hw);
+	if (ret)
+		return ret;
+
+	thc_interrupt_enable(qcdev->thc_hw, true);
+
+	ret = thc_interrupt_quiesce(qcdev->thc_hw, false);
+	if (ret)
+		return ret;
+
+	return 0;
+}
+
+static int quicki2c_poweroff(struct device *device)
+{
+	struct pci_dev *pdev = to_pci_dev(device);
+	struct quicki2c_device *qcdev;
+	int ret;
+
+	qcdev = pci_get_drvdata(pdev);
+	if (!qcdev)
+		return -ENODEV;
+
+	ret = thc_interrupt_quiesce(qcdev->thc_hw, true);
+	if (ret)
+		return ret;
+
+	thc_interrupt_enable(qcdev->thc_hw, false);
+
+	thc_ltr_unconfig(qcdev->thc_hw);
+
+	quicki2c_dma_deinit(qcdev);
+
+	return 0;
+}
+
+static int quicki2c_restore(struct device *device)
+{
+	struct pci_dev *pdev = to_pci_dev(device);
+	struct quicki2c_device *qcdev;
+	int ret;
+
+	qcdev = pci_get_drvdata(pdev);
+	if (!qcdev)
+		return -ENODEV;
+
+	/* Reconfig THC HW when back from hibernate */
+	ret = thc_port_select(qcdev->thc_hw, THC_PORT_TYPE_I2C);
+	if (ret)
+		return ret;
+
+	ret = thc_i2c_subip_init(qcdev->thc_hw, qcdev->i2c_slave_addr,
+				 qcdev->i2c_speed_mode,
+				 qcdev->i2c_clock_hcnt,
+				 qcdev->i2c_clock_lcnt);
+	if (ret)
+		return ret;
+
+	thc_interrupt_config(qcdev->thc_hw);
+
+	thc_interrupt_enable(qcdev->thc_hw, true);
+
+	ret = thc_interrupt_quiesce(qcdev->thc_hw, false);
+	if (ret)
+		return ret;
+
+	ret = thc_dma_configure(qcdev->thc_hw);
+	if (ret)
+		return ret;
+
+	thc_ltr_config(qcdev->thc_hw,
+		       qcdev->active_ltr_val,
+		       qcdev->low_power_ltr_val);
+
+	thc_change_ltr_mode(qcdev->thc_hw, THC_LTR_MODE_ACTIVE);
+
+	return 0;
+}
+
+static int quicki2c_runtime_suspend(struct device *device)
+{
+	struct pci_dev *pdev = to_pci_dev(device);
+	struct quicki2c_device *qcdev;
+
+	qcdev = pci_get_drvdata(pdev);
+	if (!qcdev)
+		return -ENODEV;
+
+	thc_change_ltr_mode(qcdev->thc_hw, THC_LTR_MODE_LP);
+
+	pci_save_state(pdev);
+
+	return 0;
+}
+
+static int quicki2c_runtime_resume(struct device *device)
+{
+	struct pci_dev *pdev = to_pci_dev(device);
+	struct quicki2c_device *qcdev;
+
+	qcdev = pci_get_drvdata(pdev);
+	if (!qcdev)
+		return -ENODEV;
+
+	thc_change_ltr_mode(qcdev->thc_hw, THC_LTR_MODE_ACTIVE);
+
+	return 0;
+}
+
+static const struct dev_pm_ops quicki2c_pm_ops = {
+	.suspend = quicki2c_suspend,
+	.resume = quicki2c_resume,
+	.freeze = quicki2c_freeze,
+	.thaw = quicki2c_thaw,
+	.poweroff = quicki2c_poweroff,
+	.restore = quicki2c_restore,
+	.runtime_suspend = quicki2c_runtime_suspend,
+	.runtime_resume = quicki2c_runtime_resume,
+	.runtime_idle = NULL,
+};
+
 static const struct pci_device_id quicki2c_pci_tbl[] = {
 	{PCI_VDEVICE(INTEL, THC_LNL_DEVICE_ID_I2C_PORT1), },
 	{PCI_VDEVICE(INTEL, THC_LNL_DEVICE_ID_I2C_PORT2), },
@@ -720,6 +952,7 @@ static struct pci_driver quicki2c_driver = {
 	.probe = quicki2c_probe,
 	.remove = quicki2c_remove,
 	.shutdown = quicki2c_shutdown,
+	.driver.pm = &quicki2c_pm_ops,
 	.driver.probe_type = PROBE_PREFER_ASYNCHRONOUS,
 };
 
drivers/hid/intel-thc-hid/intel-quicki2c/quicki2c-dev.h +8 -0
index 0fdac6ba1b04..6ddb584bd611 100644
@@ -36,6 +36,14 @@
 #define QUICKI2C_DEFAULT_LP_LTR_VALUE		500
 #define QUICKI2C_RPM_TIMEOUT_MS			500
 
+/*
+ * THC uses runtime auto suspend to dynamically switch between THC active LTR
+ * and low power LTR to save CPU power.
+ * Default value is 5000ms, that means if no touch event in this time, THC will
+ * change to low power LTR mode.
+ */
+#define DEFAULT_AUTO_SUSPEND_DELAY_MS			5000
+
 enum quicki2c_dev_state {
 	QUICKI2C_NONE,
 	QUICKI2C_RESETING,
drivers/hid/intel-thc-hid/intel-quicki2c/quicki2c-hid.c +8 -0
index e8e6f10b7952..5c3ec95bb3fd 100644
@@ -3,6 +3,7 @@
 
 #include <linux/hid.h>
 #include <linux/input.h>
+#include <linux/pm_runtime.h>
 
 #include "quicki2c-dev.h"
 #include "quicki2c-hid.h"
@@ -55,6 +56,10 @@ static int quicki2c_hid_raw_request(struct hid_device *hid,
 	struct quicki2c_device *qcdev = hid->driver_data;
 	int ret = 0;
 
+	ret = pm_runtime_resume_and_get(qcdev->dev);
+	if (ret)
+		return ret;
+
 	switch (reqtype) {
 	case HID_REQ_GET_REPORT:
 		ret = quicki2c_get_report(qcdev, rtype, reportnum, buf, len);
@@ -67,6 +72,9 @@ static int quicki2c_hid_raw_request(struct hid_device *hid,
 		break;
 	}
 
+	pm_runtime_mark_last_busy(qcdev->dev);
+	pm_runtime_put_autosuspend(qcdev->dev);
+
 	return ret;
 }
 
Signature · 1 line
2.40.1
maintainer
#28 lore raw
In reply to Even Xu
Quoted 60 lines · Even Xu

Intel Touch Host Controller (THC) is a new high performance input IP which can benefit HID device's data transaction, such as touch screen, touch pad, stylus.

THC IP now evoluates to V4, it can support 3 different modes: IPTS, HIDSPI and HIDI2C. Here are upgrade history:
- THC v1, for TGL/LKF, supports intel private IPTS (Intel Precise Touch and Stylus) protocol ( IPTS mode)
- THC v2, for ADL, adds industrial standard HID over SPI protocol support (HIDSPI mode)
- THC v3, for MTL, enhances HID over SPI mode
- THC v4, for LNL, adds inudstrial standard HID over I2C protocol support (HIDI2C mode)

Linux Surface community (https://github.com/linux-surface) already implemented IPTS mode. These patch series provides THC HIDSPI mode and THC HIDI2C mode support on Linux.

These patch series includes:
1. Document for THC hardware and software introduction.
2. Intel THC Hardware layer driver which provides control interfaces for protocol layer.
3. Intel QuickSPI (R) driver working as a HIDSPI device driver which implements HID over SPI protocol and flow.
4. Intel QuickI2C (R) driver working as a HIDI2C device driver which implements HID over I2C protocol and flow.

Change logs:
v4:
- Minor fix in documents
- Typo fixes in patch 6 & patch 7 commit descriptions

v3:
- Change tables in documents from literal block to table format
- Change symbol namespace to string literal according to patch:
commit cdd30ebb1b9f ("module: Convert symbol namespace to string literal")
- Refine Kconfig description
- Enhance Quickspi and Quicki2c driver by clearing THC hardware internal state before doing initialization to avoid BIOS impacts.
- A fix in Quicki2c driver when does set_report

v2:
- Fix document format issues
- Add THC device IDs for Intel Panther Lake (PTL) platform

Even Xu (13):
HID: THC: Add documentation
HID: intel-thc-hid: intel-thc: Add THC DMA interfaces
HID: intel-thc-hid: intel-thc: Add THC I2C config interfaces
HID: intel-thc-hid: intel-quickspi: Add THC QuickSPI driver hid layer
HID: intel-thc-hid: intel-quickspi: Add THC QuickSPI ACPI interfaces
HID: intel-thc-hid: intel-quickspi: Add HIDSPI protocol implementation
HID: intel-thc-hid: intel-quickspi: Add PM implementation
HID: intel-thc-hid: intel-quicki2c: Add THC QuickI2C driver skeleton
HID: intel-thc-hid: intel-quicki2c: Add THC QuickI2C driver hid layer
HID: intel-thc-hid: intel-quicki2c: Add THC QuickI2C ACPI interfaces
HID: intel-thc-hid: intel-quicki2c: Add HIDI2C protocol implementation
HID: intel-thc-hid: intel-quicki2c: Complete THC QuickI2C driver
HID: intel-thc-hid: intel-quicki2c: Add PM implementation

Quoted 10 lines

Xinpeng Sun (9):
HID: intel-thc-hid: Add basic THC driver skeleton
HID: intel-thc-hid: intel-thc: Add THC registers definition
HID: intel-thc-hid: intel-thc: Add THC PIO operation APIs
HID: intel-thc-hid: intel-thc: Add APIs for interrupt
HID: intel-thc-hid: intel-thc: Add THC LTR interfaces
HID: intel-thc-hid: intel-thc: Add THC interrupt handler
HID: intel-thc-hid: intel-thc: Add THC SPI config interfaces
HID: intel-thc-hid: intel-quickspi: Add THC QuickSPI driver skeleton
HID: intel-thc-hid: intel-quickspi: Complete THC QuickSPI driver

Now queued in hid.git#for-6.14/intel-thc.

Thanks,

Signature · 2 lines
Jiri Kosina
SUSE Labs
author maintainer
#29 lore raw

Thanks Jiri!

Best Regards,
Even Xu

Quoted 91 lines

-----Original Message-----
From: Jiri Kosina <[email protected]>
Sent: Thursday, January 9, 2025 5:15 PM
To: Xu, Even <[email protected]>
Cc: [email protected]; [email protected]; [email protected]; Aaron, Ma <[email protected]>; [email protected]; mpearson- [email protected]; [email protected]; [email protected]; [email protected]
Subject: Re: [PATCH v4 00/22] Add Intel Touch Host Controller drivers

Quoted 61 lines · Even Xu

Intel Touch Host Controller (THC) is a new high performance input IP which can benefit HID device's data transaction, such as touch screen, touch pad, stylus.

THC IP now evoluates to V4, it can support 3 different modes: IPTS, HIDSPI and HIDI2C. Here are upgrade history:
- THC v1, for TGL/LKF, supports intel private IPTS (Intel Precise Touch and Stylus) protocol ( IPTS mode)
- THC v2, for ADL, adds industrial standard HID over SPI protocol support (HIDSPI mode)
- THC v3, for MTL, enhances HID over SPI mode
- THC v4, for LNL, adds inudstrial standard HID over I2C protocol support (HIDI2C mode)

Linux Surface community (https://github.com/linux-surface) already implemented IPTS mode. These patch series provides THC HIDSPI mode and THC HIDI2C mode support on Linux.

These patch series includes:
1. Document for THC hardware and software introduction.
2. Intel THC Hardware layer driver which provides control interfaces for protocol layer.
3. Intel QuickSPI (R) driver working as a HIDSPI device driver which implements HID over SPI protocol and flow.
4. Intel QuickI2C (R) driver working as a HIDI2C device driver which implements HID over I2C protocol and flow.

Change logs:
v4:
- Minor fix in documents
- Typo fixes in patch 6 & patch 7 commit descriptions

v3:
- Change tables in documents from literal block to table format
- Change symbol namespace to string literal according to patch:
commit cdd30ebb1b9f ("module: Convert symbol namespace to string
literal")
- Refine Kconfig description
- Enhance Quickspi and Quicki2c driver by clearing THC hardware internal state before doing initialization to avoid BIOS impacts.
- A fix in Quicki2c driver when does set_report

v2:
- Fix document format issues
- Add THC device IDs for Intel Panther Lake (PTL) platform

Even Xu (13):
HID: THC: Add documentation
HID: intel-thc-hid: intel-thc: Add THC DMA interfaces
HID: intel-thc-hid: intel-thc: Add THC I2C config interfaces
HID: intel-thc-hid: intel-quickspi: Add THC QuickSPI driver hid layer
HID: intel-thc-hid: intel-quickspi: Add THC QuickSPI ACPI interfaces
HID: intel-thc-hid: intel-quickspi: Add HIDSPI protocol implementation
HID: intel-thc-hid: intel-quickspi: Add PM implementation
HID: intel-thc-hid: intel-quicki2c: Add THC QuickI2C driver skeleton
HID: intel-thc-hid: intel-quicki2c: Add THC QuickI2C driver hid layer
HID: intel-thc-hid: intel-quicki2c: Add THC QuickI2C ACPI interfaces
HID: intel-thc-hid: intel-quicki2c: Add HIDI2C protocol implementation
HID: intel-thc-hid: intel-quicki2c: Complete THC QuickI2C driver
HID: intel-thc-hid: intel-quicki2c: Add PM implementation

Quoted 10 lines

Xinpeng Sun (9):
HID: intel-thc-hid: Add basic THC driver skeleton
HID: intel-thc-hid: intel-thc: Add THC registers definition
HID: intel-thc-hid: intel-thc: Add THC PIO operation APIs
HID: intel-thc-hid: intel-thc: Add APIs for interrupt
HID: intel-thc-hid: intel-thc: Add THC LTR interfaces
HID: intel-thc-hid: intel-thc: Add THC interrupt handler
HID: intel-thc-hid: intel-thc: Add THC SPI config interfaces
HID: intel-thc-hid: intel-quickspi: Add THC QuickSPI driver skeleton
HID: intel-thc-hid: intel-quickspi: Complete THC QuickSPI driver

Now queued in hid.git#for-6.14/intel-thc.

Thanks,

--
Jiri Kosina
SUSE Labs

#30 lore raw
In reply to Even Xu

Hello,

Can you also add previous version support for the THC IP? linux-surface guys did a good job, but they are not full-time working on this, and mainlining their downstream driver would take a long time.

Best regards,
Shengyu

Quoted 121 lines · Even Xu

Intel Touch Host Controller (THC) is a new high performance input IP which can benefit HID device's data transaction, such as touch screen, touch pad, stylus.

THC IP now evoluates to V4, it can support 3 different modes: IPTS, HIDSPI and HIDI2C. Here are upgrade history:
- THC v1, for TGL/LKF, supports intel private IPTS (Intel Precise Touch and Stylus) protocol ( IPTS mode)
- THC v2, for ADL, adds industrial standard HID over SPI protocol support (HIDSPI mode)
- THC v3, for MTL, enhances HID over SPI mode
- THC v4, for LNL, adds inudstrial standard HID over I2C protocol support (HIDI2C mode)

Linux Surface community (https://github.com/linux-surface) already implemented IPTS mode. These patch series provides THC HIDSPI mode and THC HIDI2C mode support on Linux.

These patch series includes:
1. Document for THC hardware and software introduction.
2. Intel THC Hardware layer driver which provides control interfaces for protocol layer.
3. Intel QuickSPI (R) driver working as a HIDSPI device driver which implements HID over SPI protocol and flow.
4. Intel QuickI2C (R) driver working as a HIDI2C device driver which implements HID over I2C protocol and flow.

Change logs:
v4:
- Minor fix in documents
- Typo fixes in patch 6 & patch 7 commit descriptions

v3:
- Change tables in documents from literal block to table format
- Change symbol namespace to string literal according to patch:
commit cdd30ebb1b9f ("module: Convert symbol namespace to string literal")
- Refine Kconfig description
- Enhance Quickspi and Quicki2c driver by clearing THC hardware internal state before doing initialization to avoid BIOS impacts.
- A fix in Quicki2c driver when does set_report

v2:
- Fix document format issues
- Add THC device IDs for Intel Panther Lake (PTL) platform

Even Xu (13):
HID: THC: Add documentation
HID: intel-thc-hid: intel-thc: Add THC DMA interfaces
HID: intel-thc-hid: intel-thc: Add THC I2C config interfaces
HID: intel-thc-hid: intel-quickspi: Add THC QuickSPI driver hid layer
HID: intel-thc-hid: intel-quickspi: Add THC QuickSPI ACPI interfaces
HID: intel-thc-hid: intel-quickspi: Add HIDSPI protocol implementation
HID: intel-thc-hid: intel-quickspi: Add PM implementation
HID: intel-thc-hid: intel-quicki2c: Add THC QuickI2C driver skeleton
HID: intel-thc-hid: intel-quicki2c: Add THC QuickI2C driver hid layer
HID: intel-thc-hid: intel-quicki2c: Add THC QuickI2C ACPI interfaces
HID: intel-thc-hid: intel-quicki2c: Add HIDI2C protocol implementation
HID: intel-thc-hid: intel-quicki2c: Complete THC QuickI2C driver
HID: intel-thc-hid: intel-quicki2c: Add PM implementation

Xinpeng Sun (9):
HID: intel-thc-hid: Add basic THC driver skeleton
HID: intel-thc-hid: intel-thc: Add THC registers definition
HID: intel-thc-hid: intel-thc: Add THC PIO operation APIs
HID: intel-thc-hid: intel-thc: Add APIs for interrupt
HID: intel-thc-hid: intel-thc: Add THC LTR interfaces
HID: intel-thc-hid: intel-thc: Add THC interrupt handler
HID: intel-thc-hid: intel-thc: Add THC SPI config interfaces
HID: intel-thc-hid: intel-quickspi: Add THC QuickSPI driver skeleton
HID: intel-thc-hid: intel-quickspi: Complete THC QuickSPI driver

  Documentation/hid/index.rst                   |    1 +
  Documentation/hid/intel-thc-hid.rst           |  568 ++++++
  MAINTAINERS                                   |    6 +
  drivers/hid/Kconfig                           |    2 +
  drivers/hid/Makefile                          |    2 +
  drivers/hid/intel-thc-hid/Kconfig             |   42 +
  drivers/hid/intel-thc-hid/Makefile            |   22 +
  .../intel-quicki2c/pci-quicki2c.c             |  966 ++++++++++
  .../intel-quicki2c/quicki2c-dev.h             |  186 ++
  .../intel-quicki2c/quicki2c-hid.c             |  166 ++
  .../intel-quicki2c/quicki2c-hid.h             |   14 +
  .../intel-quicki2c/quicki2c-protocol.c        |  224 +++
  .../intel-quicki2c/quicki2c-protocol.h        |   20 +
  .../intel-quickspi/pci-quickspi.c             |  987 +++++++++++
  .../intel-quickspi/quickspi-dev.h             |  172 ++
  .../intel-quickspi/quickspi-hid.c             |  165 ++
  .../intel-quickspi/quickspi-hid.h             |   14 +
  .../intel-quickspi/quickspi-protocol.c        |  414 +++++
  .../intel-quickspi/quickspi-protocol.h        |   25 +
  .../intel-thc-hid/intel-thc/intel-thc-dev.c   | 1578 +++++++++++++++++
  .../intel-thc-hid/intel-thc/intel-thc-dev.h   |  116 ++
  .../intel-thc-hid/intel-thc/intel-thc-dma.c   |  969 ++++++++++
  .../intel-thc-hid/intel-thc/intel-thc-dma.h   |  146 ++
  .../intel-thc-hid/intel-thc/intel-thc-hw.h    |  881 +++++++++
  include/linux/hid-over-i2c.h                  |  117 ++
  include/linux/hid-over-spi.h                  |  155 ++
  26 files changed, 7958 insertions(+)

create mode 100644 Documentation/hid/intel-thc-hid.rst
create mode 100644 drivers/hid/intel-thc-hid/Kconfig
create mode 100644 drivers/hid/intel-thc-hid/Makefile
create mode 100644 drivers/hid/intel-thc-hid/intel-quicki2c/pci-quicki2c.c create mode 100644 drivers/hid/intel-thc-hid/intel-quicki2c/quicki2c-dev.h create mode 100644 drivers/hid/intel-thc-hid/intel-quicki2c/quicki2c-hid.c create mode 100644 drivers/hid/intel-thc-hid/intel-quicki2c/quicki2c-hid.h create mode 100644 drivers/hid/intel-thc-hid/intel-quicki2c/quicki2c-protocol.c create mode 100644 drivers/hid/intel-thc-hid/intel-quicki2c/quicki2c-protocol.h create mode 100644 drivers/hid/intel-thc-hid/intel-quickspi/pci-quickspi.c create mode 100644 drivers/hid/intel-thc-hid/intel-quickspi/quickspi-dev.h create mode 100644 drivers/hid/intel-thc-hid/intel-quickspi/quickspi-hid.c create mode 100644 drivers/hid/intel-thc-hid/intel-quickspi/quickspi-hid.h create mode 100644 drivers/hid/intel-thc-hid/intel-quickspi/quickspi-protocol.c create mode 100644 drivers/hid/intel-thc-hid/intel-quickspi/quickspi-protocol.h create mode 100644 drivers/hid/intel-thc-hid/intel-thc/intel-thc-dev.c create mode 100644 drivers/hid/intel-thc-hid/intel-thc/intel-thc-dev.h create mode 100644 drivers/hid/intel-thc-hid/intel-thc/intel-thc-dma.c create mode 100644 drivers/hid/intel-thc-hid/intel-thc/intel-thc-dma.h create mode 100644 drivers/hid/intel-thc-hid/intel-thc/intel-thc-hw.h create mode 100644 include/linux/hid-over-i2c.h
create mode 100644 include/linux/hid-over-spi.h

author maintainer
#31 lore raw

Hi, Shengyu,

Thanks for your feedback!

In fact, we have IPTS mode internal draft driver. It works fine and passes basic validation.
But I was told that IPTS EDS (External-interface Definition Spec) is designed as a private spec, not be published yet. This IPTS EDS is only shared with OEMs under NDA.

So, first, from my perspective, I need to consult the company's legal department and discuss with them how to proceed with this case.

Will come back to you once I get any update on this.

Thanks!

Best Regards,
Even Xu

Quoted 147 lines

-----Original Message-----
From: Shengyu Qu <[email protected]>
Sent: Thursday, April 10, 2025 10:02 AM
To: Xu, Even <[email protected]>; [email protected]; [email protected]; [email protected]; [email protected]; Aaron, Ma <[email protected]>; [email protected]; mpearson- [email protected]
Cc: [email protected]; [email protected]; linux- [email protected]; [email protected]
Subject: Re: [PATCH v4 00/22] Add Intel Touch Host Controller drivers

Hello,

Can you also add previous version support for the THC IP? linux-surface guys did a good job, but they are not full-time working on this, and mainlining their downstream driver would take a long time.

Best regards,
Shengyu

Quoted 99 lines · Even Xu

Intel Touch Host Controller (THC) is a new high performance input IP which can benefit HID device's data transaction, such as touch screen, touch pad, stylus.

THC IP now evoluates to V4, it can support 3 different modes: IPTS, HIDSPI and HIDI2C. Here are upgrade history:
- THC v1, for TGL/LKF, supports intel private IPTS (Intel Precise Touch and Stylus) protocol ( IPTS mode)
- THC v2, for ADL, adds industrial standard HID over SPI protocol support (HIDSPI mode)
- THC v3, for MTL, enhances HID over SPI mode
- THC v4, for LNL, adds inudstrial standard HID over I2C protocol support (HIDI2C mode)

Linux Surface community (https://github.com/linux-surface) already implemented IPTS mode. These patch series provides THC HIDSPI mode and THC HIDI2C mode support on Linux.

These patch series includes:
1. Document for THC hardware and software introduction.
2. Intel THC Hardware layer driver which provides control interfaces for protocol layer.
3. Intel QuickSPI (R) driver working as a HIDSPI device driver which implements HID over SPI protocol and flow.
4. Intel QuickI2C (R) driver working as a HIDI2C device driver which implements HID over I2C protocol and flow.

Change logs:
v4:
- Minor fix in documents
- Typo fixes in patch 6 & patch 7 commit descriptions

v3:
- Change tables in documents from literal block to table format
- Change symbol namespace to string literal according to patch:
commit cdd30ebb1b9f ("module: Convert symbol namespace to string
literal")
- Refine Kconfig description
- Enhance Quickspi and Quicki2c driver by clearing THC hardware internal state before doing initialization to avoid BIOS impacts.
- A fix in Quicki2c driver when does set_report

v2:
- Fix document format issues
- Add THC device IDs for Intel Panther Lake (PTL) platform

Even Xu (13):
HID: THC: Add documentation
HID: intel-thc-hid: intel-thc: Add THC DMA interfaces
HID: intel-thc-hid: intel-thc: Add THC I2C config interfaces
HID: intel-thc-hid: intel-quickspi: Add THC QuickSPI driver hid layer
HID: intel-thc-hid: intel-quickspi: Add THC QuickSPI ACPI interfaces
HID: intel-thc-hid: intel-quickspi: Add HIDSPI protocol implementation
HID: intel-thc-hid: intel-quickspi: Add PM implementation
HID: intel-thc-hid: intel-quicki2c: Add THC QuickI2C driver skeleton
HID: intel-thc-hid: intel-quicki2c: Add THC QuickI2C driver hid layer
HID: intel-thc-hid: intel-quicki2c: Add THC QuickI2C ACPI interfaces
HID: intel-thc-hid: intel-quicki2c: Add HIDI2C protocol implementation
HID: intel-thc-hid: intel-quicki2c: Complete THC QuickI2C driver
HID: intel-thc-hid: intel-quicki2c: Add PM implementation

Xinpeng Sun (9):
HID: intel-thc-hid: Add basic THC driver skeleton
HID: intel-thc-hid: intel-thc: Add THC registers definition
HID: intel-thc-hid: intel-thc: Add THC PIO operation APIs
HID: intel-thc-hid: intel-thc: Add APIs for interrupt
HID: intel-thc-hid: intel-thc: Add THC LTR interfaces
HID: intel-thc-hid: intel-thc: Add THC interrupt handler
HID: intel-thc-hid: intel-thc: Add THC SPI config interfaces
HID: intel-thc-hid: intel-quickspi: Add THC QuickSPI driver skeleton
HID: intel-thc-hid: intel-quickspi: Complete THC QuickSPI driver

  Documentation/hid/index.rst                   |    1 +
  Documentation/hid/intel-thc-hid.rst           |  568 ++++++
  MAINTAINERS                                   |    6 +
  drivers/hid/Kconfig                           |    2 +
  drivers/hid/Makefile                          |    2 +
  drivers/hid/intel-thc-hid/Kconfig             |   42 +
  drivers/hid/intel-thc-hid/Makefile            |   22 +
  .../intel-quicki2c/pci-quicki2c.c             |  966 ++++++++++
  .../intel-quicki2c/quicki2c-dev.h             |  186 ++
  .../intel-quicki2c/quicki2c-hid.c             |  166 ++
  .../intel-quicki2c/quicki2c-hid.h             |   14 +
  .../intel-quicki2c/quicki2c-protocol.c        |  224 +++
  .../intel-quicki2c/quicki2c-protocol.h        |   20 +
  .../intel-quickspi/pci-quickspi.c             |  987 +++++++++++
  .../intel-quickspi/quickspi-dev.h             |  172 ++
  .../intel-quickspi/quickspi-hid.c             |  165 ++
  .../intel-quickspi/quickspi-hid.h             |   14 +
  .../intel-quickspi/quickspi-protocol.c        |  414 +++++
  .../intel-quickspi/quickspi-protocol.h        |   25 +
  .../intel-thc-hid/intel-thc/intel-thc-dev.c   | 1578 +++++++++++++++++
  .../intel-thc-hid/intel-thc/intel-thc-dev.h   |  116 ++
  .../intel-thc-hid/intel-thc/intel-thc-dma.c   |  969 ++++++++++
  .../intel-thc-hid/intel-thc/intel-thc-dma.h   |  146 ++
  .../intel-thc-hid/intel-thc/intel-thc-hw.h    |  881 +++++++++
  include/linux/hid-over-i2c.h                  |  117 ++
  include/linux/hid-over-spi.h                  |  155 ++
  26 files changed, 7958 insertions(+)
Quoted 8 lines

create mode 100644 Documentation/hid/intel-thc-hid.rst
create mode 100644 drivers/hid/intel-thc-hid/Kconfig
create mode 100644 drivers/hid/intel-thc-hid/Makefile
create mode 100644 drivers/hid/intel-thc-hid/intel-quicki2c/pci-quicki2c.c create mode 100644 drivers/hid/intel-thc-hid/intel-quicki2c/quicki2c-dev.h create mode 100644 drivers/hid/intel-thc-hid/intel-quicki2c/quicki2c-hid.c create mode 100644 drivers/hid/intel-thc-hid/intel-quicki2c/quicki2c-hid.h create mode 100644 drivers/hid/intel-thc-hid/intel-quicki2c/quicki2c-

protocol.c

Quoted 1 line

create mode 100644 drivers/hid/intel-thc-hid/intel-quicki2c/quicki2c-

protocol.h

Quoted 5 lines

create mode 100644 drivers/hid/intel-thc-hid/intel-quickspi/pci-quickspi.c create mode 100644 drivers/hid/intel-thc-hid/intel-quickspi/quickspi-dev.h create mode 100644 drivers/hid/intel-thc-hid/intel-quickspi/quickspi-hid.c create mode 100644 drivers/hid/intel-thc-hid/intel-quickspi/quickspi-hid.h create mode 100644 drivers/hid/intel-thc-hid/intel-quickspi/quickspi-

protocol.c

Quoted 1 line

create mode 100644 drivers/hid/intel-thc-hid/intel-quickspi/quickspi-

protocol.h

Quoted 8 lines

create mode 100644 drivers/hid/intel-thc-hid/intel-thc/intel-thc-dev.c create mode 100644 drivers/hid/intel-thc-hid/intel-thc/intel-thc-dev.h create mode 100644 drivers/hid/intel-thc-hid/intel-thc/intel-thc-dma.c create mode 100644 drivers/hid/intel-thc-hid/intel-thc/intel-thc-dma.h create mode 100644 drivers/hid/intel-thc-hid/intel-thc/intel-thc-hw.h create mode 100644 include/linux/hid-over-i2c.h
create mode 100644 include/linux/hid-over-spi.h

#32 lore raw

Hello Xu,

Any updates on this? It's been a month since your last reply.

Best regards,
Shengyu

Quoted 165 lines · Even

Hi, Shengyu,

Thanks for your feedback!

In fact, we have IPTS mode internal draft driver. It works fine and passes basic validation.
But I was told that IPTS EDS (External-interface Definition Spec) is designed as a private spec, not be published yet. This IPTS EDS is only shared with OEMs under NDA.

So, first, from my perspective, I need to consult the company's legal department and discuss with them how to proceed with this case.

Will come back to you once I get any update on this.

Thanks!

Best Regards,
Even Xu

Quoted 147 lines

-----Original Message-----
From: Shengyu Qu <[email protected]>
Sent: Thursday, April 10, 2025 10:02 AM
To: Xu, Even <[email protected]>; [email protected]; [email protected]; [email protected]; [email protected]; Aaron, Ma <[email protected]>; [email protected]; mpearson- [email protected]
Cc: [email protected]; [email protected]; linux- [email protected]; [email protected]
Subject: Re: [PATCH v4 00/22] Add Intel Touch Host Controller drivers

Hello,

Can you also add previous version support for the THC IP? linux-surface guys did a good job, but they are not full-time working on this, and mainlining their downstream driver would take a long time.

Best regards,
Shengyu

Quoted 99 lines · Even Xu

Intel Touch Host Controller (THC) is a new high performance input IP which can benefit HID device's data transaction, such as touch screen, touch pad, stylus.

THC IP now evoluates to V4, it can support 3 different modes: IPTS, HIDSPI and HIDI2C. Here are upgrade history:
- THC v1, for TGL/LKF, supports intel private IPTS (Intel Precise Touch and Stylus) protocol ( IPTS mode)
- THC v2, for ADL, adds industrial standard HID over SPI protocol support (HIDSPI mode)
- THC v3, for MTL, enhances HID over SPI mode
- THC v4, for LNL, adds inudstrial standard HID over I2C protocol support (HIDI2C mode)

Linux Surface community (https://github.com/linux-surface) already implemented IPTS mode. These patch series provides THC HIDSPI mode and THC HIDI2C mode support on Linux.

These patch series includes:
1. Document for THC hardware and software introduction.
2. Intel THC Hardware layer driver which provides control interfaces for protocol layer.
3. Intel QuickSPI (R) driver working as a HIDSPI device driver which implements HID over SPI protocol and flow.
4. Intel QuickI2C (R) driver working as a HIDI2C device driver which implements HID over I2C protocol and flow.

Change logs:
v4:
- Minor fix in documents
- Typo fixes in patch 6 & patch 7 commit descriptions

v3:
- Change tables in documents from literal block to table format
- Change symbol namespace to string literal according to patch:
commit cdd30ebb1b9f ("module: Convert symbol namespace to string
literal")
- Refine Kconfig description
- Enhance Quickspi and Quicki2c driver by clearing THC hardware internal state before doing initialization to avoid BIOS impacts.
- A fix in Quicki2c driver when does set_report

v2:
- Fix document format issues
- Add THC device IDs for Intel Panther Lake (PTL) platform

Even Xu (13):
HID: THC: Add documentation
HID: intel-thc-hid: intel-thc: Add THC DMA interfaces
HID: intel-thc-hid: intel-thc: Add THC I2C config interfaces
HID: intel-thc-hid: intel-quickspi: Add THC QuickSPI driver hid layer
HID: intel-thc-hid: intel-quickspi: Add THC QuickSPI ACPI interfaces
HID: intel-thc-hid: intel-quickspi: Add HIDSPI protocol implementation
HID: intel-thc-hid: intel-quickspi: Add PM implementation
HID: intel-thc-hid: intel-quicki2c: Add THC QuickI2C driver skeleton
HID: intel-thc-hid: intel-quicki2c: Add THC QuickI2C driver hid layer
HID: intel-thc-hid: intel-quicki2c: Add THC QuickI2C ACPI interfaces
HID: intel-thc-hid: intel-quicki2c: Add HIDI2C protocol implementation
HID: intel-thc-hid: intel-quicki2c: Complete THC QuickI2C driver
HID: intel-thc-hid: intel-quicki2c: Add PM implementation

Xinpeng Sun (9):
HID: intel-thc-hid: Add basic THC driver skeleton
HID: intel-thc-hid: intel-thc: Add THC registers definition
HID: intel-thc-hid: intel-thc: Add THC PIO operation APIs
HID: intel-thc-hid: intel-thc: Add APIs for interrupt
HID: intel-thc-hid: intel-thc: Add THC LTR interfaces
HID: intel-thc-hid: intel-thc: Add THC interrupt handler
HID: intel-thc-hid: intel-thc: Add THC SPI config interfaces
HID: intel-thc-hid: intel-quickspi: Add THC QuickSPI driver skeleton
HID: intel-thc-hid: intel-quickspi: Complete THC QuickSPI driver

   Documentation/hid/index.rst                   |    1 +
   Documentation/hid/intel-thc-hid.rst           |  568 ++++++
   MAINTAINERS                                   |    6 +
   drivers/hid/Kconfig                           |    2 +
   drivers/hid/Makefile                          |    2 +
   drivers/hid/intel-thc-hid/Kconfig             |   42 +
   drivers/hid/intel-thc-hid/Makefile            |   22 +
   .../intel-quicki2c/pci-quicki2c.c             |  966 ++++++++++
   .../intel-quicki2c/quicki2c-dev.h             |  186 ++
   .../intel-quicki2c/quicki2c-hid.c             |  166 ++
   .../intel-quicki2c/quicki2c-hid.h             |   14 +
   .../intel-quicki2c/quicki2c-protocol.c        |  224 +++
   .../intel-quicki2c/quicki2c-protocol.h        |   20 +
   .../intel-quickspi/pci-quickspi.c             |  987 +++++++++++
   .../intel-quickspi/quickspi-dev.h             |  172 ++
   .../intel-quickspi/quickspi-hid.c             |  165 ++
   .../intel-quickspi/quickspi-hid.h             |   14 +
   .../intel-quickspi/quickspi-protocol.c        |  414 +++++
   .../intel-quickspi/quickspi-protocol.h        |   25 +
   .../intel-thc-hid/intel-thc/intel-thc-dev.c   | 1578 +++++++++++++++++
   .../intel-thc-hid/intel-thc/intel-thc-dev.h   |  116 ++
   .../intel-thc-hid/intel-thc/intel-thc-dma.c   |  969 ++++++++++
   .../intel-thc-hid/intel-thc/intel-thc-dma.h   |  146 ++
   .../intel-thc-hid/intel-thc/intel-thc-hw.h    |  881 +++++++++
   include/linux/hid-over-i2c.h                  |  117 ++
   include/linux/hid-over-spi.h                  |  155 ++
   26 files changed, 7958 insertions(+)
Quoted 8 lines

create mode 100644 Documentation/hid/intel-thc-hid.rst
create mode 100644 drivers/hid/intel-thc-hid/Kconfig
create mode 100644 drivers/hid/intel-thc-hid/Makefile
create mode 100644 drivers/hid/intel-thc-hid/intel-quicki2c/pci-quicki2c.c create mode 100644 drivers/hid/intel-thc-hid/intel-quicki2c/quicki2c-dev.h create mode 100644 drivers/hid/intel-thc-hid/intel-quicki2c/quicki2c-hid.c create mode 100644 drivers/hid/intel-thc-hid/intel-quicki2c/quicki2c-hid.h create mode 100644 drivers/hid/intel-thc-hid/intel-quicki2c/quicki2c-

protocol.c

Quoted 1 line

create mode 100644 drivers/hid/intel-thc-hid/intel-quicki2c/quicki2c-

protocol.h

Quoted 5 lines

create mode 100644 drivers/hid/intel-thc-hid/intel-quickspi/pci-quickspi.c create mode 100644 drivers/hid/intel-thc-hid/intel-quickspi/quickspi-dev.h create mode 100644 drivers/hid/intel-thc-hid/intel-quickspi/quickspi-hid.c create mode 100644 drivers/hid/intel-thc-hid/intel-quickspi/quickspi-hid.h create mode 100644 drivers/hid/intel-thc-hid/intel-quickspi/quickspi-

protocol.c

Quoted 1 line

create mode 100644 drivers/hid/intel-thc-hid/intel-quickspi/quickspi-

protocol.h

Quoted 8 lines

create mode 100644 drivers/hid/intel-thc-hid/intel-thc/intel-thc-dev.c create mode 100644 drivers/hid/intel-thc-hid/intel-thc/intel-thc-dev.h create mode 100644 drivers/hid/intel-thc-hid/intel-thc/intel-thc-dma.c create mode 100644 drivers/hid/intel-thc-hid/intel-thc/intel-thc-dma.h create mode 100644 drivers/hid/intel-thc-hid/intel-thc/intel-thc-hw.h create mode 100644 include/linux/hid-over-i2c.h
create mode 100644 include/linux/hid-over-spi.h

author maintainer
#33 lore raw

Hi, Shengyu,

Thanks for your email!

Yes, I checked that internally. So far, IPTS is still private, and doesn't have publish plan. So I cannot publish IPTS related drivers.
Sorry.

Best Regards,
Even Xu

Quoted 192 lines

-----Original Message-----
From: Shengyu Qu <[email protected]>
Sent: Monday, May 12, 2025 2:34 PM
To: Xu, Even <[email protected]>; [email protected]; [email protected]; [email protected]; [email protected]; Aaron, Ma <[email protected]>; [email protected]; mpearson- [email protected]
Cc: [email protected]; [email protected]; linux- [email protected]; [email protected]; Yue, Ling <[email protected]>
Subject: Re: [PATCH v4 00/22] Add Intel Touch Host Controller drivers

Hello Xu,

Any updates on this? It's been a month since your last reply.

Best regards,
Shengyu

Quoted 5 lines · Even

Hi, Shengyu,

Thanks for your feedback!

In fact, we have IPTS mode internal draft driver. It works fine and passes basic

validation.

Quoted 1 line

But I was told that IPTS EDS (External-interface Definition Spec) is designed as a

private spec, not be published yet.

Quoted 3 lines

This IPTS EDS is only shared with OEMs under NDA.

So, first, from my perspective, I need to consult the company's legal department

and discuss with them how to proceed with this case.

Quoted 160 lines

Will come back to you once I get any update on this.

Thanks!

Best Regards,
Even Xu

Quoted 151 lines

-----Original Message-----
From: Shengyu Qu <[email protected]>
Sent: Thursday, April 10, 2025 10:02 AM
To: Xu, Even <[email protected]>; [email protected]; [email protected]; [email protected]; [email protected]; Aaron, Ma <[email protected]>; [email protected]; mpearson- [email protected]
Cc: [email protected]; [email protected]; linux- [email protected]; [email protected]
Subject: Re: [PATCH v4 00/22] Add Intel Touch Host Controller drivers

Hello,

Can you also add previous version support for the THC IP? linux-surface guys did a good job, but they are not full-time working on this, and mainlining their downstream driver would take a long time.

Best regards,
Shengyu

Quoted 99 lines · Even Xu

Intel Touch Host Controller (THC) is a new high performance input IP which can benefit HID device's data transaction, such as touch screen, touch pad, stylus.

THC IP now evoluates to V4, it can support 3 different modes: IPTS, HIDSPI and HIDI2C. Here are upgrade history:
- THC v1, for TGL/LKF, supports intel private IPTS (Intel Precise Touch and Stylus) protocol ( IPTS mode)
- THC v2, for ADL, adds industrial standard HID over SPI protocol support (HIDSPI mode)
- THC v3, for MTL, enhances HID over SPI mode
- THC v4, for LNL, adds inudstrial standard HID over I2C protocol support (HIDI2C mode)

Linux Surface community (https://github.com/linux-surface) already implemented IPTS mode. These patch series provides THC HIDSPI mode and THC HIDI2C mode support on Linux.

These patch series includes:
1. Document for THC hardware and software introduction.
2. Intel THC Hardware layer driver which provides control interfaces for protocol layer.
3. Intel QuickSPI (R) driver working as a HIDSPI device driver which implements HID over SPI protocol and flow.
4. Intel QuickI2C (R) driver working as a HIDI2C device driver which implements HID over I2C protocol and flow.

Change logs:
v4:
- Minor fix in documents
- Typo fixes in patch 6 & patch 7 commit descriptions

v3:
- Change tables in documents from literal block to table format
- Change symbol namespace to string literal according to patch:
commit cdd30ebb1b9f ("module: Convert symbol namespace to string
literal")
- Refine Kconfig description
- Enhance Quickspi and Quicki2c driver by clearing THC hardware internal state before doing initialization to avoid BIOS impacts.
- A fix in Quicki2c driver when does set_report

v2:
- Fix document format issues
- Add THC device IDs for Intel Panther Lake (PTL) platform

Even Xu (13):
HID: THC: Add documentation
HID: intel-thc-hid: intel-thc: Add THC DMA interfaces
HID: intel-thc-hid: intel-thc: Add THC I2C config interfaces
HID: intel-thc-hid: intel-quickspi: Add THC QuickSPI driver hid layer
HID: intel-thc-hid: intel-quickspi: Add THC QuickSPI ACPI interfaces
HID: intel-thc-hid: intel-quickspi: Add HIDSPI protocol implementation
HID: intel-thc-hid: intel-quickspi: Add PM implementation
HID: intel-thc-hid: intel-quicki2c: Add THC QuickI2C driver skeleton
HID: intel-thc-hid: intel-quicki2c: Add THC QuickI2C driver hid layer
HID: intel-thc-hid: intel-quicki2c: Add THC QuickI2C ACPI interfaces
HID: intel-thc-hid: intel-quicki2c: Add HIDI2C protocol implementation
HID: intel-thc-hid: intel-quicki2c: Complete THC QuickI2C driver
HID: intel-thc-hid: intel-quicki2c: Add PM implementation

Xinpeng Sun (9):
HID: intel-thc-hid: Add basic THC driver skeleton
HID: intel-thc-hid: intel-thc: Add THC registers definition
HID: intel-thc-hid: intel-thc: Add THC PIO operation APIs
HID: intel-thc-hid: intel-thc: Add APIs for interrupt
HID: intel-thc-hid: intel-thc: Add THC LTR interfaces
HID: intel-thc-hid: intel-thc: Add THC interrupt handler
HID: intel-thc-hid: intel-thc: Add THC SPI config interfaces
HID: intel-thc-hid: intel-quickspi: Add THC QuickSPI driver skeleton
HID: intel-thc-hid: intel-quickspi: Complete THC QuickSPI driver

   Documentation/hid/index.rst                   |    1 +
   Documentation/hid/intel-thc-hid.rst           |  568 ++++++
   MAINTAINERS                                   |    6 +
   drivers/hid/Kconfig                           |    2 +
   drivers/hid/Makefile                          |    2 +
   drivers/hid/intel-thc-hid/Kconfig             |   42 +
   drivers/hid/intel-thc-hid/Makefile            |   22 +
   .../intel-quicki2c/pci-quicki2c.c             |  966 ++++++++++
   .../intel-quicki2c/quicki2c-dev.h             |  186 ++
   .../intel-quicki2c/quicki2c-hid.c             |  166 ++
   .../intel-quicki2c/quicki2c-hid.h             |   14 +
   .../intel-quicki2c/quicki2c-protocol.c        |  224 +++
   .../intel-quicki2c/quicki2c-protocol.h        |   20 +
   .../intel-quickspi/pci-quickspi.c             |  987 +++++++++++
   .../intel-quickspi/quickspi-dev.h             |  172 ++
   .../intel-quickspi/quickspi-hid.c             |  165 ++
   .../intel-quickspi/quickspi-hid.h             |   14 +
   .../intel-quickspi/quickspi-protocol.c        |  414 +++++
   .../intel-quickspi/quickspi-protocol.h        |   25 +
   .../intel-thc-hid/intel-thc/intel-thc-dev.c   | 1578 +++++++++++++++++
   .../intel-thc-hid/intel-thc/intel-thc-dev.h   |  116 ++
   .../intel-thc-hid/intel-thc/intel-thc-dma.c   |  969 ++++++++++
   .../intel-thc-hid/intel-thc/intel-thc-dma.h   |  146 ++
   .../intel-thc-hid/intel-thc/intel-thc-hw.h    |  881 +++++++++
   include/linux/hid-over-i2c.h                  |  117 ++
   include/linux/hid-over-spi.h                  |  155 ++
   26 files changed, 7958 insertions(+)
Quoted 9 lines

create mode 100644 Documentation/hid/intel-thc-hid.rst
create mode 100644 drivers/hid/intel-thc-hid/Kconfig
create mode 100644 drivers/hid/intel-thc-hid/Makefile
create mode 100644 drivers/hid/intel-thc-hid/intel-quicki2c/pci-quicki2c.c create mode 100644 drivers/hid/intel-thc-hid/intel-quicki2c/quicki2c-dev.h create mode 100644 drivers/hid/intel-thc-hid/intel-quicki2c/quicki2c-hid.c create mode 100644 drivers/hid/intel-thc-hid/intel-quicki2c/quicki2c-hid.h create mode 100644
drivers/hid/intel-thc-hid/intel-quicki2c/quicki2c-

protocol.c

Quoted 2 lines
   create mode 100644

drivers/hid/intel-thc-hid/intel-quicki2c/quicki2c-

protocol.h

Quoted 6 lines

create mode 100644 drivers/hid/intel-thc-hid/intel-quickspi/pci-quickspi.c create mode 100644 drivers/hid/intel-thc-hid/intel-quickspi/quickspi-dev.h create mode 100644 drivers/hid/intel-thc-hid/intel-quickspi/quickspi-hid.c create mode 100644 drivers/hid/intel-thc-hid/intel-quickspi/quickspi-hid.h create mode 100644
drivers/hid/intel-thc-hid/intel-quickspi/quickspi-

protocol.c

Quoted 2 lines
   create mode 100644

drivers/hid/intel-thc-hid/intel-quickspi/quickspi-

protocol.h

Quoted 8 lines

create mode 100644 drivers/hid/intel-thc-hid/intel-thc/intel-thc-dev.c create mode 100644 drivers/hid/intel-thc-hid/intel-thc/intel-thc-dev.h create mode 100644 drivers/hid/intel-thc-hid/intel-thc/intel-thc-dma.c create mode 100644 drivers/hid/intel-thc-hid/intel-thc/intel-thc-dma.h create mode 100644 drivers/hid/intel-thc-hid/intel-thc/intel-thc-hw.h create mode 100644 include/linux/hid-over-i2c.h
create mode 100644 include/linux/hid-over-spi.h