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

Message-ID: <b666c4ec-3aee-4917-86ed-bd65b5b7e051@infradead.org>
Date: Mon, 11 Aug 2025 22:37:04 -0700
From: Randy Dunlap <rdunlap@...radead.org>
To: Dmitry Torokhov <dmitry.torokhov@...il.com>
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 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)

-- 
~Randy