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

1 # Device Tree GPIO Naming in OpenBMC
12 subsystem. The replacement is a "descriptor-based" character device interface.
14 [libgpiod][1] is a suite of tools and library implemented in C and C++ which
17 libgpiod provides a feature where you can access gpios by a name given to them
18 in the kernel device tree files. The problem is there are no naming conventions
25 specific 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.
28 GPIOs are used for arbitrary things. It's pretty hard to have a coherent naming
29 scheme in the face of a universe of potential use-cases.
37 - Ensure common function GPIOs within OpenBMC use the same naming convention
41 Below are the standard categories. The "Pattern" in each section describes the
44 for all common GPIOs.
46 This list below includes all common GPIOs within OpenBMC. Any OpenBMC system
47 which provides one of the below GPIOs must name it as listed in this document.
48 This document must be updated as new common GPIOs are added.
52 Pattern: `*-button`
55 BMC-less machines use a button to trigger system behavior and in a BMC-managed
57 considered a button in this document but enumerated as another signal type.
59 #### power-button
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
117 number of power supplies expected of the two models. In the case when the number
122 #### power-ffs-sync-history
130 #### regulator-standby-faulted
134 non-faulted condition after AC power cycle when no standby power regulator fault
136 condition when an unexpected drop in standby power is detected.
138 #### rtc-battery-voltage-read-enable
144 Pattern: `presence-*`
146 #### presence-ps0, presence-ps1, ..., presence-ps\<N>
150 These are GPIOs that provide more detail on the reason for a BMC reset. BMC
156 Pattern: `reset-cause-*`
158 #### reset-cause-pinhole
161 been reset due to a user initiated pinhole reset. This is commonly done in error
168 #### bmc-secure-boot
178 These are special case and/or grandfathered in pin names.
180 #### air-water
184 #### factory-reset-toggle
190 ### POWER Specific GPIOs
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
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/