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