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

[Dmitry Torokhov]

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@xxxxxxxxx>
> >>> ---
> >>>  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