1# Device Tree GPIO Naming in OpenBMC
2
3Author: Andrew Geissler (geissonator)
4
5Other contributors: < None >
6
7Created: April 3, 2020
8
9## Problem Description
10
11The Linux kernel has deprecated the use of sysfs to interact with the GPIO
12subsystem. The replacement is a "descriptor-based" character device interface.
13
14[libgpiod][1] is a suite of tools and library implemented in C and C++ which
15provides an abstraction to this new character device gpio interface.
16
17libgpiod provides a feature where you can access gpios by a name given to them
18in the kernel device tree files. The problem is there are no naming conventions
19for these GPIO names and if you want userspace code to be able to be consistent
20across different machines, these names would need to be consistent.
21
22## Background and References
23
24The kernel [documentation][2] has a good summary of the GPIO subsystem. The
25specific field used to name the GPIOs in the DTS is `gpio-line-names`. This
26[patch][3] shows an example of naming the GPIOs for a system.
27
28GPIOs are used for arbitrary things. It's pretty hard to have a coherent naming
29scheme in the face of a universe of potential use-cases.
30
31Scoping the problem down to just the vastness of OpenBMC narrows the
32possibilities quite a bit and allows the possibility of a naming scheme to
33emerge.
34
35## Requirements
36
37- Ensure common function GPIOs within OpenBMC use the same naming convention
38
39## Proposed Design
40
41Below are the standard categories. The "Pattern" in each section describes the
42naming convention and then the sub bullets list the common GPIO names to be used
43(when available on an OpenBMC system). This naming convention must be followed
44for all common GPIOs.
45
46This list below includes all common GPIOs within OpenBMC. Any OpenBMC system
47which provides one of the below GPIOs must name it as listed in this document.
48This document must be updated as new common GPIOs are added.
49
50### Buttons
51
52Pattern: `*-button`
53
54Buttons should always be considered 'input' to the BMC. There may be cases where
55BMC-less machines use a button to trigger system behavior and in a BMC-managed
56system this signal is emulated by the BMC (as output). These should not be
57considered a button in this document but enumerated as another signal type.
58
59#### power-button
60
61### Host Ready
62
63Below are input GPIO names specific to Host ready. The name of Host ready GPIO
64depends on the index of Host and the active state is high or low.
65
66Pattern:
67
68- `host*-ready`: Host ready, active high
69- `host*-ready-n`: Host ready, active low
70
71Defined:
72
73- host0-ready
74- host1-ready-n
75- ...
76
77### LEDs
78
79Pattern: `led-*`
80
81#### led-fault
82
83#### led-identify
84
85#### led-power
86
87#### led-sys-boot-status
88
89#### led-attention
90
91#### led-hdd-fault
92
93#### led-rear-fault
94
95#### led-rear-power
96
97#### led-rear-id
98
99### Power and Regulators
100
101Pattern: `power-*`, `regulator-*`
102
103#### power-chassis-control
104
105Set to initiate power-on or power-off of the chassis.
106
107#### power-chassis-good
108
109Indicates the power good state of the chassis.
110
111#### power-config-full-load
112
113Output GPIO set by the power managing application that indicates to the hardware
114the threshold of power supplies that are expected to be present and working for
115this type of system for the case where a system has a model that supports two
116different number of power supplies (example 2 or 4). Default is the lowest
117number of power supplies expected of the two models. In the case when the number
118of power supplies that are present are less than the ones indicated by this
119GPIO, the hardware can then take actions such as reducing the system's
120performance so that it can maintain its powered on state.
121
122#### power-ffs-sync-history
123
124Output GPIO set by the power managing applications. The IBM Common Form Factor
125power supplies use this line as an input. When set low and left low the power
126supply fans run at full speed (Fans Full Speed). When toggled low, then high, it
127resets the power supply input history (average and maximum power values over a
128time range).
129
130#### regulator-standby-faulted
131
132This GPIO value represents the status of standby power regulator fault detection
133logic. This GPIO is an input only. The status will reflect a regulator
134non-faulted condition after AC power cycle when no standby power regulator fault
135condition is present. The status will reflect a standby regulator power faulted
136condition when an unexpected drop in standby power is detected.
137
138#### rtc-battery-voltage-read-enable
139
140Output pin that enables the ADC to read the board RTC battery voltage.
141
142### Presence
143
144Pattern: `presence-*`
145
146#### presence-ps0, presence-ps1, ..., presence-ps\<N>
147
148### Reset Cause
149
150These are GPIOs that provide more detail on the reason for a BMC reset. BMC
151hardware generally provides some information on a BMC reboot, like a EXTRST
152(i.e. a BMC reset was reset by some external source). At times though, firmware
153needs more details on the cause of a reset. Hardware can be configured to latch
154an event into a GPIO for firmware to then utilize for different software logic.
155
156Pattern: `reset-cause-*`
157
158#### reset-cause-pinhole
159
160The pinhole reset cause will be utilized by BMC firmware to know when it has
161been reset due to a user initiated pinhole reset. This is commonly done in error
162scenarios where the BMC is hanging or otherwise unresponsive. Note that this
163GPIO is not utilized to cause the actual reset, it is a GPIO that can be read
164after the BMC reset to know the reason for the reboot was a pinhole reset.
165
166### Secure Boot
167
168#### bmc-secure-boot
169
170Input pin that indicates that the BMC is configured to boot with security
171protections enforced.
172
173Pulled up by default (secure). Placing the jumper will pull the pin down (bypass
174security).
175
176### Special
177
178These are special case and/or grandfathered in pin names.
179
180#### air-water
181
182Indicates whether system is air or water cooled
183
184#### factory-reset-toggle
185
186The software records the state of this GPIO and checks upon reboot if the state
187has changed since the last reboot. If it has, it indicates that a factory reset
188should be performed.
189
190### POWER Specific GPIOs
191
192Below are GPIO names specific to the POWER processor based servers.
193
194#### Special
195
196These are special case and/or grandfathered in pin names.
197
198##### cfam-reset
199
200Utilized to issue a processor logic reset to a IBM POWER processor.
201
202##### checkstop
203
204Utilized to indicate a IBM POWER processor has entered an unrecoverable error
205state.
206
207## Alternatives Considered
208
209- Continue to hard code a config file per system type that has the gpio bank and
210  pin number. This removes a dependency on the device tree to have consistent
211  names but adds overhead in supporting each new system.
212
213- Have the device tree GPIO names match the hardware schematics and then have
214  another userspace config file that maps between the schematic names and
215  logical pin names. This makes the GPIO to schematic mapping easy but adds an
216  additional layer of work with the userspace config.
217
218## Impacts
219
220Need to ensure OpenBMC device trees conform to the above naming conventions.
221
222## Testing
223
224Userspace utilization of the GPIO names will provide some testing coverage
225during CI.
226
227[1]: https://git.kernel.org/pub/scm/libs/libgpiod/libgpiod.git/about/
228[2]: https://www.kernel.org/doc/html/latest/driver-api/gpio/index.html
229[3]:
230  https://lore.kernel.org/linux-arm-kernel/20200306170218.79698-1-geissonator@yahoo.com/
231