Re: [PATCH v2 01/22] HID: THC: Add documentation

[Bagas Sanjaya <bagasdotme@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 4914 bytes --]

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.

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

Thanks.

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]