All of lore.kernel.org
 help / color / mirror / Atom feed
* [PATCH v8 0/5] HID: intel-thc-hid: intel-ipts: support THC IPTS ports
@ 2026-11-18  6:57 Emfox Zhou
  2026-11-18  6:57 ` [PATCH v8 1/5] HID: intel-thc-hid: intel-ipts: bring up the port Emfox Zhou
                   ` (4 more replies)
  0 siblings, 5 replies; 9+ messages in thread
From: Emfox Zhou @ 2026-11-18  6:57 UTC (permalink / raw)
  To: Even Xu, Xinpeng Sun, Jiri Kosina, Benjamin Tissoires
  Cc: linux-input, linux-kernel

The THC ports on Tiger Lake, Lakefield, Alder Lake and Raptor Lake run in
IPTS mode: plain SPI with a private framing instead of HIDSPI, which is
all intel-thc-hid handles today. This adds a backend for them next to
intel-quickspi and intel-quicki2c, on top of the same core.

It is based on v7.4-rc3 with two core fix series applied, both still
under review:

  https://lore.kernel.org/r/20261118053132.253448-1-emfox@debian.org
  https://lore.kernel.org/r/20261117105420.318995-1-emfox@debian.org

One gives the DMA engines a lifetime, the other keeps a PRD table from
overrunning after a reset, and the recovery path here relies on both.
They overlap in intel-thc-dma.c: apply the first, then the second.

Register, DMA and interrupt work goes through the exported intel-thc API,
except in four places where the core has no call for it: the reset,
port-supported and quiesce-state bits of THC_M_PRT_CONTROL are accessed
directly. Nothing outside the new directory changes except Kconfig and
Makefile.

The hardware facts - port IDs, configuration block layout, frame codes and
header sizes - come from the ithc driver linux-surface ships, at
https://github.com/quo/ithc-linux 6d53c9c (dual licensed GPL-2.0 /
BSD-2-Clause); no code is taken from it. The layout, the frame format and
the ordering between quiesce, interrupt configuration and the DMA engines
are the parts most likely to need scrutiny; each is argued in the commit
message that relies on it. All of it was confirmed on a Surface Pro 8 with
a 045e:0c37 controller.

The first four patches each leave a state that builds and loads: port
bring-up, DMA and interrupts, HID registration, system sleep. The fifth
documents the frame format and the IPTS handshake.

Link to v7: https://lore.kernel.org/r/20261118054004.363766-1-emfox@debian.org

Changes in v8:

  - A request from the threaded handler is refused by comparing the caller
    with that thread, not through a device-wide flag.

  - The reset count a feature answer is checked against is sampled after
    the request is written.

  - The line is masked again after synchronize_irq() in the recovery path,
    and the thread no longer reopens it during a teardown.

Emfox Zhou (5):
  HID: intel-thc-hid: intel-ipts: bring up the port
  HID: intel-thc-hid: intel-ipts: receive reports
  HID: intel-thc-hid: intel-ipts: add the HID device
  HID: intel-thc-hid: intel-ipts: handle system sleep
  HID: intel-thc-hid: intel-ipts: document the IPTS mode

 Documentation/hid/intel-thc-hid.rst           | 109 +-
 drivers/hid/intel-thc-hid/Kconfig             |  14 +
 drivers/hid/intel-thc-hid/Makefile            |   4 +
 drivers/hid/intel-thc-hid/intel-ipts/ipts.c   | 982 ++++++++++++++++++
 drivers/hid/intel-thc-hid/intel-ipts/ipts.h   | 201 ++++
 .../hid/intel-thc-hid/intel-ipts/pci-ipts.c   | 193 ++++
 6 files changed, 1502 insertions(+), 1 deletion(-)
 create mode 100644 drivers/hid/intel-thc-hid/intel-ipts/ipts.c
 create mode 100644 drivers/hid/intel-thc-hid/intel-ipts/ipts.h
 create mode 100644 drivers/hid/intel-thc-hid/intel-ipts/pci-ipts.c


base-commit: aebb7274476403040d582c61478df8f4a7bf9cd3

^ permalink raw reply	[flat|nested] 9+ messages in thread

* [PATCH v8 1/5] HID: intel-thc-hid: intel-ipts: bring up the port
  2026-11-18  6:57 [PATCH v8 0/5] HID: intel-thc-hid: intel-ipts: support THC IPTS ports Emfox Zhou
