xref: /openbmc/phosphor-buttons/README.md (revision 4fcfadd3) 
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### Serial uart mux config
156
157Similar to host selector there are multiple gpios associated with the serial
158uart mux. These gpio configs are specificed as part of json array
159"group_gpio_config".
160
161Here the serial uart mux output is accessed via OCP debug card. SO the OCP debug
162card present gpio is mentioned part of the group_gpio_config. The debug card
163present gpio is identified by its name "debug_card_present".
164
165The other gpios part of the group gpio config is serial uart MUX gpio select
166lines and serial_uart_rx line.
167
168- name - this is name of the specific gpio line
169- pin - this represents the pin number from linux dts file.
170- polarity - polarity type of the gpio
171- serial_uart_mux_map - This is the map for selected host position to the serial
172  uart mux select output value
173
174```json
175{
176  "name": "SERIAL_UART_MUX",
177
178  "group_gpio_config": [
179    {
180      "name": "serial_uart_sel_0",
181      "pin": "E0",
182      "direction": "out",
183      "polarity": "active_high"
184    },
185    {
186      "name": "serial_uart_sel_1",
187      "pin": "E1",
188      "direction": "out",
189      "polarity": "active_high"
190    },
191    {
192      "name": "serial_uart_sel_2",
193      "pin": "E2",
194      "direction": "out",
195      "polarity": "active_high"
196    },
197    {
198      "name": "serial_uart_sel_3",
199      "pin": "E3",
200      "direction": "out",
201      "polarity": "active_high"
202    },
203    {
204      "name": "serial_uart_rx",
205      "pin": "E4",
206      "direction": "out",
207      "polarity": "active_high"
208    },
209    {
210      "name": "debug_card_present",
211      "pin": "R3",
212      "direction": "both",
213      "polarity": "active_high"
214    }
215  ],
216  "serial_uart_mux_map": {
217    "0": 4,
218    "1": 0,
219    "2": 1,
220    "3": 2,
221    "4": 3
222  }
223}
224```
225