Intel Touch Host Controller (THC)¶

Touch Host Controller (THC) 是PCH中與觸控裝置（例如：觸控式螢幕、觸控板等）介面的IP模組的名稱。它由3個關鍵功能塊組成：

一個原生半雙工的四路I/O SPI主控制器
低延遲的I2C介面，用於支援符合HIDI2C標準的裝置
一個具有讀寫DMA功能的硬體序列器，用於訪問系統記憶體

它具有一個單根空間IOSF主介面，支援與觸控裝置之間的事務。主機驅動程式透過THC介面配置和控制觸控裝置。THC為觸控驅動程式提供高頻寬DMA服務，並將HID報告傳輸到主機系統主記憶體。

THC中的硬體序列器負責將資料（透過DMA）從觸控裝置傳輸到系統記憶體。使用環形緩衝區是為了避免由於資料消耗（由主機）相對於資料生產（由觸控裝置透過DMA）的非同步性質而導致的資料丟失。

與其他常見的SPI/I2C控制器不同，THC直接處理HID裝置的資料中斷和復位訊號。

1. 概述¶

1.1 THC 軟體/硬體棧¶

下圖說明了THC軟體/硬體棧的高階架構，它完全能夠支援Linux作業系統中的HIDSPI/HIDI2C協議。

 ----------------------------------------------
|      +-----------------------------------+   |
|      |           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             |   |
|      +-----------------------------------+   |
 ----------------------------------------------

觸控IC (TIC)，也稱為觸控裝置（觸控式螢幕或觸控板）。離散的模擬元件，用於感知和傳輸離散觸控資料或熱圖資料，以HID報告的形式透過SPI/I2C匯流排傳輸到主機上的THC控制器。

THC Host Controller，這是一個PCI裝置HBA（主機匯流排介面卡），整合到PCH中，作為觸控IC和主機之間的橋樑。

THC硬體驅動程式，為上面的QuickSPI/QuickI2C驅動程式提供THC硬體操作API，它訪問THC MMIO暫存器來配置和控制THC硬體。

THC QuickSPI/QuickI2C驅動程式，也稱為HIDSPI/HIDI2C驅動程式，註冊為HID低階驅動程式，用於管理THC控制器並實現HIDSPI/HIDI2C協議。

1.2 THC 硬體圖¶

下圖顯示了THC硬體元件

                     ---------------------------------
                    |          THC Controller         |
                    |  +---------------------------+  |
                    |  |     PCI Config Space      |  |
                    |  +---------------------------+  |
                    |  +---------------------------+  |
                    |  +       MMIO Registers      |  |
                    |  +---------------------------+  |
+---------------+   |  +------------+ +------------+  |
| System Memory +---+--+      DMA   | |   PIO      |  |
+---------------+   |  +------------+ +------------+  |
                    |  +---------------------------+  |
                    |  |       HW Sequencer        |  |
                    |  +---------------------------+  |
                    |  +------------+ +------------+  |
                    |  |  SPI/I2C   | |    GPIO    |  |
                    |  | Controller | | Controller |  |
                    |  +------------+ +------------+  |
                     ---------------------------------

由於THC作為PCI裝置公開，因此它具有用於PCI列舉和配置的標準PCI配置空間暫存器。

MMIO暫存器，為驅動程式提供暫存器訪問許可權，以配置和控制THC硬體，這些暫存器包括以下幾個類別：中斷狀態和控制，DMA配置，PIO（程式設計I/O，在第3.2節中定義）狀態和控制，SPI匯流排配置，I2C subIP狀態和控制，復位狀態和控制...

THC為驅動程式提供兩種與外部觸控IC通訊的方式：PIO和DMA。 PIO允許驅動程式手動寫入/讀取資料到/從觸控IC，而THC DMA可以自動寫入/讀取資料，無需驅動程式參與。

HW Sequencer包含THC的主要邏輯，它從MMIO暫存器獲取指令來控制SPI匯流排和I2C匯流排以完成匯流排資料事務，它還可以自動處理觸控IC中斷並根據中斷型別啟動DMA接收/傳送資料到/從觸控IC。這意味著THC HW Sequencer理解HIDSPI/HIDI2C傳輸協議，並處理通訊而無需驅動程式參與，驅動程式需要做的只是正確配置THC，並準備格式化的資料包或處理接收到的資料包。

