linux-kernel - Re: [PATCH 30 4/7] Add ABI 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: <87mssl7av9.fsf@meer.lwn.net>
Date: Wed, 31 Jan 2024 08:58:50 -0700
From: Jonathan Corbet <corbet@....net>
To: "Corona, Ernesto" <ernesto.corona@...el.com>,
 "linux-doc@...r.kernel.org" <linux-doc@...r.kernel.org>,
 "linux-kernel@...r.kernel.org" <linux-kernel@...r.kernel.org>,
 "linux-arm-kernel@...ts.infradead.org"
 <linux-arm-kernel@...ts.infradead.org>, "linux-aspeed@...ts.ozlabs.org"
 <linux-aspeed@...ts.ozlabs.org>
Cc: "Corona, Ernesto" <ernesto.corona@...el.com>,
 "'oleksandrs@...lanox.com'" <oleksandrs@...lanox.com>, "Castro, Omar
 Eduardo" <omar.eduardo.castro@...el.com>,
 "'omar.eduardo.castro@...ux.intel.com'"
 <omar.eduardo.castro@...ux.intel.com>, "'arnd@...db.de'" <arnd@...db.de>,
 "'arnd@...db.de'" <arnd@...db.de>, "'mchehab+samsung@...nel.org'"
 <mchehab+samsung@...nel.org>, "'linus.walleij@...aro.org'"
 <linus.walleij@...aro.org>, "'manivannan.sadhasivam@...aro.org'"
 <manivannan.sadhasivam@...aro.org>, "'jhugo@...eaurora.org'"
 <jhugo@...eaurora.org>, "Filary, Steven A" <steven.a.filary@...el.com>,
 "'jiri@...dia.com'" <jiri@...dia.com>, "'vadimp@...lanox.com'"
 <vadimp@...lanox.com>, "'amithash@...com'" <amithash@...com>,
 "'patrickw3@...com'" <patrickw3@...com>, "Chen, Luke"
 <luke_chen@...eedtech.com>, "'billy_tsai@...eedtech.com'"
 <billy_tsai@...eedtech.com>, "'rgrs@...tonmail.com'" <rgrs@...tonmail.com>
Subject: Re: [PATCH 30 4/7] Add ABI documentation

"Corona, Ernesto" <ernesto.corona@...el.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