From nobody Mon Nov 25 23:37:27 2024 Received: from mgamail.intel.com (mgamail.intel.com [198.175.65.16]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 5C3E41AF0CF; Thu, 24 Oct 2024 08:10:53 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=198.175.65.16 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1729757457; cv=none; b=NmPcEsb5gmIQkhYLjrsXkBFY1inpQ/2ZTeK8IY+IJi7CauDJnxo3EXo6ysb9L4hsvYgeEkYYDgE2s4JGmi13Q2edqezdlLAAKHTF092nSIsixniHglwku6uSxKu/eTYVZPIaxYMzPAr2JFq67Az41Qbm5j9lClb44QYEC9UScjI= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1729757457; c=relaxed/simple; bh=X7fVu6Ub+FyCeC81XEaMO+GD4Ets5hlWMAHu1gscKfs=; h=From:To:Cc:Subject:Date:Message-Id:In-Reply-To:References: MIME-Version:Content-Type; b=BFaxM4MR6MhsebOaTe+/TAGKDBdcPHN9Z4NWULOg1PVpUlyIv96nH8XPU+Y9H8kRoRu0uvqOEsUnYJL614sDA21UdTu/GQ3nkzK8jSqcjT+HtWhU3QDaX092gtO3lers1RbRgupackz25qjgk0B/mhcakMYa4kxEhsm5YM66D/4= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=intel.com; spf=pass smtp.mailfrom=intel.com; dkim=pass (2048-bit key) header.d=intel.com header.i=@intel.com header.b=bDuTf4kn; arc=none smtp.client-ip=198.175.65.16 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=intel.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=intel.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=intel.com header.i=@intel.com header.b="bDuTf4kn" DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1729757454; x=1761293454; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=X7fVu6Ub+FyCeC81XEaMO+GD4Ets5hlWMAHu1gscKfs=; b=bDuTf4kn+RGXAnYNrQABSZYy6XYFd0iAwUdHrioi0NS5xnMlx486P6xZ NIFWpmPhdHGEDoo7PRsMC4sA1gSuTwfsuaWIY7w/S+T6QWNuxCYFBDRXN tSS8F3M1CtLkluSwU71r7qoT3QMSuFPeipZ9YV6aFv4+iko2mT3Dx4U1P sZXylluqDQmwTaXaFPlz0SOWhlTqr3aMtl/BCWAy8KOKqwVvRPWKbi8B3 KCCtl7m/hpB8qtSd82R54iN1K380MiLN+NaDEhQJiVYzrQNICWAo776QR tPU1ZBmKI8cxqNWZROiw2G2p2kPhcWyeZ5W23LcL4S3KTVPCI3JQMGtM7 Q==; X-CSE-ConnectionGUID: 8Uf8TuHSSGCzFCLm2G5Tfg== X-CSE-MsgGUID: UwYJTXbdRca5nYYphNBj8A== X-IronPort-AV: E=McAfee;i="6700,10204,11222"; a="29500971" X-IronPort-AV: E=Sophos;i="6.11,199,1725346800"; d="scan'208";a="29500971" Received: from orviesa006.jf.intel.com ([10.64.159.146]) by orvoesa108.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 24 Oct 2024 01:10:53 -0700 X-CSE-ConnectionGUID: IwbvP1F6QFGdCDK5rlcz/g== X-CSE-MsgGUID: YR5NxSDORIOtaUPhe7OMgA== X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="6.11,228,1725346800"; d="scan'208";a="80690706" Received: from shsensorbuild.sh.intel.com ([10.239.133.18]) by orviesa006.jf.intel.com with ESMTP; 24 Oct 2024 01:10:50 -0700 From: Even Xu To: jikos@kernel.org, bentiss@kernel.org, corbet@lwn.net Cc: linux-input@vger.kernel.or, linux-kernel@vger.kernel.org, linux-doc@vger.kernel.org, Even Xu , Sun Xinpeng , Srinivas Pandruvada Subject: [PATCH v1 01/22] HID: THC: Add documentation Date: Thu, 24 Oct 2024 16:10:02 +0800 Message-Id: <20241024081023.1468951-2-even.xu@intel.com> X-Mailer: git-send-email 2.40.1 In-Reply-To: <20241024081023.1468951-1-even.xu@intel.com> References: <20241024081023.1468951-1-even.xu@intel.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Add Documentation/hid/intel-thc-hid.rst file to provide hardware and software detail for intel THC drivers. Co-developed-by: Sun Xinpeng Signed-off-by: Sun Xinpeng Signed-off-by: Even Xu Reviewed-by: Srinivas Pandruvada --- Documentation/hid/intel-thc-hid.rst | 560 ++++++++++++++++++++++++++++ 1 file changed, 560 insertions(+) create mode 100644 Documentation/hid/intel-thc-hid.rst 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 + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D +Intel Touch Host Controller (THC) +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D + +Touch Host Controller is the name of the IP block in PCH that interface wi= th 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 transactio= ns 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 asynch= ronous 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 i= nterrupt and reset +signals directly. + +1. Overview +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +1.1 THC software/hardware stack +------------------------------- + +Below diagram illustrates the high-level architecture of THC software/hard= ware 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 | | +| +-----------------------------------+ | + ---------------------------------------------- + +Touch IC (TIC), also as known as the Touch devices (touchscreen or touchpa= d). The discrete analog +components that sense and transfer either discrete touch data or heatmap d= ata 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), integra= ted 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 QuickS= PI/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 re= gistered as a HID +low-level driver that manages the THC Controller and implements HIDSPI/HID= I2C 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 re= gisters 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, DM= A configure, +PIO (Programmed I/O, defined in section 3.2) status and control, SPI bus c= onfigure, I2C subIP +status and control, reset status and control... + +THC provides two ways for driver to communicate with external Touch ICs: P= IO and DMA. +PIO can let driver manually write/read data to/from Touch ICs, instead, TH= C DMA can +automatically write/read data without driver involved. + +HW Sequencer includes THC major logic, it gets instruction from MMIO regis= ters to control +SPI bus and I2C bus to finish a bus data transaction, it also can automati= cally handle +Touch ICs interrupt and start DMA receive/send data from/to Touch ICs acco= rding to interrupt +type. That means THC HW Sequencer understands HIDSPI/HIDI2C transfer proto= col, 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 pa= cket. + +As THC supports HIDSPI/HIDI2C protocols, it has SPI controller and I2C sub= IP in it to expose +SPI bus and I2C bus. THC also integrates a GPIO controller to provide inte= rrupt line support +and reset line support. + +2. THC Hardware Interface +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D + +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 an= d I2C bus. + +2.2.1 SPI Port +~~~~~~~~~~~~~~ + +When PORT_TYPE =3D 00b in MMIO registers, THC uses SPI interfaces to commu= nicate with external +Touch IC. THC enhanced SPI Bus supports different SPI modes: standard Sing= le IO mode, +Dual IO mode and Quad IO mode. + +In Single IO mode, THC drives MOSI line to send data to Touch ICs, and rec= eives data from Touch +ICs data from MISO line. In Dual IO mode, THC drivers MOSI and MISO both f= or 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>........... + +For THC receiving data from Touch IC, the data flow on SPI bus: +| ---------THC Sends---------------||-----Touch IC sends--------| +<8Bits OPCode><24Bits Slave Address>........... + +2.2.2 I2C Port +~~~~~~~~~~~~~~ + +THC also integrates I2C controller in it, it's called I2C SubSystem. When = PORT_TYPE =3D 01, THC +is configured to I2C mode. Comparing to SPI mode which can be configured t= hrough 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 oper= ation. + +2.2.3 GPIO interface +~~~~~~~~~~~~~~~~~~~~ + +THC also includes two GPIO pins, one for interrupt and the other for devic= e reset control. + +Interrupt line can be configured to either level triggerred or edge trigge= rred 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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 r= ead/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 d= river 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 n= ext PIO type: +I2C SubIP APB register read, I2C SubIP APB register write, I2C touch IC de= vice 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 acc= ess 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 da= ta registers and kick +off the sequencing cycle. THC uses different PIO opcodes to distinguish di= fferent PIO +operations (PIO read/write/write followed by read). + +If there is a Sequencing Cycle In Progress and an attempt is made to progr= am any of the control, +address, or data register the cycle is blocked and a sequence error will b= e 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 cycl= e done assertion can +interrupt driver with an interrupt. + +Because THC only has 16 FIFO registers for PIO, so all the data transfer t= hrough PIO shouldn't +exceed 64 bytes. + +As DMA needs max packet size for transferring configuration, and the max p= acket 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 co= mmand (PIO write), read +device descriptor (PIO read). + +For how to issue a PIO operation, here is the steps which driver needs fol= low: +-- 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 =3D 1 to start the PIO write sequence. +-- If THC_SS_CD_IE =3D 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). R= xDMA1 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 Rx= DMA 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 le= ngth, according to +above information, THC reads out report body to internal FIFO and start Rx= DMA coping the data +to system memory. After that, THC update interrupt cause register with rep= ort type, and update +RxDMA PRD table read pointer, then trigger a MSI interrupt to notify drive= r 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 inp= ut report address for +input report data. After that, THC update RxDMA PRD table read pointer, th= en 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 existi= ng two RxDMAs, the only +difference is this SW RxDMA is triggerred by software, and RxDMA2 is trigg= erred by external Touch IC +interrupt. It gives a flexiblity to software driver to use RxDMA read Touc= h IC data in any time. + +Before software starts a SW RxDMA, it shall stop the 1st and 2nd RxDMA, cl= ear PRD read/write pointer +and quiesce the device interrupt (THC_DEVINT_QUIESCE_HW_STS =3D 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 b= e sent to touch IC, and +before last command is completely handled, next command cannot be sent, TH= C 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 D= MA. THC will +automatically send the data to touch IC, and trigger a DMA completion inte= rrupt once transferring +is done. + +3.4 PRD +------- + +Physical Region Descriptor (PRD) provides the memory mapping description f= or THC DMAs. + +3.4.1 PRD table and entry +~~~~~~~~~~~~~~~~~~~~~~~~~ + +In order to improve physical DMA memory usage, modern drivers trend to all= ocate a virtually +contiguous, but physically fragmented buffer of memory for each data buffe= r. Linux OS also +provide SGL (scatter gather list) APIs to support this usage. + +THC uses PRD table (physical region descriptor) to support the correspondi= ng 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 bu= ffer 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 fram= es slower than the +Touch IC can send them. + +To simplify the design, SW assumes worst-case memory fragmentation. Theref= ore,each PRD table shall +contain the same number of PRD entries, allowing for a global register (pe= r 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 b= uffers. + +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 PR= D 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 initial= ization. + +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 th= e EOP bit is found set +in a PRD entry. At this point HW increments the PRD read pointer. Thus, th= e read pointer points +to the PRD which the DMA engine is currently processing. This pointer roll= s over once the circular +buffer's depth has been traversed with bit[7] the Rollover bit. E.g. if th= e 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 i= n 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 t= his 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 d= escriptor 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 bi= t set + it means THC will trigger a completion inte= rrupt. + 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 + +And one PRD table can include up to 256 PRD entries, as every entries is 4= K bytes, so every +PRD table can describe 1M bytes memory. + +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 eng= ine 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) +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D + +Intel THC is total compatible with HIDSPI protocol, THC HW sequenser can a= ccelerate 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 al= l 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 approva= l 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 =E2=80=9CInput Report Length=E2=80=9D field of the Input Re= port 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 continue= s 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 =E2=80=9CLast Fragment Flag=E2=80=9D bi= t in the Input Report Header. + If it is clear, the THC Sequencer enters an idle state. +- If the =E2=80=9CLast Fragment Flag=E2=80=9D bit is enabled the THC Seque= ncer 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 (T= HC_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 a= ny 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 f= or output report. +- THC QuickSPI Driver converts request provided data into the output repor= t packet and copies it + to THC's write DMA buffer. +- Start TxDMA to complete the write operation. + +5. HIDI2C support (QuickI2C) +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D + +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 r= ead. +- If the device descriptor is valid, allocate DMA buffers and configure al= l 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 se= nd 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 re= ceived data. +- THC Sequencer continues the Read operation as per the size of data indic= ated 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 th= e THC Sequencer + signals all data has been read or the THC DMA Read Engine reaches the en= d 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-asser= ts 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 a= ny 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 conte= nt to HID core, which + includes Report ID + Report Data Content (remove the length field from t= he 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 co= mmand 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 d= ata register. The first + 2 bytes should indicate the length of the report followed by the report = contents including + Report ID. + +6. THC Debugging +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +- 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 --=20 2.40.1