由於THC支援HIDSPI/HIDI2C協議，因此它具有SPI控制器和I2C subIP，以公開SPI匯流排和I2C匯流排。 THC還集成了GPIO控制器以提供中斷線支援和復位線支援。

2. THC 硬體介面¶

2.1 主機介面¶

THC作為“PCI Digitizer device”暴露給主機。 PCI產品和裝置ID從不同代的處理器更改。因此，列舉驅動程式的原始碼需要逐代更新。

2.2 裝置介面¶

THC支援兩種型別的匯流排用於觸控IC連線：增強型SPI匯流排和I2C匯流排。

2.2.1 SPI埠¶

當MMIO暫存器中的PORT_TYPE = 00b時，THC使用SPI介面與外部觸控IC通訊。 THC增強型SPI匯流排支援不同的SPI模式：標準單I/O模式，雙I/O模式和四路I/O模式。

在單I/O模式下，THC驅動MOSI線以將資料傳送到觸控IC，並從MISO線接收觸控IC的資料。在雙I/O模式下，THC驅動MOSI和MISO都用於資料傳送，並且還在兩條線上接收資料。在四路I/O模式下，添加了其他兩條線（IO2和IO3），THC同時驅動MOSI（IO0），MISO（IO1），IO2和IO3進行資料傳送，並且還在這4條線上接收資料。驅動程式需要透過設定不同的操作碼來在不同模式下配置THC。

除了I/O模式，驅動程式還需要配置SPI匯流排速度。 THC在Intel Lunar Lake平臺上支援高達42MHz的SPI時鐘。

對於THC將資料傳送到觸控IC，SPI總線上的資料流

| --------------------THC sends---------------------------------|
<8Bits OPCode><24Bits Slave Address><Data><Data><Data>...........

對於THC從觸控IC接收資料，SPI總線上的資料流

| ---------THC Sends---------------||-----Touch IC sends--------|
<8Bits OPCode><24Bits Slave Address><Data><Data><Data>...........

2.2.2 I2C埠¶

THC還在其中集成了I2C控制器，稱為I2C SubSystem。當PORT_TYPE = 01時，THC配置為I2C模式。與可以透過MMIO暫存器直接配置的SPI模式相比，THC需要使用PIO讀取（透過設定SubIP讀取操作碼）來獲取I2C subIP APB暫存器的值，並使用PIO寫入（透過設定SubIP寫入操作碼）來進行寫入操作。

2.2.3 GPIO介面¶

THC還包括兩個GPIO引腳，一個用於中斷，另一個用於裝置復位控制。

可以透過設定MMIO控制暫存器將中斷線配置為電平觸發或邊沿觸發。

復位線由BIOS（或EFI）透過ACPI _RST方法控制，驅動程式需要在初始化期間呼叫此裝置ACPI _RST方法來複位觸控IC。

3. 高階概念¶

3.1 操作碼¶

操作碼（operation code）用於告訴THC或觸控IC將要執行的操作，例如PIO讀取或PIO寫入。

當THC配置為SPI模式時，操作碼用於確定讀取/寫入I/O模式。以下是一些SPI I/O模式的操作碼示例

操作碼	對應的SPI命令
0x0B	讀取單路I/O
0x02	寫入單路I/O
0xBB	讀取雙路I/O
0xB2	寫入雙路I/O
0xEB	讀取四路I/O
0xE2	寫入四路I/O

通常，不同的觸控IC具有不同的OPCode定義。根據HIDSPI協議白皮書，這些OPCode在裝置ACPI表中定義，驅動程式需要在驅動程式初始化期間透過OS ACPI API查詢這些資訊，然後使用正確的設定配置THC MMIO OPCode暫存器。

當THC在I2C模式下工作時，操作碼用於告訴THC下一個PIO型別是什麼：I2C SubIP APB暫存器讀取，I2C SubIP APB暫存器寫入，I2C觸控IC裝置讀取，I2C觸控IC裝置寫入，I2C觸控IC裝置寫入，然後讀取。

以下是I2C模式下THC預定義的操作碼

操作碼	對應的I2C命令	地址
0x12	讀取I2C SubIP APB內部暫存器	0h - FFh
0x13	寫入I2C SubIP APB內部暫存器	0h - FFh
0x14	透過I2C匯流排讀取外部觸控IC	N/A
0x18	透過I2C匯流排寫入外部觸控IC	N/A
0x1C	透過I2C匯流排寫入，然後讀取外部觸控IC	N/A

3.2 PIO¶