@ 2026-11-18  6:57 ` Emfox Zhou
  2026-11-18  6:57 ` [PATCH v8 2/5] HID: intel-thc-hid: intel-ipts: receive reports Emfox Zhou
                   ` (3 subsequent siblings)
  4 siblings, 0 replies; 9+ messages in thread
From: Emfox Zhou @ 2026-11-18  6:57 UTC (permalink / raw)
  To: Even Xu, Xinpeng Sun, Jiri Kosina, Benjamin Tissoires
  Cc: linux-input, linux-kernel

Ports on Tiger Lake, Lakefield, Alder Lake and Raptor Lake can run in
IPTS mode: instead of HIDSPI the port drives the touch controller over
plain SPI, and the controller answers with a 64 byte configuration
block at address zero that carries the vendor and product IDs, the
buffer sizes and the SPI timing it expects.

Add a port driver that does that much: select the SPI port, release the
controller from reset, read the configuration block over the existing
PIO path, apply the timing the controller asked for and enable the
touch engine. Removal puts it back into reset.

Three things are not obvious from the register names:

  - The bulk data window is at 0x1000, not at zero, and has to be set
    before the DMA engines run: they write there, and left unset they
    write into the configuration block, where the controller drops the
    frames without reporting an error.

  - Quiescing gates the whole data path, not only the interrupt. The
    port stays quiesced while the block is read and the timing applied,
    and is released only once that is done.

  - The edge detect bit belongs to the interrupt setup, but is set
    here: the first configuration read is unreliable without it.

Meteor Lake and newer IDs are deliberately absent: those ports are
already claimed by the HIDSPI driver.

Signed-off-by: Emfox Zhou <emfox@debian.org>
---
 drivers/hid/intel-thc-hid/Kconfig             |  14 +
 drivers/hid/intel-thc-hid/Makefile            |   4 +
 drivers/hid/intel-thc-hid/intel-ipts/ipts.c   | 240 ++++++++++++++++++
 drivers/hid/intel-thc-hid/intel-ipts/ipts.h   | 119 +++++++++
 .../hid/intel-thc-hid/intel-ipts/pci-ipts.c   | 125 +++++++++
 5 files changed, 502 insertions(+)
 create mode 100644 drivers/hid/intel-thc-hid/intel-ipts/ipts.c
 create mode 100644 drivers/hid/intel-thc-hid/intel-ipts/ipts.h
 create mode 100644 drivers/hid/intel-thc-hid/intel-ipts/pci-ipts.c

diff --git a/drivers/hid/intel-thc-hid/Kconfig b/drivers/hid/intel-thc-hid/Kconfig
index 9d74e53b8..3df645f34 100644
--- a/drivers/hid/intel-thc-hid/Kconfig
+++ b/drivers/hid/intel-thc-hid/Kconfig
@@ -40,4 +40,18 @@ config INTEL_QUICKI2C
 
 	  Say Y/M here if you want to support Intel QuickI2C. If unsure, say N.
 
+config INTEL_IPTS
+	tristate "Intel Touch Host Controller IPTS mode"
+	depends on INTEL_THC_HID
+	help
+	  Support for THC ports in IPTS mode. Instead of HIDSPI these ports
+	  drive the touch controller over plain SPI and carry its reports in a
+	  private framing. This driver brings such a port up, reads the
+	  controller's configuration block and exposes the reports as a HID
+	  device, so that a decoder in user space can turn them into input
+	  events.
+
+	  Say Y/M here if you have an Intel touch controller that runs in IPTS
+	  mode. If unsure, say N.
+
 endmenu
diff --git a/drivers/hid/intel-thc-hid/Makefile b/drivers/hid/intel-thc-hid/Makefile
index f1182253b..049009592 100644
--- a/drivers/hid/intel-thc-hid/Makefile
+++ b/drivers/hid/intel-thc-hid/Makefile
@@ -20,4 +20,8 @@ intel-quicki2c-objs += intel-quicki2c/pci-quicki2c.o
 intel-quicki2c-objs += intel-quicki2c/quicki2c-hid.o
 intel-quicki2c-objs += intel-quicki2c/quicki2c-protocol.o
 
+obj-$(CONFIG_INTEL_IPTS) += intel-ipts.o
+intel-ipts-objs += intel-ipts/pci-ipts.o
+intel-ipts-objs += intel-ipts/ipts.o
+
 ccflags-y += -I $(src)/intel-thc
diff --git a/drivers/hid/intel-thc-hid/intel-ipts/ipts.c b/drivers/hid/intel-thc-hid/intel-ipts/ipts.c
new file mode 100644
index 000000000..2d14e5278
--- /dev/null
+++ b/drivers/hid/intel-thc-hid/intel-ipts/ipts.c
@@ -0,0 +1,240 @@
+// SPDX-License-Identifier: GPL-2.0
+/*
+ * Transport for THC ports in IPTS mode: plain SPI with a private framing.
+ */
+
+#include <linux/delay.h>
+#include <linux/math.h>
+#include <linux/regmap.h>
+#include <linux/string.h>
+
+#include "intel-thc-hw.h"
+#include "ipts.h"
+
+/* Bulk transfers have no address phase, so the SPI opcode is zero. */
+#define THC_IPTS_SPI_OPCODE		0
+
+/* Slowest clock the core can program, used until the controller is read. */
+#define THC_IPTS_BOOT_SPI_HZ		THC_IPTS_SPI_MIN_HZ
+
+/* Time the controller needs after reset before it answers on the bus. */
+#define THC_IPTS_BOOT_MS		100
+
+static int thc_ipts_read_cfg(struct thc_ipts *idev)
+{
+	int ret, try;
+
+	for (try = 0; try < THC_IPTS_CFG_TRIES; try++) {
+		u32 got = 0;
+
+		memset(&idev->cfg, 0, sizeof(idev->cfg));
+		ret = thc_tic_pio_read(idev->thc, 0, THC_IPTS_CFG_SIZE, &got,
+				       (u32 *)&idev->cfg);
+		if (!ret && got == THC_IPTS_CFG_SIZE &&
+		    le32_to_cpu(idev->cfg.device_id) == THC_IPTS_TIC_ID)
+			return 0;
+
+		if (try + 1 < THC_IPTS_CFG_TRIES)
+			msleep(THC_IPTS_CFG_RETRY_MS);
+	}
+
+	dev_err(idev->dev,
+		"controller did not answer, last id 0x%08x, error %d\n",
+		le32_to_cpu(idev->cfg.device_id), ret ?: -EIO);
+
+	return ret ?: -EIO;
+}
+
+/* Reading first keeps the core from warning when the state already matches. */
+static int thc_ipts_quiesce(struct thc_ipts *idev, bool quiesce)
+{
+	u32 ctrl;
+	int ret;
+
+	ret = regmap_read(idev->thc->thc_regmap, THC_M_PRT_CONTROL_OFFSET,
+			  &ctrl);
+	if (ret)
+		return ret;
+
+	if (!!(ctrl & THC_M_PRT_CONTROL_THC_DEVINT_QUIESCE_EN) == quiesce)
+		return 0;
+
+	return thc_interrupt_quiesce(idev->thc, quiesce);
+}
+
+static int thc_ipts_spi_set(struct thc_ipts *idev, u32 hz, u32 mode)
+{
+	int ret;
+
+	/* No multi-packet transfers in this mode, so both sizes stay zero. */
+	ret = thc_spi_read_config(idev->thc, hz, mode, THC_IPTS_SPI_OPCODE, 0);
+	if (ret)
+		return ret;
+
+	return thc_spi_write_config(idev->thc, hz, mode, THC_IPTS_SPI_OPCODE,
+				     0, 0);
+}
+
+/* The core takes the fastest gear that is not above the request. */
+static void thc_ipts_spi_from_cfg(struct thc_ipts *idev, u32 *hz, u32 *mode)
+{
+	u32 cfg = le32_to_cpu(idev->cfg.spi_cfg);
+	u32 div = THC_IPTS_SPI_CLKDIV(cfg);
+
+	if (!div) {
+		dev_warn_once(idev->dev, "controller asks for divisor 0\n");
+		*hz = THC_IPTS_SPI_MIN_HZ;
+	} else {
+		u32 step = THC_IPTS_SPI_BASE_HZ / div;
+
+		if (cfg & THC_IPTS_SPI_CLKDIV8)
+			step /= THC_IPTS_SPI_CLKDIV8_DIV;
+
+		/* Gears compare rounded to 100 Hz: round the same way, or
+		 * divisor 3 falls below the 41 MHz gear.
+		 */
+		*hz = DIV_ROUND_CLOSEST(step, 100) * 100;
+	}
+
+	/*
+	 * THC_IPTS_SPI_MIN_HZ is the slowest gear the core has, so a lower
+	 * request would be refused: run at the floor and keep the port.
+	 */
+	if (*hz < THC_IPTS_SPI_MIN_HZ) {
+		dev_warn_once(idev->dev,
+			      "controller asks for %u Hz, running at %u Hz\n",
+			      *hz, THC_IPTS_SPI_MIN_HZ);
+		*hz = THC_IPTS_SPI_MIN_HZ;
+	}
+
+	if (cfg & THC_IPTS_SPI_QUAD)
+		*mode = THC_QUAD_IO;
+	else if (cfg & THC_IPTS_SPI_DUAL)
+		*mode = THC_DUAL_IO;
+	else
+		*mode = THC_SINGLE_IO;
+}
+
+static int thc_ipts_touch_set(struct thc_ipts *idev, bool enable)
+{
+	u32 touch = le32_to_cpu(idev->cfg.touch_cfg);
+
+	touch &= ~(THC_IPTS_TOUCH_POWER_MASK | THC_IPTS_TOUCH_ENABLE |
+		   THC_IPTS_TOUCH_HID_REPORT);
+	touch |= THC_IPTS_TOUCH_POWER(enable ? THC_IPTS_TOUCH_POWER_ON : 0);
+	if (enable)
+		touch |= THC_IPTS_TOUCH_ENABLE | THC_IPTS_TOUCH_HID_REPORT;
+
+	return thc_tic_pio_write(idev->thc, THC_IPTS_CFG_TOUCH, sizeof(touch),
+				 &touch);
+}
+
+/**
+ * thc_ipts_port_start - bring one port up
+ * @idev: port to start
+ */
+int thc_ipts_port_start(struct thc_ipts *idev)
+{
+	u32 ctrl, hz, mode;
+	int ret;
+
+	ret = thc_ipts_quiesce(idev, true);
+	if (ret)
+		return ret;
+
+	ret = thc_port_select(idev->thc, THC_PORT_TYPE_SPI);
+	if (ret)
+		return ret;
+
+	ret = regmap_read(idev->thc->thc_regmap, THC_M_PRT_CONTROL_OFFSET,
+			  &ctrl);
+	if (ret)
+		return ret;
+	if (!(ctrl & THC_M_PRT_CONTROL_PORT_SUPPORTED))
+		return -ENODEV;
+
+	/* Without this the engines write into the configuration block. */
+	thc_spi_input_output_address_config(idev->thc, 0, THC_IPTS_BULK_ADDR,
+					    THC_IPTS_BULK_ADDR);
+
+	/*
+	 * Firmware may leave the receive engines armed with the PRD base of
+	 * whatever it had mapped. Stop them before the controller starts
+	 * pushing frames again, or those frames land in stale pages.
+	 */
+	thc_dma_unconfigure(idev->thc);
+
+	ret = thc_ipts_spi_set(idev, THC_IPTS_BOOT_SPI_HZ, THC_SINGLE_IO);
+	if (ret)
+		return ret;
+
+	/* The first configuration read is unreliable without edge detect. */
+	thc_int_trigger_type_select(idev->thc, true);
+
+	/*
+	 * Release the controller from reset; it answers only after this.
+	 * The bit is the reset request and one means out of reset, so it has
+	 * to be written whatever it reads back.
+	 */
+	ret = regmap_write_bits(idev->thc->thc_regmap, THC_M_PRT_CONTROL_OFFSET,
+				THC_M_PRT_CONTROL_DEVRST,
+				THC_M_PRT_CONTROL_DEVRST);
+	if (ret)
+		return ret;
+
+	msleep(THC_IPTS_BOOT_MS);
+
+	ret = thc_ipts_read_cfg(idev);
+	if (ret)
+		return ret;
+
+	idev->vendor = le16_to_cpu(idev->cfg.vendor);
+	idev->product = le16_to_cpu(idev->cfg.product);
+	idev->max_rx = THC_IPTS_RX_BUF_SIZE(le32_to_cpu(idev->cfg.buf_sizes));
+	idev->max_tx = THC_IPTS_TX_BUF_SIZE(le32_to_cpu(idev->cfg.buf_sizes));
+	/* TX_BUF_SIZE() never goes below 64, so only the rx half can fail. */
+	if (idev->max_rx <= THC_IPTS_RX_HDR_SIZE) {
+		dev_err(idev->dev, "receive buffer of %zu bytes is too small\n",
+			idev->max_rx);
+		return -ENODEV;
+	}
+	thc_ipts_spi_from_cfg(idev, &hz, &mode);
+	ret = thc_ipts_spi_set(idev, hz, mode);
+	if (ret) {
+		dev_warn(idev->dev,
+			 "cannot follow the SPI timing, going slow\n");
+		ret = thc_ipts_spi_set(idev, THC_IPTS_BOOT_SPI_HZ,
+				       THC_SINGLE_IO);
+		if (ret)
+			return ret;
+	} else {
+		dev_dbg(idev->dev, "SPI clock asked for %u Hz\n", hz);
+	}
+
+	ret = thc_ipts_quiesce(idev, false);
+	if (ret)
+		return ret;
+
+	ret = thc_ipts_touch_set(idev, true);
+	if (ret)
+		return ret;
+	idev->running = true;
+
+	return 0;
+}
+
+/**
+ * thc_ipts_port_stop - tear one port down
+ * @idev: port to stop
+ */
+void thc_ipts_port_stop(struct thc_ipts *idev)
+{
+	if (idev->running)
+		thc_ipts_touch_set(idev, false);
+
+	idev->running = false;
+	/* Forced: the bit may read as clear and still need the command. */
+	regmap_write_bits(idev->thc->thc_regmap, THC_M_PRT_CONTROL_OFFSET,
+			  THC_M_PRT_CONTROL_DEVRST, 0);
+	thc_ipts_quiesce(idev, true);
+}
diff --git a/drivers/hid/intel-thc-hid/intel-ipts/ipts.h b/drivers/hid/intel-thc-hid/intel-ipts/ipts.h
new file mode 100644
index 000000000..b4ce633fc
--- /dev/null
+++ b/drivers/hid/intel-thc-hid/intel-ipts/ipts.h
@@ -0,0 +1,119 @@
+/* SPDX-License-Identifier: GPL-2.0 */
+#ifndef _THC_IPTS_H_
+#define _THC_IPTS_H_
+
+#include <linux/bitfield.h>
+#include <linux/bits.h>
+#include <linux/build_bug.h>
+#include <linux/device.h>
+#include <linux/interrupt.h>
+#include <linux/types.h>
+
+#include "intel-thc-dev.h"
+
+/* Configuration block the controller keeps at address zero. */
+#define THC_IPTS_CFG_SIZE		64
+#define THC_IPTS_CFG_TOUCH		0x0c
+#define THC_IPTS_TIC_ID		0x43495424	/* "$TIC" */
+
+/* Bulk data window. The DMA engines have to be pointed here, not at zero. */
+#define THC_IPTS_BULK_ADDR		0x1000
+
+#define PCI_DEVICE_ID_INTEL_THC_LKF_PORT1	0x98d0
+#define PCI_DEVICE_ID_INTEL_THC_LKF_PORT2	0x98d1
+#define PCI_DEVICE_ID_INTEL_THC_TGL_LP_PORT1	0xa0d0
+#define PCI_DEVICE_ID_INTEL_THC_TGL_LP_PORT2	0xa0d1
+#define PCI_DEVICE_ID_INTEL_THC_TGL_H_PORT1	0x43d0
+#define PCI_DEVICE_ID_INTEL_THC_TGL_H_PORT2	0x43d1
+#define PCI_DEVICE_ID_INTEL_THC_ADL_S_PORT1	0x7ad8
+#define PCI_DEVICE_ID_INTEL_THC_ADL_S_PORT2	0x7ad9
+#define PCI_DEVICE_ID_INTEL_THC_ADL_P_PORT1	0x51d0
+#define PCI_DEVICE_ID_INTEL_THC_ADL_P_PORT2	0x51d1
+#define PCI_DEVICE_ID_INTEL_THC_ADL_M_PORT1	0x54d0
+#define PCI_DEVICE_ID_INTEL_THC_ADL_M_PORT2	0x54d1
+#define PCI_DEVICE_ID_INTEL_THC_RPL_S_PORT1	0x7a58
+#define PCI_DEVICE_ID_INTEL_THC_RPL_S_PORT2	0x7a59
+
+/* The block fills in while the controller starts, so $TIC is retried. */
+#define THC_IPTS_CFG_TRIES		10
+#define THC_IPTS_CFG_RETRY_MS		100
+
+#define THC_IPTS_CFG_KNOWN		40
+
+/* The block as far as this driver reads it, padded to its full size. */
+struct thc_ipts_cfg {
+	__le32	irq_cause;
+	__le32	error;		/* protocol error flags, not used */
+	__le32	buf_sizes;	/* Rx/Tx sizes, see *_BUF_SIZE() */
+	__le32	touch_cfg;	/* touch engine control, writable */
+	__le32	touch_state;	/* touch engine state, not used */
+	__le32	device_id;	/* THC_IPTS_TIC_ID after a good read */
+	__le32	spi_cfg;
+	__le16	vendor;
+	__le16	product;
+	__le32	revision;
+	__le32	fw_version;
+	u8	rest[THC_IPTS_CFG_SIZE - THC_IPTS_CFG_KNOWN];
+};
+
+static_assert(sizeof(struct thc_ipts_cfg) == THC_IPTS_CFG_SIZE);
+
+/* The core is handed the struct itself, so the offsets are part of the deal. */
+static_assert(offsetof(struct thc_ipts_cfg, buf_sizes) == 0x08);
+static_assert(offsetof(struct thc_ipts_cfg, touch_cfg) == 0x0c);
+static_assert(offsetof(struct thc_ipts_cfg, spi_cfg) == 0x18);
+static_assert(offsetof(struct thc_ipts_cfg, vendor) == 0x1c);
+
+/* Buffer sizes are stored as (size / 64) - 1, Rx in bits 13:0, Tx in 23:14. */
+#define THC_IPTS_DMA_UNIT		64
+#define THC_IPTS_RX_BUF_SIZE(val)	\
+	((size_t)(FIELD_GET(GENMASK(13, 0), (val)) + 1) * THC_IPTS_DMA_UNIT)
+#define THC_IPTS_TX_BUF_SIZE(val)	\
+	((size_t)(FIELD_GET(GENMASK(23, 14), (val)) + 1) * THC_IPTS_DMA_UNIT)
+
+#define THC_IPTS_TOUCH_ENABLE		BIT(0)
+#define THC_IPTS_TOUCH_HID_REPORT	BIT(2)
+#define THC_IPTS_TOUCH_POWER_ON	3
+#define THC_IPTS_TOUCH_POWER_MASK	GENMASK(5, 3)
+#define THC_IPTS_TOUCH_POWER(val)	\
+	FIELD_PREP(THC_IPTS_TOUCH_POWER_MASK, (val))
+
+#define THC_IPTS_SPI_CLKDIV(val)	FIELD_GET(GENMASK(3, 1), (val))
+#define THC_IPTS_SPI_CLKDIV8		BIT(4)
+#define THC_IPTS_SPI_CLKDIV8_DIV	8
+#define THC_IPTS_SPI_DUAL		BIT(6)
+#define THC_IPTS_SPI_QUAD		BIT(7)
+#define THC_IPTS_SPI_BASE_HZ		125000000
+/* Slowest gear in the core's SPI table; anything under it is refused. */
+#define THC_IPTS_SPI_MIN_HZ		7812500
+
+/* Code and length in front of the payload; the long one is inbound. */
+#define THC_IPTS_RX_HDR_SIZE		64
+#define THC_IPTS_TX_HDR_SIZE		8
+
+/**
+ * struct thc_ipts - state of one THC port in IPTS mode
+ * @dev: device used for resources and logging
+ * @thc: shared THC core context
+ * @cfg: configuration block last read from the controller
+ * @vendor: vendor ID the controller reports for its HID device
+ * @product: product ID the controller reports for its HID device
+ * @max_rx: largest frame the controller may send, in bytes
+ * @max_tx: largest frame the driver may send, in bytes
+ * @running: the controller answered and is out of reset
+ */
+struct thc_ipts {
+	struct device		*dev;
+	struct thc_device	*thc;
+	struct thc_ipts_cfg	cfg;
+	u16			vendor;
+	u16			product;
+	size_t			max_rx;
+	size_t			max_tx;
+	bool			running;
+};
+
+int thc_ipts_port_start(struct thc_ipts *idev);
+void thc_ipts_port_stop(struct thc_ipts *idev);
+
+#endif /* _THC_IPTS_H_ */
diff --git a/drivers/hid/intel-thc-hid/intel-ipts/pci-ipts.c b/drivers/hid/intel-thc-hid/intel-ipts/pci-ipts.c
new file mode 100644
index 000000000..48046cd12
--- /dev/null
+++ b/drivers/hid/intel-thc-hid/intel-ipts/pci-ipts.c
@@ -0,0 +1,125 @@
+// SPDX-License-Identifier: GPL-2.0
+/*
+ * PCI glue for the Intel Touch Host Controller in IPTS mode. Ports that
+ * the HIDSPI driver already claims are deliberately left out of the ID table.
+ */
+
+#include <linux/dma-mapping.h>
+#include <linux/module.h>
+#include <linux/pci.h>
+#include <linux/workqueue.h>
+
+#include "ipts.h"
+
+static const struct pci_device_id thc_ipts_pci_ids[] = {
+	/* Lakefield */
+	{PCI_DEVICE_DATA(INTEL, THC_LKF_PORT1, NULL)},
+	{PCI_DEVICE_DATA(INTEL, THC_LKF_PORT2, NULL)},
+	/* Tiger Lake */
+	{PCI_DEVICE_DATA(INTEL, THC_TGL_LP_PORT1, NULL)},
+	{PCI_DEVICE_DATA(INTEL, THC_TGL_LP_PORT2, NULL)},
+	{PCI_DEVICE_DATA(INTEL, THC_TGL_H_PORT1, NULL)},
+	{PCI_DEVICE_DATA(INTEL, THC_TGL_H_PORT2, NULL)},
+	/* Alder Lake */
+	{PCI_DEVICE_DATA(INTEL, THC_ADL_S_PORT1, NULL)},
+	{PCI_DEVICE_DATA(INTEL, THC_ADL_S_PORT2, NULL)},
+	{PCI_DEVICE_DATA(INTEL, THC_ADL_P_PORT1, NULL)},
+	{PCI_DEVICE_DATA(INTEL, THC_ADL_P_PORT2, NULL)},
+	{PCI_DEVICE_DATA(INTEL, THC_ADL_M_PORT1, NULL)},
+	{PCI_DEVICE_DATA(INTEL, THC_ADL_M_PORT2, NULL)},
+	/* Raptor Lake */
+	{PCI_DEVICE_DATA(INTEL, THC_RPL_S_PORT1, NULL)},
+	{PCI_DEVICE_DATA(INTEL, THC_RPL_S_PORT2, NULL)},
+	{}
+};
+MODULE_DEVICE_TABLE(pci, thc_ipts_pci_ids);
+
+static int thc_ipts_probe(struct pci_dev *pci, const struct pci_device_id *id)
+{
+	struct thc_ipts *idev;
+	void __iomem *mem;
+	int ret;
+
+	idev = devm_kzalloc_obj(&pci->dev, *idev);
+	if (!idev)
+		return -ENOMEM;
+
+	idev->dev = &pci->dev;
+	pci_set_drvdata(pci, idev);
+
+	ret = pcim_enable_device(pci);
+	if (ret) {
+		dev_err(idev->dev,
+			"cannot enable the PCI function, error %d\n", ret);
+		return ret;
+	}
+
+	pci_set_master(pci);
+
+	mem = pcim_iomap_region(pci, 0, KBUILD_MODNAME);
+	ret = PTR_ERR_OR_ZERO(mem);
+	if (ret) {
+		dev_err(idev->dev, "cannot map the register space, error %d\n",
+			ret);
+		return ret;
+	}
+
+	ret = dma_set_mask_and_coherent(idev->dev, DMA_BIT_MASK(64));
+	if (ret)
+		ret = dma_set_mask_and_coherent(idev->dev, DMA_BIT_MASK(32));
+	if (ret) {
+		dev_err(idev->dev, "no usable DMA configuration, error %d\n",
+			ret);
+		return ret;
+	}
+
+	idev->thc = thc_dev_init(idev->dev, mem);
+	if (IS_ERR(idev->thc))
+		return PTR_ERR(idev->thc);
+
+	ret = thc_ipts_port_start(idev);
+	if (ret) {
+		thc_ipts_port_stop(idev);
+		return ret;
+	}
+
+	dev_info(idev->dev, "controller %04x:%04x rev %u, firmware 0x%08x\n",
+		 idev->vendor, idev->product, le32_to_cpu(idev->cfg.revision),
+		 le32_to_cpu(idev->cfg.fw_version));
+	dev_info(idev->dev, "spi cfg 0x%08x, rx %zu tx %zu bytes\n",
+		 le32_to_cpu(idev->cfg.spi_cfg), idev->max_rx, idev->max_tx);
+
+	return 0;
+}
+
+static void thc_ipts_remove(struct pci_dev *pci)
+{
+	struct thc_ipts *idev = pci_get_drvdata(pci);
+
+	thc_ipts_port_stop(idev);
+	pci_clear_master(pci);
+}
+
+static void thc_ipts_shutdown(struct pci_dev *pci)
+{
+	struct thc_ipts *idev = pci_get_drvdata(pci);
+
+	if (idev)
+		thc_ipts_port_stop(idev);
+}
+
+static struct pci_driver thc_ipts_driver = {
+	.name		= "intel-ipts",
+	.id_table	= thc_ipts_pci_ids,
+	.probe		= thc_ipts_probe,
+	.remove		= thc_ipts_remove,
+	.shutdown	= thc_ipts_shutdown,
+	/* Bring-up waits for the controller, up to a few seconds. */
+	.driver.probe_type = PROBE_PREFER_ASYNCHRONOUS,
+};
+module_pci_driver(thc_ipts_driver);
+
+MODULE_AUTHOR("Emfox Zhou <emfox@debian.org>");
+MODULE_DESCRIPTION("IPTS transport for the Intel Touch Host Controller");
+MODULE_LICENSE("GPL");
+MODULE_IMPORT_NS("INTEL_THC");

^ permalink raw reply related	[flat|nested] 9+ messages in thread

* [PATCH v8 2/5] HID: intel-thc-hid: intel-ipts: receive reports
  2026-11-18  6:57 [PATCH v8 0/5] HID: intel-thc-hid: intel-ipts: support THC IPTS ports Emfox Zhou
  2026-11-18  6:57 ` [PATCH v8 1/5] HID: intel-thc-hid: intel-ipts: bring up the port Emfox Zhou
