xref: /openbmc/docs/designs/redfish-postcodes.md (revision ba560cc31297caddfc157c540ae9e6d760d630e5) 
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```json
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```json
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```json
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```json
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```json
137{
138  "call": "GetPostCodes",
139  "interface": "xyz.openbmc_project.State.Boot.PostCode",
140  "obj": "/xyz/openbmc_project/State/Boot/PostCode",
141  "result": [1, 2, 3, 4, 5, 6, 17, 50, 4, 173],
142  "status": "ok"
143}
144```
145
146The existing DBus GetPostCodes method will remain for backward compatibility. A
147new method GetPostCodesTS will be added to include an ISO formatted time stamp
148with micro-second resolution along with each POST code.
149
150```json
151{
152  "call": "GetPostCodesTS",
153  "interface": "xyz.openbmc_project.State.Boot.PostCode",
154  "obj": "/xyz/openbmc_project/State/Boot/PostCode",
155  "result": [
156    {"20191223T143052.632591", 1},
157    {"20191223T143052.634083", 2},
158    {"20191223T143053.928719", 3},
159    {"20191223T143053.930168", 4},
160    {"20191223T143054.512488", 5},
161    {"20191223T143054.513945", 6},
162    {"20191223T143054.960246", 17},
163    {"20191223T143054.961723", 50},
164    {"20191223T143055.368219", 4},
165    {"20191223T143055.369680", 173}
166  ],
167  "status": "ok"
168}
169```
170
171The DBus DeleteAll interface will be implemented to remove entries. The Redfish
172ClearLog action will call the DBus DeleteAll interface.
173
174```json
175{
176  "call": "DeleteAll",
177  "interface": "xyz.openbmc_project.Collection.DeleteAll",
178  "obj": "/xyz/openbmc_project/State/Boot/PostCode",
179  "result": "POST Codes Cleared"
180  "status": "ok"
181}
182```
183
184## Alternatives Considered
185
186Consideration was given to using the existing DBus method and not exposing
187associated time stamps. In this case, a single log entry could be used per boot
188cycle exposing a string with all POST codes associated with that boot cycle.
189Time stamp data was considered valuable even if the data may be skewed by DBUS.
190
191Consideration was also given to expose the POST codes through a OEM extension
192rather than using the LogEntry schema. Use of OEM extensions to Redfish are
193discouraged. It can be revisited if DMTF adds a schema for POST codes.
194
195## Impacts
196
197Backward compatibility remains with the existing DBUS interface method. Minimal
198performance impact is expected to track timestamps.
199
200## Testing
201
202Compliance with Redfish will be tested using the Redfish Service Validator.
203