xref: /openbmc/phosphor-buttons/README.md (revision 7824da46) 
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
66## example gpio def Json config
67
68```json
69{
70    "gpio_definitions": [
71        {
72            "name": "POWER_BUTTON",
73            "gpio_config" :[
74               {
75                "pin": "D0",
76                "direction": "both"
77               }
78            ]
79        },
80        {
81            "name": "RESET_BUTTON",
82            "gpio_config" :[
83                {
84                "pin": "AB0",
85                "direction": "both"
86                 }
87            ]
88        },
89        {
90            "name" : "HOST_SELECTOR",
91
92            "group_gpio_config" : [
93            {
94                "pin": "AA4",
95                "direction": "both"
96            },
97            {
98                "pin": "AA5",
99                "direction": "both"
100            },
101            {
102                "pin": "AA6",
103                "direction": "both"
104            },
105            {
106                "pin": "AA7",
107                "direction": "both"
108            }
109            ]
110        },
111
112}
113```
114
115## Single gpio config
116
117This config is original config which can be used for configs with only single
118gpio such as power button,reset button, OCP debug card host select button.
119
120```json
121{
122    "name": "POWER_BUTTON",
123    "pin": "D0",
124    "direction": "both"
125},
126```
127
128**Note:** this config is used by most of the other platforms so this format is
129kept as it is so that existing gpio configs do not get affected.
130
131## Group gpio config
132
133The following configs are related to multi-host bmc systems more info explained
134in the design:
135<https://github.com/openbmc/docs/blob/master/designs/multihost-phosphor-buttons.md>
136
137### Host selector gpio config example
138
139The host selector has four gpios associated. So the related gpios are mentioned
140in a json array named group_gpio_config.
141
142- name - This is name of the specific gpio line
143- pin - This represents the pin number from linux dts file.
144- polarity - polarity type of the gpio
145- max_position - This represents the max number of hosts in the multi-host bmc
146  system.
147- host_selector_map - This map is oem specific host position map which has how
148  the value read from the host selector gpios is mapped to the respective host
149  number.
150
151Example : The value of "7" derived from the 4 host select gpio lines are mapped
152to host position 1.
153
154```json
155{
156  "name": "HOST_SELECTOR",
157
158  "group_gpio_config": [
159    {
160      "name": "host_select_0",
161      "pin": "AA4",
162      "direction": "both",
163      "polarity": "active_high"
164    },
165    {
166      "name": "host_select_1",
167      "pin": "AA5",
168      "direction": "both",
169      "polarity": "active_high"
170    },
171    {
172      "name": "host_select_2",
173      "pin": "AA6",
174      "direction": "both",
175      "polarity": "active_high"
176    },
177    {
178      "name": "host_select_3",
179      "pin": "AA7",
180      "direction": "both",
181      "polarity": "active_high"
182    }
183  ],
184  "max_position": 4,
185  "host_selector_map": {
186    "6": 0,
187    "7": 1,
188    "8": 2,
189    "9": 3,
190    "10": 4,
191    "11": 0,
192    "12": 1,
193    "13": 2,
194    "14": 3,
195    "15": 4
196  }
197}
198```
199
200### Host selector cpld config example
201
202There are also some systems that get the host selector selection from the CPLD,
203the configuration is provided below.
204
205- name - The button interface type name.
206- i2c_bus - The i2c bus of cpld
207- i2c_address - The i2c address of cpld
208- register_name - The register file name exported by CLD driver for IO event
209  listen
210- max_position - This represents the max number of hosts in the multi-host bmc
211  system.
212
213```json
214{
215  "cpld_definitions": [
216    {
217      "name": "HOST_SELECTOR",
218      "i2c_bus": 12,
219      "i2c_address": 15,
220      "register_name": "uart-selection-debug-card",
221      "max_position": 4
222    }
223  ]
224}
225```
226
227### Serial uart mux config
228
229Similar to host selector there are multiple gpios associated with the serial
230uart mux. These gpio configs are specificed as part of json array
231"group_gpio_config".
232
233Here the serial uart mux output is accessed via OCP debug card. SO the OCP debug
234card present gpio is mentioned part of the group_gpio_config. The debug card
235present gpio is identified by its name "debug_card_present".
236
237The other gpios part of the group gpio config is serial uart MUX gpio select
238lines and serial_uart_rx line.
239
240- name - this is name of the specific gpio line
241- pin - this represents the pin number from linux dts file.
242- polarity - polarity type of the gpio
243- serial_uart_mux_map - This is the map for selected host position to the serial
244  uart mux select output value
245
246```json
247{
248  "name": "SERIAL_UART_MUX",
249
250  "group_gpio_config": [
251    {
252      "name": "serial_uart_sel_0",
253      "pin": "E0",
254      "direction": "out",
255      "polarity": "active_high"
256    },
257    {
258      "name": "serial_uart_sel_1",
259      "pin": "E1",
260      "direction": "out",
261      "polarity": "active_high"
262    },
263    {
264      "name": "serial_uart_sel_2",
265      "pin": "E2",
266      "direction": "out",
267      "polarity": "active_high"
268    },
269    {
270      "name": "serial_uart_sel_3",
271      "pin": "E3",
272      "direction": "out",
273      "polarity": "active_high"
274    },
275    {
276      "name": "serial_uart_rx",
277      "pin": "E4",
278      "direction": "out",
279      "polarity": "active_high"
280    },
281    {
282      "name": "debug_card_present",
283      "pin": "R3",
284      "direction": "both",
285      "polarity": "active_high"
286    }
287  ],
288  "serial_uart_mux_map": {
289    "0": 4,
290    "1": 0,
291    "2": 1,
292    "3": 2,
293    "4": 3
294  }
295}
296```
297