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
19**Existing postcode implementation for single host**
20
21The below component diagram shows the present implementation for postcode and
22history at high-level overview
23
24```
25+----------------------------------+              +--------------------+
26|BMC                               |              |                    |
27|  +-------------------------------+              |                    |
28|  |Phosphor-host-postd            |              |                    |
29|  |                    +----------+              +------------+       |
30|  |                    | LPC      |              |            |       |
31|  |                    |          +<-------------+            |       |
32|  |                    +----------+              |  LPC       |       |
33|  |                               |              |            |       |
34|  |xyz.openbmc_project.State.     +<-------+     +------------+       |
35|  |Boot.Raw.Value                 |        |     |                    |
36|  +------+------------------------+        |     |         Host       |
37|         |                        |        |     |                    |
38|         |                        |        |     |                    |
39|   postcode change event          |        +     +--------------------+
40|         |                        | xyz.openbmc_project.State.Boot.Raw
41|         |                        |        +
42|         |                        |        |      +------------------+
43|  +------v------------------------+        +----->+                  |
44|  |Phosphor-postcode-manager      |               |   CLI            |
45|  |                 +-------------+               |                  |
46|  |                 |   postcode  +<------------->+                  |
47|  |                 |   history   |               |                  |
48|  |                 +-------------+               +------------------+
49|  +-------------------------------+ xyz.openbmc_project.State.Boot.PostCode
50|                                  |
51|                                  |
52|  +-------------------------------+             +----------------------+
53|  |                               |  8GPIOs     |                      |
54|  |     SGPIO                     +------------>+                      |
55|  |                               |             |     7 segment        |
56|  +-------------------------------+             |     Display          |
57|                                  |             |                      |
58+----------------------------------+             +----------------------+
59```
60## Requirements
61
62 - Read postcode from all servers.
63 - Display the host postcode to the 7 segment display based on host position
64   selection.
65 - Provide a command interface for user to see any server(multi-host) current
66   postcode.
67 - Provide a command interface for user to see any server(multi-host) postcode
68   history.
69 - Support for hot-plug-able host.
70
71## Proposed Design
72
73This document proposes a new design engaging the IPMB interface to read the
74port-80 post code from multiple-host. The existing single host LPC interface
75remains unaffected. This design also supports host discovery including the
76hot-plug-able host connected in the slot.
77
78Following modules will be updated for this implementation
79
80 - phosphor-host-postd.
81 - phosphor-post-code-manager.
82 - platform specific OEM handler (fb-ipmi-oem).
83 - bmcweb(redfish logging service).
84
85**Interface Diagram**
86
87Provided below the post code interface diagram with flow sequence
88```
89+-------------------------------------------+
90|                  BMC                      |
91|                                           |
92| +--------------+     +-----------------+  |    I2C/IPMI  +----+-------------+
93| |              |     |                 |  |  +---------->|BIC |             |
94| |              |     |   ipmbbridged   <--+--+           |    |     Host1   |
95| |              |     |                 |  |  |           +------------------+
96| | oem handlers |     +-------+---------+  |  | I2C/IPMI  +------------------+
97| |              |             |            |  +---------->|BIC |             |
98| |              |             |            |  |           |    |     Host2   |
99| |              |     +-------v---------+  |  |           +------------------+
100| | (fb-ipmi-oem)|     |                 |  |  | I2C/IPMI  +------------------+
101| |              +<----+     ipmid       |  |  +---------->|BIC |             |
102| |              |     |                 |  |  |           |    |     Host3   |
103| +-+----+-------+     +-----------------+  |  |           +------------------+
104|   |    |                                  |  | I2C/IPMI  +------------------+
105|   |    |             +-----------------+  |  +---------->|BIC |             |
106|   |    |             | Host position   |  |              |    |     HostN   |
107| event  |             |  from D-Bus     |  |              +----+-------------+
108|   |    |             +-------+---------+  |
109|   |  event                   |            |             +-----------------+
110|   |    |                     |            |             |                 |
111|   |  +-v---------------------v---------+  |             | seven segment   |
112|   |  |   phosphor-host-postd           +--+------------>+ display         |
113|   |  |     (ipmisnoop)                 |  |             |                 |
114|   |  |   xyz.openbmc_project.State.    |  |             |                 |
115|   |  |   Boot.RawX(1,2,..N).Value      |  |             +-----------------+
116|   |  +---------------------------------+  |
117|   |                                       |    xyz.openbmc_project.
118|   |                                       |    State.Boot.
119| +-v------------------------------------+  |    PostcodeX(1,2..N)    +-----+
120| | +----------------+  +--------------+ |  |                         |     |
121| | |                |  |              | +<-+------------------------>+     |
122| | |  Process1      |  | Process N    | |  |                         | CLI |
123| | |   (host1)      |  |  (hostN)     | |  |                         |     |
124| | |                |  |              | +<-+------------------------>+     |
125| | +----------------+  +--------------+ |  | /redfish/v1/Systems/    |     |
126| |                                      |  | system/LogServices/     +-----+
127| | Phosphor-post-code-manager@@         |  | PostCodesX(1,2..N)
128| +--------------------------------------+  |
129+-------------------------------------------+
130
131```
132
133**Postcode Flow:**
134
135 - BMC power-on the host.
136 - Host starts sending the postcode IPMI message continuously to the BMC.
137 - The ipmbbridged(phosphor-ipmi-ipmb) extracts postcode from IPMI message.
138 - The ipmbd(phosphor-ipmi-host) appends host information with postcode and
139   sends to the phosphor-host-postd.
140 - platform specific OEM handler(fb-ipmi-oem) sends postcode by emit-change
141   event to the phosphor-host-postd and phosphor-post-code-manager.
142 - phosphor-host-postd displays postcode in the seven segment display based on
143   host position reads through D-bus interface.
144 - phosphor-post-code-manager stores the postcode as history in the /var
145   directory.
146
147##  Platform Specific OEM Handler (fb-ipmi-oem)
148
149This library is part of the [phosphor-ipmi-host]
150(https://github.com/openbmc/phosphor-host-ipmid)
151and gets the postcode from host through
152[phosphor-ipmi-ipmb](https://github.com/openbmc/ipmbbridge).
153
154 - Register IPMI OEM postcode callback handler.
155 - Extract postcode from IPMI message (phosphor-ipmi-host/phosphor-ipmi-ipmb).
156 - Generate emit-change event to phosphor-host-postd and post-code-manager
157   based on which host's postcode received from IPMB
158   interface(xyz.openbmc_project.State.Boot.RawX(1,2,3..N).Value).
159
160## phosphor-host-postd
161
162This implementation involves the following changes in the phosphor-host-postd.
163
164 - Create D-Bus service names for single-host and multi-host system
165   accordingly. The community follows conventions Host0 for single host and
166   Host1 to N for multi-host.
167 - phosphor-host-postd reads the postcode when emit-change event
168   in 'Raw.Value'.
169 - phosphor-host-postd reads the host selection from the dbus property.
170 - Display the latest postcode of the selected host read through D-Bus.
171
172 **D-Bus interface**
173
174  The following D-Bus names need to be created for the multi-host
175  post-code.
176
177    Service name      -- xyz.openbmc_project.State.Boot.Raw
178
179    Obj path name     -- /xyz/openbmc_project/State/Boot/RawX(1,2..N)
180
181    Interface name    -- xyz.openbmc_project.State.Boot.Raw
182
183## phosphor-post-code-manager
184
185The phosphor-post-code-manager is a multi service design for multi-host.
186The single host postcode handling D-bus naming conventions will be updated
187to comply the community naming scheme.
188
189 - Create D-Bus service names for single-host and multi-host system
190   accordingly.The community follows conventions Host0 for single host
191   and Host1 to N for multi-host.
192 - phosphor-post-code-manager reads the postcode when emit-change
193   event in 'Raw.Value'.
194 - Store/retrieve post-code from directory (/var/lib/phosphor-post-code-manager/
195   hostX(1,2,3..N)) based on event received from phosphor-host-postd.
196
197 **D-Bus interface**
198
199   The following D-Bus names needs to be created for multi-host post-code.
200
201    Service name     -- xyz.openbmc_project.State.Boot.PostCodeX(1,2..N)
202
203    Obj path name    -- /xyz/openbmc_project/State/Boot/PostCodeX(1,2..N)
204
205    Interface name   -- xyz.openbmc_project.State.Boot.PostCode
206
207## bmcweb
208   The postcode history needs to be handled for the multi-host through
209   redfish logging service.
210
211## Alternate design
212
213**phosphor-post-code-manager single process approach**
214
215   This implementation consider single service to handle multi-host postcode.
216   In this approach, all D-Bus handling will taken care by the single process.
217
218   Single service is different than existing x86-power-control and obmc-console
219   where multi-service approach is used.
220
221   Multi-service approach is more scalable to handle multi-host than
222   the single service.
223