From mboxrd@z Thu Jan  1 00:00:00 1970
Received: from mgamail.intel.com (mgamail.intel.com [192.198.163.7])
	(using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits))
	(No client certificate requested)
	by smtp.subspace.kernel.org (Postfix) with ESMTPS id A87A21DC9BB;
	Mon,  6 Jan 2025 13:05:36 +0000 (UTC)
Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=192.198.163.7
ARC-Seal:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116;
	t=1736168739; cv=none; b=Rk4NNNfcFgykSwBh3s1YnysMNiTg1zmnfHdKd7vOXznycQ3dIvMnqg6SvSHABwX7YPgdKKO8BkaaUTfeWiyANR/fbD6QqGOF5hbFd+iuB+msnIKy91GYR39NXaNh/8QzK7JgpRTXkGWbX5BuJZi2LR20P/6d31qDMcpAwtUJXAE=
ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org;
	s=arc-20240116; t=1736168739; c=relaxed/simple;
	bh=NdK8824/tV+4ToXjBjhbGKm5Cb0Ax+2vn7tTxHpBc8Q=;
	h=Message-ID:Subject:From:To:Cc:Date:In-Reply-To:References:
	 Content-Type:MIME-Version; b=b+kcEEOt84CYSZv3XEH/6F+yA8ocoKrnYpRwsm4w8Lc+huEzxhcV9EF+J1PFnis1b1UNnGNBYOxsb0UDDmEPZpx3olT6EXjW2tzYRhe6VaI4ga5aJlzYVaNcH8xzJOlPgpS1fvNVxpJ2BMVqivMqWCh8Mbqjsay1vLH4tX/S+lg=
ARC-Authentication-Results:i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=linux.intel.com; spf=none smtp.mailfrom=linux.intel.com; dkim=pass (2048-bit key) header.d=intel.com header.i=@intel.com header.b=iUHsZAT0; arc=none smtp.client-ip=192.198.163.7
Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=linux.intel.com
Authentication-Results: smtp.subspace.kernel.org; spf=none smtp.mailfrom=linux.intel.com
Authentication-Results: smtp.subspace.kernel.org;
	dkim=pass (2048-bit key) header.d=intel.com header.i=@intel.com header.b="iUHsZAT0"
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple;
  d=intel.com; i=@intel.com; q=dns/txt; s=Intel;
  t=1736168737; x=1767704737;
  h=message-id:subject:from:to:cc:date:in-reply-to:
   references:content-transfer-encoding:mime-version;
  bh=NdK8824/tV+4ToXjBjhbGKm5Cb0Ax+2vn7tTxHpBc8Q=;
  b=iUHsZAT0eYIXvKKU+JEW0mgeOnWH8giX5dQAn1Te0NoFhKV4qIynu9nZ
   gOcgB21ereJAQTtpKnHZNT/LS7qPSDMcqaGDGG1C+4Wl8cxad6z6EaRpa
   AqgD1rMq/KJ5RQpx23Ip9G02KhIFDqiTL2CCCkLVbAOMxw2fz1poCgKvv
   ZYU/k/zSTO2kBCv8OpQv6lkxqzlsLxPmkq7bJluNmPqcLiy53lvWo+OUe
   YLAlkr4bFzh4skA8zwqngnZio0POKBnuVqcBfYzDiWlyCFJ1bLrxk4WWD
   46BnBgtxutcQyFCpxUq1ANsRBE78zi/rhw9l5k1bEpZx9ftmvDzbZ/D/w
   w==;
X-CSE-ConnectionGUID: tZTOS/qQROKQUxHEG6gPbQ==
X-CSE-MsgGUID: 4s0bAhXTQPmJ2AYpPn+7Xw==
X-IronPort-AV: E=McAfee;i="6700,10204,11307"; a="61689115"
X-IronPort-AV: E=Sophos;i="6.12,292,1728975600"; 
   d="scan'208";a="61689115"
Received: from fmviesa010.fm.intel.com ([10.60.135.150])
  by fmvoesa101.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 06 Jan 2025 05:05:36 -0800
X-CSE-ConnectionGUID: t2aV4mwZT7uqcncM6rWeTw==
X-CSE-MsgGUID: Lp31a1P5SPq8cmcnbHsNmw==
X-ExtLoop1: 1
X-IronPort-AV: E=Sophos;i="6.12,292,1728975600"; 
   d="scan'208";a="102933198"
Received: from spandruv-desk.jf.intel.com ([10.54.75.16])
  by fmviesa010-auth.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 06 Jan 2025 05:05:35 -0800
Message-ID: <5886086c1ef2778f3b9614956d0a43dc21fc1942.camel@linux.intel.com>
Subject: Re: [PATCH v4 01/22] HID: THC: Add documentation
From: srinivas pandruvada <srinivas.pandruvada@linux.intel.com>
To: Even Xu <even.xu@intel.com>, jikos@kernel.org, bentiss@kernel.org, 
	corbet@lwn.net, bagasdotme@gmail.com, aaron.ma@canonical.com, 
	rdunlap@infradead.org, mpearson-lenovo@squebb.ca
Cc: linux-input@vger.kernel.org, linux-kernel@vger.kernel.org, 
	linux-doc@vger.kernel.org, Sun Xinpeng <xinpeng.sun@intel.com>