@ 2026-11-18  6:57 ` Emfox Zhou
  2026-11-18  7:19   ` sashiko-bot
  2026-11-18  6:57 ` [PATCH v8 3/5] HID: intel-thc-hid: intel-ipts: add the HID device Emfox Zhou
                   ` (2 subsequent siblings)
  4 siblings, 1 reply; 9+ messages in thread
From: Emfox Zhou @ 2026-11-18  6:57 UTC (permalink / raw)
  To: Even Xu, Xinpeng Sun, Jiri Kosina, Benjamin Tissoires
  Cc: linux-input, linux-kernel

Configure the receive and transmit DMA engines, take the port interrupt
and decode the frames that arrive.

Interrupt remapping rejects the MSI requests these ports send: the
requester ID in them is 01:05.0, neither the port's own function nor a
valid DMA alias for it, so only the legacy interrupt pin works once
remapping is on. MSI is the fallback for a platform that does not route
that pin. The pin is shared with other functions on the PCH, and such a
line only takes handlers that agree on oneshot, so the request asks for
it only if a sharer uses it. The hardirq masks the port itself, so a
foreign interrupt costs at most a few register reads in the thread, and
is reported as not handled.

Transfer errors are recovered from a work item and not from the threaded
handler: thc_rxdma_reset() takes the bus lock, and the core's write path
holds that lock while it waits for the very completion the handler
delivers. The port is masked as soon as the reset is queued, and the
threaded handler stops touching the status registers once the reset runs:
acknowledging a frame it is not going to read would lose the interrupt
that announces it again. The thread masks the port on entry as well,
because a sharer can queue a second run through IRQTF_RUNTHREAD with no
hardirq of ours in between. A run that is already inside can unmask just
before the wait for it returns, so the reset masks the line once more
before it touches the engines, and the thread leaves the line open only
when neither a reset nor a teardown is in flight.

Every frame carries a code and a length in front of the payload. The
receive side decodes that header and logs each frame.

Three details of the bring-up are worth spelling out:

  - The interrupt configuration has to be applied before the DMA engines
    are started: it programs the device interrupt type field to the
    invalid value, and starting the receive engine then replaces that
    field with the type it expects. The other order would leave the
    invalid value in place.

  - An event that arrives while the thread runs leaves nothing behind but
    its status bit, so the handler drains the status registers instead of
    trusting a single delivery: a write completion taken for granted this
    way makes the next transfer wait for a completion that never comes,
    and the port stays unusable until it is reset.

  - Bulk transfers have no address phase, so the SPI opcode is zero. The
    opcodes the HIDSPI path uses make this controller ignore the frames
    altogether.

The frame size the controller reports is bounded by the receive ring, one
page per PRD entry: a port that asks for a larger buffer is refused with
an explicit error instead of failing in sgl_alloc().

The reset covers the host side only and leaves the PRD table descriptors
the controller rewrites in place: taking a frame puts its entry back, but
a frame that is not read keeps the length the controller wrote, and the
next frame that does not fit ends in a PRD overrun. intel-quickspi and
intel-quicki2c recover through the same call and have the same gap.
Restoring those descriptors is the core's job, not this driver's, and a
separate change to intel-thc does it.

Signed-off-by: Emfox Zhou <emfox@debian.org>
---
 drivers/hid/intel-thc-hid/intel-ipts/ipts.c   | 319 ++++++++++++++++++
 drivers/hid/intel-thc-hid/intel-ipts/ipts.h   |  26 ++
 .../hid/intel-thc-hid/intel-ipts/pci-ipts.c   |  40 +++
 3 files changed, 385 insertions(+)

diff --git a/drivers/hid/intel-thc-hid/intel-ipts/ipts.c b/drivers/hid/intel-thc-hid/intel-ipts/ipts.c
index 2d14e5278..e7896b16f 100644
--- a/drivers/hid/intel-thc-hid/intel-ipts/ipts.c
+++ b/drivers/hid/intel-thc-hid/intel-ipts/ipts.c
@@ -5,8 +5,13 @@
 
 #include <linux/delay.h>
 #include <linux/math.h>
+#include <linux/interrupt.h>
+#include <linux/minmax.h>
 #include <linux/regmap.h>
+#include <linux/sizes.h>
 #include <linux/string.h>
+#include <linux/unaligned.h>
+#include <linux/workqueue.h>
 
 #include "intel-thc-hw.h"
 #include "ipts.h"
@@ -17,9 +22,19 @@
 /* Slowest clock the core can program, used until the controller is read. */
 #define THC_IPTS_BOOT_SPI_HZ		THC_IPTS_SPI_MIN_HZ
 
+/* One page per PRD entry; a larger frame cannot be received. */
+#define THC_IPTS_RX_MAX			(PRD_ENTRIES_NUM * SZ_4K)
+
 /* Time the controller needs after reset before it answers on the bus. */
 #define THC_IPTS_BOOT_MS		100
 
+/*
+ * The core stops at the first error cause and reports the rest as a mask, so
+ * reading until it finds nothing can take a pass per cause plus one that
+ * confirms the status is drained.
+ */
+#define THC_IPTS_IRQ_PASSES		(THC_UNKNOWN_INT + 1)
+
 static int thc_ipts_read_cfg(struct thc_ipts *idev)
 {
 	int ret, try;
@@ -129,6 +144,283 @@ static int thc_ipts_touch_set(struct thc_ipts *idev, bool enable)
 				 &touch);
 }
 
+static void thc_ipts_handle_frame(struct thc_ipts *idev, size_t len)
+{
+	size_t capacity = idev->max_rx - THC_IPTS_RX_HDR_SIZE;
+	u32 code, size;
+
+	if (len < THC_IPTS_RX_HDR_SIZE)
+		return;
+
+	code = get_unaligned_le32(idev->rx_frame);
+	/* The header may claim more than what actually arrived. */
+	size = min_t(u32, get_unaligned_le32(idev->rx_frame + 4),
+		     capacity);
+	size = min_t(u32, size, len - THC_IPTS_RX_HDR_SIZE);
+
+	dev_dbg(idev->dev, "frame code %u, %u bytes\n", code, size);
+}
+
+static void thc_ipts_dma_stop(struct thc_ipts *idev)
+{
+	if (!idev->dma_ready)
+		return;
+
+	WRITE_ONCE(idev->dma_ready, false);
+	thc_dma_unconfigure(idev->thc);
+	thc_dma_release(idev->thc);
+}
+
+static int thc_ipts_resize(struct thc_ipts *idev, u8 **buf, size_t *have,
+			   size_t want)
+{
+	u8 *p;
+
+	if (*have >= want)
+		return 0;
+
+	p = devm_krealloc(idev->dev, *buf, want, GFP_KERNEL);
+	if (!p)
+		return -ENOMEM;
+
+	*buf = p;
+	*have = want;
+
+	return 0;
+}
+
+static int thc_ipts_dma_start(struct thc_ipts *idev)
+{
+	int ret;
+
+	/*
+	 * The receive ring has one page per PRD entry and the core refuses a
+	 * frame that needs more: bound it here, or the port fails with a bare
+	 * allocation error from sgl_alloc().
+	 */
+	if (idev->max_rx > THC_IPTS_RX_MAX) {
+		dev_err(idev->dev, "receive buffer of %zu bytes is too large\n",
+			idev->max_rx);
+		return -ENODEV;
+	}
+
+	/*
+	 * A resume can report larger limits than the probe did, and the
+	 * engines would then write past the end. Follow them on every start;
+	 * the receive buffer is rounded up because the core rounds to a page.
+	 */
+	ret = thc_ipts_resize(idev, &idev->rx_frame, &idev->buf_rx,
+			      round_up(idev->max_rx, SZ_4K));
+	if (ret)
+		return ret;
+
+	ret = thc_dma_set_max_packet_sizes(idev->thc, 0, idev->max_rx,
+					   idev->max_tx, 0);
+	if (ret)
+		return ret;
+
+	ret = thc_dma_allocate(idev->thc);
+	if (ret)
+		return ret;
+
+	ret = thc_dma_configure(idev->thc);
+	if (ret) {
+		thc_dma_release(idev->thc);
+		return ret;
+	}
+
+	WRITE_ONCE(idev->dma_ready, true);
+
+	return 0;
+}
+
+irqreturn_t thc_ipts_hardirq(int irq, void *data)
+{
+	struct thc_ipts *idev = data;
+
+	/* Nothing of ours is pending: the cause belongs to a sharer. */
+	if (!READ_ONCE(idev->dma_ready))
+		return IRQ_NONE;
+
+	/* Level triggered and shared: mask first, or it stays asserted. */
+	thc_interrupt_enable(idev->thc, false);
+
+	/*
+	 * A reset or a teardown in flight still gets the thread: the status it
+	 * drains is where a pending transmit completion is delivered, and a
+	 * write waiting for that one holds the bus lock the reset needs.
+	 */
+	return IRQ_WAKE_THREAD;
+}
+
+static int thc_ipts_read_frames(struct thc_ipts *idev)
+{
+	for (;;) {
+		int finished = 0;
+		size_t len = 0;
+
+		if (thc_rxdma_read(idev->thc, THC_RXDMA2, idev->rx_frame,
+				   &len, &finished)) {
+			dev_warn_once(idev->dev,
+				      "cannot read a frame from the engine\n");
+			return -EIO;
+		}
+
+		if (!len)
+			break;
+
+		thc_ipts_handle_frame(idev, len);
+		if (finished)
+			break;
+	}
+
+	return 0;
+}
+
+/*
+ * Refuse new requests and queue the reset. The line stays open: a write that
+ * is already waiting for its completion needs this interrupt, and the work
+ * item takes the port once that write is done.
+ */
+static void thc_ipts_request_recover(struct thc_ipts *idev)
+{
+	if (READ_ONCE(idev->recover_pending))
+		return;
+
+	WRITE_ONCE(idev->recover_pending, true);
+	schedule_work(&idev->recover_work);
+}
+
+/*
+ * From a work item: the reset waits for the bus lock a pending write holds
+ * until the threaded handler delivers its completion.
+ */
+void thc_ipts_recover(struct work_struct *work)
+{
+	struct thc_ipts *idev = container_of(work, struct thc_ipts,
+					     recover_work);
+
+	/*
+	 * From here the status registers belong to the reset: the threaded
+	 * handler must not acknowledge a frame it is not going to read, or the
+	 * interrupt that would announce it again never comes. The flag alone
+	 * is only a snapshot to a run that is already inside, so the mask and
+	 * the wait below are what keeps that run out.
+	 */
+	WRITE_ONCE(idev->recovering, true);
+	thc_interrupt_enable(idev->thc, false);
+	synchronize_irq(idev->irq);
+	/* A run that unmasked just before synchronize_irq() returned leaves
+	 * the line open: mask it again, the write is idempotent.
+	 */
+	thc_interrupt_enable(idev->thc, false);
+
+	if (thc_rxdma_reset(idev->thc)) {
+		/* Nothing left: keep the port masked until it restarts. */
+		dev_err(idev->dev, "cannot reset the receive engine\n");
+		return;
+	}
+
+	/* The reset drops whatever the engines had queued. A run of the
+	 * handler that sees ->recovering clear must not be turned away by
+	 * ->recover_pending afterwards, so that one is cleared first.
+	 */
+	WRITE_ONCE(idev->recover_seq, READ_ONCE(idev->recover_seq) + 1);
+	WRITE_ONCE(idev->recover_pending, false);
+	WRITE_ONCE(idev->recovering, false);
+	if (!READ_ONCE(idev->stopping))
+		thc_interrupt_enable(idev->thc, true);
+}
+
+irqreturn_t thc_ipts_thread(int irq, void *data)
+{
+	struct thc_ipts *idev = data;
+	irqreturn_t ret = IRQ_NONE;
+	bool need_recover = false;
+	bool reported = false;
+	int pass;
+
+	/* Reports are handed to the HID core from here, and a driver callback
+	 * that sends a request would wait for a completion this very thread
+	 * delivers: it is recorded so the send path can tell.
+	 */
+	WRITE_ONCE(idev->irq_thread, current);
+
+	/* A sharer can queue a second run of this thread with no hardirq of
+	 * ours in between: mask again, the write is idempotent.
+	 */
+	thc_interrupt_enable(idev->thc, false);
+
+	/* The port stays masked, so a cause that arrives meanwhile leaves only
+	 * its status bit: read until the core reports none.
+	 */
+	for (pass = 0; pass < THC_IPTS_IRQ_PASSES; pass++) {
+		int mask;
+
+		/*
+		 * The reset owns the status registers while it runs: a frame
+		 * acknowledged here but not read is never announced again.
+		 */
+		if (READ_ONCE(idev->recovering)) {
+			/* Nothing acknowledged, but the line is still ours. */
+			ret = IRQ_HANDLED;
+			break;
+		}
+
+		mask = thc_interrupt_handler(idev->thc);
+
+		if (mask == BIT(THC_UNKNOWN_INT))
+			break;
+
+		ret = IRQ_HANDLED;
+		if (mask & (BIT(THC_FATAL_ERR_INT) | BIT(THC_TXN_ERR_INT))) {
+			/* An overrun raises this for every frame until the
+			 * reset takes the port: report the first one only.
+			 */
+			if (!reported) {
+				dev_err(idev->dev,
+					"transfer error, resetting the engine\n");
+				reported = true;
+			}
+			/* The teardown has its own reset to wait for. */
+			if (!READ_ONCE(idev->stopping))
+				need_recover = true;
+			/* The core stops at the first cause: a Tx completion
+			 * behind the error would time out under the bus lock.
+			 */
+			continue;
+		}
+
+		/* A reset is queued or running, or the port is going away: the
+		 * ring is not ours to read, only its status was.
+		 */
+		if (need_recover || READ_ONCE(idev->recover_pending) ||
+		    READ_ONCE(idev->recovering) ||
+		    READ_ONCE(idev->stopping))
+			continue;
+
+		if (mask & BIT(THC_RXDMA2_INT) && thc_ipts_read_frames(idev))
+			need_recover = true;
+	}
+
+	/* The work item resets the engine and unmasks again; a frame read
+	 * meanwhile would corrupt the ring.
+	 */
+	if (need_recover) {
+		thc_ipts_request_recover(idev);
+		return IRQ_HANDLED;
+	}
+
+	/* A reset unmasks when it is done and a teardown masks on its own, so
+	 * the line only stays open here while neither runs: a write already
+	 * on the wire needs the completion this handler delivers.
+	 */
+	if (!READ_ONCE(idev->recovering) && !READ_ONCE(idev->stopping))
+		thc_interrupt_enable(idev->thc, true);
+
+	return ret;
+}
+
 /**
  * thc_ipts_port_start - bring one port up
  * @idev: port to start
@@ -138,6 +430,9 @@ int thc_ipts_port_start(struct thc_ipts *idev)
 	u32 ctrl, hz, mode;
 	int ret;
 
+	WRITE_ONCE(idev->stopping, false);
+	WRITE_ONCE(idev->recovering, false);
+
 	ret = thc_ipts_quiesce(idev, true);
 	if (ret)
 		return ret;
@@ -220,6 +515,15 @@ int thc_ipts_port_start(struct thc_ipts *idev)
 		return ret;
 	idev->running = true;
 
+	/* Sets the type field to invalid; RXDMA2 start writes the real one. */
+	thc_interrupt_config(idev->thc);
+
+	ret = thc_ipts_dma_start(idev);
+	if (ret)
+		return ret;
+
+	thc_interrupt_enable(idev->thc, true);
+
 	return 0;
 }
 
