1# Device Tree GPIO Naming in OpenBMC
2
3Author: Andrew Geissler (geissonator)
4
5Primary assignee: Andrew Geissler (geissonator)
6
7Other contributors:
8  < None >
9
10Created: April 3, 2020
11
12## Problem Description
13The Linux kernel has deprecated the use of sysfs to interact with the GPIO
14subsystem. The replacement is a "descriptor-based" character device interface.
15
16[libgpiod][1] is a suite of tools and library implemented in C and C++ which
17provides an abstraction to this new character device gpio interface.
18
19libgpiod provides a feature where you can access gpios by a name given to
20them in the kernel device tree files. The problem is there are no naming
21conventions for these GPIO names and if you want userspace code to be able
22to be consistent across different machines, these names would need to be
23consistent.
24
25## Background and References
26The kernel [documentation][2] has a good summary of the GPIO subsystem. The
27specific field used to name the GPIO's in the DTS is `gpio-line-names`.
28This [patch][3] shows an example of naming the GPIO's for a system.
29
30GPIOs are used for arbitrary things. It's pretty hard to have a coherent naming
31scheme in the face of a universe of potential use-cases.
32
33Scoping the problem down to just the vastness of OpenBMC narrows the
34possibilities quite a bit and allows the possibility of a naming scheme to
35emerge.
36
37## Requirements
38- Ensure common function GPIO's within OpenBMC use the same naming convention
39
40## Proposed Design
41Below are the standard categories. The "Pattern" in each section describes the
42naming convention and then the "Defined" portion lists the common GPIO names to
43be used (when available on an OpenBMC system). This naming convention must be
44followed for all common GPIO's.
45
46This list below includes all common GPIO's within OpenBMC. Any OpenBMC
47system which provides one of the below GPIO's must name it as listed in
48this document. This document must be updated as new common GPIO's are added.
49
50### LEDs
51Pattern: `led-*`
52
53Defined:
54- led-fault
55- led-identify
56- led-power
57- led-sys-boot-status
58- led-attention
59- led-hdd-fault
60- led-rear-fault
61- led-rear-power
62- led-rear-id
63
64### Power and Regulators
65Pattern: `power-*`, `regulator-*`
66
67Defined:
68#### power-button
69
70#### power-chassis-control
71Set to initiate power-on or power-off of the chassis.
72
73#### power-chassis-good
74Indicates the power good state of the chassis.
75
76#### regulator-standby-faulted
77This GPIO value represents the status of standby power regulator fault detection
78logic. This GPIO is an input only. The status will reflect a regulator
79non-faulted condition after AC power cycle when no standby power regulator fault
80condition is present. The status will reflect a standby regulator power faulted
81condition when an unexpected drop in standby power is detected.
82
83### Buttons
84Pattern: `*-button`
85
86Defined:
87- power-button
88
89### Presence
90Pattern: `presence-*`
91
92Defined:
93- presence-ps0
94- presence-ps1
95- ...
96- presence-ps`<N>`
97
98### Secure Boot
99
100#### bmc-secure-boot
101
102Input pin that indicates that the BMC is configured to boot with security
103protections enforced.
104
105Pulled up by default (secure). Placing the jumper will pull the pin down
106(bypass security).
107
108### Special
109These are special case and/or grandfathered in pin names.
110
111Defined:
112#### air-water
113Indicates whether system is air or water cooled
114
115#### factory-reset-toggle
116The software records the state of this GPIO and checks upon reboot if the state
117has changed since the last reboot. If it has, it indicates that a factory reset
118should be performed.
119
120### POWER Specific GPIO's
121Below are GPIO names specific to the POWER processor based servers.
122
123#### Special
124These are special case and/or grandfathered in pin names.
125
126Defined:
127- cfam-reset
128- checkstop
129
130## Alternatives Considered
131- Continue to hard code a config file per system type that has the
132gpio bank and pin number. This removes a dependency on the device tree to
133have consistent names but adds overhead in supporting each new system.
134
135- Have the device tree GPIO names match the hardware schematics and then
136have another userspace config file that maps between the schematic names
137and logical pin names. This makes the GPIO to schematic mapping easy but
138adds an additional layer of work with the userspace config.
139
140## Impacts
141Need to ensure OpenBMC device trees conform to the above naming conventions.
142
143## Testing
144Userspace utilization of the GPIO names will provide some testing coverage
145during CI.
146
147[1]: https://git.kernel.org/pub/scm/libs/libgpiod/libgpiod.git/about/
148[2]: https://www.kernel.org/doc/html/latest/driver-api/gpio/index.html
149[3]: https://lore.kernel.org/linux-arm-kernel/20200306170218.79698-1-geissonator@yahoo.com/
150