Date: Mon, 06 Jan 2025 05:05:35 -0800
In-Reply-To: <20250106023151.3011329-2-even.xu@intel.com>
References: <20250106023151.3011329-1-even.xu@intel.com>
	 <20250106023151.3011329-2-even.xu@intel.com>
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable
User-Agent: Evolution 3.54.2 (3.54.2-1.fc41) 
Precedence: bulk
X-Mailing-List: linux-kernel@vger.kernel.org
List-Id: <linux-kernel.vger.kernel.org>
List-Subscribe: <mailto:linux-kernel+subscribe@vger.kernel.org>
List-Unsubscribe: <mailto:linux-kernel+unsubscribe@vger.kernel.org>
MIME-Version: 1.0

On Mon, 2025-01-06 at 10:31 +0800, Even Xu wrote:
> Add Documentation/hid/intel-thc-hid.rst file to provide hardware
> and software detail for intel THC drivers.
>=20
> Co-developed-by: Sun Xinpeng <xinpeng.sun@intel.com>
> Signed-off-by: Sun Xinpeng <xinpeng.sun@intel.com>
> Signed-off-by: Even Xu <even.xu@intel.com>
> Reviewed-by: Srinivas Pandruvada
> <srinivas.pandruvada@linux.intel.com>
> Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>
> Reviewed-by: Mark Pearson <mpearson-lenovo@squebb.ca>
> ---

Change logs are missing?
Also didn't receive any cover letter with any changes?

Thanks,
Srinivas

> =C2=A0Documentation/hid/index.rst=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=
=A0=C2=A0 |=C2=A0=C2=A0 1 +
> =C2=A0Documentation/hid/intel-thc-hid.rst | 568
> ++++++++++++++++++++++++++++
> =C2=A02 files changed, 569 insertions(+)
> =C2=A0create mode 100644 Documentation/hid/intel-thc-hid.rst
>=20
> diff --git a/Documentation/hid/index.rst
> b/Documentation/hid/index.rst
> index af02cf7cfa82..baf156b44b58 100644
> --- a/Documentation/hid/index.rst
> +++ b/Documentation/hid/index.rst
> @@ -18,4 +18,5 @@ Human Interface Devices (HID)
> =C2=A0
> =C2=A0=C2=A0=C2=A0 hid-alps
> =C2=A0=C2=A0=C2=A0 intel-ish-hid
> +=C2=A0=C2=A0 intel-thc-hid
> =C2=A0=C2=A0=C2=A0 amd-sfh-hid
> diff --git a/Documentation/hid/intel-thc-hid.rst
> b/Documentation/hid/intel-thc-hid.rst
> new file mode 100644
> index 000000000000..6c417205ac6a
> --- /dev/null
> +++ b/Documentation/hid/intel-thc-hid.rst
> @@ -0,0 +1,568 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D
> +Intel Touch Host Controller (THC)
> +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D
> +
> +Touch Host Controller is the name of the IP block in PCH that
> interface with Touch Devices (ex:
> +touchscreen, touchpad etc.). It is comprised of 3 key functional
> blocks:
> +
> +- A natively half-duplex Quad I/O capable SPI master
> +- Low latency I2C interface to support HIDI2C compliant devices
> +- A HW sequencer with RW DMA capability to system memory
> +
> +It has a single root space IOSF Primary interface that supports
> transactions to/from touch devices.
> +Host driver configures and controls the touch devices over THC
> interface. THC provides high
> +bandwidth DMA services to the touch driver and transfers the HID
> report to host system main memory.
> +
> +Hardware sequencer within the THC is responsible for transferring
> (via DMA) data from touch devices
> +into system memory. A ring buffer is used to avoid data loss due to
> asynchronous nature of data
> +consumption (by host) in relation to data production (by touch
> device via DMA).
> +
> +Unlike other common SPI/I2C controllers, THC handles the HID device
> data interrupt and reset
> +signals directly.
> +
> +1. Overview
> +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
> +
> +1.1 THC software/hardware stack
> +-------------------------------
> +
> +Below diagram illustrates the high-level architecture of THC
> software/hardware stack, which is fully
> +capable of supporting HIDSPI/HIDI2C protocol in Linux OS.
> +
> +::
> +
> +=C2=A0 ----------------------------------------------
> + |=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 +-----------------------------------+=
=C2=A0=C2=A0 |
> + |=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 |=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=
=C2=A0=C2=A0=C2=A0=C2=A0 Input Device=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=
=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 |=C2=A0=C2=A0 |
> + |=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 +-----------------------------------+=
=C2=A0=C2=A0 |
> + |=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 +-----------------------------------+=
=C2=A0=C2=A0 |
> + |=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 |=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 H=
ID Multi-touch Driver=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 |=C2=A0=C2=A0 |
> + |=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 +-----------------------------------+=
=C2=A0=C2=A0 |
> + |=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 +-----------------------------------+=
=C2=A0=C2=A0 |
> + |=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 |=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=
=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 HID Core=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=
=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 |=C2=A0=C2=A0 |
> + |=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 +-----------------------------------+=
=C2=A0=C2=A0 |
> + |=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 +-----------------------------------+=
=C2=A0=C2=A0 |
> + |=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 |=C2=A0=C2=A0=C2=A0 THC QuickSPI/QuickI=
2C Driver=C2=A0=C2=A0 |=C2=A0=C2=A0 |
> + |=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 +-----------------------------------+=
=C2=A0=C2=A0 |
> + |=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 +-----------------------------------+=
=C2=A0=C2=A0 |
> + |=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 |=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 THC Har=
dware Driver=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 |=C2=A0=
=C2=A0 |
> + |=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 +-----------------------------------+=
=C2=A0=C2=A0 |
> + |=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 +----------------+ +----------------+=
=C2=A0=C2=A0 |
> + |=C2=A0 SW=C2=A0 | PCI Bus Driver | | ACPI Resource=C2=A0 |=C2=A0=C2=A0=
 |
