linux-kernel - RE: [PATCH v2 01/22] HID: THC: Add documentation

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives
Hash Suite: Windows password security audit tool. GUI, reports in PDF.
[<prev] [next>] [<thread-prev] [day] [month] [year] [list]
Message-ID: <IA1PR11MB6098DC3CDFE27E4E23105950F4272@IA1PR11MB6098.namprd11.prod.outlook.com>
Date: Mon, 18 Nov 2024 00:34:54 +0000
From: "Xu, Even" <even.xu@...el.com>
To: Bagas Sanjaya <bagasdotme@...il.com>, "jikos@...nel.org"
	<jikos@...nel.org>, "bentiss@...nel.org" <bentiss@...nel.org>,
	"corbet@....net" <corbet@....net>, "Aaron, Ma" <aaron.ma@...onical.com>
CC: "linux-input@...r.kernel.org" <linux-input@...r.kernel.org>,
	"linux-kernel@...r.kernel.org" <linux-kernel@...r.kernel.org>,
	"linux-doc@...r.kernel.org" <linux-doc@...r.kernel.org>, "Sun, Xinpeng"
	<xinpeng.sun@...el.com>, Srinivas Pandruvada
	<srinivas.pandruvada@...ux.intel.com>
Subject: RE: [PATCH v2 01/22] HID: THC: Add documentation



> -----Original Message-----
> From: Bagas Sanjaya <bagasdotme@...il.com>
> Sent: Friday, November 15, 2024 7:39 PM
> To: Xu, Even <even.xu@...el.com>; jikos@...nel.org; bentiss@...nel.org;
> corbet@....net; Aaron, Ma <aaron.ma@...onical.com>
> Cc: linux-input@...r.kernel.org; linux-kernel@...r.kernel.org; linux-
> doc@...r.kernel.org; Sun, Xinpeng <xinpeng.sun@...el.com>; Srinivas
> Pandruvada <srinivas.pandruvada@...ux.intel.com>
> Subject: Re: [PATCH v2 01/22] HID: THC: Add documentation
> 
> On Fri, Nov 15, 2024 at 05:10:55AM +0000, Xu, Even wrote:
> >
> >
> > > -----Original Message-----
> > > From: Bagas Sanjaya <bagasdotme@...il.com>
> > > Sent: Friday, November 15, 2024 12:04 PM
> > > To: Xu, Even <even.xu@...el.com>; jikos@...nel.org;
> > > bentiss@...nel.org; corbet@....net; Aaron, Ma
> > > <aaron.ma@...onical.com>
> > > Cc: linux-input@...r.kernel.org; linux-kernel@...r.kernel.org;
> > > linux- doc@...r.kernel.org; Sun, Xinpeng <xinpeng.sun@...el.com>;
> > > Srinivas Pandruvada <srinivas.pandruvada@...ux.intel.com>
> > > Subject: Re: [PATCH v2 01/22] HID: THC: Add documentation
> > >
> > > On Thu, Nov 14, 2024 at 01:33:55PM +0800, Even Xu wrote:
> > > > +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
> > >
> > > I see in my htmldocs output that the list above is long running paragraph
> instead.
> >
> > You are right, let me fix it in next version.
> 
> OK.
> 
> >
> > >
> > > > +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::
> > > > +
> > > > + +--------+---------------------------------+
> > > > + | opcode |  Corresponding SPI command      |
> > > > + +========+=================================+
> > > > + |  0x0B  | Read Single I/O                 |
> > > > + +--------+---------------------------------+
> > > > + |  0x02  | Write Single I/O                |
> > > > + +--------+---------------------------------+
> > > > + |  0xBB  | Read Dual I/O                   |
> > > > + +--------+---------------------------------+
> > > > + |  0xB2  | Write Dual I/O                  |
> > > > + +--------+---------------------------------+
> > > > + |  0xEB  | Read Quad I/O                   |
> > > > + +--------+---------------------------------+
> > > > + |  0xE2  | Write Quad I/O                  |
> > > > + +--------+---------------------------------+
> > > > +
> > > > <snipped>...
> > > > +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::
> > > > +
> > > > + +--------+-------------------------------------------+----------+
> > > > + | opcode |       Corresponding I2C command           | Address  |
> > > > +
> > >
> +========+===========================================+==========+
> > > > + |  0x12  | Read I2C SubIP APB internal registers     | 0h - FFh |
> > > > + +--------+-------------------------------------------+----------+
> > > > + |  0x13  | Write I2C SubIP APB internal registers    | 0h - FFh |
> > > > + +--------+-------------------------------------------+----------+
> > > > + |  0x14  | Read external Touch IC through I2C bus    | N/A      |
> > > > + +--------+-------------------------------------------+----------+
> > > > + |  0x18  | Write external Touch IC through I2C bus   | N/A      |
> > > > + +--------+-------------------------------------------+----------+
> > > > + |  0x1C  | Write then read external Touch IC through | N/A      |
> > > > + |        | I2C bus                                   |          |
> > > > + +--------+-------------------------------------------+----------+
> > > > +
> > > > <snipped>...
> > > > +Intel THC uses PRD entry descriptor for every PRD entry. Every
> > > > +PRD entry descriptor occupies
> > > > +128 bits memories::
> > > > +
> > > > + +-------------------+---------+------------------------------------------------+
> > > > + | struct field      | bit(s)  | description                                    |
> > > > +
> > >
> +===================+=========+==================================
> > > ===
> > > > + +===========+
> > > > + | dest_addr         | 53..0   | destination memory address, as every entry     |
> > > > + |                   |         | is 4KB, ignore lowest 10 bits of address.      |
> > > > + +-------------------+---------+------------------------------------------------+
> > > > + | reserved1         | 54..62  | reserved                                       |
> > > > + +-------------------+---------+------------------------------------------------+
> > > > + | int_on_completion | 63      | completion interrupt enable bit, if this bit   |
> > > > + |                   |         | set it means THC will trigger a completion     |
> > > > + |                   |         | interrupt. This bit is set by SW driver.       |
> > > > + +-------------------+---------+------------------------------------------------+
> > > > + | len               | 87..64  | how many bytes of data in this entry.          |
> > > > + +-------------------+---------+------------------------------------------------+
> > > > + | end_of_prd        | 88      | end of PRD table bit, if this bit is set,      |
> > > > + |                   |         | it means this entry is last entry in this PRD  |
> > > > + |                   |         | table. This bit is set by SW driver.           |
> > > > + +-------------------+---------+------------------------------------------------+
> > > > + | hw_status         | 90..89  | HW status bits                                 |
> > > > + +-------------------+---------+------------------------------------------------+
> > > > + | reserved2         | 127..91 | reserved                                       |
> > > > + +-------------------+---------+------------------------------------------------+
> > >
> > > Shouldn't these tables be formatted as tables?
> >
> > Good idea!
> > Let's format them.
> 
> Just drop the literal block formatting, keeping the table as-is.
> 

Thanks, already updated on my local, will send the modified patch in next version.

Best Regards,
Even Xu

> --
> An old man doll... just what I always wanted! - Clara