THC為驅動程式提供了一個程式設計I/O（PIO）訪問介面，以訪問觸控IC的配置暫存器或訪問I2C subIP的配置暫存器。要使用PIO執行I/O操作，驅動程式應預先程式設計PIO控制暫存器和PIO資料暫存器，並啟動序列迴圈。 THC使用不同的PIO操作碼來區分不同的PIO操作（PIO讀取/寫入/寫入後讀取）。

如果正在進行排序迴圈，並且嘗試程式設計任何控制，地址或資料暫存器，則該迴圈將被阻止，並且將遇到序列錯誤。

狀態位指示迴圈何時完成，允許驅動程式知道何時可以檢查讀取結果和/或何時啟動新命令。如果啟用，迴圈完成斷言可以使用中斷中斷驅動程式。

由於THC僅具有16個FIFO暫存器用於PIO，因此透過PIO傳輸的所有資料不應超過64位元組。

由於DMA需要用於傳輸配置的最大資料包大小，並且最大資料包大小資訊始終在HID裝置描述符中，該描述符需要THC驅動程式從HID裝置（觸控IC）中讀取。因此，PIO的典型用例是，在DMA初始化之前，寫入RESET命令（PIO寫入），讀取RESET響應（PIO讀取或PIO寫入後讀取），寫入Power ON命令（PIO寫入），讀取裝置描述符（PIO讀取）。

對於如何發出PIO操作，以下是驅動程式需要遵循的步驟

在THC_SS_BC中程式設計讀取/寫入資料大小。
在THC_SW_SEQ_DATA0_ADDR中程式設計I/O目標地址。
如果寫入，請在THC_SW_SEQ_DATA0..THC_SW_SEQ_DATAn中程式設計寫入資料。
在THC_SS_CMD中程式設計PIO操作碼。
設定TSSGO = 1以啟動PIO寫入序列。
如果THC_SS_CD_IE = 1，則SW將在PIO完成時接收MSI。
如果讀取，則在THC_SW_SEQ_DATA0..THC_SW_SEQ_DATAn中讀取資料。

3.3 DMA¶

THC具有4個DMA通道：讀取DMA1，讀取DMA2，寫入DMA和軟體DMA。

3.3.1 讀取DMA通道¶

THC具有兩個讀取DMA引擎：第一個RxDMA (RxDMA1) 和第二個RxDMA (RxDMA2)。 RxDMA1保留用於原始資料模式。 RxDMA2用於HID資料模式，並且是驅動程式當前用於HID輸入報告資料檢索的RxDMA引擎。

RxDMA的典型用例是自動從觸控IC接收資料。一旦軟體啟用RxDMA，THC將開始自動處理接收邏輯。

對於SPI模式，THC RxDMA序列為：當觸控IC向THC觸發中斷時，THC讀取報告頭以識別報告型別以及報告長度，根據以上資訊，THC讀取報告主體到內部FIFO，並啟動RxDMA將資料複製到系統記憶體。之後，THC使用報告型別更新中斷原因暫存器，並更新RxDMA PRD表讀取指標，然後觸發MSI中斷以通知驅動程式RxDMA完成資料接收。

對於I2C模式，THC RxDMA的行為略有不同，因為HIDI2C協議與HIDSPI協議不同，RxDMA僅用於接收輸入報告。該序列是，當觸控IC向THC觸發中斷時，THC首先從輸入報告地址讀取2個位元組以確定資料包長度，然後使用此資料包長度從輸入報告地址啟動DMA讀取以獲取輸入報告資料。之後，THC更新RxDMA PRD表讀取指標，然後觸發MSI中斷以通知驅動程式輸入報告資料已準備好在系統記憶體中。

以上所有序列都是硬體自動處理的，驅動程式需要做的只是配置RxDMA並等待中斷準備就緒，然後從系統記憶體中讀取資料。

3.3.2 軟體DMA通道¶

THC支援軟體觸發的RxDMA模式，以從觸控IC讀取觸控資料。此SW RxDMA是第三個THC RxDMA引擎，其功能與現有的兩個RxDMA相似，唯一的區別是此SW RxDMA由軟體觸發，而RxDMA2由外部觸控IC中斷觸發。它為軟體驅動程式提供了靈活性，可以隨時使用RxDMA讀取觸控IC資料。

在軟體啟動SW RxDMA之前，應停止第一個和第二個RxDMA，清除PRD讀/寫指標並使裝置中斷靜止（THC_DEVINT_QUIESCE_HW_STS = 1），其他操作與RxDMA相同。