> + |=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 +----------------+ +----------------+=
=C2=A0=C2=A0 |
> +=C2=A0 ----------------------------------------------
> +=C2=A0 ----------------------------------------------
> + |=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 +-----------------------------------+=
=C2=A0=C2=A0 |
> + |=C2=A0 HW=C2=A0 |=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=
=A0=C2=A0=C2=A0=C2=A0=C2=A0 PCI Bus=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=
=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 |=C2=A0=C2=A0 |
> + |=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 +-----------------------------------+=
=C2=A0=C2=A0 |
> + |=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 +-----------------------------------+=
=C2=A0=C2=A0 |
> + |=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 |=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=
=C2=A0=C2=A0=C2=A0=C2=A0 THC Controller=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=
=C2=A0=C2=A0=C2=A0 |=C2=A0=C2=A0 |
> + |=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 +-----------------------------------+=
=C2=A0=C2=A0 |
> + |=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 +-----------------------------------+=
=C2=A0=C2=A0 |
> + |=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 |=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=
=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 Touch IC=C2=A0=C2=A0=C2=A0=C2=A0=
=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 |=C2=A0=C2=A0 |
> + |=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 +-----------------------------------+=
=C2=A0=C2=A0 |
> +=C2=A0 ----------------------------------------------
> +
> +Touch IC (TIC), also as known as the Touch devices (touchscreen or
> touchpad). The discrete analog
> +components that sense and transfer either discrete touch data or
> heatmap data in the form of HID
> +reports over the SPI/I2C bus to the THC Controller on the host.
> +
> +THC Host Controller, which is a PCI device HBA (host bus adapter),
> integrated into the PCH, that
> +serves as a bridge between the Touch ICs and the host.
> +
> +THC Hardware Driver, provides THC hardware operation APIs for above
> QuickSPI/QuickI2C driver, it
> +accesses THC MMIO registers to configure and control THC hardware.
> +
> +THC QuickSPI/QuickI2C driver, also as known as HIDSPI/HIDI2C driver,
> is registered as a HID
> +low-level driver that manages the THC Controller and implements
> HIDSPI/HIDI2C protocol.
> +
> +
> +1.2 THC hardware diagram
> +------------------------
> +Below diagram shows THC hardware components::
> +
> +=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=
=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 --------------------=
-------------
> +=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=
=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 |=C2=A0=C2=A0=C2=A0=C2=A0=
=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 THC Controller=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=
=C2=A0=C2=A0=C2=A0 |
> +=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=
=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 |=C2=A0 +-----------------=
----------+=C2=A0 |
> +=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=
=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 |=C2=A0 |=C2=A0=C2=A0=C2=
=A0=C2=A0 PCI Config Space=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 |=C2=A0 |
> +=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=
=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 |=C2=A0 +-----------------=
----------+=C2=A0 |
> +=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=
=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 |=C2=A0 +-----------------=
----------+=C2=A0 |
> +=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=
=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 |=C2=A0 +=C2=A0=C2=A0=C2=
=A0=C2=A0=C2=A0=C2=A0 MMIO Registers=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 |=C2=A0 =
|
> +=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=
=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 |=C2=A0 +-----------------=
----------+=C2=A0 |
> + +---------------+=C2=A0=C2=A0 |=C2=A0 +------------+ +------------+=C2=
=A0 |
> + | System Memory +---+--+=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 DMA=C2=A0=C2=A0 =
| |=C2=A0=C2=A0 PIO=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 |=C2=A0 |
> + +---------------+=C2=A0=C2=A0 |=C2=A0 +------------+ +------------+=C2=
=A0 |
> +=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=
=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 |=C2=A0 +-----------------=
----------+=C2=A0 |
> +=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=
=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 |=C2=A0 |=C2=A0=C2=A0=C2=
=A0=C2=A0=C2=A0=C2=A0 HW Sequencer=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=
=A0 |=C2=A0 |
> +=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=
=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 |=C2=A0 +-----------------=
----------+=C2=A0 |
> +=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=
=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 |=C2=A0 +------------+ +--=
----------+=C2=A0 |
> +=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=
=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 |=C2=A0 |=C2=A0 SPI/I2C=C2=
=A0=C2=A0 | |=C2=A0=C2=A0=C2=A0 GPIO=C2=A0=C2=A0=C2=A0 |=C2=A0 |
> +=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=
=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 |=C2=A0 | Controller | | C=
ontroller |=C2=A0 |
> +=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=
=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 |=C2=A0 +------------+ +--=
----------+=C2=A0 |
> +=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=
=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 --------------------=
-------------
> +
> +As THC is exposed as a PCI devices, so it has standard PCI config
> space registers for PCI
> +enumeration and configuration.
> +
> +MMIO Registers, which provide registers access for driver to
> configure and control THC hardware,
> +the registers include several categories: Interrupt status and
> control, DMA configure,
> +PIO (Programmed I/O, defined in section 3.2) status and control, SPI
> bus configure, I2C subIP
> +status and control, reset status and control...
> +
> +THC provides two ways for driver to communicate with external Touch
> ICs: PIO and DMA.
> +PIO can let driver manually write/read data to/from Touch ICs,
> instead, THC DMA can
> +automatically write/read data without driver involved.
> +
> +HW Sequencer includes THC major logic, it gets instruction from MMIO
> registers to control
> +SPI bus and I2C bus to finish a bus data transaction, it also can
> automatically handle
> +Touch ICs interrupt and start DMA receive/send data from/to Touch
> ICs according to interrupt
> +type. That means THC HW Sequencer understands HIDSPI/HIDI2C transfer
> protocol, and handle
> +the communication without driver involved, what driver needs to do
> is just configure the THC
> +properly, and prepare the formatted data packet or handle received
> data packet.
> +
> +As THC supports HIDSPI/HIDI2C protocols, it has SPI controller and
> I2C subIP in it to expose
> +SPI bus and I2C bus. THC also integrates a GPIO controller to
> provide interrupt line support
> +and reset line support.
> +
> +2. THC Hardware Interface
> +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D
> +
> +2.1 Host Interface
> +------------------
> +
> +THC is exposed as "PCI Digitizer device" to the host. The PCI
> product and device IDs are
> +changed from different generations of processors. So the source code
> which enumerates drivers
> +needs to update from generation to generation.
> +
> +
> +2.2 Device Interface
> +--------------------
> +
> +THC supports two types of bus for Touch IC connection: Enhanced SPI
> bus and I2C bus.
> +
> +2.2.1 SPI Port
> +~~~~~~~~~~~~~~
> +
> +When PORT_TYPE =3D 00b in MMIO registers, THC uses SPI interfaces to
> communicate with external
> +Touch IC. THC enhanced SPI Bus supports different SPI modes:
> standard Single IO mode,
> +Dual IO mode and Quad IO mode.
> +
> +In Single IO mode, THC drives MOSI line to send data to Touch ICs,
> and receives data from Touch
> +ICs data from MISO line. In Dual IO mode, THC drivers MOSI and MISO
> both for data sending, and
> +also receives the data on both line. In Quad IO mode, there are
> other two lines (IO2 and IO3)
> +are added, THC drives MOSI (IO0), MISO (IO1), IO2 and IO3 at the
> same time for data sending, and
> +also receives the data on those 4 lines. Driver needs to configure
> THC in different mode by
> +setting different opcode.
> +
> +Beside IO mode, driver also needs to configure SPI bus speed. THC
> supports up to 42MHz SPI clock
> +on Intel Lunar Lake platform.
> +
> +For THC sending data to Touch IC, the data flow on SPI bus::
> +
> + | --------------------THC sends---------------------------------|
> + <8Bits OPCode><24Bits Slave Address><Data><Data><Data>...........
> +
> +For THC receiving data from Touch IC, the data flow on SPI bus::
> +
> + | ---------THC Sends---------------||-----Touch IC sends--------|
> + <8Bits OPCode><24Bits Slave Address><Data><Data><Data>...........
> +
> +2.2.2 I2C Port
> +~~~~~~~~~~~~~~
> +
> +THC also integrates I2C controller in it, it's called I2C SubSystem.
> When PORT_TYPE =3D 01, THC
> +is configured to I2C mode. Comparing to SPI mode which can be
> configured through MMIO registers
> +directly, THC needs to use PIO read (by setting SubIP read opcode)
> to I2C subIP APB registers'
> +value and use PIO write (by setting SubIP write opcode) to do a
> write operation.
> +
> +2.2.3 GPIO interface
> +~~~~~~~~~~~~~~~~~~~~
> +
> +THC also includes two GPIO pins, one for interrupt and the other for
> device reset control.
> +
> +Interrupt line can be configured to either level triggerred or edge
> triggerred by setting MMIO
> +Control register.
> +
> +Reset line is controlled by BIOS (or EFI) through ACPI _RST method,
> driver needs to call this
> +device ACPI _RST method to reset touch IC during initialization.
> +
> +3. High level concept
> +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
> +
> +3.1 Opcode
> +----------
> +
> +Opcode (operation code) is used to tell THC or Touch IC what the
> operation will be, such as PIO
> +read or PIO write.
> +
> +When THC is configured to SPI mode, opcodes are used for determining
> the read/write IO mode.
> +There are some OPCode examples for SPI IO mode:
> +
> +=3D=3D=3D=3D=3D=3D=3D=C2=A0=C2=A0 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
> +opcode=C2=A0=C2=A0=C2=A0 Corresponding SPI command
> +=3D=3D=3D=3D=3D=3D=3D=C2=A0=C2=A0 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
> +0x0B=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 Read Single I/O
> +0x02=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 Write Single I/O
> +0xBB=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 Read Dual I/O
> +0xB2=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 Write Dual I/O
> +0xEB=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 Read Quad I/O
> +0xE2=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 Write Quad I/O
> +=3D=3D=3D=3D=3D=3D=3D=C2=A0=C2=A0 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
> +
> +In general, different touch IC has different OPCode definition.
> According to HIDSPI
> +protocol whitepaper, those OPCodes are defined in device ACPI table,
> and driver needs to
> +query those information through OS ACPI APIs during driver
> initialization, then configures
> +THC MMIO OPCode registers with correct setting.
> +
> +When THC is working in I2C mode, opcodes are used to tell THC what's
> the next PIO type:
> +I2C SubIP APB register read, I2C SubIP APB register write, I2C touch
> IC device read,
> +I2C touch IC device write, I2C touch IC device write followed by
> read.
> +
> +Here are the THC pre-defined opcodes for I2C mode:
> +
> +=3D=3D=3D=3D=3D=3D=3D=C2=A0=C2=A0 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=C2=A0=C2=A0
> =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
> +opcode=C2=A0=C2=A0=C2=A0 Corresponding I2C command=C2=A0=C2=A0=C2=A0=C2=
=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=
=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0
> Address
> +=3D=3D=3D=3D=3D=3D=3D=C2=A0=C2=A0 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=C2=A0=C2=A0
> =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
> +0x12=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 Read I2C SubIP APB internal registers=
=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=
=A0=C2=A0=C2=A0=C2=A0 0h -
> FFh
> +0x13=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 Write I2C SubIP APB internal register=
s=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=
=C2=A0=C2=A0=C2=A0 0h -
> FFh
> +0x14=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 Read external Touch IC through I2C bu=
s=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=
=C2=A0=C2=A0=C2=A0 N/A
> +0x18=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 Write external Touch IC through I2C b=
us=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=
=C2=A0=C2=A0 N/A
> +0x1C=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 Write then read external Touch IC thr=
ough I2C bus=C2=A0=C2=A0=C2=A0=C2=A0 N/A
> +=3D=3D=3D=3D=3D=3D=3D=C2=A0=C2=A0 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=C2=A0=C2=A0
> =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
> +
> +3.2 PIO
> +-------
> +
> +THC provides a programmed I/O (PIO) access interface for the driver
> to access the touch IC's
> +configuration registers, or access I2C subIP's configuration
> registers. To use PIO to perform
> +I/O operations, driver should pre-program PIO control registers and
> PIO data registers and kick
> +off the sequencing cycle. THC uses different PIO opcodes to
> distinguish different PIO
> +operations (PIO read/write/write followed by read).
> +
> +If there is a Sequencing Cycle In Progress and an attempt is made to
> program any of the control,
> +address, or data register the cycle is blocked and a sequence error
> will be encountered.
> +
> +A status bit indicates when the cycle has completed allowing the
> driver to know when read results
> +can be checked and/or when to initiate a new command. If enabled,
> the cycle done assertion can
> +interrupt driver with an interrupt.
> +
> +Because THC only has 16 FIFO registers for PIO, so all the data
> transfer through PIO shouldn't
> +exceed 64 bytes.
> +
> +As DMA needs max packet size for transferring configuration, and the
> max packet size information
> +always in HID device descriptor which needs THC driver to read it
> out from HID Device (Touch IC).
> +So PIO typical use case is, before DMA initialization, write RESET
> command (PIO write), read
> +RESET response (PIO read or PIO write followed by read), write Power
> ON command (PIO write), read
> +device descriptor (PIO read).
> +
> +For how to issue a PIO operation, here is the steps which driver
> needs follow:
> +
> +- Program read/write data size in THC_SS_BC.
> +- Program I/O target address in THC_SW_SEQ_DATA0_ADDR.
> +- If write, program the write data in
> THC_SW_SEQ_DATA0..THC_SW_SEQ_DATAn.
> +- Program the PIO opcode in THC_SS_CMD.
> +- Set TSSGO =3D 1 to start the PIO write sequence.
> +- If THC_SS_CD_IE =3D 1, SW will receives a MSI when the PIO is
> completed.
> +- If read, read out the data in THC_SW_SEQ_DATA0..THC_SW_SEQ_DATAn.
> +
> +3.3 DMA
> +-------
> +
> +THC has 4 DMA channels: Read DMA1, Read DMA2, Write DMA and Software
> DMA.
> +
> +3.3.1 Read DMA Channel
> +~~~~~~~~~~~~~~~~~~~~~~
> +
> +THC has two Read DMA engines: 1st RxDMA (RxDMA1) and 2nd RxDMA
> (RxDMA2). RxDMA1 is reserved for
> +raw data mode. RxDMA2 is used for HID data mode and it is the RxDMA
> engine currently driver uses
> +for HID input report data retrieval.
> +
> +RxDMA's typical use case is auto receiving the data from Touch IC.
> Once RxDMA is enabled by
> +software, THC will start auto-handling receiving logic.
> +
> +For SPI mode, THC RxDMA sequence is: when Touch IC triggers a
> interrupt to THC, THC reads out
> +report header to identify what's the report type, and what's the
> report length, according to
> +above information, THC reads out report body to internal FIFO and
> start RxDMA coping the data
> +to system memory. After that, THC update interrupt cause register
> with report type, and update
> +RxDMA PRD table read pointer, then trigger a MSI interrupt to notify
> driver RxDMA finishing
> +data receiving.
> +
> +For I2C mode, THC RxDMA's behavior is a little bit different,
> because of HIDI2C protocol difference
> +with HIDSPI protocol, RxDMA only be used to receive input report.
> The sequence is, when Touch IC
> +triggers a interrupt to THC, THC first reads out 2 bytes from input
> report address to determine the
> +packet length, then use this packet length to start a DMA reading
> from input report address for
> +input report data. After that, THC update RxDMA PRD table read
> pointer, then trigger a MSI interrupt
> +to notify driver input report data is ready in system memory.
> +
> +All above sequence is hardware automatically handled, all driver
> needs to do is configure RxDMA and
> +waiting for interrupt ready then read out the data from system
> memory.
> +
> +3.3.2 Software DMA channel
> +~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +THC supports a software triggerred RxDMA mode to read the touch data
> from touch IC. This SW RxDMA
> +is the 3rd THC RxDMA engine with the similar functionalities as the
> existing two RxDMAs, the only
> +difference is this SW RxDMA is triggerred by software, and RxDMA2 is
> triggerred by external Touch IC
> +interrupt. It gives a flexiblity to software driver to use RxDMA
> read Touch IC data in any time.
> +
> +Before software starts a SW RxDMA, it shall stop the 1st and 2nd
> RxDMA, clear PRD read/write pointer
> +and quiesce the device interrupt (THC_DEVINT_QUIESCE_HW_STS =3D 1),
> other operations are the same with
> +RxDMA.
> +
> +3.3.3 Write DMA Channel
> +~~~~~~~~~~~~~~~~~~~~~~~
> +
> +THC has one write DMA engine, which can be used for sending data to
> Touch IC automatically.
> +According to HIDSPI and HIDI2C protocol, every time only one command
> can be sent to touch IC, and
> +before last command is completely handled, next command cannot be
> sent, THC write DMA engine only
> +supports single PRD table.
> +
> +What driver needs to do is, preparing PRD table and DMA buffer, then
> copy data to DMA buffer and
> +update PRD table with buffer address and buffer length, then start
> write DMA. THC will
> +automatically send the data to touch IC, and trigger a DMA
> completion interrupt once transferring
> +is done.
> +
> +3.4 PRD
> +-------
> +
> +Physical Region Descriptor (PRD) provides the memory mapping
> description for THC DMAs.
> +
> +3.4.1 PRD table and entry
> +~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +In order to improve physical DMA memory usage, modern drivers trend
> to allocate a virtually
> +contiguous, but physically fragmented buffer of memory for each data
> buffer. Linux OS also
> +provide SGL (scatter gather list) APIs to support this usage.
> +
> +THC uses PRD table (physical region descriptor) to support the
> corresponding OS kernel
> +SGL that describes the virtual to physical buffer mapping.
> +
> +::
> +
> +=C2=A0 ------------------------=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 ----------=
----=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 --------------
> + | PRD table base address +----+ PRD table #1 +-----+ PRD Entry #1 |
> +=C2=A0 ------------------------=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 ----------=
----=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 --------------
> +=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=
=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=
=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=
=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=
=A0=C2=A0=C2=A0 --------------
> +=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=
=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=
=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=
=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=
=A0=C2=A0 | PRD Entry #2 |
> +=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=
=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=
=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=
=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=
=A0=C2=A0=C2=A0 --------------
> +=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=
=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=
=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=
=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=
=A0=C2=A0=C2=A0 --------------
> +=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=
=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=
=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=
=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=
=A0=C2=A0 | PRD Entry #n |
> +=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=
=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=
=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=
=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=
=A0=C2=A0=C2=A0 --------------
> +
> +The read DMA engine supports multiple PRD tables held within a
> circular buffer that allow the THC
> +to support multiple data buffers from the Touch IC. This allows host
> SW to arm the Read DMA engine
> +with multiple buffers, allowing the Touch IC to send multiple data
> frames to the THC without SW
> +interaction. This capability is required when the CPU processes
> touch frames slower than the
> +Touch IC can send them.
> +
> +To simplify the design, SW assumes worst-case memory fragmentation.
> Therefore,each PRD table shall
> +contain the same number of PRD entries, allowing for a global
> register (per Touch IC) to hold the
> +number of PRD-entries per PRD table.
> +
> +SW allocates up to 128 PRD tables per Read DMA engine as specified
> in the THC_M_PRT_RPRD_CNTRL.PCD
> +register field. The number of PRD tables should equal the number of
> data buffers.
> +
> +Max OS memory fragmentation will be at a 4KB boundary, thus to
> address 1MB of virtually contiguous
> +memory 256 PRD entries are required for a single PRD Table. SW
> writes the number of PRD entries
> +for each PRD table in the THC_M_PRT_RPRD_CNTRL.PTEC register field.
> The PRD entry's length must be
> +multiple of 4KB except for the last entry in a PRD table.
> +
> +SW allocates all the data buffers and PRD tables only once at host
> initialization.
> +
> +3.4.2 PRD Write pointer and read pointer
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +As PRD tables are organized as a Circular Buffer (CB), a read
> pointer and a write pointer for a CB
> +are needed.
> +
> +DMA HW consumes the PRD tables in the CB, one PRD entry at a time
> until the EOP bit is found set
> +in a PRD entry. At this point HW increments the PRD read pointer.
> Thus, the read pointer points
> +to the PRD which the DMA engine is currently processing. This
> pointer rolls over once the circular
> +buffer's depth has been traversed with bit[7] the Rollover bit. E.g.
> if the DMA CB depth is equal
> +to 4 entries (0011b), then the read pointers will follow this
> pattern (HW is required to honor
> +this behavior): 00h 01h 02h 03h 80h 81h 82h 83h 00h 01h ...
> +
> +The write pointer is updated by SW. The write pointer points to
> location in the DMA CB, where the
> +next PRD table is going to be stored. SW needs to ensure that this
> pointer rolls over once the
> +circular buffer's depth has been traversed with Bit[7] as the
> rollover bit. E.g. if the DMA CB
> +depth is equal to 5 entries (0100b), then the write pointers will
> follow this pattern (SW is
> +required to honor this behavior): 00h 01h 02h 03h 04h 80h 81h 82h
> 83h 84h 00h 01h ..
> +
> +3.4.3 PRD descriptor structure
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +Intel THC uses PRD entry descriptor for every PRD entry. Every PRD
> entry descriptor occupies
> +128 bits memories:
> +
> +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=C2=A0=C2=A0 =
=3D=3D=3D=3D=3D=3D=3D=3D=C2=A0=C2=A0
> =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
> +struct field=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 bit(s=
)=C2=A0=C2=A0=C2=A0=C2=A0 description
> +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=C2=A0=C2=A0 =
=3D=3D=3D=3D=3D=3D=3D=3D=C2=A0=C2=A0
> =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
> +dest_addr=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=
=A0=C2=A0 53..0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 destination memory address, a=
s
> every entry
> +=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=
=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=
=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 is 4KB, ignore lowest 10 bits=
 of
