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