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 GPIOs in the DTS is `gpio-line-names`.
28This [patch][3] shows an example of naming the GPIOs 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 GPIOs 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 sub bullets list the common GPIO names to
43be used (when available on an OpenBMC system). This naming convention must be
44followed for all common GPIOs.
45
46This list below includes all common GPIOs within OpenBMC. Any OpenBMC
47system which provides one of the below GPIOs must name it as listed in
48this document. This document must be updated as new common GPIOs are added.
49
50### Buttons
51Pattern: `*-button`
52
53#### power-button
54
55### LEDs
56Pattern: `led-*`
57
58#### led-fault
59#### led-identify
60#### led-power
61#### led-sys-boot-status
62#### led-attention
63#### led-hdd-fault
64#### led-rear-fault
65#### led-rear-power
66#### led-rear-id
67
68### Power and Regulators
69Pattern: `power-*`, `regulator-*`
70
71#### power-chassis-control
72Set to initiate power-on or power-off of the chassis.
73
74#### power-chassis-good
75Indicates the power good state of the chassis.
76
77#### power-config-full-load
78Output GPIO set by the power managing application that indicates to the hardware
79the threshold of power supplies that are expected to be present and working for
80this type of system for the case where a system has a model that supports two
81different number of power supplies (example 2 or 4). Default is the lowest
82number of power supplies expected of the two models. In the case when the number
83of power supplies that are present are less than the ones indicated by this
84GPIO, the hardware can then take actions such as reducing the system's
85performance so that it can maintain its powered on state.
86
87#### regulator-standby-faulted
88This GPIO value represents the status of standby power regulator fault detection
89logic. This GPIO is an input only. The status will reflect a regulator
90non-faulted condition after AC power cycle when no standby power regulator fault
91condition is present. The status will reflect a standby regulator power faulted
92condition when an unexpected drop in standby power is detected.
93
94### Presence
95Pattern: `presence-*`
96
97#### presence-ps0, presence-ps1, ..., presence-ps\<N>
98
99### Reset Cause
100These are GPIOs that provide more detail on the reason for a BMC reset. BMC
101hardware generally provides some information on a BMC reboot, like a EXTRST
102(i.e. a BMC reset was reset by some external source). At times though,
103firmware needs more details on the cause of a reset. Hardware can be configured
104to latch an event into a GPIO for firmware to then utilize for different
105software logic.
106
107Pattern: `reset-cause-*`
108
109#### reset-cause-pinhole
110The pinhole reset cause will be utilized by BMC firmware to know when it
111has been reset due to a user initiated pinhole reset. This is commonly done in
112error scenarios where the BMC is hanging or otherwise unresponsive. Note that
113this GPIO is not utilized to cause the actual reset, it is a GPIO that can be
114read after the BMC reset to know the reason for the reboot was a pinhole reset.
115
116### Secure Boot
117
118#### bmc-secure-boot
119Input pin that indicates that the BMC is configured to boot with security
120protections enforced.
121
122Pulled up by default (secure). Placing the jumper will pull the pin down
123(bypass security).
124
125### Special
126These are special case and/or grandfathered in pin names.
127
128#### air-water
129Indicates whether system is air or water cooled
130
131#### factory-reset-toggle
132The software records the state of this GPIO and checks upon reboot if the state
133has changed since the last reboot. If it has, it indicates that a factory reset
134should be performed.
135
136### POWER Specific GPIOs
137Below are GPIO names specific to the POWER processor based servers.
138
139#### Special
140These are special case and/or grandfathered in pin names.
141
142##### cfam-reset
143Utilized to issue a processor logic reset to a IBM POWER processor.
144
145##### checkstop
146Utilized to indicate a IBM POWER processor has entered an unrecoverable error
147state.
148
149## Alternatives Considered
150- Continue to hard code a config file per system type that has the
151gpio bank and pin number. This removes a dependency on the device tree to
152have consistent names but adds overhead in supporting each new system.
153
154- Have the device tree GPIO names match the hardware schematics and then
155have another userspace config file that maps between the schematic names
156and logical pin names. This makes the GPIO to schematic mapping easy but
157adds an additional layer of work with the userspace config.
158
159## Impacts
160Need to ensure OpenBMC device trees conform to the above naming conventions.
161
162## Testing
163Userspace utilization of the GPIO names will provide some testing coverage
164during CI.
165
166[1]: https://git.kernel.org/pub/scm/libs/libgpiod/libgpiod.git/about/
167[2]: https://www.kernel.org/doc/html/latest/driver-api/gpio/index.html
168[3]: https://lore.kernel.org/linux-arm-kernel/20200306170218.79698-1-geissonator@yahoo.com/
169