linux-kernel - Re: [PATCH] Documentation: gpio: add documentation about using software nodes

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] [thread-next>] [day] [month] [year] [list]

Message-ID: <mztcugybpsp47mmw4253djjuw5bpqlrvyb57youx2jt7gqkyj3@tifd34ke76i5>
Date: Tue, 12 Aug 2025 09:10:23 -0700
From: Dmitry Torokhov <dmitry.torokhov@...il.com>
To: Randy Dunlap <rdunlap@...radead.org>
Cc: Linus Walleij <linus.walleij@...aro.org>, 
	Bartosz Golaszewski <brgl@...ev.pl>, Jonathan Corbet <corbet@....net>, 
	Andy Shevchenko <andriy.shevchenko@...ux.intel.com>, Arnd Bergmann <arnd@...nel.org>, 
	Hans de Goede <hansg@...nel.org>, linux-gpio@...r.kernel.org, linux-doc@...r.kernel.org, 
	linux-kernel@...r.kernel.org
Subject: Re: [PATCH] Documentation: gpio: add documentation about using
 software nodes

On Mon, Aug 11, 2025 at 10:37:04PM -0700, Randy Dunlap wrote:
> 
> 
> On 8/11/25 10:17 PM, Dmitry Torokhov wrote:
> > Hi Randy,
> > 
> > On Mon, Aug 11, 2025 at 05:46:02PM -0700, Randy Dunlap wrote:
> >> Hi,
> >>
> >> On 8/11/25 2:30 PM, Dmitry Torokhov wrote:
> >>> Introduce documentation regarding use of software nodes to describe
> >>> GPIOs on legacy boards that have not been converted to device tree.
> >>>
> >>
> >> Thanks for the additional documentation.
> > 
> > Thanks for the review.
> > 
> >>
> >>> Signed-off-by: Dmitry Torokhov <dmitry.torokhov@...il.com>
> >>> ---
> >>>  Documentation/driver-api/gpio/board.rst       |  64 ++++
> >>>  Documentation/driver-api/gpio/index.rst       |   1 +
> >>>  .../driver-api/gpio/legacy-boards.rst         | 298 ++++++++++++++++++
> >>>  3 files changed, 363 insertions(+)
> >>>
> >>> diff --git a/Documentation/driver-api/gpio/board.rst b/Documentation/driver-api/gpio/board.rst
> >>> index 4fd1cbd8296e..0cf64e1f2623 100644
> >>> --- a/Documentation/driver-api/gpio/board.rst
> >>> +++ b/Documentation/driver-api/gpio/board.rst
> >>> @@ -94,6 +94,70 @@ with the help of _DSD (Device Specific Data), introduced in ACPI 5.1::
> >>>  For more information about the ACPI GPIO bindings see
> >>>  Documentation/firmware-guide/acpi/gpio-properties.rst.
> >>>  
> >>> +Software Nodes
> >>> +--------------
> >>> +Software nodes allows to construct an in-memory, device-tree-like structure
> >>
> >>                   allow { drivers | modules | software | us}
> >>
> >> although "software" seems redundant.
> > 
> > I changed it to "... allows board specific code ..."
> > 
> >>
> >>> +using ``struct software_node`` and ``struct property_entry``. This structure
> >>
> >> Quoting Jon (for a different struct):
> >>   Better to just say "struct list_head", and the automarkup logic should
> >>   take care of the rest.
> >>
> >> @Jon: ISTM that we need something in Documentation/doc-guide/sphinx.rst (?) about which
> >> keywords are handled by automarkup logic. AFAIK, they are struct, union, enum,
> >> and typedef (keywords) and function() as indicated by the "()".
> > 
> > Unfortunately device properties/software nodes are not yet hooked to the
> > documentations, so automatic markup/cross referencing does not work.
> > 
> > I changed this to :c:type:`struct software_node <software_node>`.
> 
> Oh no, that's worse from a human readability standpoint. :(
> 
> We try (would like to) keep .rst files as readable as .txt files.
> All of that extra markup and notation is noisy and usually not needed.
> Are you saying that the extra markup (as you listed above) is needed?
> for cross-referencing?
> 
> The original would be better.
> 
> (same in the other .rst file)

OK, I  was trying to make html output look pretty. If we want to favor
.rst readability that is fine, I'll drop the :c:*: annotations.

Thanks.

-- 
Dmitry