1# phosphor-buttons 2 3Phosphor-buttons has a collection of IO event handler interfaces for physical 4inputs which are typically part of some sort of panel. 5 6It defines an individual dbus interface object for each physical button/switch 7inputs such as power button, reset button etc. Each button interface monitors 8its associated IO for event changes and emits signals that the button-handler 9application listens for. 10 11## Button Behavior 12 13### Power Button 14 15All events occur when the button is released. 16 17If the power is off, power on the host. 18 19If the power is on, it depends on how long the press was and which options are 20enabled: 21 22- Short press: Do a host power off 23- Long press, as determined by the 'long-press-time-ms' meson option: Do a 24 chassis (hard) power off. 25 26#### Custom Power Button Profiles 27 28The 'power-button-profile' meson option can be used to select custom power 29button profiles that have different behaviors. 30 31Available profiles are: 32 33- host_then_chassis_poweroff: When power is on, short presses are ignored and a 34 long press issues a host power off first and then a chassis power off if held 35 past a certain time. [This class](inc/host_then_chassis_poweroff.hpp) has 36 additional details. 37 38### Multi-Host Buttons 39 40See [this section below](#group-gpio-config). 41 42### Reset Button 43 44When released: 45 46- If 'reset-button-do-warm-reboot' meson option is set to enabled, does warm 47 reboot the host. 48- Otherwise, reboots the host (default behavior) 49 50### ID Button 51 52When released, toggles the 'enclosure_identify' LED group provided by the 53phosphor-led-manager repository. The group name can be changed using the 54'id-led-group' meson option. 55 56## Gpio defs config 57 58In order to monitor a button/input interface the respective gpio config details 59should be mentioned in the gpio defs json file - 60`/etc/default/obmc/gpio/gpio_defs.json` 61 621. The button interface type name. 632. An array consists of single or multiple gpio configs associated with the 64 specific button interface. 65 66A gpio can be mapped using the "pin" or "num" keyword. The "pin" key uses 67alphanumerical references while the "num" key supports the integer pin number. 68 69## example gpio def Json config 70 71```json 72{ 73 "gpio_definitions": [ 74 { 75 "name": "POWER_BUTTON", 76 "gpio_config" :[ 77 { 78 "pin": "D0", 79 "direction": "both" 80 } 81 ] 82 }, 83 { 84 "name": "RESET_BUTTON", 85 "gpio_config" :[ 86 { 87 "pin": "AB0", 88 "direction": "both" 89 } 90 ] 91 }, 92 { 93 "name" : "HOST_SELECTOR", 94 95 "group_gpio_config" : [ 96 { 97 "pin": "AA4", 98 "direction": "both" 99 }, 100 { 101 "pin": "AA5", 102 "direction": "both" 103 }, 104 { 105 "pin": "AA6", 106 "direction": "both" 107 }, 108 { 109 "pin": "AA7", 110 "direction": "both" 111 } 112 ] 113 }, 114 115} 116``` 117 118## Single gpio config 119 120This config is original config which can be used for configs with only single 121gpio such as power button,reset button, OCP debug card host select button. 122 123```json 124{ 125 "name": "POWER_BUTTON", 126 "pin": "D0", 127 "direction": "both" 128}, 129``` 130 131**Note:** this config is used by most of the other platforms so this format is 132kept as it is so that existing gpio configs do not get affected. 133 134## Group gpio config 135 136The following configs are related to multi-host bmc systems more info explained 137in the design: 138<https://github.com/openbmc/docs/blob/master/designs/multihost-phosphor-buttons.md> 139 140### Host selector gpio config example 141 142The host selector has four gpios associated. So the related gpios are mentioned 143in a json array named group_gpio_config. 144 145- name - This is name of the specific gpio line 146- pin - This represents the pin number from linux dts file. 147- polarity - polarity type of the gpio 148- max_position - This represents the max number of hosts in the multi-host bmc 149 system. 150- host_selector_map - This map is oem specific host position map which has how 151 the value read from the host selector gpios is mapped to the respective host 152 number. 153 154Example : The value of "7" derived from the 4 host select gpio lines are mapped 155to host position 1. 156 157```json 158{ 159 "name": "HOST_SELECTOR", 160 161 "group_gpio_config": [ 162 { 163 "name": "host_select_0", 164 "pin": "AA4", 165 "direction": "both", 166 "polarity": "active_high" 167 }, 168 { 169 "name": "host_select_1", 170 "pin": "AA5", 171 "direction": "both", 172 "polarity": "active_high" 173 }, 174 { 175 "name": "host_select_2", 176 "pin": "AA6", 177 "direction": "both", 178 "polarity": "active_high" 179 }, 180 { 181 "name": "host_select_3", 182 "pin": "AA7", 183 "direction": "both", 184 "polarity": "active_high" 185 } 186 ], 187 "max_position": 4, 188 "host_selector_map": { 189 "6": 0, 190 "7": 1, 191 "8": 2, 192 "9": 3, 193 "10": 4, 194 "11": 0, 195 "12": 1, 196 "13": 2, 197 "14": 3, 198 "15": 4 199 } 200} 201``` 202 203### Host selector cpld config example 204 205There are also some systems that get the host selector selection from the CPLD, 206the configuration is provided below. 207 208- name - The button interface type name. 209- i2c_bus - The i2c bus of cpld 210- i2c_address - The i2c address of cpld 211- register_name - The register file name exported by CLD driver for IO event 212 listen 213- max_position - This represents the max number of hosts in the multi-host bmc 214 system. 215 216```json 217{ 218 "cpld_definitions": [ 219 { 220 "name": "HOST_SELECTOR", 221 "i2c_bus": 12, 222 "i2c_address": 15, 223 "register_name": "uart-selection-debug-card", 224 "max_position": 4 225 } 226 ] 227} 228``` 229 230### Serial uart mux config 231 232Similar to host selector there are multiple gpios associated with the serial 233uart mux. These gpio configs are specified as part of json array 234"group_gpio_config". 235 236Here the serial uart mux output is accessed via OCP debug card. SO the OCP debug 237card present gpio is mentioned part of the group_gpio_config. The debug card 238present gpio is identified by its name "debug_card_present". 239 240The other gpios part of the group gpio config is serial uart MUX gpio select 241lines and serial_uart_rx line. 242 243- name - this is name of the specific gpio line 244- pin - this represents the pin number from linux dts file. 245- polarity - polarity type of the gpio 246- serial_uart_mux_map - This is the map for selected host position to the serial 247 uart mux select output value 248 249```json 250{ 251 "name": "SERIAL_UART_MUX", 252 253 "group_gpio_config": [ 254 { 255 "name": "serial_uart_sel_0", 256 "pin": "E0", 257 "direction": "out", 258 "polarity": "active_high" 259 }, 260 { 261 "name": "serial_uart_sel_1", 262 "pin": "E1", 263 "direction": "out", 264 "polarity": "active_high" 265 }, 266 { 267 "name": "serial_uart_sel_2", 268 "pin": "E2", 269 "direction": "out", 270 "polarity": "active_high" 271 }, 272 { 273 "name": "serial_uart_sel_3", 274 "pin": "E3", 275 "direction": "out", 276 "polarity": "active_high" 277 }, 278 { 279 "name": "serial_uart_rx", 280 "pin": "E4", 281 "direction": "out", 282 "polarity": "active_high" 283 }, 284 { 285 "name": "debug_card_present", 286 "pin": "R3", 287 "direction": "both", 288 "polarity": "active_high" 289 } 290 ], 291 "serial_uart_mux_map": { 292 "0": 4, 293 "1": 0, 294 "2": 1, 295 "3": 2, 296 "4": 3 297 } 298} 299``` 300