3.3.3 寫入DMA通道¶

THC具有一個寫入DMA引擎，可用於自動將資料傳送到觸控IC。根據HIDSPI和HIDI2C協議，每次只能將一個命令傳送到觸控IC，並且在完全處理完最後一個命令之前，無法傳送下一個命令，THC寫入DMA引擎僅支援單個PRD表。

驅動程式需要做的是，準備PRD表和DMA緩衝區，然後將資料複製到DMA緩衝區，並使用緩衝區地址和緩衝區長度更新PRD表，然後啟動寫入DMA。 THC將自動將資料傳送到觸控IC，並在傳輸完成後觸發DMA完成中斷。

3.4 PRD¶

物理區域描述符（PRD）為THC DMA提供記憶體對映描述。

3.4.1 PRD表和條目¶

為了提高物理DMA記憶體使用率，現代驅動程式趨向於為每個資料緩衝區分配一個虛擬連續但物理上分散的記憶體緩衝區。 Linux作業系統還提供SGL（scatter gather list）API來支援此用法。

THC使用PRD表（物理區域描述符）來支援相應的OS核心SGL，該SGL描述了虛擬到物理的緩衝區對映。

 ------------------------      --------------       --------------
| PRD table base address +----+ PRD table #1 +-----+ PRD Entry #1 |
 ------------------------      --------------       --------------
                                                    --------------
                                                   | PRD Entry #2 |
                                                    --------------
                                                    --------------
                                                   | PRD Entry #n |
                                                    --------------

讀取DMA引擎支援多個PRD表，這些表儲存在迴圈緩衝區中，該迴圈緩衝區允許THC支援來自觸控IC的多個數據緩衝區。這允許主機軟體使用多個緩衝區來武裝讀取DMA引擎，從而允許觸控IC將多個數據幀傳送到THC，而無需SW互動。當CPU處理觸控幀的速度慢於觸控IC傳送它們的速度時，需要此功能。

為了簡化設計，SW假定最壞情況的記憶體碎片。因此，每個PRD表應包含相同數量的PRD條目，從而允許使用全域性暫存器（每個觸控IC）來儲存每個PRD表的PRD條目數。

SW每個讀取DMA引擎最多分配128個PRD表，如THC_M_PRT_RPRD_CNTRL.PCD暫存器欄位中所指定。 PRD表的數量應等於資料緩衝區的數量。

最大OS記憶體碎片將位於4KB邊界，因此，要定址1MB的虛擬連續記憶體，單個PRD表需要256個PRD條目。 SW在THC_M_PRT_RPRD_CNTRL.PTEC暫存器欄位中寫入每個PRD表的PRD條目數。 PRD條目的長度必須是4KB的倍數，除了PRD表中的最後一個條目。

SW僅在主機初始化時分配所有資料緩衝區和PRD表一次。

3.4.2 PRD寫入指標和讀取指標¶

由於PRD表被組織為迴圈緩衝區（CB），因此需要CB的讀取指標和寫入指標。

DMA HW消耗CB中的PRD表，一次消耗一個PRD條目，直到在PRD條目中找到EOP位集。此時，HW遞增PRD讀取指標。因此，讀取指標指向DMA引擎當前正在處理的PRD。一旦迴圈緩衝區的深度被遍歷，此指標就會翻轉，bit[7]是翻轉位。例如，如果DMA CB深度等於4個條目（0011b），則讀取指標將遵循以下模式（HW必須遵守此行為）：00h 01h 02h 03h 80h 81h 82h 83h 00h 01h ...

寫入指標由SW更新。寫入指標指向DMA CB中將要儲存下一個PRD表的位置。 SW需要確保一旦透過Bit[7]作為翻轉位遍歷迴圈緩衝區的深度，此指標就會翻轉。例如，如果DMA CB深度等於5個條目（0100b），則寫入指標將遵循以下模式（SW必須遵守此行為）：00h 01h 02h 03h 04h 80h 81h 82h 83h 84h 00h 01h ..

3.4.3 PRD描述符結構¶

Intel THC為每個PRD條目使用PRD條目描述符。每個PRD條目描述符佔用128位記憶體

