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