@@ -229,6 +533,19 @@ int thc_ipts_port_start(struct thc_ipts *idev)
  */
 void thc_ipts_port_stop(struct thc_ipts *idev)
 {
+	/*
+	 * Mask the line, then wait for a handler that may be holding a
+	 * frame for the HID device which is about to go away.
+	 */
+	WRITE_ONCE(idev->stopping, true);
+	thc_interrupt_enable(idev->thc, false);
+	synchronize_irq(idev->irq);
+	cancel_work_sync(&idev->recover_work);
+
+	/* A handler that read ->stopping early may have unmasked. */
+	thc_interrupt_enable(idev->thc, false);
+
+	/* Stop the controller before the buffers it writes into go away. */
 	if (idev->running)
 		thc_ipts_touch_set(idev, false);
 
@@ -237,4 +554,6 @@ void thc_ipts_port_stop(struct thc_ipts *idev)
 	regmap_write_bits(idev->thc->thc_regmap, THC_M_PRT_CONTROL_OFFSET,
 			  THC_M_PRT_CONTROL_DEVRST, 0);
 	thc_ipts_quiesce(idev, true);
+
+	thc_ipts_dma_stop(idev);
 }
diff --git a/drivers/hid/intel-thc-hid/intel-ipts/ipts.h b/drivers/hid/intel-thc-hid/intel-ipts/ipts.h
index b4ce633fc..0a14ec4e8 100644
--- a/drivers/hid/intel-thc-hid/intel-ipts/ipts.h
+++ b/drivers/hid/intel-thc-hid/intel-ipts/ipts.h
@@ -7,7 +7,9 @@
 #include <linux/build_bug.h>
 #include <linux/device.h>
 #include <linux/interrupt.h>
+#include <linux/sched.h>
 #include <linux/types.h>
+#include <linux/wait.h>
 
 #include "intel-thc-dev.h"
 
@@ -95,24 +97,48 @@ static_assert(offsetof(struct thc_ipts_cfg, vendor) == 0x1c);
  * struct thc_ipts - state of one THC port in IPTS mode
  * @dev: device used for resources and logging
  * @thc: shared THC core context
+ * @irq: interrupt line of the port
  * @cfg: configuration block last read from the controller
  * @vendor: vendor ID the controller reports for its HID device
  * @product: product ID the controller reports for its HID device
  * @max_rx: largest frame the controller may send, in bytes
  * @max_tx: largest frame the driver may send, in bytes
+ * @buf_rx: allocated size of @rx_frame
+ * @rx_frame: buffer for one received frame, including its header
+ * @recover_work: resets the receive engine after a transfer error
  * @running: the controller answered and is out of reset
+ * @dma_ready: DMA engines are configured and may be used
+ * @recover_pending: a reset is wanted, refuse new requests
+ * @recovering: a reset is queued or running, ignore the interrupt
+ * @recover_seq: number of resets that ran, to tell a dropped answer apart
+ * @stopping: the port is being torn down, ignore the interrupt
+ * @irq_thread: thread the port interrupt is handled in, once it has run
  */
 struct thc_ipts {
 	struct device		*dev;
 	struct thc_device	*thc;
+	int			irq;
 	struct thc_ipts_cfg	cfg;
 	u16			vendor;
 	u16			product;
 	size_t			max_rx;
 	size_t			max_tx;
+	size_t			buf_rx;
+	u8			*rx_frame;
+	struct work_struct	recover_work;
 	bool			running;
+	bool			dma_ready;
+	bool			recover_pending;
+	bool			recovering;
+	unsigned int		recover_seq;
+	bool			stopping;
+	struct task_struct	*irq_thread;
 };
 
+irqreturn_t thc_ipts_hardirq(int irq, void *data);
+irqreturn_t thc_ipts_thread(int irq, void *data);
+void thc_ipts_recover(struct work_struct *work);
+
 int thc_ipts_port_start(struct thc_ipts *idev);
 void thc_ipts_port_stop(struct thc_ipts *idev);
 
diff --git a/drivers/hid/intel-thc-hid/intel-ipts/pci-ipts.c b/drivers/hid/intel-thc-hid/intel-ipts/pci-ipts.c
index 48046cd12..1670d116a 100644
--- a/drivers/hid/intel-thc-hid/intel-ipts/pci-ipts.c
+++ b/drivers/hid/intel-thc-hid/intel-ipts/pci-ipts.c
@@ -46,6 +46,7 @@ static int thc_ipts_probe(struct pci_dev *pci, const struct pci_device_id *id)
 
 	idev->dev = &pci->dev;
 	pci_set_drvdata(pci, idev);
+	INIT_WORK(&idev->recover_work, thc_ipts_recover);
 
 	ret = pcim_enable_device(pci);
 	if (ret) {
@@ -77,9 +78,43 @@ static int thc_ipts_probe(struct pci_dev *pci, const struct pci_device_id *id)
 	if (IS_ERR(idev->thc))
 		return PTR_ERR(idev->thc);
 
+	/*
+	 * Firmware may leave the global enable set, and the line is shared and
+	 * level triggered: mask it until a handler is in place.
+	 */
+	thc_interrupt_enable(idev->thc, false);
+
+	/*
+	 * Interrupt remapping rejects the MSI these ports ask for, so take the
+	 * shared legacy pin; MSI is for a platform that routes no pin.
+	 */
+	ret = pci_alloc_irq_vectors(pci, 1, 1, PCI_IRQ_INTX);
+	if (ret < 0) {
+		dev_warn(idev->dev, "no interrupt pin, falling back to MSI\n");
+		ret = pci_alloc_irq_vectors(pci, 1, 1,
+					    PCI_IRQ_MSI | PCI_IRQ_MSIX);
+	}
+	if (ret < 0) {
+		dev_err(idev->dev, "no interrupt vector, error %d\n", ret);
+		return ret;
+	}
+
+	idev->irq = pci_irq_vector(pci, 0);
+
+	/* Oneshot only if a sharer has it: the hardirq masks the port. */
+	ret = devm_request_threaded_irq(idev->dev, idev->irq, thc_ipts_hardirq,
+					thc_ipts_thread,
+					IRQF_SHARED | IRQF_COND_ONESHOT,
+					KBUILD_MODNAME, idev);
+	if (ret) {
+		dev_err(idev->dev, "cannot get the interrupt, error %d\n", ret);
+		return ret;
+	}
+
 	ret = thc_ipts_port_start(idev);
 	if (ret) {
 		thc_ipts_port_stop(idev);
+		devm_free_irq(idev->dev, idev->irq, idev);
 		return ret;
 	}
 
@@ -97,6 +132,11 @@ static void thc_ipts_remove(struct pci_dev *pci)
 	struct thc_ipts *idev = pci_get_drvdata(pci);
 
 	thc_ipts_port_stop(idev);
+
+	/* The handler has to go before the vector it is bound to is freed;
+	 * the vectors themselves belong to pcim_enable_device().
+	 */
+	devm_free_irq(idev->dev, idev->irq, idev);
 	pci_clear_master(pci);
 }
 

^ permalink raw reply related	[flat|nested] 9+ messages in thread

* [PATCH v8 3/5] HID: intel-thc-hid: intel-ipts: add the HID device
  2026-11-18  6:57 [PATCH v8 0/5] HID: intel-thc-hid: intel-ipts: support THC IPTS ports Emfox Zhou
  2026-11-18  6:57 ` [PATCH v8 1/5] HID: intel-thc-hid: intel-ipts: bring up the port Emfox Zhou
  2026-11-18  6:57 ` [PATCH v8 2/5] HID: intel-thc-hid: intel-ipts: receive reports Emfox Zhou
@ 2026-11-18  6:57 ` Emfox Zhou
  2026-11-18  7:14   ` sashiko-bot
  2026-11-18  6:57 ` [PATCH v8 4/5] HID: intel-thc-hid: intel-ipts: handle system sleep Emfox Zhou
  2026-11-18  6:57 ` [PATCH v8 5/5] HID: intel-thc-hid: intel-ipts: document the IPTS mode Emfox Zhou
  4 siblings, 1 reply; 9+ messages in thread
From: Emfox Zhou @ 2026-11-18  6:57 UTC (permalink / raw)
  To: Even Xu, Xinpeng Sun, Jiri Kosina, Benjamin Tissoires
  Cc: linux-input, linux-kernel

Register a HID device and let it own the handshake: the report descriptor
is not read once at probe and kept, it is asked for over the transport
whenever the HID core parses the device, and feature reports are fetched
the same way. Both need a lock that keeps one frame on the wire at a time,
a wait queue the answer is delivered on, and buffers for the answers. The
descriptor is asked for up to six times, 300 ms each; a request that finds
the port masked by a reset waits for that reset instead of spending a try.

A feature answer arrives as a frame of its own and carries only the report
ID back, which does not tell it from the answer to the next request for
the same report: nothing on the wire says which request a frame answers.
So the request is sent once, and a timeout shuts the channel until the
port is started again, the only point where controller and device are
known to agree. A reset is counted: an answer it dropped returns -EIO and
leaves the channel open, because that frame was never left out there. The
count is taken after the request is written, so a reset that finished
before the write is not taken for one that dropped this frame.
Resetting the engine instead would drop a late answer, and the reset does
not restore the PRD table, so a frame left unread would make the next one
overrun.

