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

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

[Andrew Jeffery]

Hello,

In the comment thread at [1] I've proposed deprecating the directions
in device-tree-gpio-naming.md[2] for the purpose of describing GPIOs in
devicetrees. 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.

However, perhaps it's still a reasonable set of suggestions for
consumption of pins with the translation from net names done by the
applications themselves?

Please provide feedback!

Andrew

[1]: https://gerrit.openbmc.org/c/openbmc/docs/+/82246/comments/08d45bf5_d54036d7
[2]: https://gerrit.openbmc.org/plugins/gitiles/openbmc/docs/+/refs/heads/master/designs/device-tree-gpio-naming.md

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

[Andrew Geissler]

On Tue, Aug 5, 2025 at 6:54 PM Andrew Jeffery
<andrew@codeconstruct.com.au> wrote:
>
> Hello,
>
> In the comment thread at [1] I've proposed deprecating the directions
> in device-tree-gpio-naming.md[2] for the purpose of describing GPIOs in
> devicetrees. 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.

Yeah agree, it seemed like a good idea at the time but there has been a
lot of friction with this design over time. I know some reviews have simply
been abandoned due to the frustrations of coming up with an agreed to
gpio name. And other reviews have taken an excessive amount of time
to get through.

> However, perhaps it's still a reasonable set of suggestions for
> consumption of pins with the translation from net names done by the
> applications themselves?

If we all agree, I could do one final update to the doc stating it's
been deprecated but feel free to use the existing recommendations
when creating a new system if it makes sense. And another note
indicating some OpenBMC repos may require some work to support
a new GPIO name.

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

[Andrew Jeffery]

On Wed, 2025-08-06 at 14:21 -0500, Andrew Geissler wrote:
> On Tue, Aug 5, 2025 at 6:54 PM Andrew Jeffery
> <andrew@codeconstruct.com.au> wrote:
> > 
> > Hello,
> > 
> > In the comment thread at [1] I've proposed deprecating the directions
> > in device-tree-gpio-naming.md[2] for the purpose of describing GPIOs in
> > devicetrees. 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.
> 
> Yeah agree, it seemed like a good idea at the time but there has been a
> lot of friction with this design over time. I know some reviews have simply
> been abandoned due to the frustrations of coming up with an agreed to
> gpio name. And other reviews have taken an excessive amount of time
> to get through.
> 
> > However, perhaps it's still a reasonable set of suggestions for
> > consumption of pins with the translation from net names done by the
> > applications themselves?
> 
> If we all agree, I could do one final update to the doc stating it's
> been deprecated
> 

Thanks!

>  but feel free to use the existing recommendations
> when creating a new system if it makes sense. And another note
> indicating some OpenBMC repos may require some work to support
> a new GPIO name.

Sounds good to me.

Andrew

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

[Patrick Williams]

[-- Attachment #1: Type: text/plain, Size: 2095 bytes --]

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.

Devicetrees do often represent the hardware but they don't just represent the
hardware.  For example, we have the flash layout in there.  That's
strictly a software function that has no connection to the hardware
(except for the flash size itself).  I'm not convinced we have enough
words as to why it is okay to specify the flash layout but not okay to
represent the intended purpose of a GPIO.

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.

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.  Having a devicetree named
"power-sequence-start" is way better than "DC_SCM_GPIO_P7", right? 

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".

> However, perhaps it's still a reasonable set of suggestions for
> consumption of pins with the translation from net names done by the
> applications themselves?

I think it is.

-- 
Patrick Williams

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: 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