=================================
Capacitive touch (Parade pt_core)
=================================

Register/protocol-level reverse engineering of the capacitive-touch kernel
driver — covered on its own page because it's an independent digitizer stack
from the pen (:doc:`/display/wacom-pen`) with its
own vendor driver and firmware. Built into ``artifacts/kernel`` and bound by
the DTB overlay (:doc:`/boot/dtbo`).

Method: the driver ``compatible``/GPIO bindings are read from
``artifacts/dtbo_a/overlay_0.dts``; the protocol details are from static
disassembly of the kernel (function starts located by ``__func__`` string
cross-reference, then read with ``capstone`` — the same toolkit as
:doc:`/display/tcon`, scripts in ``artifacts/re_static/``).
No code was executed.

DT binding
==========

.. list-table::
   :header-rows: 1
   :widths: 22 16 12 50

   * - Device
     - ``compatible``
     - Bus
     - GPIOs / notes
   * - **Capacitive touch** (``pt_tp@24``)
     - Parade TrueTouch (``pt_*``)
     - I²C ``0x24``
     - ``onyx-tp,irq/rst/vdd-ctrl/vcc-ctrl`` GPIOs (finger layer, distinct from
       the pen)

A **Parade TrueTouch**, current-generation **PIP2**-protocol finger-touch
controller, separate from the pen. It shares the Onyx ``onyx-tp,*`` GPIO
binding convention (irq/rst/vdd-ctrl/vcc-ctrl). The pen (EMR) and finger
(capacitive) layers are independent digitizers stacked on the panel. The
driver (``CONFIG_TOUCHSCREEN_PARADE=y``, built into this kernel, not a
loadable module) was disassembled directly from ``artifacts/kernel`` — the
same vendor code actually running this touchscreen right now, not an
assumption about what a similarly-named mainline driver does.

Driver internals
=================

- **``pt_probe`` (0x9f3a78)** is a real, large (~4 KB) driver-init
  function: per-instance naming via ``"%s%d"`` + the literal ``"pt_core"``,
  five distinct spinlocks (``module_list_lock``/``system_lock``/
  ``sysfs_lock``/``ttdl_restart_lock``/``firmware_class_lock``), ~8
  linked-list heads, and a userspace firmware-override path,
  ``/data/ttdl/pt_fw.bin`` (Parade's "TTDL" — Touch Tools Driver Library —
  naming), in addition to the built-in ``vendor/firmware/tp_fw/*.bin``
  blob (:doc:`/userspace/firmware-blobs`).
- **The runtime input-report path (``pt_parse_input``, ~0x9eebc0)** does a
  **plain, register-less, 2-byte length-prefixed I²C read** — no
  register-select write beforehand, just an
  ``i2c_master_recv()``-equivalent read of 2 bytes giving the pending
  report length, then a second read of that many bytes into the report
  buffer. This is the same algorithm mainline's generic
  ``i2c-hid-core.c`` uses (:doc:`/linux-port-status`), and is a different,
  simpler convention than the Wacom driver's explicit
  command-register(``0x0004``)/data-register(``0x0005``) addressing on
  the same I²C bus (:doc:`/display/wacom-pen`). A short length-based dispatch
  handles a bootloader "reset sentinel" (len``0xb`` with a specific byte
  pattern), an "empty buffer" case (len``2``), and a max-report-size sanity
  check (len``0x211``) before falling through to the actual multitouch
  decode (not traced further). Full disassembly notes:
  ``artifacts/re_static/item_touch_pt_core_recheck.txt``.
- A shared Onyx "TP info" debug function (0x9e94a8) prints
  device/touch-name, firmware version, manufacturer, panel thickness,
  product ID and a magic word for **both** this chip and the Wacom pen
  through one common struct — alongside the fingerprint sensor's
  three-vendor-drivers-compiled-in pattern (:doc:`misc`), this is consistent
  with "compile every candidate vendor driver, whichever chip answers wins"
  being a house convention across all of this device's swappable-supplier
  peripherals, not just fingerprint (inferred from static structure, not
  traced at runtime).
- **Exact chip self-ID struct offsets recovered, the value itself still
  live-only.** A debug-log dump function (``pt_si_put_log_data``,
  0x9efa80) reads the JTAG silicon ID and manufacturer ID directly off
  fixed offsets in the driver's private struct: ``+0x734`` = ``jtag_id_l``
  (u16), ``+0x736`` = ``jtag_id_h`` (u16), ``+0x738`` = ``mfg_id[]``
  (u8 array), ``+0x727`` = ``bl_ver_minor`` (u8). A sysfs "show" handler
  (0x9ff460) calls into the same read path, exposing this struct to
  userspace at runtime. This precisely scopes (but does not close) the
  "exact Parade part number" question the same way the boot-chain
  residuals in :doc:`/open-questions` are scoped to an exact
  register/offset rather than left as "somewhere in the chip".

Provenance
==========

:Source: ``artifacts/dtbo_a/overlay_0.dts`` (the ``compatible`` binding, I²C
   address, GPIO assignments); ``artifacts/kernel`` (Parade ``pt_core`` driver
   functions, disassembled via the ``__func__``-xref + ``capstone`` toolkit;
   full evidence in ``artifacts/re_static/item_touch_pt_core_recheck.txt``).
:Method: device-tree reading + targeted static disassembly (no ELF symbols /
   no ``kallsyms`` for the kernel). No code executed; nothing run on a device.
:Cross-refs: :doc:`/display/wacom-pen`, :doc:`misc`, :doc:`/display/tcon`,
   :doc:`/display/stack`, :doc:`/userspace/firmware-blobs`, :doc:`/boot/dtbo`,
   :doc:`/linux-port-status`.