1# Multi-host front panel phosphor buttons interface
2
3Author:
4  Velumani T(velu),  [velumanit@hcl](mailto:velumanit@hcl.com)
5  Naveen Moses S(naveen.moses), [naveen.mosess@hcl.com](mailto:naveen.mosess@hcl.com)
6
7Other contributors:
8
9Created:
10  August 3, 2021
11
12## Problem Description
13Phosphor buttons module has currently option to monitor gpio events of power
14and reset buttons and trigger power event handlers.
15
16phosphor-buttons currently only support push type buttons.support for
17different form factor inputs such as switches/MUX other than push type
18buttons are needed for some hardwares. It will be helpful if we could
19add option to support additional input types in phosphor button interfaces
20and event handling.
21
22Currently handler events are only based on monitoring gpio events
23as input (power and reset).There may be cases where we need to create
24button interface which monitors non gpio events
25and triggers button actions for example events based on dbus property changes.
26
27## Requirements
28This feature is needed to support additional phosphor button interfaces
29corresponding to platform specific hardware buttons/MUX/Switches which are
30available in the front panel apart from existing power and reset button
31interfaces.
32
33## Background and References
34The front panel of bmc has buttons like power button, reset button
35in general the code for monitoring these buttons and triggering actions are
36supported.
37
38```
39   +----------------------------------------------+
40   |                                              |
41   |       Front panel                            |
42   |                                              |
43   |   +--------------+      +--------------+     |
44   |   |              |      |              |     |
45   |   | power button |      | reset button |     |
46   |   |              |      |              |     |
47   |   +--------------+      +--------------+     |
48   |                                              |
49   |                                              |
50   |                                              |
51   |                                              |
52   +----------------------------------------------+
53```
54
55platform specific front panel may contain additional hardware buttons or
56mux switch
57
58example for a multihost platform yosemite-V2 it has host selector switch mux
59as additional button in front panel.
60
61```
62+---------------------------+                                      +------------+
63|                           |                                      |            |
64|       yv2 front panel     |           power/           ---------+|  host 1    |
65|                           |           reset/serial mux |         |            |
66|     +----------------+    |           control          |         +------------+
67|     |                |    |                            |
68|     |  power button  |-+  |                            |         +------------+
69|     |                | |  |                            |         |            |
70|     +----------------+ |  |                            |--------+|  host 2    |
71|                        |  |                            |         |            |
72|                        |  |                            |         +------------+
73|                        |  |     +---------------+      |
74|     +----------------+ |  |     |    host       |      |         +-------------+
75|     |                | |  |     |  selector     |------+         |             |
76|     |  reset button  --|--------+   switch      |      |---------+  host 3     |
77|     |                |    |     +---------------+      |         |             |
78|     +----------------+    |                            |         +-------------+
79|                           |                            |
80|                           |                            |          +------------+
81|                           |                            |          |            |
82|     +----------------+    |                            |----------+ host 4     |
83|     | serial console +---------------------------------|          |            |
84|     |    mux switch  |    |                            |          +------------+
85|     |                |    |                            |
86|     +----------------+    |                            |           +-----------+
87|                           |                            +-----------|   BMC     |
88|                           |                                        |           |
89+---------------------------+                                        +-----------+
90
91```
92
93There are two additional hardware buttons/switch available in the
94frontpanel for yv2.
95
96## 1.Host selector switch (selector switch)
97This host selector switch/selector switch has 4 gpio connected as input and
98based on the gpio state values the host selector switch value is derived.
99The possible switch values can vary from 0 to 10.
100The specific mapping between gpio values and host selector values
101can be stored as part of gpio json config.
102
103yosemiteV2 platform has 1 bmc and 4 hosts and only one power button and
104reset button.
105
106For example, when the power button is pressed,
107The value of the host selector switch position(1 to 10) decides whether the
108power button action is needs to be triggered for bmc or any one of the
109hosts.
110
111This option is to use same power button and reset button for multiple hosts.
112
113The power/reset button press events are triggered based on the value of
114host selector switch position.
115
116### Example :
117host selector position value = 0,bmc is mapped to power and reset buttons
118host selector position value = 1,host 1 is mapped to power and reset buttons
119host selector position value = 2,host 2 is mapped to power and reset buttons
120host selector position value = 3,host 3 is mapped to power and reset buttons
121host selector position value = 4,host 4 is mapped to power and reset buttons
122
123## 2.Serial console MUX switch
124
125There is also uart console for each host and bmc which is connected via a
126MUX switch.
127
128At a time any one of the device (either bmc or any one host) can be accessed
129via the console which is based on the UART MUX switch configuration.
130
131Based on the position of the host selector switch, a separate handler interface
132can configure the respective serial console device is selected.
133
134## 3.OCP debug card host selector button
135
136An OCP debug card can be connected to yosemitev2 via usb for debugging purpose.
137
138This is a extension which has three buttons :
1391.Power button
1402.reset button
1413.host selector button
142
143Power and reset buttons are mapped to the same gpio of frontpanel so no
144separate event handling is required.
145
146The host selector button purpose is same as that of the front panel
147host selector switch in yosemitev2 front panel. The debug card host selector
148button (push button) has different gpio lines than that of front panel
149host selector switch gpios.
150Whenever the debug host selector button is pressed the host
151selector switch position value should be increased up to MaxPosition.
152If the host selector switch value is more than MaxPosition then it
153should be reset to zero.
154
155# Proposed Design
156Three high level changes are required in the phosphor button interface class
157
1581. Add support for adding button interfaces which are monitoring more than
159 one gpio event and process with single event handler.
160
1612. Add support to monitor button / switch interface event  based on dbus
162property changes (needed for serial console MUX).
163
1643. Each button interface class can be extended with the following overridable
165methods to allow platform specific logic if needed in a derived class.
166
167- init() - This method may have gpio configuration and
168      event handler initialization.
169
170- handleEvent() - This method may have custom event handling
171    routines for the respective button interface.This should be
172    be called from the main even handler function.
173
174## The host selector switch interface
175
176The host selector switch has 4 gpios associated with it. host selector
177switch button interface monitors these 4 gpio io events as sd-event
178based event loop and a single event handler function is called for
179all 4 gpio events.
180
181Based on the 4 gpio state values, the host selector switch position value
182is derived and stored as a dbus property with name "Position".
183
184### Host selector dbus interface details
185  1. Position(property) - This is the property which holds the current
186  value of the host selector switch based on the GPIO state.
187
188  2. MaxPosition(property) - This is the property which keeps the maximum
189  number of Position the Position property can hold.(This value is based
190  on the number of hosts available in the platform)
191
192## OCP Debug card  host selector button interface
193A separate interface for debug card host selector button is created.
194
195This button interface monitors the corresponding gpio lines for debug card
196host selection button press and release event via sd-event based loop.
197
198### OCP Debug card host selector button dbus interface details :
199  1. Released(signal) - This is signal is triggered in the ocp debug card event
200  handler when the ocp debug card button is pressed and released.
201
202 When the event handler is called once the  button is released,
203then the host selector switch  dbus property "Position" is increased by 1.
204The host selector switch dbus property value is rollover to zero after Position
205value exceeds MaxPosition Value.
206
207This way when power and reset button press events are handled,
208the Host selector Position property is referred and based on the
209Position respective power events are called.
210
211## serial console MUX  interface
212This button interface monitors for change in host selector switch Position dbus
213property and based on the dbus property value change, corresponding serial
214console is selected.mux value can be  set as configuring 4 gpio lines dedicated
215for the serial console mux.
216### Example
2170 - bmc serial console
2181 - host 1 serial console
2192 - host 2 serial console
2203 - host 3 serial console
2214 - host 4 serial console
222
223### Change in power button and reset button interface event handler
224If selector button instance is available,then the power button and reset
225button pressed events must route to appropriate multihost dbus service name
226
227## Impacts
228 The change impacts are under phosphor buttons repo,the existing power and
229 reset button handlers are calling dbus calls for single host power events.
230 This calls should be modified to adapt corresponding multi host power events
231 and the respective host dbus object is based on host selector position.
232
233## Testing
234The proposed design can be tested in a platform in which the multiple hosts
235are connected.
236