docs/designs/device-tree-gpio-naming.md

1 # Device Tree GPIO Naming in OpenBMC
11 The Linux kernel has deprecated the use of sysfs to interact with the GPIO
12 subsystem. The replacement is a "descriptor-based" character device interface.
15 provides an abstraction to this new character device gpio interface.
19 for these GPIO names and if you want userspace code to be able to be consistent
20 across different machines, these names would need to be consistent.
24 The kernel [documentation][2] has a good summary of the GPIO subsystem. The
25 specific field used to name the GPIOs in the DTS is `gpio-line-names`. This
29 scheme in the face of a universe of potential use-cases.
37 - Ensure common function GPIOs within OpenBMC use the same naming convention
42 naming convention and then the sub bullets list the common GPIO names to be used
52 Pattern: `*-button`
55 BMC-less machines use a button to trigger system behavior and in a BMC-managed
59 #### power-button
63 Below are input GPIO names specific to Host ready. The name of Host ready GPIO
68 - `host*-ready`: Host ready, active high
69 - `host*-ready-n`: Host ready, active low
73 - host0-ready
74 - host1-ready-n
75 - ...
79 Pattern: `led-*`
81 #### led-fault
83 #### led-identify
85 #### led-power
87 #### led-sys-boot-status
89 #### led-attention
91 #### led-hdd-fault
93 #### led-rear-fault
95 #### led-rear-power
97 #### led-rear-id
101 Pattern: `power-*`, `regulator-*`
103 #### power-chassis-control
105 Set to initiate power-on or power-off of the chassis.
107 #### power-chassis-good
111 #### power-config-full-load
113 Output GPIO set by the power managing application that indicates to the hardware
119 GPIO, the hardware can then take actions such as reducing the system's
122 #### power-ffs-sync-history
124 Output GPIO set by the power managing applications. The IBM Common Form Factor
125 power supplies use this line as an input. When set low and left low the power
130 #### regulator-standby-faulted
132 This GPIO value represents the status of standby power regulator fault detection
133 logic. This GPIO is an input only. The status will reflect a regulator
134 non-faulted condition after AC power cycle when no standby power regulator fault
138 #### rtc-battery-voltage-read-enable
144 Pattern: `presence-*`
146 #### presence-ps0, presence-ps1, ..., presence-ps\<N>
154 an event into a GPIO for firmware to then utilize for different software logic.
156 Pattern: `reset-cause-*`
158 #### reset-cause-pinhole
163 GPIO is not utilized to cause the actual reset, it is a GPIO that can be read
168 #### bmc-secure-boot
178 These are special case and/or grandfathered in pin names.
180 #### air-water
184 #### factory-reset-toggle
186 The software records the state of this GPIO and checks upon reboot if the state
192 Below are GPIO names specific to the POWER processor based servers.
196 These are special case and/or grandfathered in pin names.
198 ##### cfam-reset
209 - Continue to hard code a config file per system type that has the gpio bank and
211   names but adds overhead in supporting each new system.
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
224 Userspace utilization of the GPIO names will provide some testing coverage
228 [2]: https://www.kernel.org/doc/html/latest/driver-api/gpio/index.html
230   https://lore.kernel.org/linux-arm-kernel/20200306170218.79698-1-geissonator@yahoo.com/