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