結構欄位	位	描述
dest_addr	53..0	目標記憶體地址，由於每個條目為4KB，因此忽略地址的最低10位。
reserved1	54..62	保留
int_on_completion	63	完成中斷使能位，如果設定了此位，則表示THC將觸發完成中斷。此位由SW驅動程式設定。
len	87..64	此條目中有多少位元組的資料。
end_of_prd	88	PRD表位的結尾，如果設定了此位，則表示此條目是此PRD表中的最後一個條目。此位由SW驅動程式設定。
hw_status	90..89	硬體狀態位
reserved2	127..91	保留

一個PRD表最多可以包括256個PRD條目，因為每個條目都是4K位元組，所以每個PRD表可以描述1M位元組的記憶體。

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

通常，每個PRD表都意味著一個HID觸控資料包。每個DMA引擎最多可以支援128個PRD表（寫入DMA除外，寫入DMA只有一個PRD表）。 SW驅動程式負責從觸控IC獲取最大資料包長度，並使用此最大資料包長度為每個PRD表建立PRD條目。

4. HIDSPI支援 (QuickSPI)¶

Intel THC與HIDSPI協議完全相容，THC HW sequenser可以加速HIDSPI協議傳輸。

4.1 復位流程¶

呼叫ACPI _RST方法來複位觸控IC裝置。
透過PIO讀取從TIC讀取復位響應。
發出命令以透過PIO寫入從觸控IC檢索裝置描述符。
透過PIO讀取從觸控IC讀取裝置描述符。
如果裝置描述符有效，請分配DMA緩衝區並配置所有DMA通道。
發出命令以透過DMA從觸控IC檢索報告描述符。

4.2 輸入報告資料流¶

基本流程

觸控IC使用帶內THC中斷中斷THC控制器。
THC Sequencer透過傳送讀取批准作為訊號來讀取輸入報告頭，以告知觸控IC準備好從裝置讀取資料。
THC Sequencer執行與輸入報告頭中的“輸入報告長度”欄位中反映的值相對應的輸入報告主體讀取操作。
THC DMA引擎開始從THC Sequencer提取資料，並將資料寫入當前CB PRD表條目的PRD條目0上的主機記憶體。此過程將繼續，直到THC Sequencer發出訊號表示已讀取所有資料，或者THC DMA讀取引擎到達其最後一個PRD條目的末尾（或兩者都滿足）。
THC Sequencer檢查輸入報告頭中的“Last Fragment Flag”位。如果清除，THC Sequencer將進入空閒狀態。
如果啟用了“Last Fragment Flag”位，則THC Sequencer將進入幀結束處理。

THC Sequencer幀結束處理

THC DMA引擎遞增讀取PRD CB的讀取指標，並在RxDMA2暫存器（THC_M_PRT_READ_DMA_INT_STS_2）中設定EOF中斷狀態。
如果驅動程式在控制暫存器（THC_M_PRT_READ_DMA_CNTRL_2）中啟用了THC EOF中斷，則會生成中斷到軟體。

從RX DMA緩衝區讀取資料的步驟順序

THC QuickSPI驅動程式檢查CB寫入Ptr和CB讀取Ptr，以識別DMA迴圈緩衝區中是否有任何資料幀。
THC QuickSPI驅動程式獲取第一個未處理的PRD表。
THC QuickSPI驅動程式掃描此PRD表中的所有PRD條目以計算總幀大小。
THC QuickSPI驅動程式複製所有幀資料。
THC QuickSPI驅動程式根據輸入報告主體檢查資料型別，並呼叫相關的回撥來處理資料。
THC QuickSPI驅動程式更新寫入Ptr。

4.3 輸出報告資料流¶

通用輸出報告流程

HID核心使用raw_request回撥呼叫請求到THC QuickSPI驅動程式。
THC QuickSPI驅動程式將請求提供的資料轉換為輸出報告資料包，並將其複製到THC的寫入DMA緩衝區。
啟動TxDMA以完成寫入操作。

5. HIDI2C支援 (QuickI2C)¶

5.1 復位流程¶

透過PIO寫入，然後讀取從觸控IC裝置讀取裝置描述符。
如果裝置描述符有效，請分配DMA緩衝區並配置所有DMA通道。
使用PIO或TxDMA將SET_POWER請求寫入TIC的命令暫存器，並檢查寫入操作是否成功完成。
使用PIO或TxDMA將RESET請求寫入TIC的命令暫存器。如果寫入操作成功完成，請等待TIC的復位響應。
使用SWDMA透過TIC的報告描述符暫存器讀取報告描述符。

5.2 輸入報告資料流¶