Proposed deprecation of device-tree-gpio-naming.md

[Andrew Jeffery]

On Tue, 2025-08-12 at 17:14 -0400, Patrick Williams wrote:
> On Wed, Aug 06, 2025 at 09:24:37AM +0930, Andrew Jeffery wrote:
> 
> > Devicetrees represent the hardware, and from experience
> > over time I think it's best that they reflect the information from the
> > schematics without influence from software implementation choices.
> 
> Can you elaborate on what this experience is?  I'm not sure what this is
> referring to or what issues you've observed with it.

- All devicetrees that get merged upstream, because I'm merging them,
- The bikeshedding that occurs when trying to update the document
- The lack of coverage in the design document that results in people
using net names regardless
- The avoidance of updating the document, by the existence of net names
in the submitted devicetrees
- That to name the GPIO you then have to consult some other piece of
documentation that isn't the schematic, whose existence you must first
be aware of, that may have little meaning to you otherwise

> 
> If GPIO names were to reflect the "information from the schematics", I
> assume this is to mean the net-name?  Which net-name are we going to
> use?  The one on the DC-SCM, the one on the connector the DC-SCM is
> plugged into, etc.  There are probably, on average, 4 different names
> from a source of a signal to the BMC.

Sure.

> 
> You could of course say "whatever the person implementing the devicetree
> wants" for the pin name, but usually that's the least useful name to
> anyone else.  On top of that, schematics are often times closed and
> unavailable to more than a handful of people. 
> 

Contribution of reverse-engineered of boards is not something that
tends to happen frequently. I don't think we should weigh its
importance too highly here.

https://discord.com/channels/775381525260664832/775381525260664836/1288160738157924362

If the schematic is closed and broadly unavailable then perhaps the
document serves as a reasonable way to name things, but I'm not sure it
should take priority.

>  Having a devicetree named
> "power-sequence-start" is way better than "DC_SCM_GPIO_P7", right? 

If you have enough information to confidently name the GPIO "power-
sequence-start" in the devicetree, where that isn't the net name, then
you have enough information to choose a net name that isn't
"DC_SCM_GPIO_P7". Pick the most useful net name? We can query this in
review.

> 
> Sure, we can have this translation in entity-manager or wherever, if
> someone contributes the entity-manager config for their board.  But,
> that means it's only available to BMC code.  When I'm actively debugging
> something, I have yet another hoop to jump through to go from
> "DC_SCM_GPIO_P7" to "this is the power sequence start".  If it is in the
> device tree it shows up right in "gpioinfo".

Picking a more useful net name likely helps the cause there.

Andrew