Plea for help with GPIO pin naming

[Bills, Jason M]

On 8/26/2024 12:35 PM, Johannes Truschnigg wrote:
> Dear list,
> 
> in my ongoing hobbyist quest to port OpenBMC to the Gigabyte MC12-LE0, I face
> some challenges that leave me scratching my head - hence me posting here.
> Today's questions concern GPIO line names and x86-power-control aka
> /usr/bin/power-control.
> 
> I've been reverse-engineering my board's GPIO pins for a while now, and once I
> figure out what a particular pin is (probably) actually good and used for, I
> most of the time have a hard time identifying the proper name/label for that
> particular pin.
> 
> I don't have a background in electronics, much less PCB design, but I guess
> most line names in OpenBMC's DTS files are lifted verbatim from board
> schematics, which I do not have for my board. That, as well as the sprawl of
> pin labels and names used between existing platforms and boards, makes it very
> hard for me to infer the meaning of most pins defined for supported OpenBMC
> machines.

The original thought in x86-power-control was for the GPIO names to 
remain static and be routed to the correct pin in the DTS. This didn't 
turn out to be the direction, so the config file was created later to 
allow specifying GPIO names.

> 
> My research led me to a design document from 2020 with the promising title
> "Device Tree GPIO Naming in OpenBMC"[0], but since I can't seem to find the
> proposed names in any of OpenBMC meta layers, I guess it always remained a
> proposal, without proper uptake in the real world? This hunch of mine is
> somewhat exacerbated by the fact that the x86-power-control package assumes
> very different pin names in its default example config file[1] (although a
> GitHub issue[2] exists that makes it somewhat plausible that might not be 100%
> deliberate)...

The GPIO names in x86-power-control pre-date the proposal and would just 
need some transition with backward-compatibility to move to the proposed 
names, if the community would like to go that direction.

If I understand that GitHub issue, it's just that the README doesn't 
list all the GPIOs that must be defined (which doesn't really apply 
anymore since the config file allows any GPIO name). But it may be good 
to update the README overall.

> 
> What I'd like to have is a solid guideline on how to interpret existing boards'
> DTS pin names (unfortunately, I don't know what either of SIO_POWER_GOOD or
> PS_PWROK exactly describe, or what the difference between the concepts the two
> strings of characters map to in the physical world might be), assuming little
> prior knowledge of these dark arts. Is there material on the web that isn't
> buried under mountains of mainboard-designer-specific NDAs that could help me
> with making sense of all the jargon I don't know? I'd be very thankful if
> someone could point me a way!

I won't be able to help with general guidelines for existing boards' 
DTSes, but I can definitely help with what x86-power-control uses.

SIO_POWER_GOOD is named for the POWER_GOOD pin on the Aspeed BMC SIO 
signal block (probably a poor name in hindsight). On every system I have 
worked on, the CPU Power Good signal has been connected to that BMC pin. 
In x86-power-control, this signals that the system is fully powered and 
running.

PS_PWROK is the Power Good or Power OK signal from the power supplies. 
In x86-power-control, this signals that the power supplies are enabled 
and supplying power to the system.

> 
> Thanks very much for reading this far! :)
> 
> [0]: https://github.com/openbmc/docs/blob/master/designs/device-tree-gpio-naming.md
> [1]: https://github.com/openbmc/x86-power-control/blob/master/config/power-config-host0.json
> [2]: https://github.com/openbmc/x86-power-control/issues/4
>