> -----Original Message----- > From: Bagas Sanjaya <bagasdotme@xxxxxxxxx> > Sent: Thursday, October 24, 2024 9:18 PM > To: Xu, Even <even.xu@xxxxxxxxx>; jikos@xxxxxxxxxx; bentiss@xxxxxxxxxx; > corbet@xxxxxxx > Cc: linux-input@xxxxxxxxxxxxxx; linux-kernel@xxxxxxxxxxxxxxx; linux- > doc@xxxxxxxxxxxxxxx; Sun, Xinpeng <xinpeng.sun@xxxxxxxxx>; Srinivas > Pandruvada <srinivas.pandruvada@xxxxxxxxxxxxxxx> > Subject: Re: [PATCH v1 01/22] HID: THC: Add documentation > > On Thu, Oct 24, 2024 at 04:10:02PM +0800, Even Xu wrote: > > Add Documentation/hid/intel-thc-hid.rst file to provide hardware and > > software detail for intel THC drivers. > > > > Co-developed-by: Sun Xinpeng <xinpeng.sun@xxxxxxxxx> > > Signed-off-by: Sun Xinpeng <xinpeng.sun@xxxxxxxxx> > > Signed-off-by: Even Xu <even.xu@xxxxxxxxx> > > Reviewed-by: Srinivas Pandruvada <srinivas.pandruvada@xxxxxxxxxxxxxxx> > > --- > > Documentation/hid/intel-thc-hid.rst | 560 > > ++++++++++++++++++++++++++++ > > 1 file changed, 560 insertions(+) > > create mode 100644 Documentation/hid/intel-thc-hid.rst > > > > Don't forget to add toctree entry: Sure, will add, thanks! > > ---- >8 ---- > diff --git a/Documentation/hid/index.rst b/Documentation/hid/index.rst index > af02cf7cfa8207..baf156b44b58a7 100644 > --- a/Documentation/hid/index.rst > +++ b/Documentation/hid/index.rst > @@ -18,4 +18,5 @@ Human Interface Devices (HID) > > hid-alps > intel-ish-hid > + intel-thc-hid > amd-sfh-hid > > > diff --git a/Documentation/hid/intel-thc-hid.rst > > b/Documentation/hid/intel-thc-hid.rst > > new file mode 100644 > > index 000000000000..9f1781af99cf > > --- /dev/null > > +++ b/Documentation/hid/intel-thc-hid.rst > > @@ -0,0 +1,560 @@ > > +.. 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: > > +- 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. > > + > > +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). > > + > > +Unlike other common SPI/I2C controllers, THC handles the HID device > > +data interrupt and reset 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 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 | | > > +| +-----------------------------------+ | > > + ---------------------------------------------- > > Sphinx errors out on htmldocs build: > > Documentation/hid/intel-thc-hid.rst:33: CRITICAL: Unexpected section title or > transition. > > ---------------------------------------------- > > reST markup error: > Documentation/hid/intel-thc-hid.rst:33: (SEVERE/4) Unexpected section title or > transition. > > ---------------------------------------------- > > I have to wrap the diagrams and fix up tables: Will fix it in next version, thanks! > > ---- >8 ---- > diff --git a/Documentation/hid/intel-thc-hid.rst b/Documentation/hid/intel-thc- > hid.rst > index 9f1781af99cf81..6c9d791c5312f1 100644 > --- a/Documentation/hid/intel-thc-hid.rst > +++ b/Documentation/hid/intel-thc-hid.rst > @@ -30,37 +30,39 @@ signals directly. > Below diagram illustrates the high-level architecture of THC software/hardware > stack, which is fully 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 | | > -| +-----------------------------------+ | > - ---------------------------------------------- > +:: > + > + ---------------------------------------------- > + | +-----------------------------------+ | > + | | 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 @@ -78,7 +80,7 @@ low-level driver > that manages the THC Controller and implements HIDSPI/HIDI2C pr > > 1.2 THC hardware diagram > ------------------------ > -Below diagram shows THC hardware components: > +Below diagram shows THC hardware components:: > > --------------------------------- > | THC Controller | > @@ -156,13 +158,15 @@ setting different opcode. > Beside IO mode, driver also needs to configure SPI bus speed. THC supports up to > 42MHz SPI clock 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 sending data to Touch IC, the data flow on SPI bus:: > > -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>........... > + | --------------------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 > ~~~~~~~~~~~~~~ > @@ -194,23 +198,22 @@ read or PIO write. > > When THC is configured to SPI mode, opcodes are used for determining the > read/write IO mode. > There are some OPCode examples for SPI IO mode: > - ------------------------------------------ > -| example of SPI PIO opcode | > - ------------------------------------------ > + > ++--------+---------------------------------+ > | 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 @@ -223,22 +226,20 @@ I2C touch IC device write, I2C touch IC > device write followed by read. > > Here are the THC pre-defined opcodes for I2C mode: > > - --------------------------------------------------------------- > -| THC I2C PIO OPCode | > - --------------------------------------------------------------- > ++--------+-------------------------------------------+----------+ > | 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 | N/A | > | | I2C bus | | > - --------------------------------------------------------------- > ++--------+-------------------------------------------+----------+ > > 3.2 PIO > ------- > @@ -346,15 +347,17 @@ provide SGL (scatter gather list) APIs to support this > usage. > THC uses PRD table (physical region descriptor) to support the corresponding OS > kernel 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 | > - -------------- > +:: > + > + ------------------------ -------------- -------------- > + | 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 > > > + > > +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 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 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 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. > > + > > + > > +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 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 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 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. > > + > > +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 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 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. > > + > > +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, 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 setting different > opcode. > > + > > +Beside IO mode, driver also needs to configure SPI bus speed. THC > > +supports up to 42MHz SPI clock 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. > > + > > +2.2.3 GPIO interface > > +~~~~~~~~~~~~~~~~~~~~ > > + > > +THC also includes two GPIO pins, one for interrupt and the other for device > reset control. > > + > > +Interrupt line can be configured to either level triggerred or edge > > +triggerred by setting MMIO Control register. > > + > > +Reset line is controlled by BIOS (or EFI) through ACPI _RST method, > > +driver needs to call this 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 read or PIO write. > > + > > +When THC is configured to SPI mode, opcodes are used for determining the > read/write IO mode. > > +There are some OPCode examples for SPI IO mode: > > + ------------------------------------------ > > +| example of SPI PIO opcode | > > + ------------------------------------------ > > +| 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 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. > > + > > +Here are the THC pre-defined opcodes for I2C mode: > > + > > + --------------------------------------------------------------- > > +| THC I2C PIO OPCode | > > + --------------------------------------------------------------- > > +| 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 | N/A | > > +| | I2C bus | | > > + --------------------------------------------------------------- > > + > > +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 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. > > + > > +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 interrupt > driver with an interrupt. > > + > > +Because THC only has 16 FIFO registers for PIO, so all the data > > +transfer through PIO shouldn't 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 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. > > + > > +3.3 DMA > > +------- > > + > > +THC has 4 DMA channels: Read DMA1, Read DMA2, Write DMA and Software > DMA. > > + > > +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 for HID input > report data retrieval. > > + > > +RxDMA's typical use case is auto receiving the data from Touch IC. > > +Once RxDMA is enabled by 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 data > receiving. > > + > > +For I2C mode, THC RxDMA's behavior is little difference, 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 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. > > + > > +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. > > + > > +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 > 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 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 is > done. > > + > > +3.4 PRD > > +------- > > + > > +Physical Region Descriptor (PRD) provides the memory mapping description for > THC DMAs. > > + > > +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 provide SGL (scatter gather list) > APIs to support this usage. > > + > > +THC uses PRD table (physical region descriptor) to support the > > +corresponding OS kernel 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 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 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. > > + > > +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 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. > > + > > +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 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 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 .. > > + > > +3.4.3 PRD descriptor structure > > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ > > + > > +Intel THC uses PRD entry descriptor for every PRD entry. Every PRD > > +entry descriptor occupies > > +128 bits memories:: > > + > > + dest_addr Bits 53..0 : destination memory address, as every entry is 4KB, > > + ignore lowest 10 bits of address. > > + reserved1 Bits 54..62 : reserved > > + int_on_completion Bit 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 Bits 87..64 : how many bytes of data in this entry. > > + end_of_prd Bit 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. > > + hw_status Bits 90..89 : HW status bits > > + reserved2 Bits 127..91 : reserved > > + > > How about listing the struct fields as a grid table below? Good suggestion! Will use it, Thanks! > > ---- >8 ---- > diff --git a/Documentation/hid/intel-thc-hid.rst b/Documentation/hid/intel-thc- > hid.rst > index 0e034e84b62310..280303d6c09de1 100644 > --- a/Documentation/hid/intel-thc-hid.rst > +++ b/Documentation/hid/intel-thc-hid.rst > @@ -403,20 +403,30 @@ required to honor this behavior): 00h 01h 02h 03h 04h > 80h 81h 82h 83h 84h 00h 01 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ > > Intel THC uses PRD entry descriptor for every PRD entry. Every PRD entry > descriptor occupies > -128 bits memories:: > +128 bits memories: > > - dest_addr Bits 53..0 : destination memory address, as every entry is 4KB, > - ignore lowest 10 bits of address. > - reserved1 Bits 54..62 : reserved > - int_on_completion Bit 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 Bits 87..64 : how many bytes of data in this entry. > - end_of_prd Bit 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. > - hw_status Bits 90..89 : HW status bits > - reserved2 Bits 127..91 : reserved > ++-------------------+---------+------------------------------------------------+ > +| struct field | bit(s) | description | > ++===================+=========+================================= > ======= > ++========+ > +| dest_addr | 53..0 | destination memory address, as every entry | > +| | | is 4KB, ignore lowest 10 bits of address. | > ++-------------------+---------+------------------------------------------------+ > +| 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. | > ++-------------------+---------+------------------------------------------------+ > +| hw_status | 90..89 | HW status bits | > ++-------------------+---------+------------------------------------------------+ > +| reserved2 | 127..91 | reserved | > ++-------------------+---------+------------------------------------------------+ > > And one PRD table can include up to 256 PRD entries, as every entries is 4K > bytes, so every PRD table can describe 1M bytes memory. > > > +And one PRD table can include up to 256 PRD entries, as every entries > > +is 4K bytes, so every PRD table can describe 1M bytes memory. > > + > > +struct thc_prd_table { > > + struct thc_prd_entry entries[PRD_ENTRIES_NUM]; }; > > Wrap the struct definition above in syntax-highlighted code block: > > ---- >8 ---- > diff --git a/Documentation/hid/intel-thc-hid.rst b/Documentation/hid/intel-thc- > hid.rst > index 6c9d791c5312f1..bcd711dc015426 100644 > --- a/Documentation/hid/intel-thc-hid.rst > +++ b/Documentation/hid/intel-thc-hid.rst > @@ -420,9 +420,11 @@ Intel THC uses PRD entry descriptor for every PRD entry. > Every PRD entry descrip And one PRD table can include up to 256 PRD entries, as > every entries is 4K bytes, so every PRD table can describe 1M bytes memory. > > -struct thc_prd_table { > - struct thc_prd_entry entries[PRD_ENTRIES_NUM]; > -}; > +.. code-block:: c > + > + struct thc_prd_table { > + struct thc_prd_entry entries[PRD_ENTRIES_NUM]; > + }; Will use it, thank you! > > 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 > > > + > > +In general, every PRD table means one HID touch data packet. Every > > +DMA engine can support up to 128 PRD tables (except write DMA, write > > +DMA only has one PRD table). SW driver is responsible to get max > > +packet length from touch IC, and use this max packet length to create PRD > entries for each PRD table. > > + > > +4. HIDSPI support (QuickSPI) > > +============================ > > + > > +Intel THC is total compatible with HIDSPI protocol, THC HW sequenser > > +can accelerate HIDSPI protocol transferring. > > + > > +4.1 Reset Flow > > +-------------- > > + > > +- Call ACPI _RST method to reset Touch IC device. > > +- Read the reset response from TIC through PIO read. > > +- Issue a command to retrieve device descriptor from Touch IC through PIO > write. > > +- Read the device descriptor from Touch IC through PIO read. > > +- If the device descriptor is valid, allocate DMA buffers and configure all DMA > channels. > > + > > +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. > > The flow and PIO sequence lists renders inconsistently, so I have to fix it > up: Will fix in next version, thanks! > > ---- >8 ---- > diff --git a/Documentation/hid/intel-thc-hid.rst b/Documentation/hid/intel-thc- > hid.rst > index bcd711dc015426..0e034e84b62310 100644 > --- a/Documentation/hid/intel-thc-hid.rst > +++ b/Documentation/hid/intel-thc-hid.rst > @@ -267,13 +267,14 @@ RESET response (PIO read or PIO write followed by > read), write Power ON command 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. > + > +- 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. > > 3.3 DMA > ------- > @@ -450,6 +451,7 @@ protocol transferring. > -------------------------- > > 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. > @@ -464,12 +466,14 @@ Basic Flow: > - If the “Last Fragment Flag” bit is enabled the THC Sequencer enters End-of- > Frame Processing. > > THC Sequencer End of Frame Processing: > + > - THC DMA engine increments the read pointer of the Read PRD CB, sets EOF > interrupt status > in RxDMA2 register (THC_M_PRT_READ_DMA_INT_STS_2). > - If THC EOF interrupt is enabled by the driver in the control register > (THC_M_PRT_READ_DMA_CNTRL_2), > generates interrupt to software. > > Sequence of steps to read data from RX DMA buffer: > + > - THC QuickSPI driver checks CB write Ptr and CB read Ptr to identify if any data > frame in DMA > circular buffers. > - THC QuickSPI driver gets first unprocessed PRD table. > @@ -483,6 +487,7 @@ Sequence of steps to read data from RX DMA buffer: > --------------------------- > > Generic Output Report Flow: > + > - HID core calls hid_request or hid_output_report callback with a request to THC > QuickSPI driver. > hid_request is used for set/get feature report, and hid_output_request for > output report. > - THC QuickSPI Driver converts request provided data into the output report > packet and copies it @@ -508,6 +513,7 @@ Generic Output Report 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. > @@ -524,12 +530,14 @@ Basic Flow: > 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 > (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. > @@ -544,6 +552,7 @@ Sequence of steps to read data from RX DMA buffer: > --------------------------- > > Generic Output Report Flow: > + > - HID core call THC QuickI2C thc_hidi2c_hid_output_report 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. > Will fix in next version. > > + > > +THC Sequencer End of Frame Processing: > > +- THC DMA engine increments the read pointer of the Read PRD CB, sets > > +EOF interrupt status > > + in RxDMA2 register (THC_M_PRT_READ_DMA_INT_STS_2). > > +- If THC EOF interrupt is enabled by the driver in the control > > +register (THC_M_PRT_READ_DMA_CNTRL_2), > > + generates interrupt to software. > > + > > +Sequence of steps to read data from RX DMA buffer: > > +- THC QuickSPI driver checks CB write Ptr and CB read Ptr to identify > > +if any data frame in DMA > > + circular buffers. > > +- THC QuickSPI driver gets first unprocessed PRD table. > > +- THC QuickSPI driver scans all PRD entries in this PRD table to calculate the > total frame size. > > +- THC QuickSPI driver copies all frame data out. > > +- THC QuickSPI driver checks the data type according to input report > > +body, and calls related > > + callbacks to process the data. > > +- THC QuickSPI driver updates write Ptr. > > + > > +4.3 Output Report Data Flow > > +--------------------------- > > + > > +Generic Output Report Flow: > > +- HID core calls hid_request or hid_output_report callback with a request to > THC QuickSPI driver. > > + hid_request is used for set/get feature report, and hid_output_request for > output report. > > +- 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. > > + > > +5. HIDI2C support (QuickI2C) > > +============================ > > + > > +5.1 Reset Flow > > +-------------- > > + > > +- Call ACPI _RST method to reset Touch IC device (HW reset). > > +- Read the reset response from Touch IC through PIO read. > > +- Read the device descriptor from Touch IC 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 (SW reset). > > + > > +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. > > + > > +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. > > + > > +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. > > + > > +5.3 Output Report Data Flow > > +--------------------------- > > + > > +Generic Output Report Flow: > > +- HID core call THC QuickI2C thc_hidi2c_hid_output_report 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. > > + > > +6. THC Debugging > > +================ > > + > > +To debug THC, event tracing mechanism is used. To enable debug logs:: > > + > > + 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 > > Thanks. Thanks Bagas for your review and useful suggestions. Will fix all of them in next version, and run "make htmldocs" for verification. Best Regards, Even Xu > > -- > An old man doll... just what I always wanted! - Clara