xref: /openbmc/docs/designs/redfish-postcodes.md (revision 74d3bf47) 
1# Logging BIOS POST Codes Through Redfish
2
3Author:
4  Terry Duncan
5
6Primary assignee:
7  Zhikui Ren
8
9Other contributors:
10  Jason Bills, Zhikui Ren
11
12Created:
13  December 23, 2019
14
15## Problem Description
16BIOS Power-On Self-Test (POST) codes are exposed on DBUS but not currently over
17Redfish. This describes a method to expose the BIOS POST codes over the Redfish
18interface using the logging service.
19
20## Background and References
21The standard Redfish LogService and LogEntry schemas will be used to expose
22BIOS POST codes. An additional log service (PostCodes) will be added to
23the LogServiceCollection.
24
25Sample [LogService](https://redfish.dmtf.org/schemas/LogService_v1.xml) entry:
26```
27https://obmc/redfish/v1/Systems/system/LogServices/PostCodes
28{
29    "@odata.context": "/redfish/v1/$metadata#LogService.LogService",
30    "@odata.id": "/redfish/v1/Systems/system/LogServices/PostCodes",
31    "@odata.type": "#LogService.v1_1_0.LogService",
32    "Actions": {
33        "#LogService.ClearLog": {
34            "target": "/redfish/v1/Systems/system/LogServices/PostCodes/Actions/LogService.ClearLog"
35        }
36    },
37    "Description": "POST Code Log Service",
38    "Entries": {
39        "@odata.id": "/redfish/v1/Systems/system/LogServices/PostCodes/Entries"
40    },
41    "Id": "BIOS POST Code Log",
42    "Name": "POST Code Log Service",
43    "OverWritePolicy": "WrapsWhenFull"
44}
45```
46
47Events will be exposed using the
48[LogEntry](https://redfish.dmtf.org/schemas/LogEntry_v1.xml) schema.
49```
50https://obmc/redfish/v1/Systems/system/LogServices/PostCodes/Entries
51{
52    "@odata.context": "/redfish/v1/$metadata#LogEntryCollection.LogEntryCollection",
53    "@odata.id": "/redfish/v1/Systems/system/LogServices/PostCodes/Entries",
54    "@odata.type": "#LogEntryCollection.LogEntryCollection",
55    "Description": "Collection of POST Code Log Entries",
56    "Members": [
57        {
58            "@odata.context": "/redfish/v1/$metadata#LogEntry.LogEntry",
59            "@odata.id": "/redfish/v1/Systems/system/LogServices/PostCodes/Entries/B1-03",
60            "@odata.type": "#LogEntry.v1_4_0.LogEntry",
61            "Created": "2019-12-06T14:10:30+00:00",
62            "EntryType": "Event",
63            "Id": "B1-03",
64            "Message": "Boot Count: 4: TS Offset: 0.0033; POST Code: 0x43",
65            "MessageArgs": [
66                4,
67                0.0033,
68                "0x43"
69            ],
70            "MessageId": "OpenBMC.0.1.BiosPostCode",
71            "Name": "POST Code Log Entry",
72            "Severity": "OK"
73        },
74        ...
75    ],
76    "Members@odata.count": 10000,
77    "Name": "BIOS POST Code Log Entries"
78}
79```
80
81A new
82[MessageRegistry](https://redfish.dmtf.org/schemas/MessageRegistry_v1.xml)
83schema entry defines the format for the message.
84```
85https://obmc/redfish/v1/Registries/OpenBMC/OpenBMC
86{
87    "@Redfish.Copyright": "Copyright 2018 OpenBMC. All rights reserved.",
88    "@odata.type": "#MessageRegistry.v1_0_0.MessageRegistry",
89    "Description": "This registry defines the base messages for OpenBMC.",
90    "Id": "OpenBMC.0.1.0",
91    "Language": "en",
92    "Messages": {
93        "BiosPostCode": {
94            "Description": "BIOS Power-On Self-Test Code received.",
95            "Message": "Boot Count: %1: TS Offset: %2; POST Code: %3",
96            "NumberOfArgs": 3,
97            "ParamTypes": [
98                "number",
99                "number",
100                "string"
101            ],
102            "Resolution": "None.",
103            "Severity": "OK"
104        },
105        ...
106    }
107    "Name": "OpenBMC Message Registry",
108    "OwningEntity": "OpenBMC",
109    "RegistryPrefix": "OpenBMC",
110    "RegistryVersion": "0.1.0"
111}
112```
113
114## Requirements
115The Redfish Interface shall be Redfish compliant and pass the Redfish
116compliancy tests.
117
118The Redfish interface shall expose POST codes tracked on DBUS since the last
119BMC reset.
120
121## Proposed Design
122Currently, OpenBMC exposes BIOS POST codes on DBus using the
123xyz.openbmc_project.State.Boot.PostCode service. The existing interface tracks
124POST codes for the past 100 host boot events and the current boot cycle index.
125```
126xyz.openbmc_project.State.Boot.PostCode
127    GetPostCodes(q undefined) → [uint64] undefined
128    CurrentBootCycleIndex = 1
129    MaxBootCycleIndex = 100
130```
131
132The GetPostCodes method is called using the boot cycle index to retrieve the
133codes for the boot cycle.
134```
135{
136  "call": "GetPostCodes",
137  "interface": "xyz.openbmc_project.State.Boot.PostCode",
138  "obj": "/xyz/openbmc_project/State/Boot/PostCode",
139  "result": [
140    1,
141    2,
142    3,
143    4,
144    5,
145    6,
146    17,
147    50,
148    4,
149    173
150  ],
151  "status": "ok"
152}
153```
154
155The existing DBus GetPostCodes method will remain for backward compatibility. A
156new method GetPostCodesTS will be added to include an ISO formatted time stamp
157with micro-second resolution along with each POST code.
158```
159{
160  "call": "GetPostCodesTS",
161  "interface": "xyz.openbmc_project.State.Boot.PostCode",
162  "obj": "/xyz/openbmc_project/State/Boot/PostCode",
163  "result": [
164    {"20191223T143052.632591", 1},
165    {"20191223T143052.634083", 2},
166    {"20191223T143053.928719", 3},
167    {"20191223T143053.930168", 4},
168    {"20191223T143054.512488", 5},
169    {"20191223T143054.513945", 6},
170    {"20191223T143054.960246", 17},
171    {"20191223T143054.961723", 50},
172    {"20191223T143055.368219", 4},
173    {"20191223T143055.369680", 173}
174  ],
175  "status": "ok"
176}
177```
178
179The DBus DeleteAll interface will be implemented to remove entries. The Redfish
180ClearLog action will call the DBus DeleteAll interface.
181```
182{
183  "call": "DeleteAll",
184  "interface": "xyz.openbmc_project.Collection.DeleteAll",
185  "obj": "/xyz/openbmc_project/State/Boot/PostCode",
186  "result": "POST Codes Cleared"
187  "status": "ok"
188}
189```
190
191## Alternatives Considered
192Consideration was given to using the existing DBus method and not exposing
193associated time stamps. In this case, a single log entry could be used per boot
194cycle exposing a string with all POST codes associated with that boot cycle.
195Time stamp data was considered valuable even if the data may be skewed by DBUS.
196
197Consideration was also given to expose the POST codes through a OEM extension
198rather than using the LogEntry schema. Use of OEM extensions to Redfish are
199discouraged. It can be revisited if DMTF adds a schema for POST codes.
200
201## Impacts
202Backward compatibility remains with the existing DBUS interface method.
203Minimal performance impact is expected to track timestamps.
204
205## Testing
206Compliance with Redfish will be tested using the Redfish Service Validator.
207