xref: /openbmc/phosphor-buttons/README.md (revision 9479b06c)
1# phosphor-buttons
2
3Phosphor-buttons has a collection of IO event handler interfaces for physical
4inputs which are part of OCP front panel.
5
6It defines an individual dbus interface object for each physical button/switch
7inputs such as power button, reset button etc. Each of this button interfaces
8monitors it's associated io for event changes and calls the respective event
9handlers.
10
11## Gpio defs config
12
13In order to monitor a button/input interface the respective gpio config details
14should be mentioned in the gpio defs json file -
15`/etc/default/obmc/gpio/gpio_defs.json`
16
171. The button interface type name.
182. An array consists of single or multiple gpio configs associated with the
19   specific button interface.
20
21## example gpio def Json config
22
23```json
24{
25    "gpio_definitions": [
26        {
27            "name": "POWER_BUTTON",
28            "gpio_config" :[
29               {
30                "pin": "D0",
31                "direction": "both"
32               }
33            ]
34        },
35        {
36            "name": "RESET_BUTTON",
37            "gpio_config" :[
38                {
39                "pin": "AB0",
40                "direction": "both"
41                 }
42            ]
43        },
44        {
45            "name" : "HOST_SELECTOR",
46
47            "group_gpio_config" : [
48            {
49                "pin": "AA4",
50                "direction": "both"
51            },
52            {
53                "pin": "AA5",
54                "direction": "both"
55            },
56            {
57                "pin": "AA6",
58                "direction": "both"
59            },
60            {
61                "pin": "AA7",
62                "direction": "both"
63            }
64            ]
65        },
66
67}
68```
69
70## Single gpio config
71
72This config is original config which can be used for configs with only single
73gpio such as power button,reset button, OCP debug card host select button.
74
75```json
76{
77    "name": "POWER_BUTTON",
78    "pin": "D0",
79    "direction": "both"
80},
81```
82
83**Note:** this config is used by most of the other platforms so this format is
84kept as it is so that existing gpio configs do not get affected.
85
86## Group gpio config
87
88The following configs are related to multi-host bmc systems more info explained
89in the design:
90<https://github.com/openbmc/docs/blob/master/designs/multihost-phosphor-buttons.md>
91
92### Host selector gpio config example
93
94The host selector has four gpios associated. So the related gpios are mentioned
95in a json array named group_gpio_config.
96
97- name - This is name of the specific gpio line
98- pin - This represents the pin number from linux dts file.
99- polarity - polarity type of the gpio
100- max_position - This represents the max number of hosts in the multi-host bmc
101  system.
102- host_selector_map - This map is oem specific host position map which has how
103  the value read from the host selector gpios is mapped to the respective host
104  number.
105
106Example : The value of "7" derived from the 4 host select gpio lines are mapped
107to host position 1.
108
109```json
110{
111  "name": "HOST_SELECTOR",
112
113  "group_gpio_config": [
114    {
115      "name": "host_select_0",
116      "pin": "AA4",
117      "direction": "both",
118      "polarity": "active_high"
119    },
120    {
121      "name": "host_select_1",
122      "pin": "AA5",
123      "direction": "both",
124      "polarity": "active_high"
125    },
126    {
127      "name": "host_select_2",
128      "pin": "AA6",
129      "direction": "both",
130      "polarity": "active_high"
131    },
132    {
133      "name": "host_select_3",
134      "pin": "AA7",
135      "direction": "both",
136      "polarity": "active_high"
137    }
138  ],
139  "max_position": 4,
140  "host_selector_map": {
141    "6": 0,
142    "7": 1,
143    "8": 2,
144    "9": 3,
145    "10": 4,
146    "11": 0,
147    "12": 1,
148    "13": 2,
149    "14": 3,
150    "15": 4
151  }
152}
153```
154
155### Host selector cpld config example
156
157There are also some systems that get the host selector selection from the CPLD,
158the configuration is provided below.
159
160- name - The button interface type name.
161- i2c_bus - The i2c bus of cpld
162- i2c_address - The i2c address of cpld
163- register_name - The register file name exported by CLD driver for IO event
164  listen
165- max_position - This represents the max number of hosts in the multi-host bmc
166  system.
167
168```json
169{
170  "cpld_definitions": [
171    {
172      "name": "HOST_SELECTOR",
173      "i2c_bus": 12,
174      "i2c_address": 15,
175      "register_name": "uart-selection-debug-card",
176      "max_position": 4
177    }
178  ]
179}
180```
181
182### Serial uart mux config
183
184Similar to host selector there are multiple gpios associated with the serial
185uart mux. These gpio configs are specificed as part of json array
186"group_gpio_config".
187
188Here the serial uart mux output is accessed via OCP debug card. SO the OCP debug
189card present gpio is mentioned part of the group_gpio_config. The debug card
190present gpio is identified by its name "debug_card_present".
191
192The other gpios part of the group gpio config is serial uart MUX gpio select
193lines and serial_uart_rx line.
194
195- name - this is name of the specific gpio line
196- pin - this represents the pin number from linux dts file.
197- polarity - polarity type of the gpio
198- serial_uart_mux_map - This is the map for selected host position to the serial
199  uart mux select output value
200
201```json
202{
203  "name": "SERIAL_UART_MUX",
204
205  "group_gpio_config": [
206    {
207      "name": "serial_uart_sel_0",
208      "pin": "E0",
209      "direction": "out",
210      "polarity": "active_high"
211    },
212    {
213      "name": "serial_uart_sel_1",
214      "pin": "E1",
215      "direction": "out",
216      "polarity": "active_high"
217    },
218    {
219      "name": "serial_uart_sel_2",
220      "pin": "E2",
221      "direction": "out",
222      "polarity": "active_high"
223    },
224    {
225      "name": "serial_uart_sel_3",
226      "pin": "E3",
227      "direction": "out",
228      "polarity": "active_high"
229    },
230    {
231      "name": "serial_uart_rx",
232      "pin": "E4",
233      "direction": "out",
234      "polarity": "active_high"
235    },
236    {
237      "name": "debug_card_present",
238      "pin": "R3",
239      "direction": "both",
240      "polarity": "active_high"
241    }
242  ],
243  "serial_uart_mux_map": {
244    "0": 4,
245    "1": 0,
246    "2": 1,
247    "3": 2,
248    "4": 3
249  }
250}
251```
252