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