The state is updated under a lock, so accepting an answer and consuming it
are one step; it is a mutex, because the answer is copied in the threaded
handler and can be as large as a receive frame. The waits happen outside
it: the thread that delivers an answer calls into the HID core on its way
and would otherwise wait for a lock the waiter holds, and one that sends a
request from there waits for a completion only it can deliver, so the send
path refuses that thread and serves every other context. A second feature
request while one is outstanding is refused rather than queued, for that
reason and because its answer could not be told from the first one's.

Requests are refused while a recovery is in flight: the port is masked, so
a write would wait out its one second timeout holding the bus lock the
reset needs. Teardown refuses new requests, then waits for one already
inside thc_dma_write(), which needs the interrupt the mask takes away; the
mask follows that wait, and the line is waited on once more after the
buffers are gone. The transmit lock is not held across synchronize_irq():
the threaded handler can issue a request of its own from a HID callback.

Input reports go straight to the input layer and the raw stream is
available through hidraw, where decoding belongs: the reports carry a
heatmap, and turning it into contacts needs floating point arithmetic the
kernel cannot do. The controller starts streaming once user space asks for
it, through a set feature request on report 5.

Signed-off-by: Emfox Zhou <emfox@debian.org>
---
 drivers/hid/intel-thc-hid/intel-ipts/ipts.c   | 463 +++++++++++++++++-
 drivers/hid/intel-thc-hid/intel-ipts/ipts.h   |  56 +++
 .../hid/intel-thc-hid/intel-ipts/pci-ipts.c   |   3 +
 3 files changed, 502 insertions(+), 20 deletions(-)

diff --git a/drivers/hid/intel-thc-hid/intel-ipts/ipts.c b/drivers/hid/intel-thc-hid/intel-ipts/ipts.c
index e7896b16f..f519ba2f7 100644
--- a/drivers/hid/intel-thc-hid/intel-ipts/ipts.c
+++ b/drivers/hid/intel-thc-hid/intel-ipts/ipts.c
@@ -3,8 +3,10 @@
  * Transport for THC ports in IPTS mode: plain SPI with a private framing.
  */
 
+#include <linux/cleanup.h>
 #include <linux/delay.h>
 #include <linux/math.h>
+#include <linux/hid.h>
 #include <linux/interrupt.h>
 #include <linux/minmax.h>
 #include <linux/regmap.h>
@@ -144,8 +146,88 @@ static int thc_ipts_touch_set(struct thc_ipts *idev, bool enable)
 				 &touch);
 }
 
+/*
+ * Frames are built in @idev->tx_frame, so the lock is taken here rather than
+ * by the callers: none of them may hold it across a wait.
+ */
+static int thc_ipts_send(struct thc_ipts *idev, u32 code, const void *data,
+			 size_t len)
+{
+	size_t padded = round_up(len, 4);
+	u8 *frame = idev->tx_frame;
+
+	/* The completion of a write is delivered by the threaded handler, so
+	 * one issued from there would wait out its timeout: refuse it instead,
+	 * and let the caller retry from its own context. The check is against
+	 * the thread itself, not a flag it sets: a request from any other
+	 * context is served while the handler runs.
+	 */
+	if (current == READ_ONCE(idev->irq_thread))
+		return -EBUSY;
+
+	guard(mutex)(&idev->tx_lock);
+
+	if (READ_ONCE(idev->stopping))
+		return -ESHUTDOWN;
+	/* A reset is queued or running: the write would only time out. */
+	if (READ_ONCE(idev->recover_pending) || READ_ONCE(idev->recovering))
+		return -EAGAIN;
+	/* No engine to write into: waiting for a reset would not help. */
+	if (!READ_ONCE(idev->dma_ready))
+		return -ENODEV;
+	if (THC_IPTS_TX_HDR_SIZE + padded > idev->max_tx)
+		return -EMSGSIZE;
+
+	put_unaligned_le32(code, frame);
+	put_unaligned_le32((u32)len, frame + 4);
+	memset(frame + THC_IPTS_TX_HDR_SIZE, 0, padded);
+	if (len && data)
+		memcpy(frame + THC_IPTS_TX_HDR_SIZE, data, len);
+
+	return thc_dma_write(idev->thc, frame, THC_IPTS_TX_HDR_SIZE + padded);
+}
+
+static void thc_ipts_descriptor(struct thc_ipts *idev, const u8 *data,
+				size_t len)
+{
+	/* One answer per request: a late reply must not overwrite it. */
+	if (len <= THC_IPTS_DESC_PREAMBLE || READ_ONCE(idev->have_desc))
+		return;
+
+	len = min(len - THC_IPTS_DESC_PREAMBLE, idev->max_rx);
+	memcpy(idev->desc, data + THC_IPTS_DESC_PREAMBLE, len);
+	idev->desc_len = len;
+	/* The bytes and the length have to land before the flag is seen. */
+	smp_store_release(&idev->have_desc, true);
+	wake_up(&idev->wq);
+}
+
+static void thc_ipts_feature(struct thc_ipts *idev, const u8 *data,
+			     size_t len)
+{
+	if (!len)
+		return;
+
+	/* Only a frame that arrives while a request is waiting is taken. */
+	mutex_lock(&idev->feature_lock);
+	if (!idev->feature_pending ||
+	    (idev->feature_id && data[0] != idev->feature_id)) {
+		mutex_unlock(&idev->feature_lock);
+		return;
+	}
+
+	len = min(len, idev->max_rx);
+	memcpy(idev->feature, data, len);
+	idev->feature_len = len;
+	WRITE_ONCE(idev->feature_done, true);
+	mutex_unlock(&idev->feature_lock);
+
+	wake_up(&idev->wq);
+}
+
 static void thc_ipts_handle_frame(struct thc_ipts *idev, size_t len)
 {
+	const u8 *payload = idev->rx_frame + THC_IPTS_RX_HDR_SIZE;
 	size_t capacity = idev->max_rx - THC_IPTS_RX_HDR_SIZE;
 	u32 code, size;
 
@@ -154,11 +236,31 @@ static void thc_ipts_handle_frame(struct thc_ipts *idev, size_t len)
 
 	code = get_unaligned_le32(idev->rx_frame);
 	/* The header may claim more than what actually arrived. */
-	size = min_t(u32, get_unaligned_le32(idev->rx_frame + 4),
-		     capacity);
+	size = min_t(u32, get_unaligned_le32(idev->rx_frame + 4), capacity);
 	size = min_t(u32, size, len - THC_IPTS_RX_HDR_SIZE);
 
-	dev_dbg(idev->dev, "frame code %u, %u bytes\n", code, size);
+	switch (code) {
+	case THC_IPTS_RX_INPUT: {
+		struct hid_device *hdev = READ_ONCE(idev->hid);
+
+		if (hdev)
+			hid_safe_input_report(hdev, HID_INPUT_REPORT,
+					      (u8 *)payload, capacity, size, 1);
+		break;
+	}
+	case THC_IPTS_RX_DESC:
+		thc_ipts_descriptor(idev, payload, size);
+		break;
+	case THC_IPTS_RX_FEATURE:
+		thc_ipts_feature(idev, payload, size);
+		break;
+	case THC_IPTS_RX_RESET:
+		dev_warn(idev->dev, "controller asked for a reset\n");
+		break;
+	default:
+		dev_dbg(idev->dev, "frame code %u, %u bytes\n", code, size);
+		break;
+	}
 }
 
 static void thc_ipts_dma_stop(struct thc_ipts *idev)
@@ -211,9 +313,19 @@ static int thc_ipts_dma_start(struct thc_ipts *idev)
 	 */
 	ret = thc_ipts_resize(idev, &idev->rx_frame, &idev->buf_rx,
 			      round_up(idev->max_rx, SZ_4K));
+	if (!ret)
+		ret = thc_ipts_resize(idev, &idev->tx_frame, &idev->buf_tx,
+				      round_up(idev->max_tx, 4));
+	if (!ret)
+		ret = thc_ipts_resize(idev, &idev->desc, &idev->buf_desc,
+				      idev->max_rx);
+	if (!ret)
+		ret = thc_ipts_resize(idev, &idev->feature, &idev->buf_feat,
+				      idev->max_rx);
 	if (ret)
 		return ret;
 
+	/* Only RXDMA2 (in) and TXDMA (out) are used; the other two stay 0. */
 	ret = thc_dma_set_max_packet_sizes(idev->thc, 0, idev->max_rx,
 					   idev->max_tx, 0);
 	if (ret)
@@ -289,6 +401,8 @@ static void thc_ipts_request_recover(struct thc_ipts *idev)
 
 	WRITE_ONCE(idev->recover_pending, true);
 	schedule_work(&idev->recover_work);
+	/* A request waiting for the port looks at that flag. */
+	wake_up(&idev->wq);
 }
 
 /*
@@ -300,6 +414,14 @@ void thc_ipts_recover(struct work_struct *work)
 	struct thc_ipts *idev = container_of(work, struct thc_ipts,
 					     recover_work);
 
+	/*
+	 * A write that is already on the wire holds this lock and needs the
+	 * interrupt that the mask below takes away: let it finish first, or it
+	 * times out over the bus lock the reset is waiting for.
+	 */
+	mutex_lock(&idev->tx_lock);
+	mutex_unlock(&idev->tx_lock);
+
 	/*
 	 * From here the status registers belong to the reset: the threaded
 	 * handler must not acknowledge a frame it is not going to read, or the
@@ -318,6 +440,8 @@ void thc_ipts_recover(struct work_struct *work)
 	if (thc_rxdma_reset(idev->thc)) {
 		/* Nothing left: keep the port masked until it restarts. */
 		dev_err(idev->dev, "cannot reset the receive engine\n");
+		/* It stays masked, so the waiters learn it from the flags. */
+		wake_up(&idev->wq);
 		return;
 	}
 
@@ -328,6 +452,10 @@ void thc_ipts_recover(struct work_struct *work)
 	WRITE_ONCE(idev->recover_seq, READ_ONCE(idev->recover_seq) + 1);
 	WRITE_ONCE(idev->recover_pending, false);
 	WRITE_ONCE(idev->recovering, false);
+
+	/* A request waiting out the reset is looking at that flag. */
+	wake_up(&idev->wq);
+
 	if (!READ_ONCE(idev->stopping))
 		thc_interrupt_enable(idev->thc, true);
 }
