4459c0350e6f8964c1a890207dd75750edda5f46
[mirror_edk2.git] / MdePkg / Library / BaseReportStatusCodeLibNull / ReportStatusCodeLib.c
1 /** @file
2 Report Status Code Library template for Base modules.
3
4 Copyright (c) 2006, Intel Corporation<BR>
5 All rights reserved. This program and the accompanying materials
6 are licensed and made available under the terms and conditions of the BSD License
7 which accompanies this distribution. The full text of the license may be found at
8 http://opensource.org/licenses/bsd-license.php
9
10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
12
13 **/
14
15 /**
16 Converts a status code to an 8-bit POST code value.
17
18 Converts the status code specified by CodeType and Value to an 8-bit POST code
19 and returns the 8-bit POST code in PostCode. If CodeType is an
20 EFI_PROGRESS_CODE or CodeType is an EFI_ERROR_CODE, then bits 0..4 of PostCode
21 are set to bits 16..20 of Value, and bits 5..7 of PostCode are set to bits
22 24..26 of Value., and TRUE is returned. Otherwise, FALSE is returned.
23
24 If PostCode is NULL, then ASSERT().
25
26 @param CodeType The type of status code being converted.
27 @param Value The status code value being converted.
28 @param PostCode A pointer to the 8-bit POST code value to return.
29
30 @retval TRUE The status code specified by CodeType and Value was converted
31 to an 8-bit POST code and returned in PostCode.
32 @retval FALSE The status code specified by CodeType and Value could not be
33 converted to an 8-bit POST code value.
34
35 **/
36 BOOLEAN
37 EFIAPI
38 CodeTypeToPostCode (
39 IN EFI_STATUS_CODE_TYPE CodeType,
40 IN EFI_STATUS_CODE_VALUE Value,
41 OUT UINT8 *PostCode
42 )
43 {
44 //
45 // If PostCode is NULL, then ASSERT()
46 //
47 ASSERT (PostCode != NULL);
48
49 //
50 // Convert Value to an 8 bit post code
51 //
52 if (((CodeType & EFI_STATUS_CODE_TYPE_MASK) == EFI_PROGRESS_CODE) ||
53 ((CodeType & EFI_STATUS_CODE_TYPE_MASK) == EFI_ERROR_CODE) ) {
54 *PostCode = (UINT8) (((Value & EFI_STATUS_CODE_CLASS_MASK) >> 24) << 5);
55 *PostCode |= (UINT8) (((Value & EFI_STATUS_CODE_SUBCLASS_MASK) >> 16) & 0x1f);
56 return TRUE;
57 }
58 return FALSE;
59 }
60
61
62 /**
63 Extracts ASSERT() information from a status code structure.
64
65 Converts the status code specified by CodeType, Value, and Data to the ASSERT()
66 arguments specified by Filename, Description, and LineNumber. If CodeType is
67 an EFI_ERROR_CODE, and CodeType has a severity of EFI_ERROR_UNRECOVERED, and
68 Value has an operation mask of EFI_SW_EC_ILLEGAL_SOFTWARE_STATE, extract
69 Filename, Description, and LineNumber from the optional data area of the
70 status code buffer specified by Data. The optional data area of Data contains
71 a Null-terminated ASCII string for the FileName, followed by a Null-terminated
72 ASCII string for the Description, followed by a 32-bit LineNumber. If the
73 ASSERT() information could be extracted from Data, then return TRUE.
74 Otherwise, FALSE is returned.
75
76 If Data is NULL, then ASSERT().
77 If Filename is NULL, then ASSERT().
78 If Description is NULL, then ASSERT().
79 If LineNumber is NULL, then ASSERT().
80
81 @param CodeType The type of status code being converted.
82 @param Value The status code value being converted.
83 @param Data Pointer to status code data buffer.
84 @param Filename Pointer to the source file name that generated the ASSERT().
85 @param Description Pointer to the description of the ASSERT().
86 @param LineNumber Pointer to source line number that generated the ASSERT().
87
88 @retval TRUE The status code specified by CodeType, Value, and Data was
89 converted ASSERT() arguments specified by Filename, Description,
90 and LineNumber.
91 @retval FALSE The status code specified by CodeType, Value, and Data could
92 not be converted to ASSERT() arguments.
93
94 **/
95 BOOLEAN
96 EFIAPI
97 ReportStatusCodeExtractAssertInfo (
98 IN EFI_STATUS_CODE_TYPE CodeType,
99 IN EFI_STATUS_CODE_VALUE Value,
100 IN CONST EFI_STATUS_CODE_DATA *Data,
101 OUT CHAR8 **Filename,
102 OUT CHAR8 **Description,
103 OUT UINT32 *LineNumber
104 )
105 {
106 EFI_DEBUG_ASSERT_DATA *AssertData;
107
108 ASSERT (Data != NULL);
109 ASSERT (Filename != NULL);
110 ASSERT (Description != NULL);
111 ASSERT (LineNumber != NULL);
112
113 if (((CodeType & EFI_STATUS_CODE_TYPE_MASK) == EFI_ERROR_CODE) &&
114 ((CodeType & EFI_STATUS_CODE_SEVERITY_MASK) == EFI_ERROR_UNRECOVERED) &&
115 ((Value & EFI_STATUS_CODE_OPERATION_MASK) == EFI_SW_EC_ILLEGAL_SOFTWARE_STATE)) {
116 AssertData = (EFI_DEBUG_ASSERT_DATA *)(Data + 1);
117 *Filename = (CHAR8 *)(AssertData + 1);
118 *Description = *Filename + AsciiStrLen (*Filename) + 1;
119 *LineNumber = AssertData->LineNumber;
120 return TRUE;
121 }
122 return FALSE;
123 }
124
125
126 /**
127 Extracts DEBUG() information from a status code structure.
128
129 Converts the status code specified by Data to the DEBUG() arguments specified
130 by ErrorLevel, Marker, and Format. If type GUID in Data is
131 EFI_STATUS_CODE_DATA_TYPE_DEBUG_GUID, then extract ErrorLevel, Marker, and
132 Format from the optional data area of the status code buffer specified by Data.
133 The optional data area of Data contains a 32-bit ErrorLevel followed by Marker
134 which is 12 UINTN parameters, followed by a Null-terminated ASCII string for
135 the Format. If the DEBUG() information could be extracted from Data, then
136 return TRUE. Otherwise, FALSE is returned.
137
138 If Data is NULL, then ASSERT().
139 If ErrorLevel is NULL, then ASSERT().
140 If Marker is NULL, then ASSERT().
141 If Format is NULL, then ASSERT().
142
143 @param Data Pointer to status code data buffer.
144 @param ErrorLevel Pointer to error level mask for a debug message.
145 @param Marker Pointer to the variable argument list associated with Format.
146 @param Format Pointer to a Null-terminated ASCII format string of a
147 debug message.
148
149 @retval TRUE The status code specified by Data was converted DEBUG() arguments
150 specified by ErrorLevel, Marker, and Format.
151 @retval FALSE The status code specified by Data could not be converted to
152 DEBUG() arguments.
153
154 **/
155 BOOLEAN
156 EFIAPI
157 ReportStatusCodeExtractDebugInfo (
158 IN CONST EFI_STATUS_CODE_DATA *Data,
159 OUT UINT32 *ErrorLevel,
160 OUT VA_LIST *Marker,
161 OUT CHAR8 **Format
162 )
163 {
164 EFI_DEBUG_INFO *DebugInfo;
165
166 ASSERT (Data != NULL);
167 ASSERT (ErrorLevel != NULL);
168 ASSERT (Marker != NULL);
169 ASSERT (Format != NULL);
170
171 //
172 // If the GUID type is not EFI_STATUS_CODE_DATA_TYPE_DEBUG_GUID then return FALSE
173 //
174 if (!CompareGuid (&Data->Type, &gEfiStatusCodeDataTypeDebugGuid)) {
175 return FALSE;
176 }
177
178 //
179 // Retrieve the debug information from the status code record
180 //
181 DebugInfo = (EFI_DEBUG_INFO *)(Data + 1);
182
183 *ErrorLevel = DebugInfo->ErrorLevel;
184
185 //
186 // The first 12 * UINTN bytes of the string are really an
187 // argument stack to support varargs on the Format string.
188 //
189 *Marker = (VA_LIST) (DebugInfo + 1);
190 *Format = (CHAR8 *)(((UINT64 *)*Marker) + 12);
191
192 return TRUE;
193 }
194
195
196 /**
197 Reports a status code.
198
199 Reports the status code specified by the parameters Type and Value. Status
200 code also require an instance, caller ID, and extended data. This function
201 passed in a zero instance, NULL extended data, and a caller ID of
202 gEfiCallerIdGuid, which is the GUID for the module.
203
204 ReportStatusCode()must actively prevent recusrsion. If ReportStatusCode()
205 is called while processing another any other Report Status Code Library function,
206 then ReportStatusCode() must return immediately.
207
208 @param Type Status code type.
209 @param Value Status code value.
210
211 @retval EFI_SUCCESS The status code was reported.
212 @retval EFI_DEVICE_ERROR There status code could not be reported due to a
213 device error.
214 @retval EFI_UNSUPPORTED Report status code is not supported
215
216 **/
217 EFI_STATUS
218 EFIAPI
219 ReportStatusCode (
220 IN EFI_STATUS_CODE_TYPE Type,
221 IN EFI_STATUS_CODE_VALUE Value
222 )
223 {
224 return EFI_UNSUPPORTED;
225 }
226
227
228 /**
229 Reports a status code with a Device Path Protocol as the extended data.
230
231 Allocates and fills in the extended data section of a status code with the
232 Device Path Protocol specified by DevicePath. This function is responsible
233 for allocating a buffer large enough for the standard header and the device
234 path. The standard header is filled in with a GUID of
235 gEfiStatusCodeSpecificDataGuid. The status code is reported with a zero
236 instance and a caller ID of gEfiCallerIdGuid.
237
238 ReportStatusCodeWithDevicePath()must actively prevent recursion. If
239 ReportStatusCodeWithDevicePath() is called while processing another any other
240 Report Status Code Library function, then ReportStatusCodeWithDevicePath()
241 must return EFI_DEVICE_ERROR immediately.
242
243 If DevicePath is NULL, then ASSERT().
244
245 @param Type Status code type.
246 @param Value Status code value.
247 @param DevicePath Pointer to the Device Path Protocol to be reported.
248
249 @retval EFI_SUCCESS The status code was reported with the extended
250 data specified by DevicePath.
251 @retval EFI_OUT_OF_RESOURCES There were not enough resources to allocate the
252 extended data section.
253 @retval EFI_UNSUPPORTED Report status code is not supported
254
255 **/
256 EFI_STATUS
257 EFIAPI
258 ReportStatusCodeWithDevicePath (
259 IN EFI_STATUS_CODE_TYPE Type,
260 IN EFI_STATUS_CODE_VALUE Value,
261 IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath
262 )
263 {
264 ASSERT (DevicePath != NULL);
265 return EFI_UNSUPPORTED;
266 }
267
268
269 /**
270 Reports a status code with an extended data buffer.
271
272 Allocates and fills in the extended data section of a status code with the
273 extended data specified by ExtendedData and ExtendedDataSize. ExtendedData
274 is assumed to be one of the data structures specified in Related Definitions.
275 These data structure do not have the standard header, so this function is
276 responsible for allocating a buffer large enough for the standard header and
277 the extended data passed into this function. The standard header is filled
278 in with a GUID of gEfiStatusCodeSpecificDataGuid. The status code is reported
279 with a zero instance and a caller ID of gEfiCallerIdGuid.
280
281 ReportStatusCodeWithExtendedData()must actively prevent recursion. If
282 ReportStatusCodeWithExtendedData() is called while processing another any other
283 Report Status Code Library function, then ReportStatusCodeWithExtendedData()
284 must return EFI_DEVICE_ERROR immediately.
285
286 If ExtendedData is NULL, then ASSERT().
287 If ExtendedDataSize is 0, then ASSERT().
288
289 @param Type Status code type.
290 @param Value Status code value.
291 @param ExtendedData Pointer to the extended data buffer to be reported.
292 @param ExtendedDataSize The size, in bytes, of the extended data buffer to
293 be reported.
294
295 @retval EFI_SUCCESS The status code was reported with the extended
296 data specified by ExtendedData and ExtendedDataSize.
297 @retval EFI_OUT_OF_RESOURCES There were not enough resources to allocate the
298 extended data section.
299 @retval EFI_UNSUPPORTED Report status code is not supported
300
301 **/
302 EFI_STATUS
303 EFIAPI
304 ReportStatusCodeWithExtendedData (
305 IN EFI_STATUS_CODE_TYPE Type,
306 IN EFI_STATUS_CODE_VALUE Value,
307 IN CONST VOID *ExtendedData,
308 IN UINTN ExtendedDataSize
309 )
310 {
311 ASSERT (ExtendedData != NULL);
312 ASSERT (ExtendedDataSize != 0);
313 return EFI_UNSUPPORTED;
314 }
315
316
317 /**
318 Reports a status code with full parameters.
319
320 The function reports a status code. If ExtendedData is NULL and ExtendedDataSize
321 is 0, then an extended data buffer is not reported. If ExtendedData is not
322 NULL and ExtendedDataSize is not 0, then an extended data buffer is allocated.
323 ExtendedData is assumed not have the standard status code header, so this function
324 is responsible for allocating a buffer large enough for the standard header and
325 the extended data passed into this function. The standard header is filled in
326 with a GUID specified by ExtendedDataGuid. If ExtendedDataGuid is NULL, then a
327 GUID of gEfiStatusCodeSpecificDatauid is used. The status code is reported with
328 an instance specified by Instance and a caller ID specified by CallerId. If
329 CallerId is NULL, then a caller ID of gEfiCallerIdGuid is used.
330
331 ReportStatusCodeEx()must actively prevent recursion. If ReportStatusCodeEx()
332 is called while processing another any other Report Status Code Library function,
333 then ReportStatusCodeEx() must return EFI_DEVICE_ERROR immediately.
334
335 If ExtendedData is NULL and ExtendedDataSize is not zero, then ASSERT().
336 If ExtendedData is not NULL and ExtendedDataSize is zero, then ASSERT().
337
338 @param Type Status code type.
339 @param Value Status code value.
340 @param Instance Status code instance number.
341 @param CallerId Pointer to a GUID that identifies the caller of this
342 function. If this parameter is NULL, then a caller
343 ID of gEfiCallerIdGuid is used.
344 @param ExtendedDataGuid Pointer to the GUID for the extended data buffer.
345 If this parameter is NULL, then a the status code
346 standard header is filled in with
347 gEfiStatusCodeSpecificDataGuid.
348 @param ExtendedData Pointer to the extended data buffer. This is an
349 optional parameter that may be NULL.
350 @param ExtendedDataSize The size, in bytes, of the extended data buffer.
351
352 @retval EFI_SUCCESS The status code was reported.
353 @retval EFI_OUT_OF_RESOURCES There were not enough resources to allocate
354 the extended data section if it was specified.
355 @retval EFI_UNSUPPORTED Report status code is not supported
356
357 **/
358 EFI_STATUS
359 EFIAPI
360 ReportStatusCodeEx (
361 IN EFI_STATUS_CODE_TYPE Type,
362 IN EFI_STATUS_CODE_VALUE Value,
363 IN UINT32 Instance,
364 IN CONST EFI_GUID *CallerId OPTIONAL,
365 IN CONST EFI_GUID *ExtendedDataGuid OPTIONAL,
366 IN CONST VOID *ExtendedData OPTIONAL,
367 IN UINTN ExtendedDataSize
368 )
369 {
370 ASSERT (!((ExtendedData == NULL) && (ExtendedDataSize != 0)));
371 ASSERT (!((ExtendedData != NULL) && (ExtendedDataSize == 0)));
372 return EFI_UNSUPPORTED;
373 }
374
375
376 /**
377 Returns TRUE if status codes of type EFI_PROGRESS_CODE are enabled
378
379 This function returns TRUE if the REPORT_STATUS_CODE_PROPERTY_PROGRESS_CODE_ENABLED
380 bit of PcdReportStatusCodeProperyMask is set. Otherwise FALSE is returned.
381
382 @retval TRUE The REPORT_STATUS_CODE_PROPERTY_PROGRESS_CODE_ENABLED bit of
383 PcdReportStatusCodeProperyMask is set.
384 @retval FALSE The REPORT_STATUS_CODE_PROPERTY_PROGRESS_CODE_ENABLED bit of
385 PcdReportStatusCodeProperyMask is clear.
386
387 **/
388 BOOLEAN
389 EFIAPI
390 ReportProgressCodeEnabled (
391 VOID
392 )
393 {
394 return ((PcdGet8(PcdReportStatusCodePropertyMask) & REPORT_STATUS_CODE_PROPERTY_PROGRESS_CODE_ENABLED) != 0);
395 }
396
397
398 /**
399 Returns TRUE if status codes of type EFI_ERROR_CODE are enabled
400
401 This function returns TRUE if the REPORT_STATUS_CODE_PROPERTY_ERROR_CODE_ENABLED
402 bit of PcdReportStatusCodeProperyMask is set. Otherwise FALSE is returned.
403
404 @retval TRUE The REPORT_STATUS_CODE_PROPERTY_ERROR_CODE_ENABLED bit of
405 PcdReportStatusCodeProperyMask is set.
406 @retval FALSE The REPORT_STATUS_CODE_PROPERTY_ERROR_CODE_ENABLED bit of
407 PcdReportStatusCodeProperyMask is clear.
408
409 **/
410 BOOLEAN
411 EFIAPI
412 ReportErrorCodeEnabled (
413 VOID
414 )
415 {
416 return ((PcdGet8(PcdReportStatusCodePropertyMask) & REPORT_STATUS_CODE_PROPERTY_ERROR_CODE_ENABLED) != 0);
417 }
418
419
420 /**
421 Returns TRUE if status codes of type EFI_DEBUG_CODE are enabled
422
423 This function returns TRUE if the REPORT_STATUS_CODE_PROPERTY_DEBUG_CODE_ENABLED
424 bit of PcdReportStatusCodeProperyMask is set. Otherwise FALSE is returned.
425
426 @retval TRUE The REPORT_STATUS_CODE_PROPERTY_DEBUG_CODE_ENABLED bit of
427 PcdReportStatusCodeProperyMask is set.
428 @retval FALSE The REPORT_STATUS_CODE_PROPERTY_DEBUG_CODE_ENABLED bit of
429 PcdReportStatusCodeProperyMask is clear.
430
431 **/
432 BOOLEAN
433 EFIAPI
434 ReportDebugCodeEnabled (
435 VOID
436 )
437 {
438 return ((PcdGet8(PcdReportStatusCodePropertyMask) & REPORT_STATUS_CODE_PROPERTY_DEBUG_CODE_ENABLED) != 0);
439 }