Received-SPF: pass (google.com: domain of linux-kernel+bounces-46746-linux.lists.archive=gmail.com@vger.kernel.org designates 2604:1380:45d1:ec00::1 as permitted sender) client-ip=2604:1380:45d1:ec00::1;
From: Jonathan Corbet <corbet@lwn.net>
To: "Corona, Ernesto" <ernesto.corona@intel.com>,
 "linux-doc@vger.kernel.org" <linux-doc@vger.kernel.org>,
 "linux-kernel@vger.kernel.org" <linux-kernel@vger.kernel.org>,
 "linux-arm-kernel@lists.infradead.org"
 <linux-arm-kernel@lists.infradead.org>, "linux-aspeed@lists.ozlabs.org"
 <linux-aspeed@lists.ozlabs.org>
Cc: "Corona, Ernesto" <ernesto.corona@intel.com>,
 "'oleksandrs@mellanox.com'" <oleksandrs@mellanox.com>, "Castro, Omar
 Eduardo" <omar.eduardo.castro@intel.com>,
 "'omar.eduardo.castro@linux.intel.com'"
 <omar.eduardo.castro@linux.intel.com>, "'arnd@arndb.de'" <arnd@arndb.de>,
 "'arnd@arndb.de'" <arnd@arndb.de>, "'mchehab+samsung@kernel.org'"
 <mchehab+samsung@kernel.org>, "'linus.walleij@linaro.org'"
 <linus.walleij@linaro.org>, "'manivannan.sadhasivam@linaro.org'"
 <manivannan.sadhasivam@linaro.org>, "'jhugo@codeaurora.org'"
 <jhugo@codeaurora.org>, "Filary, Steven A" <steven.a.filary@intel.com>,
 "'jiri@nvidia.com'" <jiri@nvidia.com>, "'vadimp@mellanox.com'"
 <vadimp@mellanox.com>, "'amithash@fb.com'" <amithash@fb.com>,
 "'patrickw3@fb.com'" <patrickw3@fb.com>, "Chen, Luke"
 <luke_chen@aspeedtech.com>, "'billy_tsai@aspeedtech.com'"
 <billy_tsai@aspeedtech.com>, "'rgrs@protonmail.com'" <rgrs@protonmail.com>
Subject: Re: [PATCH 30 4/7] Add ABI documentation
In-Reply-To: <LV8PR11MB8463E4402495BACB9E3ACE588B7D2@LV8PR11MB8463.namprd11.prod.outlook.com>
References: <LV8PR11MB8463E4402495BACB9E3ACE588B7D2@LV8PR11MB8463.namprd11.prod.outlook.com>
Date: Wed, 31 Jan 2024 08:58:50 -0700
Message-ID: <87mssl7av9.fsf@meer.lwn.net>
Precedence: bulk
MIME-Version: 1.0
Content-Type: text/plain

"Corona, Ernesto" <ernesto.corona@intel.com> writes:

> Added document that describe the ABI for JTAG class driver

A few comments

> diff --git a/Documentation/jtag/index.rst b/Documentation/jtag/index.rst
> new file mode 100644
> index 000000000000..8a2761d1c17e
> --- /dev/null
> +++ b/Documentation/jtag/index.rst

Please, let's not create another top-level directory for this; this
looks like information that belongs in the userspace-api book.

> @@ -0,0 +1,18 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +==============================
> +Joint Test Action Group (JTAG)
> +==============================
> +
> +.. toctree::
> +   :maxdepth: 1
> +
> +   jtag-summary
> +   jtagdev
> +
> +.. only::  subproject and html
> +
> +   Indices
> +   =======
> +
> +   * :ref:`genindex`
> diff --git a/Documentation/jtag/jtag-summary.rst b/Documentation/jtag/jtag-summary.rst
> new file mode 100644
> index 000000000000..07cfa7a761d7
> --- /dev/null
> +++ b/Documentation/jtag/jtag-summary.rst
> @@ -0,0 +1,49 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +====================================
> +Linux kernel JTAG support
> +====================================
> +
> +Introduction to JTAG
> +====================
> +
> +JTAG is an industry standard for verifying hardware. JTAG provides access to
> +many logic signals of a complex integrated circuit, including the device pins.
> +
> +A JTAG interface is a special interface added to a chip.
> +Depending on the version of JTAG, two, four, or five pins are added.
> +
> +The connector pins are:
> + * TDI (Test Data In)
> + * TDO (Test Data Out)
> + * TCK (Test Clock)
> + * TMS (Test Mode Select)
> + * TRST (Test Reset) optional
> +
> +JTAG interface is designed to have two parts - basic core driver and
> +hardware specific driver. The basic driver introduces a general interface
> +which is not dependent of specific hardware. It provides communication
> +between user space and hardware specific driver.
> +Each JTAG device is represented as a char device from (jtag0, jtag1, ...).
> +Access to a JTAG device is performed through IOCTL calls.
> +
> +Call flow example:
> +::

You can express this more readably as just

  Call flow example::


> +
> +	User: open  -> /dev/jatgX -> JTAG core driver -> JTAG hardware specific driver
> +	User: ioctl -> /dev/jtagX -> JTAG core driver -> JTAG hardware specific driver
> +	User: close -> /dev/jatgX -> JTAG core driver -> JTAG hardware specific driver
> +
> +
> +THANKS TO
> +---------
> +Contributors to Linux-JTAG discussions include (in alphabetical order,
> +by last name):
> +
> +- Omar Castro
> +- Ernesto Corona
> +- Steven Filary
> +- Vadim Pasternak
> +- Jiri Pirko
> +- Oleksandr Shamray
> +- Billy Tsai
> \ No newline at end of file

Files should end in a newline

[...]

> +===============  =========  =======  =====================================================
> +Bit Field        Bit begin  Bit end  Description
> +===============  =========  =======  =====================================================
> +rsvd             25         31       Reserved, not used
> +pad data         24         24       Value used for pre and post padding. Either 1 or 0.
> +post pad count   12         23       Number of padding bits to be executed after transfer.
> +pre pad count    0          11       Number of padding bit to be executed before transfer.
> +===============  =========  =======  =====================================================

You should be able to wrap the final column of the table, avoiding these
long lines.

Thanks,

jon