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