1# Multi-host Postcode Support
2
3Author: Manikandan Elumalai, [manikandan.hcl.ers.epl@gmail.com]
4
5Other contributors: None
6
7Created: 2020-07-02
8
9## Problem Description
10
11The current implementation in the phosphor-host-postd supports only single host
12postcode access through LPC interface.
13
14As the open BMC architecture is evolving, the single host support becomes
15contingent and needs multiple-host post code access to be implemented.
16
17## Background and References
18
19The below component diagram shows the design for single-host postcode and history at
20high-level overview. The single-host design is updated slightly from the
21original to better comply with community conventions (using suffix 0 on D-Bus
22objects).
23
24Diagram Legend:
25|Label|Signifies|
26|-----|---------|
27|`I:` |D-Bus interface|
28|`S:` |D-Bus service name (well-known bus name)|
29|`R:` |Repository name|
30|`U:` |Systemd service unit name|
31|`A:` |Executable name|
32|`H:` |HW Module|
33
34```
35                                         +-----------+
36                       +------+          | 7 segment |
37                       | Host |          |  display  |
38                       +--+---+          +-----^-----+
39                          |                    |
40+-------------------------+--------------------+--------+
41| BMC                     |                    |        |
42|                      +--v----+         +-----+-----+  |
43|                      | H:LPC +---------> H:(S)GPIO |  |
44|                      +--+----+         +-----------+  |
45|                         |                             |
46| +-----------------------v--------------+              |
47| | U:lpcsnoop                           |              |
48| |                                      |              |
49| | Current POST code:                   |              |
50| | S:xyz.openbmc_project.State.Boot.Raw |              |
51| | /xyz/openbmc_project/state/boot/raw0 |              |
52| | I:xyz.openbmc_project.State.Boot.Raw >----+         |
53| +--------------------------------------+    |         |
54|                                             |         |
55| +-------------------------------------------v---+     |
56| | U:xyz.openbmc_project.State.Boot.PostCode     |     |
57| | POST code history:                            |     |
58| | +-------------------------------------------+ |     |
59| | | S:xyz.openbmc_project.State.Boot.PostCode0| |     |
60| | | /xyz/openbmc_project/State/Boot/PostCode0 | |     |
61| | | I:xyz.openbmc_project.State.Boot.PostCode >----+  |
62| | +-------------------------------------------+ |  |  |
63| +-----------------------------------------------+  |  |
64|                                                    |  |
65|      +--------------------------------+            |  |
66|      | Other consumers of POST codes: <------------+  |
67|      | Redfish, etc...                |               |
68|      +--------------------------------+               |
69+-------------------------------------------------------+
70```
71
72Since multiple hosts cannot coherently write their POST codes to the same place,
73an additional datapath is needed to receive POST codes from each host. Since
74this new datapath would not have built-in support in ASPEED hardware, additional
75logic is also needed drive the 7-segment display.
76
77## Requirements
78
79 - Read postcode from all servers.
80 - Display the host postcode to the 7 segment display based on host position
81   selection.
82 - Provide a command interface for user to see any server(multi-host) current
83   postcode.
84 - Provide a command interface for user to see any server(multi-host) postcode
85   history.
86 - Support for hot-plug-able host.
87
88## Proposed Design
89
90This document proposes a new design engaging the IPMB interface to read the
91port-80 post code from multiple-host. The existing single host LPC snooping
92mechanism remains unaffected, and is not shown in diagrams below. This design
93also supports host discovery including the hot-plug-able host connected in the
94slot.
95
96Following modules will be updated for this implementation
97
98 - phosphor-host-postd.
99 - phosphor-post-code-manager.
100 - platform specific OEM handler (fb-ipmi-oem).
101 - bmcweb (redfish logging service).
102
103**Interface Diagram**
104
105Provided below the post code interface diagram with flow sequence
106```
107+---------------------------------------------------+
108| BMC                                               |
109|                                                   |
110|  +-----------------------+    +----------------+  |         +----+-------------+
111|  | A:ipmid               |    | IPMB Bridge    <--+--IPMB-+-|BIC |             |
112|  |                       |    | (R:ipmbbridge) |  |       | |    |     Host1   |
113|  | +-------------------+ |    +--------+-------+  |       | +------------------+
114|  | | OEM IPMI Handlers | |             |          |       |           .
115|  | | (R:fb-ipmi-oem)   <-+-------------+          |       |           .
116|  | --------------------+ |   +----------------+   |       |           .
117|  +-+---------------------+   | Host selection |   |       | +------------------+
118|    |                         | monitoring     <---+--+    +-|BIC |             |
119|    |                         +---------+------+   |  |      |    |     HostN   |
120|    |                                   |          |  |      +------------------+
121|    | +---------------------------------v------+   |  |
122|    | | R:phosphor-host-postd (1 process)      |   |  |      +---------------+
123|    | | Per-host POST code object:             |   |  +-GPIO-| Button/switch |
124|    | | /xyz/openbmc_project/state/boot/raw<N> |   |         | input device  |
125|    +-> I:xyz.openbmc_project.State.Boot.Raw   >-+ |         +---------------+
126|      +---------------------------------+------+ | |
127|                                        |        | |         +-------------------+
128|                                        +--------+-+----GPIO-> 7-segment display |
129|                                                 | |         +-------------------+
130|                                                 | +------+
131|                                                 |        |
132|  +----------------------------------------------v---+    |
133|  | R:phosphor-post-code-manager (N processes)       |    |
134|  | Per-host POST code history service:              |    |
135|  | +----------------------------------------------+ |    |
136|  | | S:xyz.openbmc_project.State.Boot.PostCode<N> | |    |
137|  | | /xyz/openbmc_project/State/Boot/PostCode<N>  | |    |
138|  | | I:xyz.openbmc_project.State.Boot.PostCode    >-+-+  |
139|  | +----------------------------------------------+ | |  |
140|  |                        ...                       | |  |
141|  +--------------------------------------------------+ |  |
142|                                                       |  |
143|       +--------------------------------+              |  |
144|       | Other consumers of POST codes: <--------------+  |
145|       | Redfish, CLI, etc...           |                 |
146|       +--------------------------------+                 |
147|                                                          |
148+----------------------------------------------------------+
149```
150
151**Postcode Flow:**
152
153 - BMC power-on the host.
154 - Host starts sending the postcode IPMI message continuously to the BMC.
155 - The ipmbbridged (phosphor-ipmi-ipmb) passes along the message to IPMI daemon.
156 - The ipmid (phosphor-ipmi-host) appends host information with postcode and
157   writes value to appropriate D-Bus object hosted by phosphor-host-postd.
158 - phosphor-host-postd displays postcode in the seven segment display based on
159   host position reads through D-bus interface.
160 - phosphor-post-code-manager receives new POST codes via D-Bus signal and
161   stores the postcode as history in the /var directory.
162
163##  Platform Specific OEM Handler (fb-ipmi-oem)
164
165This library is part of the [phosphor-ipmi-host](https://github.com/openbmc/phosphor-host-ipmid)
166and gets the postcode from host through
167[phosphor-ipmi-ipmb](https://github.com/openbmc/ipmbbridge).
168
169 - Register IPMI OEM postcode callback handler.
170 - Extract postcode from IPMI message (phosphor-ipmi-host/phosphor-ipmi-ipmb).
171 - Sets `Value` property on appropriate D-Bus `Raw` object hosted by
172   `phosphor-host-postd`. Other programs (e.g. `phosphor-post-code-manager`) can
173   subscribe to `PropertiesChanged` signals on this object to get the updates.
174
175## phosphor-host-postd
176
177This implementation involves the following changes in the phosphor-host-postd.
178
179 - `phosphor-host-postd` handles property set events for the `Value` property on
180   each instance of the `xyz.openbmc_project.State.Boot.Raw` interface.
181 - phosphor-host-postd reads the host selection from the dbus property.
182 - Display the latest postcode of the selected host read through D-Bus on a
183   7-segment display.
184
185 **D-Bus interface**
186
187  The following D-Bus names need to be created for the multi-host
188  post-code.
189
190    Service name      -- xyz.openbmc_project.State.Boot.Raw
191
192    Obj path name     -- /xyz/openbmc_project/State/Boot/RawX(1,2..N)
193
194    Interface name    -- xyz.openbmc_project.State.Boot.Raw
195
196## phosphor-post-code-manager
197
198The phosphor-post-code-manager is a multi service design for multi-host.
199The single host postcode handling D-bus naming conventions will be updated
200to comply with the community naming scheme.
201
202 - Create D-Bus service names for single-host and multi-host system
203   accordingly. The community follows conventions Host0 for single host
204   and Host1 to N for multi-host.
205 - phosphor-post-code-manager subscribes to changes on the `Raw<N>` object
206   hosted by `phosphor-host-postd`.
207 - Store/retrieve post-code from directory (/var/lib/phosphor-post-code-manager/
208   hostX(1,2,3..N)) based on event received from phosphor-host-postd.
209
210 **D-Bus interface**
211
212   The following D-Bus names needs to be created for multi-host post-code.
213
214    Service name     -- xyz.openbmc_project.State.Boot.PostCodeX(1,2..N)
215
216    Obj path name    -- /xyz/openbmc_project/State/Boot/PostCodeX(1,2..N)
217
218    Interface name   -- xyz.openbmc_project.State.Boot.PostCode
219
220## bmcweb
221   The postcode history needs to be handled for the multi-host through
222   redfish logging service.
223
224## Alternate design
225
226**phosphor-post-code-manager single process approach**
227
228   This implementation consider single service to handle multi-host postcode.
229   In this approach, all D-Bus handling will taken care by the single process.
230
231   Single service is different than existing x86-power-control and obmc-console
232   where multi-service approach is used.
233
234   Multi-service approach is more scalable to handle multi-host than
235   the single service.
236