> address.
> +reserved1=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=
=A0=C2=A0 54..62=C2=A0=C2=A0=C2=A0=C2=A0 reserved
> +int_on_completion=C2=A0=C2=A0=C2=A0=C2=A0 63=C2=A0=C2=A0=C2=A0=C2=A0=C2=
=A0=C2=A0=C2=A0=C2=A0 completion interrupt enable bit, if
> this bit
> +=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=
=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=
=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 set it means THC will trigger=
 a
> completion
> +=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=
=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=
=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 interrupt. This bit is set by=
 SW
> driver.
> +len=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=
=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 87..64=C2=A0=C2=A0=C2=A0=C2=A0 how =
many bytes of data in this
> entry.
> +end_of_prd=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=
=C2=A0 88=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 end of PRD table =
bit, if this bit
> is set,
> +=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=
=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=
=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 it means this entry is last e=
ntry
> in this PRD
> +=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=
=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=
=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 table. This bit is set by SW
> driver.
> +hw_status=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=
=A0=C2=A0 90..89=C2=A0=C2=A0=C2=A0=C2=A0 HW status bits
> +reserved2=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=
=A0=C2=A0 127..91=C2=A0=C2=A0=C2=A0 reserved
> +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=C2=A0=C2=A0 =
=3D=3D=3D=3D=3D=3D=3D=3D=C2=A0=C2=A0
> =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
> +
> +And one PRD table can include up to 256 PRD entries, as every
> entries is 4K bytes, so every
> +PRD table can describe 1M bytes memory.
> +
> +.. code-block:: c
> +
> +=C2=A0=C2=A0 struct thc_prd_table {
> +=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 struct thc_prd_entry entries[=
PRD_ENTRIES_NUM];
> +=C2=A0=C2=A0 };
> +
> +In general, every PRD table means one HID touch data packet. Every
> DMA engine can support
> +up to 128 PRD tables (except write DMA, write DMA only has one PRD
> table). SW driver is responsible
> +to get max packet length from touch IC, and use this max packet
> length to create PRD entries for
> +each PRD table.
> +
> +4. HIDSPI support (QuickSPI)
> +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D
> +
> +Intel THC is total compatible with HIDSPI protocol, THC HW sequenser
> can accelerate HIDSPI
> +protocol transferring.
> +
> +4.1 Reset Flow
> +--------------
> +
> +- Call ACPI _RST method to reset Touch IC device.
> +- Read the reset response from TIC through PIO read.
> +- Issue a command to retrieve device descriptor from Touch IC
> through PIO write.
> +- Read the device descriptor from Touch IC through PIO read.
> +- If the device descriptor is valid, allocate DMA buffers and
> configure all DMA channels.
> +- Issue a command to retrieve report descriptor from Touch IC
> through DMA.
> +
> +4.2 Input Report Data Flow
> +--------------------------
> +
> +Basic Flow:
> +
> +- Touch IC interrupts the THC Controller using an in-band THC
> interrupt.
> +- THC Sequencer reads the input report header by transmitting read
> approval as a signal
> +=C2=A0 to the Touch IC to prepare for host to read from the device.
> +- THC Sequencer executes a Input Report Body Read operation
> corresponding to the value
> +=C2=A0 reflected in =E2=80=9CInput Report Length=E2=80=9D field of the I=
nput Report
> Header.
> +- THC DMA engine begins fetching data from the THC Sequencer and
> writes to host memory
> +=C2=A0 at PRD entry 0 for the current CB PRD table entry. This process
> continues until the
> +=C2=A0 THC Sequencer signals all data has been read or the THC DMA Read
> Engine reaches the
> +=C2=A0 end of it's last PRD entry (or both).
> +- The THC Sequencer checks for the =E2=80=9CLast Fragment Flag=E2=80=9D =
bit in the
> Input Report Header.
> +=C2=A0 If it is clear, the THC Sequencer enters an idle state.
> +- If the =E2=80=9CLast Fragment Flag=E2=80=9D bit is enabled the THC Seq=
uencer
> enters End-of-Frame Processing.
> +
> +THC Sequencer End of Frame Processing:
> +
> +- THC DMA engine increments the read pointer of the Read PRD CB,
> sets EOF interrupt status
> +=C2=A0 in RxDMA2 register (THC_M_PRT_READ_DMA_INT_STS_2).
> +- If THC EOF interrupt is enabled by the driver in the control
> register (THC_M_PRT_READ_DMA_CNTRL_2),
> +=C2=A0 generates interrupt to software.
> +
> +Sequence of steps to read data from RX DMA buffer:
> +
> +- THC QuickSPI driver checks CB write Ptr and CB read Ptr to
> identify if any data frame in DMA
> +=C2=A0 circular buffers.
> +- THC QuickSPI driver gets first unprocessed PRD table.
> +- THC QuickSPI driver scans all PRD entries in this PRD table to
> calculate the total frame size.
> +- THC QuickSPI driver copies all frame data out.
> +- THC QuickSPI driver checks the data type according to input report
> body, and calls related
> +=C2=A0 callbacks to process the data.
> +- THC QuickSPI driver updates write Ptr.
> +
> +4.3 Output Report Data Flow
> +---------------------------
> +
> +Generic Output Report Flow:
> +
> +- HID core calls raw_request callback with a request to THC QuickSPI
> driver.
> +- THC QuickSPI Driver converts request provided data into the output
> report packet and copies it
> +=C2=A0 to THC's write DMA buffer.
> +- Start TxDMA to complete the write operation.
> +
> +5. HIDI2C support (QuickI2C)
> +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D
> +
> +5.1 Reset Flow
> +--------------
> +
> +- Read device descriptor from Touch IC device through PIO write
> followed by read.
> +- If the device descriptor is valid, allocate DMA buffers and
> configure all DMA channels.
> +- Use PIO or TxDMA to write a SET_POWER request to TIC's command
> register, and check if the
> +=C2=A0 write operation is successfully completed.
> +- Use PIO or TxDMA to write a RESET request to TIC's command
> register. If the write operation
> +=C2=A0 is successfully completed, wait for reset response from TIC.
> +- Use SWDMA to read report descriptor through TIC's report
> descriptor register.
> +
> +5.2 Input Report Data Flow
> +--------------------------
> +
> +Basic Flow:
> +
> +- Touch IC asserts the interrupt indicating that it has an interrupt
> to send to HOST.
> +=C2=A0 THC Sequencer issues a READ request over the I2C bus. The HIDI2C
> device returns the
> +=C2=A0 first 2 bytes from the HIDI2C device which contains the length of
> the received data.
> +- THC Sequencer continues the Read operation as per the size of data
> indicated in the
> +=C2=A0 length field.
> +- THC DMA engine begins fetching data from the THC Sequencer and
> writes to host memory
> +=C2=A0 at PRD entry 0 for the current CB PRD table entry. THC writes
> 2Bytes for length field
> +=C2=A0 plus the remaining data to RxDMA buffer. This process continues
> until the THC Sequencer
> +=C2=A0 signals all data has been read or the THC DMA Read Engine reaches
> the end of it's last
> +=C2=A0 PRD entry (or both).
> +- THC Sequencer enters End-of-Input Report Processing.
> +- If the device has no more input reports to send to the host, it
> de-asserts the interrupt
> +=C2=A0 line. For any additional input reports, device keeps the interrup=
t
> line asserted and
> +=C2=A0 steps 1 through 4 in the flow are repeated.
> +
> +THC Sequencer End of Input Report Processing:
> +
> +- THC DMA engine increments the read pointer of the Read PRD CB,
> sets EOF interrupt status
> +=C2=A0 in RxDMA 2 register (THC_M_PRT_READ_DMA_INT_STS_2).
> +- If THC EOF interrupt is enabled by the driver in the control
> register
> +=C2=A0 (THC_M_PRT_READ_DMA_CNTRL_2), generates interrupt to software.
> +
> +Sequence of steps to read data from RX DMA buffer:
> +
> +- THC QuickI2C driver checks CB write Ptr and CB read Ptr to
> identify if any data frame in DMA
> +=C2=A0 circular buffers.
> +- THC QuickI2C driver gets first unprocessed PRD table.
> +- THC QuickI2C driver scans all PRD entries in this PRD table to
> calculate the total frame size.
> +- THC QuickI2C driver copies all frame data out.
> +- THC QuickI2C driver call hid_input_report to send the input report
> content to HID core, which
> +=C2=A0 includes Report ID + Report Data Content (remove the length field
> from the original report
> +=C2=A0 data).
> +- THC QuickI2C driver updates write Ptr.
> +
> +5.3 Output Report Data Flow
> +---------------------------
> +
> +Generic Output Report Flow:
> +
> +- HID core call THC QuickI2C raw_request callback.
> +- THC QuickI2C uses PIO or TXDMA to write a SET_REPORT request to
> TIC's command register. Report
> +=C2=A0 type in SET_REPORT should be set to Output.
> +- THC QuickI2C programs TxDMA buffer with TX Data to be written to
> TIC's data register. The first
> +=C2=A0 2 bytes should indicate the length of the report followed by the
> report contents including
> +=C2=A0 Report ID.
> +
> +6. THC Debugging
> +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
> +
> +To debug THC, event tracing mechanism is used. To enable debug
> logs::
> +
> +=C2=A0 echo 1 > /sys/kernel/debug/tracing/events/intel_thc/enable
> +=C2=A0 cat /sys/kernel/debug/tracing/trace
> +
> +7. Reference
> +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
> +- HIDSPI:
> https://download.microsoft.com/download/c/a/0/ca07aef3-3e10-4022-b1e9-c98=
cea99465d/HidSpiProtocolSpec.pdf
> +- HIDI2C:
> https://download.microsoft.com/download/7/d/d/7dd44bb7-2a7a-4505-ac1c-722=
7d3d96d5b/hid-over-i2c-protocol-spec-v1-0.docx