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