@@ -374,10 +502,10 @@ irqreturn_t thc_ipts_thread(int irq, void *data)
 
 		ret = IRQ_HANDLED;
 		if (mask & (BIT(THC_FATAL_ERR_INT) | BIT(THC_TXN_ERR_INT))) {
-			/* An overrun raises this for every frame until the
-			 * reset takes the port: report the first one only.
+			/* An overrun raises this until the reset takes the
+			 * port: report the first one only.
 			 */
-			if (!reported) {
+			if (!reported && !READ_ONCE(idev->recover_pending)) {
 				dev_err(idev->dev,
 					"transfer error, resetting the engine\n");
 				reported = true;
@@ -403,17 +531,19 @@ irqreturn_t thc_ipts_thread(int irq, void *data)
 			need_recover = true;
 	}
 
-	/* The work item resets the engine and unmasks again; a frame read
-	 * meanwhile would corrupt the ring.
+	/*
+	 * The work item resets the engine in its own time; a frame read
+	 * meanwhile would corrupt the ring, so only queue the reset.
 	 */
-	if (need_recover) {
+	if (need_recover)
 		thc_ipts_request_recover(idev);
-		return IRQ_HANDLED;
-	}
 
-	/* A reset unmasks when it is done and a teardown masks on its own, so
-	 * the line only stays open here while neither runs: a write already
-	 * on the wire needs the completion this handler delivers.
+	/*
+	 * A reset unmasks when it is done, and a teardown masks on its own.
+	 * Leaving the line open here is what a write already on the wire
+	 * needs: this handler is where its completion is delivered, and
+	 * masking it away would make that write time out over the bus lock
+	 * the reset is waiting for.
 	 */
 	if (!READ_ONCE(idev->recovering) && !READ_ONCE(idev->stopping))
 		thc_interrupt_enable(idev->thc, true);
@@ -421,6 +551,277 @@ irqreturn_t thc_ipts_thread(int irq, void *data)
 	return ret;
 }
 
+/* No reset is queued or running, and the port is not going away. */
+static bool thc_ipts_idle(const struct thc_ipts *idev)
+{
+	return !READ_ONCE(idev->recover_pending) &&
+	       !READ_ONCE(idev->recovering) &&
+	       !READ_ONCE(idev->stopping);
+}
+
+static int thc_ipts_hid_parse(struct hid_device *hdev)
+{
+	struct thc_ipts *idev = hdev->driver_data;
+	unsigned long timeout = msecs_to_jiffies(THC_IPTS_REQ_TIMEOUT_MS);
+	u64 zero = 0;
+	unsigned int retries = 0;
+	int ret;
+	int try = 0;
+
+	/* A descriptor from a previous start is not this one's. */
+	WRITE_ONCE(idev->have_desc, false);
+
+	while (try < THC_IPTS_REQ_TRIES) {
+		/* An answer that landed after a wait expired is taken here. */
+		if (smp_load_acquire(&idev->have_desc))
+			break;
+
+		/* The controller ignores the eight byte argument. */
+		ret = thc_ipts_send(idev, THC_IPTS_TX_GET_DESC, &zero,
+				    sizeof(zero));
+		/*
+		 * -EAGAIN is our own reset refusing the request. -ETIMEDOUT is
+		 * a write that was already on the wire when one started: its
+		 * completion went away with the mask. Both are worth another
+		 * try, a descriptor request carries nothing a late answer could
+		 * spoil.
+		 */
+		if (ret == -EAGAIN || ret == -ETIMEDOUT) {
+			if (++retries > THC_IPTS_REQ_TRIES ||
+			    !wait_event_timeout(idev->wq,
+						thc_ipts_idle(idev), timeout))
+				break;
+			continue;
+		}
+		if (ret)
+			return ret;
+
+		try++;
+		wait_event_timeout(idev->wq, READ_ONCE(idev->have_desc),
+				   timeout);
+	}
+
+	/* Pairs with the release in thc_ipts_descriptor(). */
+	if (smp_load_acquire(&idev->have_desc) && idev->desc_len > 0) {
+		/* The receive buffer holds more than a descriptor may be. */
+		if (idev->desc_len > HID_MAX_DESCRIPTOR_SIZE) {
+			dev_err(idev->dev,
+				"report descriptor of %zu bytes is too large\n",
+				idev->desc_len);
+			return -EINVAL;
+		}
+
+		return hid_parse_report(hdev, idev->desc, idev->desc_len);
+	}
+
+	dev_err(idev->dev, "controller did not return a report descriptor\n");
+
+	return -ETIMEDOUT;
+}
+
+/* A feature report comes back as a frame of its own: the request waits. */
+static int thc_ipts_get_feature(struct thc_ipts *idev, unsigned char reportnum,
+				u8 *buf, size_t len)
+{
+	unsigned long timeout = msecs_to_jiffies(THC_IPTS_REQ_TIMEOUT_MS);
+	unsigned int seq;
+	int ret;
+
+	/*
+	 * One request at a time, and the wait below happens without a lock: a
+	 * request issued from a HID callback in the handler thread would be
+	 * waiting for an answer only that very thread can deliver. The gate is
+	 * released by whoever takes the answer, not by the frame that brings
+	 * it, or a second request could be answered into this one's buffer.
+	 */
+	mutex_lock(&idev->feature_lock);
+
+	/* The frame carries only the report ID, so a late answer cannot be
+	 * told from the next one's: after a timeout the channel stays shut.
+	 */
+	if (idev->feature_off) {
+		mutex_unlock(&idev->feature_lock);
+		return -EIO;
+	}
+	if (idev->feature_pending) {
+		mutex_unlock(&idev->feature_lock);
+		return -EBUSY;
+	}
+
+	WRITE_ONCE(idev->feature_done, false);
+	idev->feature_id = reportnum;
+	idev->feature_pending = true;
+	mutex_unlock(&idev->feature_lock);
+
+	/* A refusal happens before anything is written, so the channel stays
+	 * open for it; a timeout is a different matter, see below.
+	 */
+	ret = thc_ipts_send(idev, THC_IPTS_TX_GET_FEATURE, &reportnum, 1);
+	if (ret) {
+		mutex_lock(&idev->feature_lock);
+		idev->feature_pending = false;
+
+		/* The start bit was written before the wait, so the frame may
+		 * well be on the wire: its answer cannot be told from the next
+		 * request's one.
+		 */
+		if (ret == -ETIMEDOUT)
+			WRITE_ONCE(idev->feature_off, true);
+		mutex_unlock(&idev->feature_lock);
+
+		if (ret == -ETIMEDOUT)
+			dev_err(idev->dev, "feature report %u not acknowledged\n",
+				reportnum);
+
+		return ret;
+	}
+
+	/* Taken after the write, or a reset that ran before it would be
+	 * mistaken for one that dropped this frame.
+	 */
+	seq = READ_ONCE(idev->recover_seq);
+
+	wait_event_timeout(idev->wq, READ_ONCE(idev->feature_done) ||
+			   READ_ONCE(idev->recover_pending) ||
+			   READ_ONCE(idev->recovering) ||
+			   READ_ONCE(idev->stopping), timeout);
+
+	mutex_lock(&idev->feature_lock);
+	/* An answer that landed while the wait was expiring counts too. */
+	if (!idev->feature_done) {
+		/* A reset discards what the engines had queued, so an answer
+		 * that was on its way is gone and cannot be waited for.
+		 */
+		if (READ_ONCE(idev->recover_seq) != seq ||
+		    READ_ONCE(idev->recover_pending) ||
+		    READ_ONCE(idev->recovering) ||
+		    READ_ONCE(idev->stopping))
+			ret = -EIO;
+		else
+			ret = -ETIMEDOUT;
+
+		idev->feature_pending = false;
+		/* Only a timeout leaves a frame out there: after a reset the
+		 * answer was dropped and the channel is still in step.
+		 */
+		if (ret == -ETIMEDOUT)
+			WRITE_ONCE(idev->feature_off, true);
+		mutex_unlock(&idev->feature_lock);
+
+		if (ret == -ETIMEDOUT)
+			dev_err(idev->dev, "no feature report %u\n", reportnum);
+
+		return ret;
+	}
+
+	/* The payload is the report as user space writes it: ID first. */
+	len = min(len, idev->feature_len);
+	if (len)
+		memcpy(buf, idev->feature, len);
+	idev->feature_pending = false;
+	mutex_unlock(&idev->feature_lock);
+
+	return len ?: -EPROTO;
+}
+
+static int thc_ipts_hid_raw_request(struct hid_device *hdev,
+				    unsigned char reportnum, __u8 *buf,
+				    size_t len, unsigned char rtype,
+				    int reqtype)
+{
+	struct thc_ipts *idev = hdev->driver_data;
+	u32 code;
+	int ret;
+
+	if (!buf || !len)
+		return -EINVAL;
+
+	if (reqtype == HID_REQ_GET_REPORT && rtype == HID_FEATURE_REPORT)
+		return thc_ipts_get_feature(idev, reportnum, buf, len);
+
+	if (reqtype != HID_REQ_SET_REPORT ||
+	    (rtype != HID_OUTPUT_REPORT && rtype != HID_FEATURE_REPORT))
+		return -EOPNOTSUPP;
+
+	code = rtype == HID_OUTPUT_REPORT ? THC_IPTS_TX_OUTPUT :
+					    THC_IPTS_TX_SET_FEATURE;
+
+	ret = thc_ipts_send(idev, code, buf, len);
+	if (ret)
+		return ret;
+
+	/* raw_request returns the byte count, which hidraw forwards. */
+	return (int)len;
+}
+
+/* The HID core calls these unconditionally; nothing to do in this mode. */
+static int thc_ipts_hid_start(struct hid_device *hdev)
+{
+	return 0;
+}
+
+static void thc_ipts_hid_stop(struct hid_device *hdev)
+{
+}
+
+static int thc_ipts_hid_open(struct hid_device *hdev)
+{
+	return 0;
+}
+
+static void thc_ipts_hid_close(struct hid_device *hdev)
+{
+}
+
+static const struct hid_ll_driver thc_ipts_ll_driver = {
+	.start		= thc_ipts_hid_start,
+	.stop		= thc_ipts_hid_stop,
+	.open		= thc_ipts_hid_open,
+	.close		= thc_ipts_hid_close,
+	.parse		= thc_ipts_hid_parse,
+	.raw_request	= thc_ipts_hid_raw_request,
+};
+
+static void thc_ipts_hid_remove(struct thc_ipts *idev)
+{
+	if (!READ_ONCE(idev->hid))
+		return;
+
+	hid_destroy_device(idev->hid);
+	WRITE_ONCE(idev->hid, NULL);
+}
+
+static int thc_ipts_hid_add(struct thc_ipts *idev)
+{
+	struct hid_device *hdev;
+	int ret;
+
+	hdev = hid_allocate_device();
+	if (IS_ERR(hdev))
+		return PTR_ERR(hdev);
+
+	hdev->ll_driver = &thc_ipts_ll_driver;
+	hdev->bus = BUS_PCI;
+	hdev->vendor = idev->vendor;
+	hdev->product = idev->product;
+	hdev->version = le32_to_cpu(idev->cfg.revision) & 0xffff;
+	hdev->dev.parent = idev->dev;
+	hdev->driver_data = idev;
+	snprintf(hdev->name, sizeof(hdev->name), "intel-ipts %04X:%04X",
+		 idev->vendor, idev->product);
+	strscpy(hdev->phys, dev_name(idev->dev), sizeof(hdev->phys));
+
+	ret = hid_add_device(hdev);
+	if (ret) {
+		hid_destroy_device(hdev);
+		return ret;
+	}
+
+	WRITE_ONCE(idev->hid, hdev);
+
+	return 0;
+}
+
 /**
  * thc_ipts_port_start - bring one port up
  * @idev: port to start
@@ -431,7 +832,9 @@ int thc_ipts_port_start(struct thc_ipts *idev)
 	int ret;
 
 	WRITE_ONCE(idev->stopping, false);
+	WRITE_ONCE(idev->recover_pending, false);
 	WRITE_ONCE(idev->recovering, false);
+	WRITE_ONCE(idev->feature_off, false);
 
 	ret = thc_ipts_quiesce(idev, true);
 	if (ret)
@@ -524,7 +927,7 @@ int thc_ipts_port_start(struct thc_ipts *idev)
 
 	thc_interrupt_enable(idev->thc, true);
 
-	return 0;
+	return thc_ipts_hid_add(idev);
 }
 
 /**
@@ -533,11 +936,17 @@ int thc_ipts_port_start(struct thc_ipts *idev)
  */
 void thc_ipts_port_stop(struct thc_ipts *idev)
 {
-	/*
-	 * Mask the line, then wait for a handler that may be holding a
-	 * frame for the HID device which is about to go away.
+	/* Refuse new requests first, then wait for one that is already inside
+	 * thc_dma_write(): the completion it waits for comes through the
+	 * handler this teardown is about to mask. The lock is not held across
+	 * synchronize_irq(), because the threaded handler can issue a request
+	 * of its own from a HID callback.
 	 */
 	WRITE_ONCE(idev->stopping, true);
+	wake_up(&idev->wq);
+	mutex_lock(&idev->tx_lock);
+	mutex_unlock(&idev->tx_lock);
+
 	thc_interrupt_enable(idev->thc, false);
 	synchronize_irq(idev->irq);
 	cancel_work_sync(&idev->recover_work);
@@ -545,7 +954,7 @@ void thc_ipts_port_stop(struct thc_ipts *idev)
 	/* A handler that read ->stopping early may have unmasked. */
 	thc_interrupt_enable(idev->thc, false);
 
-	/* Stop the controller before the buffers it writes into go away. */
+	/* Stop the controller before its buffers go away. */
 	if (idev->running)
 		thc_ipts_touch_set(idev, false);
 
@@ -553,7 +962,21 @@ void thc_ipts_port_stop(struct thc_ipts *idev)
 	/* Forced: the bit may read as clear and still need the command. */
 	regmap_write_bits(idev->thc->thc_regmap, THC_M_PRT_CONTROL_OFFSET,
 			  THC_M_PRT_CONTROL_DEVRST, 0);
-	thc_ipts_quiesce(idev, true);
 
+	/* The buffers are not devm-managed, so releasing them is the only way
+	 * back: do it even when the engine did not acknowledge the stop, and
+	 * let thc_dma_unconfigure() clear the start bits on its way out.
+	 */
+	if (thc_ipts_quiesce(idev, true))
+		dev_warn(idev->dev, "engine did not stop, releasing anyway\n");
 	thc_ipts_dma_stop(idev);
+
+	/* ->dma_ready goes away with the buffers, and a handler woken before
+	 * that still looks at the ring: wait for it once more, then mask what
+	 * it may have left open.
+	 */
+	synchronize_irq(idev->irq);
+	thc_interrupt_enable(idev->thc, false);
+
+	thc_ipts_hid_remove(idev);
 }
diff --git a/drivers/hid/intel-thc-hid/intel-ipts/ipts.h b/drivers/hid/intel-thc-hid/intel-ipts/ipts.h
index 0a14ec4e8..8d2e6e421 100644
--- a/drivers/hid/intel-thc-hid/intel-ipts/ipts.h
+++ b/drivers/hid/intel-thc-hid/intel-ipts/ipts.h
@@ -6,8 +6,11 @@
 #include <linux/bits.h>
 #include <linux/build_bug.h>
 #include <linux/device.h>
+#include <linux/hid.h>
 #include <linux/interrupt.h>
+#include <linux/mutex.h>
 #include <linux/sched.h>
+#include <linux/spinlock.h>
 #include <linux/types.h>
 #include <linux/wait.h>
 
@@ -40,6 +43,13 @@
 #define THC_IPTS_CFG_TRIES		10
 #define THC_IPTS_CFG_RETRY_MS		100
 
+/* A report descriptor arrives with eight bytes of preamble in front of it. */
+#define THC_IPTS_DESC_PREAMBLE	8
+
+/* Retry budget for the report descriptor handshake. */
+#define THC_IPTS_REQ_TRIES		6
+#define THC_IPTS_REQ_TIMEOUT_MS	300
+
 #define THC_IPTS_CFG_KNOWN		40
 
 /* The block as far as this driver reads it, padded to its full size. */
@@ -93,6 +103,17 @@ static_assert(offsetof(struct thc_ipts_cfg, vendor) == 0x1c);
 #define THC_IPTS_RX_HDR_SIZE		64
 #define THC_IPTS_TX_HDR_SIZE		8
 
+/* Frame codes. The same numbers mean different things per direction. */
+#define THC_IPTS_RX_INPUT		3
+#define THC_IPTS_RX_FEATURE		4
+#define THC_IPTS_RX_DESC		5
+#define THC_IPTS_RX_RESET		7
+
+#define THC_IPTS_TX_SET_FEATURE	3
+#define THC_IPTS_TX_GET_FEATURE	4
+#define THC_IPTS_TX_OUTPUT		5
+#define THC_IPTS_TX_GET_DESC		7
+
 /**
  * struct thc_ipts - state of one THC port in IPTS mode
  * @dev: device used for resources and logging
@@ -104,7 +125,25 @@ static_assert(offsetof(struct thc_ipts_cfg, vendor) == 0x1c);
  * @max_rx: largest frame the controller may send, in bytes
  * @max_tx: largest frame the driver may send, in bytes
  * @buf_rx: allocated size of @rx_frame
+ * @buf_tx: allocated size of @tx_frame
+ * @buf_desc: allocated size of @desc
+ * @buf_feat: allocated size of @feature
  * @rx_frame: buffer for one received frame, including its header
+ * @tx_frame: buffer for one frame to send, including its header
+ * @desc: copy of the report descriptor, past its preamble
+ * @desc_len: length of @desc
+ * @have_desc: a descriptor arrived and has not been consumed yet
+ * @feature: buffer a feature report is collected in
+ * @feature_len: length of the report in @feature
+ * @feature_id: report ID that was asked for, checked against the answer
+ * @feature_pending: a feature report was asked for and has not arrived yet
+ * @feature_done: a feature report arrived and has not been consumed yet
+ * @feature_off: a request timed out and no more are taken until the port
+ *	restarts
+ * @feature_lock: protects the feature report buffer and its flags
+ * @wq: waited on for a report descriptor or a feature report
+ * @tx_lock: serialises writes into @tx_frame
+ * @hid: HID device the reports are handed to, once it has been registered
  * @recover_work: resets the receive engine after a transfer error
  * @running: the controller answered and is out of reset
  * @dma_ready: DMA engines are configured and may be used
@@ -124,7 +163,24 @@ struct thc_ipts {
 	size_t			max_rx;
 	size_t			max_tx;
 	size_t			buf_rx;
+	size_t			buf_tx;
+	size_t			buf_desc;
+	size_t			buf_feat;
 	u8			*rx_frame;
+	u8			*tx_frame;
+	u8			*desc;
+	size_t			desc_len;
+	bool			have_desc;
+	u8			*feature;
+	size_t			feature_len;
+	u8			feature_id;
+	bool			feature_pending;
+	bool			feature_done;
+	bool			feature_off;
+	struct mutex		feature_lock;	/* feature report handshake */
+	wait_queue_head_t	wq;
+	struct mutex		tx_lock;	/* transmit frame */
+	struct hid_device	*hid;
 	struct work_struct	recover_work;
 	bool			running;
 	bool			dma_ready;
diff --git a/drivers/hid/intel-thc-hid/intel-ipts/pci-ipts.c b/drivers/hid/intel-thc-hid/intel-ipts/pci-ipts.c
index 1670d116a..5aa0ad6fb 100644
--- a/drivers/hid/intel-thc-hid/intel-ipts/pci-ipts.c
+++ b/drivers/hid/intel-thc-hid/intel-ipts/pci-ipts.c
@@ -45,6 +45,9 @@ static int thc_ipts_probe(struct pci_dev *pci, const struct pci_device_id *id)
 		return -ENOMEM;
 
 	idev->dev = &pci->dev;
+	mutex_init(&idev->tx_lock);
+	mutex_init(&idev->feature_lock);
+	init_waitqueue_head(&idev->wq);
 	pci_set_drvdata(pci, idev);
 	INIT_WORK(&idev->recover_work, thc_ipts_recover);
 

^ permalink raw reply related	[flat|nested] 9+ messages in thread

* [PATCH v8 4/5] HID: intel-thc-hid: intel-ipts: handle system sleep
  2026-11-18  6:57 [PATCH v8 0/5] HID: intel-thc-hid: intel-ipts: support THC IPTS ports Emfox Zhou
                   ` (2 preceding siblings ...)
  2026-11-18  6:57 ` [PATCH v8 3/5] HID: intel-thc-hid: intel-ipts: add the HID device Emfox Zhou
@ 2026-11-18  6:57 ` Emfox Zhou
  2026-11-18  7:17   ` sashiko-bot
  2026-11-18  6:57 ` [PATCH v8 5/5] HID: intel-thc-hid: intel-ipts: document the IPTS mode Emfox Zhou
  4 siblings, 1 reply; 9+ messages in thread
From: Emfox Zhou @ 2026-11-18  6:57 UTC (permalink / raw)
  To: Even Xu, Xinpeng Sun, Jiri Kosina, Benjamin Tissoires
  Cc: linux-input, linux-kernel

System sleep takes the port down and builds it up again rather than
keeping the HID device across it: the controller forgets the streaming
mode user space asked it for, and hidraw offers no way to tell user space
to ask again. A new HID device is what comes back, so the hidraw node and
the input device are destroyed on the way down and reappear under a new
minor; a daemon holding them open sees that and repeats the request.

Nothing here arms a wakeup source, so the port does not have to stay alive
across sleep: DEFINE_SIMPLE_DEV_PM_OPS() installs the same pair for freeze
and restore, and a controller that lost power in hibernation comes back
through the full bring-up.

Signed-off-by: Emfox Zhou <emfox@debian.org>
---
 .../hid/intel-thc-hid/intel-ipts/pci-ipts.c   | 25 +++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/drivers/hid/intel-thc-hid/intel-ipts/pci-ipts.c b/drivers/hid/intel-thc-hid/intel-ipts/pci-ipts.c
index 5aa0ad6fb..b2d9be4ee 100644
--- a/drivers/hid/intel-thc-hid/intel-ipts/pci-ipts.c
+++ b/drivers/hid/intel-thc-hid/intel-ipts/pci-ipts.c
@@ -143,6 +143,30 @@ static void thc_ipts_remove(struct pci_dev *pci)
 	pci_clear_master(pci);
 }
 
+static int thc_ipts_suspend(struct device *dev)
+{
+	struct thc_ipts *idev = dev_get_drvdata(dev);
+
+	thc_ipts_port_stop(idev);
+
+	return 0;
+}
+
+static int thc_ipts_resume(struct device *dev)
+{
+	struct thc_ipts *idev = dev_get_drvdata(dev);
+	int ret;
+
+	ret = thc_ipts_port_start(idev);
+	if (ret)
+		thc_ipts_port_stop(idev);
+
+	return ret;
+}
+
+static DEFINE_SIMPLE_DEV_PM_OPS(thc_ipts_pm_ops, thc_ipts_suspend,
+				thc_ipts_resume);
+
 static void thc_ipts_shutdown(struct pci_dev *pci)
 {
 	struct thc_ipts *idev = pci_get_drvdata(pci);
@@ -157,6 +181,7 @@ static struct pci_driver thc_ipts_driver = {
 	.probe		= thc_ipts_probe,
 	.remove		= thc_ipts_remove,
 	.shutdown	= thc_ipts_shutdown,
+	.driver.pm	= pm_sleep_ptr(&thc_ipts_pm_ops),
 	/* Bring-up waits for the controller, up to a few seconds. */
 	.driver.probe_type = PROBE_PREFER_ASYNCHRONOUS,
 };

^ permalink raw reply related	[flat|nested] 9+ messages in thread

* [PATCH v8 5/5] HID: intel-thc-hid: intel-ipts: document the IPTS mode
  2026-11-18  6:57 [PATCH v8 0/5] HID: intel-thc-hid: intel-ipts: support THC IPTS ports Emfox Zhou
                   ` (3 preceding siblings ...)
  2026-11-18  6:57 ` [PATCH v8 4/5] HID: intel-thc-hid: intel-ipts: handle system sleep Emfox Zhou
@ 2026-11-18  6:57 ` Emfox Zhou
  4 siblings, 0 replies; 9+ messages in thread
From: Emfox Zhou @ 2026-11-18  6:57 UTC (permalink / raw)
  To: Even Xu, Xinpeng Sun, Jiri Kosina, Benjamin Tissoires
  Cc: linux-input, linux-kernel

The THC documentation only covers HIDSPI and HIDI2C. Ports from before
Meteor Lake run in a third mode, and the intel-ipts driver is
written against behaviour that is not described anywhere in tree.

Record what the driver depends on: the layout of the configuration
block, the frame codes and header sizes, the bulk data window, and the
order in which quiesce, interrupt configuration and the DMA engines
have to be set up.

Signed-off-by: Emfox Zhou <emfox@debian.org>
---
 Documentation/hid/intel-thc-hid.rst | 109 +++++++++++++++++++++++++++-
 1 file changed, 108 insertions(+), 1 deletion(-)

diff --git a/Documentation/hid/intel-thc-hid.rst b/Documentation/hid/intel-thc-hid.rst
index 8b378c57b..e6bdf30b6 100644
--- a/Documentation/hid/intel-thc-hid.rst
+++ b/Documentation/hid/intel-thc-hid.rst
@@ -590,7 +590,114 @@ 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
+7. IPTS Mode
+============
+
+THC also supports IPTS mode, the private Intel Precise Touch and Stylus
+protocol. The port drives the touch controller over plain SPI and moves the
+data through the same DMA engines, but the framing is private and the
+parameters come from the controller itself instead of ACPI. The
+``intel-ipts`` module handles ports in that mode, which is what Tiger Lake,
+Lakefield, Alder Lake and Raptor Lake hardware use.
+
+This section describes how the driver uses those ports. It is not a
+specification: everything below comes from observing the controller and is
+limited to what this driver relies on.
+
+7.1 Configuration Block
+-----------------------
+
+At SPI address 0 the controller exposes a 64 byte block. The driver reads it
+over the PIO path after releasing the controller from reset, and retries
+until the tag ``$TIC`` (``0x43495424``) appears, because the block is only
+partially filled while the controller is still starting.
+
+Two steps come before that read: the DMA engines are unconfigured first, so
+engines the firmware left armed do not keep writing through the PRD base it
+had mapped, and the interrupt trigger is switched to edge, without which the
+first read is unreliable.
+
+Fields the driver uses:
+
+======  ==========================================================
+Offset  Meaning
+======  ==========================================================
+0x00    pending interrupt causes
+0x08    buffer sizes, ``(size / 64) - 1``; Rx bits 13:0, Tx 23:14
+0x0c    touch engine control: enable BIT(0), HID reports BIT(2),
+        power state GENMASK(5, 3)
+0x14    controller tag, ``$TIC``
+0x18    SPI timing: clock divisor GENMASK(3, 1), divide-by-8 and
+        dual/quad bits
+0x1c    vendor and product ID reported to HID
+0x20    product revision
+0x24    firmware version word
+======  ==========================================================
+
+The driver enables the touch engine with reports and full power, and clears
+it again when the port is shut down.
+
+The offsets above, the frame codes and the header sizes below are compiled
+into ``ipts.h``; a ``static_assert()`` on every offset makes a mismatch a
+build failure rather than a quiet misread.
+
+7.2 Frames
+----------
+
+Both directions carry a code and a length in front of the payload. Frames
+from the controller use a 64 byte header, frames to it an 8 byte header, and
+only the latter has the payload padded to a four byte boundary.
+
+==== ========================== =======================
+Code Received from controller   Sent to controller
+==== ========================== =======================
+3    input report               set feature
+4    feature report             get feature
+5    report descriptor          output report
+7    reset request              get report descriptor
+==== ========================== =======================
+
+A report descriptor comes back with eight bytes of preamble that the driver
+skips.
+
+7.3 Data Window
+---------------
+
+Bulk transfers go through address ``0x1000`` of the controller, not through
+address 0. The DMA engines have to be pointed there explicitly, otherwise
+they write into the configuration block and the controller drops the frames
+without reporting an error. The input header address is zero: that is where
+the controller writes the interrupt cause word, at the start of the
+configuration block.
+
+7.4 Enabling and Flow Control
+-----------------------------
+
+The port has to be released from quiesce before the driver enables the
+touch engine: quiescing holds back the device interrupt and the data path,
+not the configuration access, which is why the block above is read while the
+port is still quiesced. The interrupt configuration programs the interrupt
+type field in the device to the invalid value, and starting the receive
+engine then replaces that field with the type it expects, so the two have to
+happen in that order.
+
+The controller starts streaming once user space asks for it, through a set
+feature request on report 5. The driver does not do that on its own; the
+daemon that opens hidraw sends it.
+
+7.5 What Is Left to User Space
+------------------------------
+
+The reports carry heatmap data, and turning that into contacts is a
+substantial image-processing job that already exists in user space. The
+driver therefore stops at the HID layer: the report descriptor comes from
+the controller and is not written by the driver, the report stream is
+available through hidraw, and ``iptsd`` decodes it into input events.
+
+System sleep tears the port down and brings it back, so the hidraw node is
+destroyed and re-created: a daemon has to reopen it after resume.
+
+8. Reference
 ============
 - HIDSPI: https://download.microsoft.com/download/c/a/0/ca07aef3-3e10-4022-b1e9-c98cea99465d/HidSpiProtocolSpec.pdf
 - HIDI2C: https://download.microsoft.com/download/7/d/d/7dd44bb7-2a7a-4505-ac1c-7227d3d96d5b/hid-over-i2c-protocol-spec-v1-0.docx

^ permalink raw reply related	[flat|nested] 9+ messages in thread

* Re: [PATCH v8 3/5] HID: intel-thc-hid: intel-ipts: add the HID device
  2026-11-18  6:57 ` [PATCH v8 3/5] HID: intel-thc-hid: intel-ipts: add the HID device Emfox Zhou
@ 2026-11-18  7:14   ` sashiko-bot
  0 siblings, 0 replies; 9+ messages in thread
From: sashiko-bot @ 2026-11-18  7:14 UTC (permalink / raw)
  To: Emfox Zhou; +Cc: linux-input, dmitry.torokhov

Thank you for your contribution! Sashiko AI review found 2 potential
issues to consider:
- [Medium] HID: intel-thc-hid: intel-ipts: race on recover_seq in
  thc_ipts_get_feature()
- [Medium] HID: intel-thc-hid: intel-ipts: stale recovery state in
  thc_ipts_recover()
--

commit e0bc1fa63dd36608a943c89014dbfd5351a76676
Author: Emfox Zhou <emfox@debian.org>

HID: intel-thc-hid: intel-ipts: add the HID device

This commit registers a HID device for Intel THC ports in IPTS mode and
implements report descriptor parsing, input report forwarding, and raw
feature and output report transfers.

> diff --git a/drivers/hid/intel-thc-hid/intel-ipts/ipts.c b/drivers/hid/intel-thc-hid/intel-ipts/ipts.c
> index e7896b16f1ada..f519ba2f7ce3d 100644
> --- a/drivers/hid/intel-thc-hid/intel-ipts/ipts.c
> +++ b/drivers/hid/intel-thc-hid/intel-ipts/ipts.c

[ ... ]

> @@ -318,6 +440,8 @@ void thc_ipts_recover(struct work_struct *work)
>  	if (thc_rxdma_reset(idev->thc)) {
>  		/* Nothing left: keep the port masked until it restarts. */
>  		dev_err(idev->dev, "cannot reset the receive engine\n");
> +		/* It stays masked, so the waiters learn it from the flags. */
> +		wake_up(&idev->wq);
>  		return;
>  	}

[Severity: Medium]
When thc_rxdma_reset() fails, does leaving idev->recover_pending and
idev->recovering set while idev->dma_ready remains true keep waiters and
callers of thc_ipts_send() stuck in a transient recovery state?

thc_ipts_hid_parse() waits on thc_ipts_idle(idev), which requires both
recover_pending and recovering to be false, so wake_up(&idev->wq) here does
not wake it and it waits out all THC_IPTS_REQ_TRIES timeouts.  In addition,
thc_ipts_send() checks recover_pending and recovering before dma_ready, so
subsequent sends keep returning -EAGAIN instead of -ENODEV.

[ ... ]

> +/* A feature report comes back as a frame of its own: the request waits. */
> +static int thc_ipts_get_feature(struct thc_ipts *idev, unsigned char reportnum,
> +				u8 *buf, size_t len)
> +{
> +	unsigned long timeout = msecs_to_jiffies(THC_IPTS_REQ_TIMEOUT_MS);
> +	unsigned int seq;
> +	int ret;

[ ... ]

> +	ret = thc_ipts_send(idev, THC_IPTS_TX_GET_FEATURE, &reportnum, 1);
> +	if (ret) {
> +		mutex_lock(&idev->feature_lock);
> +		idev->feature_pending = false;
> +
> +		/* The start bit was written before the wait, so the frame may
> +		 * well be on the wire: its answer cannot be told from the next
> +		 * request's one.
> +		 */
> +		if (ret == -ETIMEDOUT)
> +			WRITE_ONCE(idev->feature_off, true);
> +		mutex_unlock(&idev->feature_lock);
> +
> +		if (ret == -ETIMEDOUT)
> +			dev_err(idev->dev, "feature report %u not acknowledged\n",
> +				reportnum);
> +
> +		return ret;
> +	}
> +
> +	/* Taken after the write, or a reset that ran before it would be
> +	 * mistaken for one that dropped this frame.
> +	 */
> +	seq = READ_ONCE(idev->recover_seq);
> +
> +	wait_event_timeout(idev->wq, READ_ONCE(idev->feature_done) ||
> +			   READ_ONCE(idev->recover_pending) ||
> +			   READ_ONCE(idev->recovering) ||
> +			   READ_ONCE(idev->stopping), timeout);
> +
> +	mutex_lock(&idev->feature_lock);
> +	/* An answer that landed while the wait was expiring counts too. */
> +	if (!idev->feature_done) {
> +		/* A reset discards what the engines had queued, so an answer
> +		 * that was on its way is gone and cannot be waited for.
> +		 */
> +		if (READ_ONCE(idev->recover_seq) != seq ||
> +		    READ_ONCE(idev->recover_pending) ||
> +		    READ_ONCE(idev->recovering) ||
> +		    READ_ONCE(idev->stopping))
> +			ret = -EIO;
> +		else
> +			ret = -ETIMEDOUT;
> +
> +		idev->feature_pending = false;
> +		/* Only a timeout leaves a frame out there: after a reset the
> +		 * answer was dropped and the channel is still in step.
> +		 */
> +		if (ret == -ETIMEDOUT)
> +			WRITE_ONCE(idev->feature_off, true);

[Severity: Medium]
Can a reset that was queued during thc_ipts_send() finish before
thc_ipts_get_feature() samples idev->recover_seq, causing the dropped
feature response to be treated as a timeout?

CPU0                                  CPU1 (kworker)
thc_ipts_get_feature()
  thc_ipts_send()
    lock(&idev->tx_lock)
    thc_dma_write()
      ... (Rx error queues recover_work)
                                      thc_ipts_recover()
                                        lock(&idev->tx_lock)
    unlock(&idev->tx_lock)
                                        unlock(&idev->tx_lock)
                                        thc_rxdma_reset()
                                        idev->recover_seq++
                                        idev->recover_pending = false
                                        idev->recovering = false
  seq = READ_ONCE(idev->recover_seq)
  wait_event_timeout(...)
  /* times out with recover_seq == seq */
  idev->feature_off = true            <-- disables feature reports

Because idev->recover_seq is read after thc_ipts_send() drops
idev->tx_lock, thc_ipts_recover() can reset the receive engine (dropping
the answer), increment recover_seq, and clear recover_pending and
recovering before seq is sampled.  thc_ipts_get_feature() then sees no
change in recover_seq, returns -ETIMEDOUT instead of -EIO, and sets
idev->feature_off = true, shutting off all further feature requests until
the port restarts.

Also, wait_event_timeout() does not check READ_ONCE(idev->recover_seq) !=
seq in its condition, so if thc_ipts_recover() completes before the wait
condition is evaluated, the caller sleeps for the full timeout before
returning -EIO.

-- 
Sashiko AI review · https://sashiko.dev/#/patchset/20261118065725.673090-1-emfox@debian.org?part=3

^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: [PATCH v8 4/5] HID: intel-thc-hid: intel-ipts: handle system sleep
  2026-11-18  6:57 ` [PATCH v8 4/5] HID: intel-thc-hid: intel-ipts: handle system sleep Emfox Zhou
@ 2026-11-18  7:17   ` sashiko-bot
  0 siblings, 0 replies; 9+ messages in thread
From: sashiko-bot @ 2026-11-18  7:17 UTC (permalink / raw)
  To: Emfox Zhou; +Cc: linux-input, dmitry.torokhov

Thank you for your contribution! Sashiko AI review found 1 potential
issue to consider:
- [Medium] HID: intel-thc-hid: intel-ipts: unmasked IRQ in
  thc_ipts_resume()
--

commit 94ab9ee55e7317c455856236882094712be26a95
Author: Emfox Zhou <emfox@debian.org>

HID: intel-thc-hid: intel-ipts: handle system sleep

This commit adds system sleep and hibernation power management callbacks for
the intel-ipts PCI driver by stopping the port on suspend and restarting it on
resume.

> diff --git a/drivers/hid/intel-thc-hid/intel-ipts/pci-ipts.c b/drivers/hid/intel-thc-hid/intel-ipts/pci-ipts.c
> index 5aa0ad6fb19cb..b2d9be4eef248 100644
> --- a/drivers/hid/intel-thc-hid/intel-ipts/pci-ipts.c
> +++ b/drivers/hid/intel-thc-hid/intel-ipts/pci-ipts.c
> @@ -143,6 +143,30 @@ static void thc_ipts_remove(struct pci_dev *pci)
>  	pci_clear_master(pci);
>  }
>  
> +static int thc_ipts_suspend(struct device *dev)
> +{
> +	struct thc_ipts *idev = dev_get_drvdata(dev);
> +
> +	thc_ipts_port_stop(idev);
> +
> +	return 0;
> +}
> +
> +static int thc_ipts_resume(struct device *dev)
> +{
> +	struct thc_ipts *idev = dev_get_drvdata(dev);
> +	int ret;
> +
> +	ret = thc_ipts_port_start(idev);
> +	if (ret)
> +		thc_ipts_port_stop(idev);
> +
> +	return ret;
> +}

[Severity: Medium]
Should thc_ipts_resume() mask interrupts with thc_interrupt_enable(idev->thc,
false) before calling thc_ipts_port_start(), just as thc_ipts_probe() does?

Across system sleep or hibernation restore, firmware can leave the global
interrupt enable set while idev->dma_ready is false (cleared during
thc_ipts_port_stop()).  During thc_ipts_port_start(), the controller is
released from reset, unquiesced, and has touch and DMA enabled before
thc_ipts_dma_start() sets idev->dma_ready to true:

drivers/hid/intel-thc-hid/intel-ipts/ipts.c:thc_ipts_hardirq() {
	/* Nothing of ours is pending: the cause belongs to a sharer. */
	if (!READ_ONCE(idev->dma_ready))
		return IRQ_NONE;

	/* Level triggered and shared: mask first, or it stays asserted. */
	thc_interrupt_enable(idev->thc, false);
}

If the port asserts the shared level-triggered interrupt before
idev->dma_ready becomes true, thc_ipts_hardirq() returns IRQ_NONE without
masking the line, causing an unhandled interrupt storm that disables the
shared IRQ vector.

-- 
Sashiko AI review · https://sashiko.dev/#/patchset/20261118065725.673090-1-emfox@debian.org?part=4

^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: [PATCH v8 2/5] HID: intel-thc-hid: intel-ipts: receive reports
  2026-11-18  6:57 ` [PATCH v8 2/5] HID: intel-thc-hid: intel-ipts: receive reports Emfox Zhou
@ 2026-11-18  7:19   ` sashiko-bot
  0 siblings, 0 replies; 9+ messages in thread
From: sashiko-bot @ 2026-11-18  7:19 UTC (permalink / raw)
  To: Emfox Zhou; +Cc: linux-input, dmitry.torokhov

Thank you for your contribution! Sashiko AI review found 2 potential
issues to consider:
- [Medium] HID: intel-thc-hid: intel-ipts: invalid wait context in
  thc_ipts_hardirq()
- [Medium] HID: intel-ipts: thc_ipts_thread() claims foreign shared IRQs
  when recovering
--

commit 2c695eb72f038a390034bb1c66eb88c4e1603067
Author: Emfox Zhou <emfox@debian.org>

HID: intel-thc-hid: intel-ipts: receive reports

This commit configures the receive and transmit DMA engines, requests the
port interrupt with error recovery, and decodes incoming frames.

> diff --git a/drivers/hid/intel-thc-hid/intel-ipts/ipts.c b/drivers/hid/intel-thc-hid/intel-ipts/ipts.c
> index 2d14e5278f986..e7896b16f1ada 100644
> --- a/drivers/hid/intel-thc-hid/intel-ipts/ipts.c
> +++ b/drivers/hid/intel-thc-hid/intel-ipts/ipts.c
[ ... ]
> @@ -129,6 +144,283 @@ static int thc_ipts_touch_set(struct thc_ipts *idev, bool enable)
[ ... ]
> +irqreturn_t thc_ipts_hardirq(int irq, void *data)
> +{
> +	struct thc_ipts *idev = data;
> +
> +	/* Nothing of ours is pending: the cause belongs to a sharer. */
> +	if (!READ_ONCE(idev->dma_ready))
> +		return IRQ_NONE;
> +
> +	/* Level triggered and shared: mask first, or it stays asserted. */
> +	thc_interrupt_enable(idev->thc, false);
> +
> +	/*
> +	 * A reset or a teardown in flight still gets the thread: the status it
> +	 * drains is where a pending transmit completion is delivered, and a
> +	 * write waiting for that one holds the bus lock the reset needs.
> +	 */
> +	return IRQ_WAKE_THREAD;
> +}

[Severity: Medium]
Can calling thc_interrupt_enable() here trigger a lockdep invalid wait
context splat when sharing the legacy INTx line with an IRQF_ONESHOT
handler?

thc_ipts_probe() requests a PCI_IRQ_INTX vector with IRQF_SHARED |
IRQF_COND_ONESHOT.  When another handler on that line uses IRQF_ONESHOT,
__setup_irq() promotes this action to IRQF_ONESHOT on an IO-APIC chip
without IRQCHIP_ONESHOT_SAFE, so __handle_irq_event_percpu() runs
thc_ipts_hardirq() in LD_WAIT_SPIN context without calling
lockdep_hardirq_threaded().  thc_interrupt_enable() then calls
regmap_write_bits() on dev->thc_regmap, which uses a non-raw spinlock_t
because thc_regmap_cfg sets .fast_io = true without .use_raw_spinlock =
true.

[ ... ]

> +void thc_ipts_recover(struct work_struct *work)
> +{
> +	struct thc_ipts *idev = container_of(work, struct thc_ipts,
> +					     recover_work);
[ ... ]
> +	WRITE_ONCE(idev->recovering, true);
> +	thc_interrupt_enable(idev->thc, false);
> +	synchronize_irq(idev->irq);
> +	/* A run that unmasked just before synchronize_irq() returned leaves
> +	 * the line open: mask it again, the write is idempotent.
> +	 */
> +	thc_interrupt_enable(idev->thc, false);
> +
> +	if (thc_rxdma_reset(idev->thc)) {
> +		/* Nothing left: keep the port masked until it restarts. */
> +		dev_err(idev->dev, "cannot reset the receive engine\n");
> +		return;
> +	}
[ ... ]
> +irqreturn_t thc_ipts_thread(int irq, void *data)
> +{
[ ... ]
> +	for (pass = 0; pass < THC_IPTS_IRQ_PASSES; pass++) {
> +		int mask;
> +
> +		/*
> +		 * The reset owns the status registers while it runs: a frame
> +		 * acknowledged here but not read is never announced again.
> +		 */
> +		if (READ_ONCE(idev->recovering)) {
> +			/* Nothing acknowledged, but the line is still ours. */
> +			ret = IRQ_HANDLED;
> +			break;
> +		}

[Severity: Medium]
Does returning IRQ_HANDLED whenever idev->recovering is set claim foreign
interrupts on the shared INTx line?

While thc_ipts_recover() is running, or permanently if thc_rxdma_reset()
fails and returns early with idev->recovering and idev->dma_ready still
true, the port interrupt is masked in hardware.  Every interrupt from
another device sharing the INTx line still causes thc_ipts_hardirq() to
write MMIO and return IRQ_WAKE_THREAD, and thc_ipts_thread() then writes
MMIO again and returns IRQ_HANDLED without checking any status registers,
adding a thread wakeup on every shared interrupt and defeating spurious
interrupt detection if a sibling device gets stuck.

-- 
Sashiko AI review · https://sashiko.dev/#/patchset/20261118065725.673090-1-emfox@debian.org?part=2

^ permalink raw reply	[flat|nested] 9+ messages in thread

end of thread, other threads:[~2026-11-18  7:19 UTC | newest]

Thread overview: 9+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2026-11-18  6:57 [PATCH v8 0/5] HID: intel-thc-hid: intel-ipts: support THC IPTS ports Emfox Zhou
2026-11-18  6:57 ` [PATCH v8 1/5] HID: intel-thc-hid: intel-ipts: bring up the port Emfox Zhou
2026-11-18  6:57 ` [PATCH v8 2/5] HID: intel-thc-hid: intel-ipts: receive reports Emfox Zhou
2026-11-18  7:19   ` sashiko-bot
2026-11-18  6:57 ` [PATCH v8 3/5] HID: intel-thc-hid: intel-ipts: add the HID device Emfox Zhou
2026-11-18  7:14   ` sashiko-bot
2026-11-18  6:57 ` [PATCH v8 4/5] HID: intel-thc-hid: intel-ipts: handle system sleep Emfox Zhou
2026-11-18  7:17   ` sashiko-bot
2026-11-18  6:57 ` [PATCH v8 5/5] HID: intel-thc-hid: intel-ipts: document the IPTS mode Emfox Zhou

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.