#sphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget%/translations/zh_CN/hid/intel-thc-hidmodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget%/translations/zh_TW/hid/intel-thc-hidmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget%/translations/it_IT/hid/intel-thc-hidmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget%/translations/ja_JP/hid/intel-thc-hidmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget%/translations/ko_KR/hid/intel-thc-hidmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hPortuguese (Brazilian)}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget%/translations/pt_BR/hid/intel-thc-hidmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget%/translations/sp_SP/hid/intel-thc-hidmodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhcomment)}(h SPDX-License-Identifier: GPL-2.0h]h SPDX-License-Identifier: GPL-2.0}hhsbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1hhhhhh?/var/lib/git/docbuild/linux/Documentation/hid/intel-thc-hid.rsthKubhsection)}(hhh](htitle)}(h!Intel Touch Host Controller (THC)h]h!Intel Touch Host Controller (THC)}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh paragraph)}(hTouch 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:h]hTouch 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:}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh bullet_list)}(hhh](h list_item)}(h2A natively half-duplex Quad I/O capable SPI masterh]h)}(hhh]h2A natively half-duplex Quad I/O capable SPI master}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK hhubah}(h]h ]h"]h$]h&]uh1hhhhhhhhNubh)}(h=Low latency I2C interface to support HIDI2C compliant devicesh]h)}(hj h]h=Low latency I2C interface to support HIDI2C compliant devices}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK hj ubah}(h]h ]h"]h$]h&]uh1hhhhhhhhNubh)}(h7A HW sequencer with RW DMA capability to system memory h]h)}(h6A HW sequencer with RW DMA capability to system memoryh]h6A HW sequencer with RW DMA capability to system memory}(hj&hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK hj"ubah}(h]h ]h"]h$]h&]uh1hhhhhhhhNubeh}(h]h ]h"]h$]h&]bullet-uh1hhhhK hhhhubh)}(hX#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.h]hX#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.}(hjBhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hXHardware 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).h]hXHardware 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).}(hjPhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hnUnlike other common SPI/I2C controllers, THC handles the HID device data interrupt and reset signals directly.h]hnUnlike other common SPI/I2C controllers, THC handles the HID device data interrupt and reset signals directly.}(hj^hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hhh](h)}(h 1. Overviewh]h 1. Overview}(hjohhhNhNubah}(h]h ]h"]h$]h&]uh1hhjlhhhhhKubh)}(hhh](h)}(h1.1 THC software/hardware stackh]h1.1 THC software/hardware stack}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj}hhhhhKubh)}(hBelow diagram illustrates the high-level architecture of THC software/hardware stack, which is fully capable of supporting HIDSPI/HIDI2C protocol in Linux OS.h]hBelow diagram illustrates the high-level architecture of THC software/hardware stack, which is fully capable of supporting HIDSPI/HIDI2C protocol in Linux OS.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj}hhubh literal_block)}(hX ---------------------------------------------- | +-----------------------------------+ | | | 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 | | | +-----------------------------------+ | ----------------------------------------------h]hX ---------------------------------------------- | +-----------------------------------+ | | | 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 | | | +-----------------------------------+ | ----------------------------------------------}hjsbah}(h]h ]h"]h$]h&]hhuh1jhhhK$hj}hhubh)}(hXTouch 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.h]hXTouch 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.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKDhj}hhubh)}(hTHC 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.h]hTHC 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.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKHhj}hhubh)}(hTHC Hardware Driver, provides THC hardware operation APIs for above QuickSPI/QuickI2C driver, it accesses THC MMIO registers to configure and control THC hardware.h]hTHC Hardware Driver, provides THC hardware operation APIs for above QuickSPI/QuickI2C driver, it accesses THC MMIO registers to configure and control THC hardware.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKKhj}hhubh)}(hTHC 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.h]hTHC 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.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKNhj}hhubeh}(h]thc-software-hardware-stackah ]h"]1.1 thc software/hardware stackah$]h&]uh1hhjlhhhhhKubh)}(hhh](h)}(h1.2 THC hardware diagramh]h1.2 THC hardware diagram}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKSubh)}(h-Below diagram shows THC hardware components::h]h,Below diagram shows THC hardware components:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKThjhhubj)}(hX% --------------------------------- | THC Controller | | +---------------------------+ | | | PCI Config Space | | | +---------------------------+ | | +---------------------------+ | | + MMIO Registers | | | +---------------------------+ | +---------------+ | +------------+ +------------+ | | System Memory +---+--+ DMA | | PIO | | +---------------+ | +------------+ +------------+ | | +---------------------------+ | | | HW Sequencer | | | +---------------------------+ | | +------------+ +------------+ | | | SPI/I2C | | GPIO | | | | Controller | | Controller | | | +------------+ +------------+ | ---------------------------------h]hX% --------------------------------- | THC Controller | | +---------------------------+ | | | PCI Config Space | | | +---------------------------+ | | +---------------------------+ | | + MMIO Registers | | | +---------------------------+ | +---------------+ | +------------+ +------------+ | | System Memory +---+--+ DMA | | PIO | | +---------------+ | +------------+ +------------+ | | +---------------------------+ | | | HW Sequencer | | | +---------------------------+ | | +------------+ +------------+ | | | SPI/I2C | | GPIO | | | | Controller | | Controller | | | +------------+ +------------+ | ---------------------------------}hj sbah}(h]h ]h"]h$]h&]hhuh1jhhhKVhjhhubh)}(hxAs THC is exposed as a PCI devices, so it has standard PCI config space registers for PCI enumeration and configuration.h]hxAs THC is exposed as a PCI devices, so it has standard PCI config space registers for PCI enumeration and configuration.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKjhjhhubh)}(hXEMMIO 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...h]hXEMMIO 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...}(hj'hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKmhjhhubh)}(hTHC 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.h]hTHC 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.}(hj5hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKrhjhhubh)}(hXHW 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.h]hXHW 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.}(hjChhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKvhjhhubh)}(hAs 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.h]hAs 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.}(hjQhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK}hjhhubeh}(h]thc-hardware-diagramah ]h"]1.2 thc hardware diagramah$]h&]uh1hhjlhhhhhKSubeh}(h]overviewah ]h"] 1. overviewah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h2. THC Hardware Interfaceh]h2. THC Hardware Interface}(hjrhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjohhhhhKubh)}(hhh](h)}(h2.1 Host Interfaceh]h2.1 Host Interface}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hTHC 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.h]hTHC 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.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]host-interfaceah ]h"]2.1 host interfaceah$]h&]uh1hhjohhhhhKubh)}(hhh](h)}(h2.2 Device Interfaceh]h2.2 Device Interface}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hTTHC supports two types of bus for Touch IC connection: Enhanced SPI bus and I2C bus.h]hTTHC supports two types of bus for Touch IC connection: Enhanced SPI bus and I2C bus.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hhh](h)}(h2.2.1 SPI Porth]h2.2.1 SPI Port}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hWhen 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.h]hWhen 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.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hXIn 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.h]hXIn 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.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(h~Beside IO mode, driver also needs to configure SPI bus speed. THC supports up to 42MHz SPI clock on Intel Lunar Lake platform.h]h~Beside IO mode, driver also needs to configure SPI bus speed. THC supports up to 42MHz SPI clock on Intel Lunar Lake platform.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(h<24Bits Slave Address>...........h]h| --------------------THC sends---------------------------------| <8Bits OPCode><24Bits Slave Address>...........}hjsbah}(h]h ]h"]h$]h&]hhuh1jhhhKhjhhubh)}(h@For THC receiving data from Touch IC, the data flow on SPI bus::h]h?For THC receiving data from Touch IC, the data flow on SPI bus:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(h| ---------THC Sends---------------||-----Touch IC sends--------| <8Bits OPCode><24Bits Slave Address>...........h]h| ---------THC Sends---------------||-----Touch IC sends--------| <8Bits OPCode><24Bits Slave Address>...........}hj+sbah}(h]h ]h"]h$]h&]hhuh1jhhhKhjhhubeh}(h]spi-portah ]h"]2.2.1 spi portah$]h&]uh1hhjhhhhhKubh)}(hhh](h)}(h2.2.2 I2C Porth]h2.2.2 I2C Port}(hjDhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjAhhhhhKubh)}(hXmTHC 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.h]hXqTHC 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.}(hjRhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjAhhubeh}(h]i2c-portah ]h"]2.2.2 i2c portah$]h&]uh1hhjhhhhhKubh)}(hhh](h)}(h2.2.3 GPIO interfaceh]h2.2.3 GPIO interface}(hjkhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhhKubh)}(hZTHC also includes two GPIO pins, one for interrupt and the other for device reset control.h]hZTHC also includes two GPIO pins, one for interrupt and the other for device reset control.}(hjyhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhhubh)}(hnInterrupt line can be configured to either level triggered or edge triggered by setting MMIO Control register.h]hnInterrupt line can be configured to either level triggered or edge triggered by setting MMIO Control register.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhhubh)}(hReset 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.h]hReset 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.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhhubeh}(h]gpio-interfaceah ]h"]2.2.3 gpio interfaceah$]h&]uh1hhjhhhhhKubeh}(h]device-interfaceah ]h"]2.2 device interfaceah$]h&]uh1hhjohhhhhKubh)}(hhh](h)}(h2.3 Max input size controlh]h2.3 Max input size control}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hXDThis is a new feature introduced in Panther Lake platform, THC hardware allows driver to set a max input size for RxDMA. After this max size gets set and enabled, for every input report packet reading, THC hardware sequencer will first read incoming input packet size, then compare input packet size with the given max size:h]hXDThis is a new feature introduced in Panther Lake platform, THC hardware allows driver to set a max input size for RxDMA. After this max size gets set and enabled, for every input report packet reading, THC hardware sequencer will first read incoming input packet size, then compare input packet size with the given max size:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hhh](h)}(h]if input packet size <= max size, THC continues using input packet size to finish the readingh]h)}(hjh]h]if input packet size <= max size, THC continues using input packet size to finish the reading}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubh)}(hif input packet size > max size, there is potential input data crash risk during transferring, THC will use max size instead of input packet size for reading h]h)}(hif input packet size > max size, there is potential input data crash risk during transferring, THC will use max size instead of input packet size for readingh]hif input packet size > max size, there is potential input data crash risk during transferring, THC will use max size instead of input packet size for reading}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubeh}(h]h ]h"]h$]h&]j@jAuh1hhhhKhjhhubh)}(hThis feature is used to avoid data corruption which will cause RxDMA buffer overrun issue for I2C bus, and enhance whole system stability.h]hThis feature is used to avoid data corruption which will cause RxDMA buffer overrun issue for I2C bus, and enhance whole system stability.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]max-input-size-controlah ]h"]2.3 max input size controlah$]h&]uh1hhjohhhhhKubh)}(hhh](h)}(h2.4 Interrupt delayh]h2.4 Interrupt delay}(hj#hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhKubh)}(hXBecause of MCU performance limitation, some touch devices cannot de-assert interrupt pin immediately after input data is transferred, which cause an interrupt toggle delay. But THC always detects next interrupt immediately after last input interrupt is handled. In this case, the delayed interrupt de-assertion will be recognized as a new interrupt signal by THC, and causes THC to start an input report reading spuriously.h]hXBecause of MCU performance limitation, some touch devices cannot de-assert interrupt pin immediately after input data is transferred, which cause an interrupt toggle delay. But THC always detects next interrupt immediately after last input interrupt is handled. In this case, the delayed interrupt de-assertion will be recognized as a new interrupt signal by THC, and causes THC to start an input report reading spuriously.}(hj1hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj hhubh)}(hIn order to avoid this situation, THC introduced interrupt delay new feature in Panther Lake platform, where THC allows driver to set an interrupt delay. After this feature is enabled, THC will delay this given time for next interrupt detection.h]hIn order to avoid this situation, THC introduced interrupt delay new feature in Panther Lake platform, where THC allows driver to set an interrupt delay. After this feature is enabled, THC will delay this given time for next interrupt detection.}(hj?hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj hhubeh}(h]interrupt-delayah ]h"]2.4 interrupt delayah$]h&]uh1hhjohhhhhKubeh}(h]thc-hardware-interfaceah ]h"]2. thc hardware interfaceah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h3. High level concepth]h3. High level concept}(hj`hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj]hhhhhKubh)}(hhh](h)}(h 3.1 Opcodeh]h 3.1 Opcode}(hjqhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjnhhhhhKubh)}(hrOpcode (operation code) is used to tell THC or Touch IC what the operation will be, such as PIO read or PIO write.h]hrOpcode (operation code) is used to tell THC or Touch IC what the operation will be, such as PIO read or PIO write.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjnhhubh)}(hWhen 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:h]hWhen 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:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjnhhubhtable)}(hhh]htgroup)}(hhh](hcolspec)}(hhh]h}(h]h ]h"]h$]h&]colwidthKuh1jhjubj)}(hhh]h}(h]h ]h"]h$]h&]colwidthKuh1jhjubhthead)}(hhh]hrow)}(hhh](hentry)}(hhh]h)}(hopcodeh]hopcode}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(hCorresponding SPI commandh]hCorresponding SPI command}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1jhjubhtbody)}(hhh](j)}(hhh](j)}(hhh]h)}(h0x0Bh]h0x0B}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(hRead Single I/Oh]hRead Single I/O}(hj#hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh](j)}(hhh]h)}(h0x02h]h0x02}(hjChhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj@ubah}(h]h ]h"]h$]h&]uh1jhj=ubj)}(hhh]h)}(hWrite Single I/Oh]hWrite Single I/O}(hjZhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjWubah}(h]h ]h"]h$]h&]uh1jhj=ubeh}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh](j)}(hhh]h)}(h0xBBh]h0xBB}(hjzhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjwubah}(h]h ]h"]h$]h&]uh1jhjtubj)}(hhh]h)}(h Read Dual I/Oh]h Read Dual I/O}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjtubeh}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh](j)}(hhh]h)}(h0xB2h]h0xB2}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(hWrite Dual I/Oh]hWrite Dual I/O}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh](j)}(hhh]h)}(h0xEBh]h0xEB}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(h Read Quad I/Oh]h Read Quad I/O}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh](j)}(hhh]h)}(h0xE2h]h0xE2}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(hWrite Quad I/Oh]hWrite Quad I/O}(hj6hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj3ubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]colsKuh1jhjubah}(h]h ]h"]h$]h&]uh1jhjnhhhhhNubh)}(hX7In 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.h]hX7In 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.}(hjchhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjnhhubh)}(hWhen 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.h]hWhen 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.}(hjqhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjnhhubh)}(h2Here are the THC pre-defined opcodes for I2C mode:h]h2Here are the THC pre-defined opcodes for I2C mode:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjnhhubj)}(hhh]j)}(hhh](j)}(hhh]h}(h]h ]h"]h$]h&]colwidthKuh1jhjubj)}(hhh]h}(h]h ]h"]h$]h&]colwidthK3uh1jhjubj)}(hhh]h}(h]h ]h"]h$]h&]colwidthK uh1jhjubj)}(hhh]j)}(hhh](j)}(hhh]h)}(hopcodeh]hopcode}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(hCorresponding I2C commandh]hCorresponding I2C command}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(hAddressh]hAddress}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh](j)}(hhh](j)}(hhh]h)}(h0x12h]h0x12}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h)}(h%Read I2C SubIP APB internal registersh]h%Read I2C SubIP APB internal registers}(hj(hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj%ubah}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h)}(h0h - FFhh]h0h - FFh}(hj?hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj<ubah}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh](j)}(hhh]h)}(h0x13h]h0x13}(hj_hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj\ubah}(h]h ]h"]h$]h&]uh1jhjYubj)}(hhh]h)}(h&Write I2C SubIP APB internal registersh]h&Write I2C SubIP APB internal registers}(hjvhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjsubah}(h]h ]h"]h$]h&]uh1jhjYubj)}(hhh]h)}(h0h - FFhh]h0h - FFh}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjYubeh}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh](j)}(hhh]h)}(h0x14h]h0x14}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(h&Read external Touch IC through I2C bush]h&Read external Touch IC through I2C bus}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(hN/Ah]hN/A}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh](j)}(hhh]h)}(h0x18h]h0x18}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(h'Write external Touch IC through I2C bush]h'Write external Touch IC through I2C bus}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(hN/Ah]hN/A}(hj)hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj&ubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh](j)}(hhh]h)}(h0x1Ch]h0x1C}(hjIhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjFubah}(h]h ]h"]h$]h&]uh1jhjCubj)}(hhh]h)}(h1Write then read external Touch IC through I2C bush]h1Write then read external Touch IC through I2C bus}(hj`hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj]ubah}(h]h ]h"]h$]h&]uh1jhjCubj)}(hhh]h)}(hN/Ah]hN/A}(hjwhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjtubah}(h]h ]h"]h$]h&]uh1jhjCubeh}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]colsKuh1jhjubah}(h]h ]h"]h$]h&]uh1jhjnhhhhhNubeh}(h]opcodeah ]h"] 3.1 opcodeah$]h&]uh1hhj]hhhhhKubh)}(hhh](h)}(h3.2 PIOh]h3.2 PIO}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMubh)}(hXTHC 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).h]hXTHC 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).}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM hjhhubh)}(hIf 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.h]hIf 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.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hA 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.h]hA 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.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hoBecause THC only has 16 FIFO registers for PIO, so all the data transfer through PIO shouldn't exceed 64 bytes.h]hqBecause THC only has 16 FIFO registers for PIO, so all the data transfer through PIO shouldn’t exceed 64 bytes.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hXAs 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).h]hXAs 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).}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hNFor how to issue a PIO operation, here is the steps which driver needs follow:h]hNFor how to issue a PIO operation, here is the steps which driver needs follow:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM hjhhubh)}(hhh](h)}(h*Program read/write data size in THC_SS_BC.h]h)}(hj h]h*Program read/write data size in THC_SS_BC.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM"hj ubah}(h]h ]h"]h$]h&]uh1hhj hhhhhNubh)}(h4Program I/O target address in THC_SW_SEQ_DATA0_ADDR.h]h)}(hj- h]h4Program I/O target address in THC_SW_SEQ_DATA0_ADDR.}(hj/ hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM#hj+ ubah}(h]h ]h"]h$]h&]uh1hhj hhhhhNubh)}(hGIf write, program the write data in THC_SW_SEQ_DATA0..THC_SW_SEQ_DATAn.h]h)}(hjD h]hGIf write, program the write data in THC_SW_SEQ_DATA0..THC_SW_SEQ_DATAn.}(hjF hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM$hjB ubah}(h]h ]h"]h$]h&]uh1hhj hhhhhNubh)}(h%Program the PIO opcode in THC_SS_CMD.h]h)}(hj[ h]h%Program the PIO opcode in THC_SS_CMD.}(hj] hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM%hjY ubah}(h]h ]h"]h$]h&]uh1hhj hhhhhNubh)}(h.Set TSSGO = 1 to start the PIO write sequence.h]h)}(hjr h]h.Set TSSGO = 1 to start the PIO write sequence.}(hjt hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM&hjp ubah}(h]h ]h"]h$]h&]uh1hhj hhhhhNubh)}(hFIf THC_SS_CD_IE = 1, SW will receives a MSI when the PIO is completed.h]h)}(hj h]hFIf THC_SS_CD_IE = 1, SW will receives a MSI when the PIO is completed.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM'hj ubah}(h]h ]h"]h$]h&]uh1hhj hhhhhNubh)}(hBIf read, read out the data in THC_SW_SEQ_DATA0..THC_SW_SEQ_DATAn. h]h)}(hAIf read, read out the data in THC_SW_SEQ_DATA0..THC_SW_SEQ_DATAn.h]hAIf read, read out the data in THC_SW_SEQ_DATA0..THC_SW_SEQ_DATAn.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM(hj ubah}(h]h ]h"]h$]h&]uh1hhj hhhhhNubeh}(h]h ]h"]h$]h&]j@jAuh1hhhhM"hjhhubeh}(h]pioah ]h"]3.2 pioah$]h&]uh1hhj]hhhhhMubh)}(hhh](h)}(h3.3 DMAh]h3.3 DMA}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhM+ubh)}(hITHC has 4 DMA channels: Read DMA1, Read DMA2, Write DMA and Software DMA.h]hITHC has 4 DMA channels: Read DMA1, Read DMA2, Write DMA and Software DMA.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM-hj hhubh)}(hhh](h)}(h3.3.1 Read DMA Channelh]h3.3.1 Read DMA Channel}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhM0ubh)}(hTHC 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.h]hTHC 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.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM2hj hhubh)}(hRxDMA'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.h]hRxDMA’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.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM6hj hhubh)}(hXFor 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.h]hXFor 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.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM9hj hhubh)}(hX+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 to notify driver input report data is ready in system memory.h]hX-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 to notify driver input report data is ready in system memory.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM@hj hhubh)}(hAll 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.h]hAll 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.}(hj, hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMGhj hhubeh}(h]read-dma-channelah ]h"]3.3.1 read dma channelah$]h&]uh1hhj hhhhhM0ubh)}(hhh](h)}(h3.3.2 Software DMA channelh]h3.3.2 Software DMA channel}(hjE hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjB hhhhhMKubh)}(hXTHC supports a software triggered 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 triggered by software, and RxDMA2 is triggered by external Touch IC interrupt. It gives a flexibility to software driver to use RxDMA read Touch IC data in any time.h]hXTHC supports a software triggered 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 triggered by software, and RxDMA2 is triggered by external Touch IC interrupt. It gives a flexibility to software driver to use RxDMA read Touch IC data in any time.}(hjS hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMMhjB hhubh)}(hBefore 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.h]hBefore 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.}(hja hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMRhjB hhubeh}(h]software-dma-channelah ]h"]3.3.2 software dma channelah$]h&]uh1hhj hhhhhMKubh)}(hhh](h)}(h3.3.3 Write DMA Channelh]h3.3.3 Write DMA Channel}(hjz hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjw hhhhhMWubh)}(hX: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.h]hX: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.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMYhjw hhubh)}(hX"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.h]hX"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.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM^hjw hhubeh}(h]write-dma-channelah ]h"]3.3.3 write dma channelah$]h&]uh1hhj hhhhhMWubeh}(h]dmaah ]h"]3.3 dmaah$]h&]uh1hhj]hhhhhM+ubh)}(hhh](h)}(h3.4 PRDh]h3.4 PRD}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhMdubh)}(hVPhysical Region Descriptor (PRD) provides the memory mapping description for THC DMAs.h]hVPhysical Region Descriptor (PRD) provides the memory mapping description for THC DMAs.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMfhj hhubh)}(hhh](h)}(h3.4.1 PRD table and entryh]h3.4.1 PRD table and entry}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhMiubh)}(hIn 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.h]hIn 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.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMkhj hhubh)}(hTHC uses PRD table (physical region descriptor) to support the corresponding OS kernel SGL that describes the virtual to physical buffer mapping.h]hTHC uses PRD table (physical region descriptor) to support the corresponding OS kernel SGL that describes the virtual to physical buffer mapping.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMohj hhubj)}(hX] ------------------------ -------------- -------------- | PRD table base address +----+ PRD table #1 +-----+ PRD Entry #1 | ------------------------ -------------- -------------- -------------- | PRD Entry #2 | -------------- -------------- | PRD Entry #n | --------------h]hX] ------------------------ -------------- -------------- | PRD table base address +----+ PRD table #1 +-----+ PRD Entry #1 | ------------------------ -------------- -------------- -------------- | PRD Entry #2 | -------------- -------------- | PRD Entry #n | --------------}hj sbah}(h]h ]h"]h$]h&]hhuh1jhhhMthj hhubh)}(hXThe 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.h]hXThe 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.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM~hj hhubh)}(hTo 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.h]hTo 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.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubh)}(hSW 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.h]hSW 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.}(hj* hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubh)}(hX_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.h]hXaMax 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.}(hj8 hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubh)}(hRSW allocates all the data buffers and PRD tables only once at host initialization.h]hRSW allocates all the data buffers and PRD tables only once at host initialization.}(hjF hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubeh}(h]prd-table-and-entryah ]h"]3.4.1 prd table and entryah$]h&]uh1hhj hhhhhMiubh)}(hhh](h)}(h(3.4.2 PRD Write pointer and read pointerh]h(3.4.2 PRD Write pointer and read pointer}(hj_ hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj\ hhhhhMubh)}(hnAs PRD tables are organized as a Circular Buffer (CB), a read pointer and a write pointer for a CB are needed.h]hnAs PRD tables are organized as a Circular Buffer (CB), a read pointer and a write pointer for a CB are needed.}(hjm hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj\ hhubh)}(hX 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 ...h]hX"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 ...}(hj{ hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj\ hhubh)}(hXThe 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 ..h]hXThe 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 ..}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj\ hhubeh}(h]"prd-write-pointer-and-read-pointerah ]h"](3.4.2 prd write pointer and read pointerah$]h&]uh1hhj hhhhhMubh)}(hhh](h)}(h3.4.3 PRD descriptor structureh]h3.4.3 PRD descriptor structure}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhMubh)}(hoIntel THC uses PRD entry descriptor for every PRD entry. Every PRD entry descriptor occupies 128 bits memories:h]hoIntel THC uses PRD entry descriptor for every PRD entry. Every PRD entry descriptor occupies 128 bits memories:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubj)}(hhh]j)}(hhh](j)}(hhh]h}(h]h ]h"]h$]h&]colwidthKuh1jhj ubj)}(hhh]h}(h]h ]h"]h$]h&]colwidthKuh1jhj ubj)}(hhh]h}(h]h ]h"]h$]h&]colwidthK/uh1jhj ubj)}(hhh]j)}(hhh](j)}(hhh]h)}(h struct fieldh]h struct field}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h)}(hbit(s)h]hbit(s)}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h)}(h descriptionh]h description}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]uh1jhj ubah}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh](j)}(hhh](j)}(hhh]h)}(h dest_addrh]h dest_addr}(hjB hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj? ubah}(h]h ]h"]h$]h&]uh1jhj< ubj)}(hhh]h)}(h53..0h]h53..0}(hjY hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjV ubah}(h]h ]h"]h$]h&]uh1jhj< ubj)}(hhh]h)}(hTdestination memory address, as every entry is 4KB, ignore lowest 10 bits of address.h]hTdestination memory address, as every entry is 4KB, ignore lowest 10 bits of address.}(hjp hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjm ubah}(h]h ]h"]h$]h&]uh1jhj< ubeh}(h]h ]h"]h$]h&]uh1jhj9 ubj)}(hhh](j)}(hhh]h)}(h reserved1h]h reserved1}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h)}(h54..62h]h54..62}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h)}(hreservedh]hreserved}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]uh1jhj9 ubj)}(hhh](j)}(hhh]h)}(hint_on_completionh]hint_on_completion}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h)}(h63h]h63}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h)}(hcompletion interrupt enable bit, if this bit set it means THC will trigger a completion interrupt. This bit is set by SW driver.h]hcompletion interrupt enable bit, if this bit set it means THC will trigger a completion interrupt. This bit is set by SW driver.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]uh1jhj9 ubj)}(hhh](j)}(hhh]h)}(hlenh]hlen}(hj, hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj) ubah}(h]h ]h"]h$]h&]uh1jhj& ubj)}(hhh]h)}(h87..64h]h87..64}(hjC hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj@ ubah}(h]h ]h"]h$]h&]uh1jhj& ubj)}(hhh]h)}(h%how many bytes of data in this entry.h]h%how many bytes of data in this entry.}(hjZ hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjW ubah}(h]h ]h"]h$]h&]uh1jhj& ubeh}(h]h ]h"]h$]h&]uh1jhj9 ubj)}(hhh](j)}(hhh]h)}(h end_of_prdh]h end_of_prd}(hjz hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjw ubah}(h]h ]h"]h$]h&]uh1jhjt ubj)}(hhh]h)}(h88h]h88}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jhjt ubj)}(hhh]h)}(h|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.h]h|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.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jhjt ubeh}(h]h ]h"]h$]h&]uh1jhj9 ubj)}(hhh](j)}(hhh]h)}(h hw_statush]h hw_status}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h)}(h90..89h]h90..89}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h)}(hHW status bitsh]hHW status bits}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]uh1jhj9 ubj)}(hhh](j)}(hhh]h)}(h reserved2h]h reserved2}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(h127..91h]h127..91}(hj-hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj*ubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(hreservedh]hreserved}(hjDhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjAubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhj9 ubeh}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]colsKuh1jhj ubah}(h]h ]h"]h$]h&]uh1jhj hhhhhNubh)}(hAnd 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.h]hAnd 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.}(hjqhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubj)}(hMstruct thc_prd_table { struct thc_prd_entry entries[PRD_ENTRIES_NUM]; };h]hMstruct thc_prd_table { struct thc_prd_entry entries[PRD_ENTRIES_NUM]; };}hjsbah}(h]h ]h"]h$]h&]hhƌforcelanguagechighlight_args}uh1jhhhMhj hhubh)}(hX.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.h]hX.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.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubeh}(h]prd-descriptor-structureah ]h"]3.4.3 prd descriptor structureah$]h&]uh1hhj hhhhhMubeh}(h]prdah ]h"]3.4 prdah$]h&]uh1hhj]hhhhhMdubeh}(h]high-level-conceptah ]h"]3. high level conceptah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h4. HIDSPI support (QuickSPI)h]h4. HIDSPI support (QuickSPI)}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMubh)}(hqIntel THC is total compatible with HIDSPI protocol, THC HW sequenser can accelerate HIDSPI protocol transferring.h]hqIntel THC is total compatible with HIDSPI protocol, THC HW sequenser can accelerate HIDSPI protocol transferring.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hhh](h)}(h4.1 Reset Flowh]h4.1 Reset Flow}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMubh)}(hhh](h)}(h/Call ACPI _RST method to reset Touch IC device.h]h)}(hjh]h/Call ACPI _RST method to reset Touch IC device.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubh)}(h2Read the reset response from TIC through PIO read.h]h)}(hjh]h2Read the reset response from TIC through PIO read.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubh)}(hNIssue a command to retrieve device descriptor from Touch IC through PIO write.h]h)}(hjh]hNIssue a command to retrieve device descriptor from Touch IC through PIO write.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubh)}(h:Read the device descriptor from Touch IC through PIO read.h]h)}(hj2h]h:Read the device descriptor from Touch IC through PIO read.}(hj4hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj0ubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubh)}(hWIf the device descriptor is valid, allocate DMA buffers and configure all DMA channels.h]h)}(hjIh]hWIf the device descriptor is valid, allocate DMA buffers and configure all DMA channels.}(hjKhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjGubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubh)}(hIIssue a command to retrieve report descriptor from Touch IC through DMA. h]h)}(hHIssue a command to retrieve report descriptor from Touch IC through DMA.h]hHIssue a command to retrieve report descriptor from Touch IC through DMA.}(hjbhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj^ubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubeh}(h]h ]h"]h$]h&]j@jAuh1hhhhMhjhhubeh}(h] reset-flowah ]h"]4.1 reset flowah$]h&]uh1hhjhhhhhMubh)}(hhh](h)}(h4.2 Input Report Data Flowh]h4.2 Input Report Data Flow}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMubh)}(h Basic Flow:h]h Basic Flow:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hhh](h)}(hFTouch IC interrupts the THC Controller using an in-band THC interrupt.h]h)}(hjh]hFTouch IC interrupts the THC Controller using an in-band THC interrupt.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubh)}(hTHC 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.h]h)}(hTHC 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.h]hTHC 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.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubh)}(hTHC Sequencer executes a Input Report Body Read operation corresponding to the value reflected in “Input Report Length” field of the Input Report Header.h]h)}(hTHC Sequencer executes a Input Report Body Read operation corresponding to the value reflected in “Input Report Length” field of the Input Report Header.h]hTHC Sequencer executes a Input Report Body Read operation corresponding to the value reflected in “Input Report Length” field of the Input Report Header.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubh)}(hX"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).h]h)}(hX"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).h]hX$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).}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubh)}(hThe 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.h]h)}(hThe 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.h]hThe 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.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubh)}(haIf the “Last Fragment Flag” bit is enabled the THC Sequencer enters End-of-Frame Processing. h]h)}(h`If the “Last Fragment Flag” bit is enabled the THC Sequencer enters End-of-Frame Processing.h]h`If the “Last Fragment Flag” bit is enabled the THC Sequencer enters End-of-Frame Processing.}(hj!hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubeh}(h]h ]h"]h$]h&]j@jAuh1hhhhMhjhhubh)}(h&THC Sequencer End of Frame Processing:h]h&THC Sequencer End of Frame Processing:}(hj;hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hhh](h)}(hTHC 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).h]h)}(hTHC 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).h]hTHC 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).}(hjPhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjLubah}(h]h ]h"]h$]h&]uh1hhjIhhhhhNubh)}(hIf THC EOF interrupt is enabled by the driver in the control register (THC_M_PRT_READ_DMA_CNTRL_2), generates interrupt to software. h]h)}(hIf THC EOF interrupt is enabled by the driver in the control register (THC_M_PRT_READ_DMA_CNTRL_2), generates interrupt to software.h]hIf THC EOF interrupt is enabled by the driver in the control register (THC_M_PRT_READ_DMA_CNTRL_2), generates interrupt to software.}(hjhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjdubah}(h]h ]h"]h$]h&]uh1hhjIhhhhhNubeh}(h]h ]h"]h$]h&]j@jAuh1hhhhMhjhhubh)}(h2Sequence of steps to read data from RX DMA buffer:h]h2Sequence of steps to read data from RX DMA buffer:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hhh](h)}(hnTHC QuickSPI driver checks CB write Ptr and CB read Ptr to identify if any data frame in DMA circular buffers.h]h)}(hnTHC QuickSPI driver checks CB write Ptr and CB read Ptr to identify if any data frame in DMA circular buffers.h]hnTHC QuickSPI driver checks CB write Ptr and CB read Ptr to identify if any data frame in DMA circular buffers.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubh)}(h5THC QuickSPI driver gets first unprocessed PRD table.h]h)}(hjh]h5THC QuickSPI driver gets first unprocessed PRD table.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubh)}(h^THC QuickSPI driver scans all PRD entries in this PRD table to calculate the total frame size.h]h)}(hjh]h^THC QuickSPI driver scans all PRD entries in this PRD table to calculate the total frame size.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubh)}(h.THC QuickSPI driver copies all frame data out.h]h)}(hjh]h.THC QuickSPI driver copies all frame data out.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubh)}(hyTHC QuickSPI driver checks the data type according to input report body, and calls related callbacks to process the data.h]h)}(hyTHC QuickSPI driver checks the data type according to input report body, and calls related callbacks to process the data.h]hyTHC QuickSPI driver checks the data type according to input report body, and calls related callbacks to process the data.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubh)}(h'THC QuickSPI driver updates write Ptr. h]h)}(h&THC QuickSPI driver updates write Ptr.h]h&THC QuickSPI driver updates write Ptr.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubeh}(h]h ]h"]h$]h&]j@jAuh1hhhhMhjhhubeh}(h]input-report-data-flowah ]h"]4.2 input report data flowah$]h&]uh1hhjhhhhhMubh)}(hhh](h)}(h4.3 Output Report Data Flowh]h4.3 Output Report Data Flow}(hj1hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj.hhhhhMubh)}(hGeneric Output Report Flow:h]hGeneric Output Report Flow:}(hj?hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj.hhubh)}(hhh](h)}(hJHID core calls raw_request callback with a request to THC QuickSPI driver.h]h)}(hjRh]hJHID core calls raw_request callback with a request to THC QuickSPI driver.}(hjThhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjPubah}(h]h ]h"]h$]h&]uh1hhjMhhhhhNubh)}(hyTHC QuickSPI Driver converts request provided data into the output report packet and copies it to THC's write DMA buffer.h]h)}(hyTHC QuickSPI Driver converts request provided data into the output report packet and copies it to THC's write DMA buffer.h]h{THC QuickSPI Driver converts request provided data into the output report packet and copies it to THC’s write DMA buffer.}(hjkhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjgubah}(h]h ]h"]h$]h&]uh1hhjMhhhhhNubh)}(h-Start TxDMA to complete the write operation. h]h)}(h,Start TxDMA to complete the write operation.h]h,Start TxDMA to complete the write operation.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1hhjMhhhhhNubeh}(h]h ]h"]h$]h&]j@jAuh1hhhhMhj.hhubeh}(h]output-report-data-flowah ]h"]4.3 output report data flowah$]h&]uh1hhjhhhhhMubeh}(h]hidspi-support-quickspiah ]h"]4. hidspi support (quickspi)ah$]h&]uh1hhhhhhhhMubh)}(hhh](h)}(h5. HIDI2C support (QuickI2C)h]h5. HIDI2C support (QuickI2C)}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhM ubh)}(hhh](h)}(h5.1 Reset Flowh]h5.1 Reset Flow}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhM ubh)}(hhh](h)}(hORead device descriptor from Touch IC device through PIO write followed by read.h]h)}(hjh]hORead device descriptor from Touch IC device through PIO write followed by read.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubh)}(hWIf the device descriptor is valid, allocate DMA buffers and configure all DMA channels.h]h)}(hjh]hWIf the device descriptor is valid, allocate DMA buffers and configure all DMA channels.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubh)}(hUse PIO or TxDMA to write a SET_POWER request to TIC's command register, and check if the write operation is successfully completed.h]h)}(hUse PIO or TxDMA to write a SET_POWER request to TIC's command register, and check if the write operation is successfully completed.h]hUse PIO or TxDMA to write a SET_POWER request to TIC’s command register, and check if the write operation is successfully completed.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubh)}(hUse 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.h]h)}(hUse 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.h]hUse 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.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubh)}(hNUse SWDMA to read report descriptor through TIC's report descriptor register. h]h)}(hMUse SWDMA to read report descriptor through TIC's report descriptor register.h]hOUse SWDMA to read report descriptor through TIC’s report descriptor register.}(hj4hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj0ubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubeh}(h]h ]h"]h$]h&]j@jAuh1hhhhMhjhhubeh}(h]id1ah ]h"]5.1 reset flowah$]h&]uh1hhjhhhhhM ubh)}(hhh](h)}(h5.2 Input Report Data Flowh]h5.2 Input Report Data Flow}(hjYhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjVhhhhhMubh)}(h Basic Flow:h]h Basic Flow:}(hjghhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjVhhubh)}(hhh](h)}(hTouch 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.h]h)}(hTouch 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.h]hTouch 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.}(hj|hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjxubah}(h]h ]h"]h$]h&]uh1hhjuhhhhhNubh)}(haTHC Sequencer continues the Read operation as per the size of data indicated in the length field.h]h)}(haTHC Sequencer continues the Read operation as per the size of data indicated in the length field.h]haTHC Sequencer continues the Read operation as per the size of data indicated in the length field.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1hhjuhhhhhNubh)}(hXnTHC 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).h]h)}(hXnTHC 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).h]hXpTHC 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).}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM hjubah}(h]h ]h"]h$]h&]uh1hhjuhhhhhNubh)}(h4THC Sequencer enters End-of-Input Report Processing.h]h)}(hjh]h4THC Sequencer enters End-of-Input Report Processing.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM%hjubah}(h]h ]h"]h$]h&]uh1hhjuhhhhhNubh)}(hIf 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. h]h)}(hIf 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.h]hIf 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.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM&hjubah}(h]h ]h"]h$]h&]uh1hhjuhhhhhNubeh}(h]h ]h"]h$]h&]j@jAuh1hhhhMhjVhhubh)}(h-THC Sequencer End of Input Report Processing:h]h-THC Sequencer End of Input Report Processing:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM*hjVhhubh)}(hhh](h)}(hTHC 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).h]h)}(hTHC 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).h]hTHC 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).}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM,hjubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubh)}(hIf THC EOF interrupt is enabled by the driver in the control register (THC_M_PRT_READ_DMA_CNTRL_2), generates interrupt to software. h]h)}(hIf THC EOF interrupt is enabled by the driver in the control register (THC_M_PRT_READ_DMA_CNTRL_2), generates interrupt to software.h]hIf THC EOF interrupt is enabled by the driver in the control register (THC_M_PRT_READ_DMA_CNTRL_2), generates interrupt to software.}(hj"hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM.hjubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubeh}(h]h ]h"]h$]h&]j@jAuh1hhhhM,hjVhhubh)}(h2Sequence of steps to read data from RX DMA buffer:h]h2Sequence of steps to read data from RX DMA buffer:}(hj<hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM1hjVhhubh)}(hhh](h)}(hnTHC QuickI2C driver checks CB write Ptr and CB read Ptr to identify if any data frame in DMA circular buffers.h]h)}(hnTHC QuickI2C driver checks CB write Ptr and CB read Ptr to identify if any data frame in DMA circular buffers.h]hnTHC QuickI2C driver checks CB write Ptr and CB read Ptr to identify if any data frame in DMA circular buffers.}(hjQhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM3hjMubah}(h]h ]h"]h$]h&]uh1hhjJhhhhhNubh)}(h5THC QuickI2C driver gets first unprocessed PRD table.h]h)}(hjgh]h5THC QuickI2C driver gets first unprocessed PRD table.}(hjihhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM5hjeubah}(h]h ]h"]h$]h&]uh1hhjJhhhhhNubh)}(h^THC QuickI2C driver scans all PRD entries in this PRD table to calculate the total frame size.h]h)}(hj~h]h^THC QuickI2C driver scans all PRD entries in this PRD table to calculate the total frame size.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM6hj|ubah}(h]h ]h"]h$]h&]uh1hhjJhhhhhNubh)}(h.THC QuickI2C driver copies all frame data out.h]h)}(hjh]h.THC QuickI2C driver copies all frame data out.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM7hjubah}(h]h ]h"]h$]h&]uh1hhjJhhhhhNubh)}(hTHC 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).h]h)}(hTHC 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).h]hTHC 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).}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM8hjubah}(h]h ]h"]h$]h&]uh1hhjJhhhhhNubh)}(h'THC QuickI2C driver updates write Ptr. h]h)}(h&THC QuickI2C driver updates write Ptr.h]h&THC QuickI2C driver updates write Ptr.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM;hjubah}(h]h ]h"]h$]h&]uh1hhjJhhhhhNubeh}(h]h ]h"]h$]h&]j@jAuh1hhhhM3hjVhhubeh}(h]id2ah ]h"]5.2 input report data flowah$]h&]uh1hhjhhhhhMubh)}(hhh](h)}(h5.3 Output Report Data Flowh]h5.3 Output Report Data Flow}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhM>ubh)}(hGeneric Output Report Flow:h]hGeneric Output Report Flow:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM@hjhhubh)}(hhh](h)}(h0HID core call THC QuickI2C raw_request callback.h]h)}(hj h]h0HID core call THC QuickI2C raw_request callback.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMBhj ubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubh)}(hTHC 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.h]h)}(hTHC 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.h]hTHC 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.}(hj%hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMChj!ubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubh)}(hTHC 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. h]h)}(hTHC 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.h]hTHC 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.}(hj=hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMEhj9ubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubeh}(h]h ]h"]h$]h&]j@jAuh1hhhhMBhjhhubeh}(h]id3ah ]h"]5.3 output report data flowah$]h&]uh1hhjhhhhhM>ubeh}(h]hidi2c-support-quicki2cah ]h"]5. hidi2c support (quicki2c)ah$]h&]uh1hhhhhhhhM ubh)}(hhh](h)}(h6. THC Debuggingh]h6. THC Debugging}(hjjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjghhhhhMJubh)}(hETo debug THC, event tracing mechanism is used. To enable debug logs::h]hDTo debug THC, event tracing mechanism is used. To enable debug logs:}(hjxhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMLhjghhubj)}(h^echo 1 > /sys/kernel/debug/tracing/events/intel_thc/enable cat /sys/kernel/debug/tracing/traceh]h^echo 1 > /sys/kernel/debug/tracing/events/intel_thc/enable cat /sys/kernel/debug/tracing/trace}hjsbah}(h]h ]h"]h$]h&]hhuh1jhhhMNhjghhubeh}(h] thc-debuggingah ]h"]6. thc debuggingah$]h&]uh1hhhhhhhhMJubh)}(hhh](h)}(h 7. Referenceh]h 7. Reference}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMRubh)}(hhh](h)}(hqHIDSPI: https://download.microsoft.com/download/c/a/0/ca07aef3-3e10-4022-b1e9-c98cea99465d/HidSpiProtocolSpec.pdfh]h)}(hjh](hHIDSPI: }(hjhhhNhNubh reference)}(hihttps://download.microsoft.com/download/c/a/0/ca07aef3-3e10-4022-b1e9-c98cea99465d/HidSpiProtocolSpec.pdfh]hihttps://download.microsoft.com/download/c/a/0/ca07aef3-3e10-4022-b1e9-c98cea99465d/HidSpiProtocolSpec.pdf}(hjhhhNhNubah}(h]h ]h"]h$]h&]refurijuh1jhjubeh}(h]h ]h"]h$]h&]uh1hhhhMShjubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubh)}(hHIDI2C: https://download.microsoft.com/download/7/d/d/7dd44bb7-2a7a-4505-ac1c-7227d3d96d5b/hid-over-i2c-protocol-spec-v1-0.docxh]h)}(hjh](hHIDI2C: }(hjhhhNhNubj)}(hwhttps://download.microsoft.com/download/7/d/d/7dd44bb7-2a7a-4505-ac1c-7227d3d96d5b/hid-over-i2c-protocol-spec-v1-0.docxh]hwhttps://download.microsoft.com/download/7/d/d/7dd44bb7-2a7a-4505-ac1c-7227d3d96d5b/hid-over-i2c-protocol-spec-v1-0.docx}(hjhhhNhNubah}(h]h ]h"]h$]h&]refurijuh1jhjubeh}(h]h ]h"]h$]h&]uh1hhhhMThjubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubeh}(h]h ]h"]h$]h&]j@jAuh1hhhhMShjhhubeh}(h] referenceah ]h"] 7. referenceah$]h&]uh1hhhhhhhhMRubeh}(h]intel-touch-host-controller-thcah ]h"]!intel touch host controller (thc)ah$]h&]uh1hhhhhhhhKubeh}(h]h ]h"]h$]h&]sourcehuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(hN generatorN datestampN source_linkN source_urlN toc_backlinksjfootnote_backlinksK sectnum_xformKstrip_commentsNstrip_elements_with_classesN strip_classesN report_levelK halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-siginput_encoding_error_handlerstrictoutput_encodingutf-8output_encoding_error_handlerj6error_encodingutf-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourcehnj _destinationN _config_files]7/var/lib/git/docbuild/linux/Documentation/docutils.confafile_insertion_enabled raw_enabledKline_length_limitM'pep_referencesN pep_base_urlhttps://peps.python.org/pep_file_url_templatepep-%04drfc_referencesN rfc_base_url&https://datatracker.ietf.org/doc/html/ tab_widthKtrim_footnote_reference_spacesyntax_highlightlong smart_quotessmartquotes_locales]character_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xform image_loadinglinkembed_stylesheetcloak_email_addressessection_self_linkenvNubreporterNindirect_targets]substitution_defs}substitution_names}refnames}refids}nameids}(jjjljijjjdjajZjWjjjjj>j;jejbjjjjjRjOjjjjj j j j j? j< jt jq j j jjjY jV j j jjjjjj~j+j(jjjdjajSjPjjj\jYjjj ju nametypes}(jjljjdjZjjj>jejjjRjjj j j? jt j jjY j jjjj+jjdjSjj\jj uh}(jhjijljj}jajjWjojjjjj;jjbjAjjhjjjOj jj]jjnj jj j j< j jq jB j jw jj jV j j j\ jj jjj~jj(jjj.jajjPjjjVjYjjjgjju footnote_refs} citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}jDKsRparse_messages]transform_messages] transformerN include_log] decorationNhhub.