Skip to contentSkip to conversation

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

DISCUSSION Andrew Jeffery 3 participants 5 messages Aug 5, 2025 – Aug 13, 2025

lore
Share & tools
lore
#0 lore raw

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

#1 lore raw
Quoted 8 lines · 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.

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.

Quoted 3 lines

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.

#2 lore raw
Quoted 17 lines · Andrew Geissler
Quoted 8 lines · 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.

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.

Quoted 7 lines
Quoted 3 lines

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!

Quoted 4 lines

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

#3 lore raw
In reply to Andrew Jeffery
Quoted 3 lines · Andrew Jeffery

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

Quoted 3 lines

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.

Signature · 1 line
Patrick Williams
#4 lore raw
Quoted 8 lines · Patrick Williams
Quoted 3 lines · Andrew Jeffery

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

Quoted 6 lines

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.

Quoted 6 lines

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.

Quoted 2 lines

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.

Quoted 7 lines

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