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