2 Report Status Code Library for DXE Phase.
4 Copyright (c) 2006 - 2011, Intel Corporation. All rights reserved.<BR>
5 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
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.
15 #include <Library/ReportStatusCodeLib.h>
16 #include <Library/BaseLib.h>
17 #include <Library/DebugLib.h>
18 #include <Library/UefiBootServicesTableLib.h>
19 #include <Library/BaseMemoryLib.h>
20 #include <Library/PcdLib.h>
21 #include <Library/DevicePathLib.h>
23 #include <Protocol/StatusCode.h>
25 #include <Guid/StatusCodeDataTypeId.h>
26 #include <Guid/StatusCodeDataTypeDebug.h>
29 // Define the maximum extended data size that is supported when a status code is
30 // reported at TPL_HIGH_LEVEL.
32 #define MAX_EXTENDED_DATA_SIZE 0x200
34 EFI_STATUS_CODE_PROTOCOL
*mReportStatusCodeLibStatusCodeProtocol
= NULL
;
37 Locate the report status code service.
39 Retrieve ReportStatusCode() API of Report Status Code Protocol.
43 InternalGetReportStatusCode (
50 if (mReportStatusCodeLibStatusCodeProtocol
!= NULL
) {
55 // Check gBS just in case ReportStatusCode is called before gBS is initialized.
57 if ((gBS
!= NULL
) && (gBS
->LocateProtocol
!= NULL
) && (gBS
->RaiseTPL
!= NULL
) && (gBS
->RestoreTPL
!= NULL
)) {
59 // Retrieve the current TPL
61 Tpl
= gBS
->RaiseTPL (TPL_HIGH_LEVEL
);
62 gBS
->RestoreTPL (Tpl
);
64 if (Tpl
< TPL_NOTIFY
) {
65 Status
= gBS
->LocateProtocol (&gEfiStatusCodeRuntimeProtocolGuid
, NULL
, (VOID
**) &mReportStatusCodeLibStatusCodeProtocol
);
66 if (EFI_ERROR (Status
)) {
67 mReportStatusCodeLibStatusCodeProtocol
= NULL
;
74 Internal worker function that reports a status code through the Report Status Code Protocol.
76 If status code service is not cached, then this function checks if Report Status Code
77 Protocol is available in system. If Report Status Code Protocol is not available, then
78 EFI_UNSUPPORTED is returned. If Report Status Code Protocol is present, then it is
79 cached in mReportStatusCodeLibStatusCodeProtocol. Finally this function reports status
80 code through the Report Status Code Protocol.
82 @param Type Status code type.
83 @param Value Status code value.
84 @param Instance Status code instance number.
85 @param CallerId Pointer to a GUID that identifies the caller of this
86 function. This is an optional parameter that may be
88 @param Data Pointer to the extended data buffer. This is an
89 optional parameter that may be NULL.
91 @retval EFI_SUCCESS The status code was reported.
92 @retval EFI_UNSUPPORTED Report Status Code Protocol is not available.
93 @retval EFI_UNSUPPORTED Status code type is not supported.
97 InternalReportStatusCode (
98 IN EFI_STATUS_CODE_TYPE Type
,
99 IN EFI_STATUS_CODE_VALUE Value
,
101 IN CONST EFI_GUID
*CallerId OPTIONAL
,
102 IN EFI_STATUS_CODE_DATA
*Data OPTIONAL
105 if ((ReportProgressCodeEnabled() && ((Type
) & EFI_STATUS_CODE_TYPE_MASK
) == EFI_PROGRESS_CODE
) ||
106 (ReportErrorCodeEnabled() && ((Type
) & EFI_STATUS_CODE_TYPE_MASK
) == EFI_ERROR_CODE
) ||
107 (ReportDebugCodeEnabled() && ((Type
) & EFI_STATUS_CODE_TYPE_MASK
) == EFI_DEBUG_CODE
)) {
109 // If mReportStatusCodeLibStatusCodeProtocol is NULL, then check if Report Status Code Protocol is available in system.
111 InternalGetReportStatusCode ();
112 if (mReportStatusCodeLibStatusCodeProtocol
== NULL
) {
113 return EFI_UNSUPPORTED
;
117 // A Report Status Code Protocol is present in system, so pass in all the parameters to the service.
119 return mReportStatusCodeLibStatusCodeProtocol
->ReportStatusCode (Type
, Value
, Instance
, (EFI_GUID
*)CallerId
, Data
);
122 return EFI_UNSUPPORTED
;
127 Converts a status code to an 8-bit POST code value.
129 Converts the status code specified by CodeType and Value to an 8-bit POST code
130 and returns the 8-bit POST code in PostCode. If CodeType is an
131 EFI_PROGRESS_CODE or CodeType is an EFI_ERROR_CODE, then bits 0..4 of PostCode
132 are set to bits 16..20 of Value, and bits 5..7 of PostCode are set to bits
133 24..26 of Value., and TRUE is returned. Otherwise, FALSE is returned.
135 If PostCode is NULL, then ASSERT().
137 @param CodeType The type of status code being converted.
138 @param Value The status code value being converted.
139 @param PostCode A pointer to the 8-bit POST code value to return.
141 @retval TRUE The status code specified by CodeType and Value was converted
142 to an 8-bit POST code and returned in PostCode.
143 @retval FALSE The status code specified by CodeType and Value could not be
144 converted to an 8-bit POST code value.
150 IN EFI_STATUS_CODE_TYPE CodeType
,
151 IN EFI_STATUS_CODE_VALUE Value
,
156 // If PostCode is NULL, then ASSERT()
158 ASSERT (PostCode
!= NULL
);
161 // Convert Value to an 8 bit post code
163 if (((CodeType
& EFI_STATUS_CODE_TYPE_MASK
) == EFI_PROGRESS_CODE
) ||
164 ((CodeType
& EFI_STATUS_CODE_TYPE_MASK
) == EFI_ERROR_CODE
) ) {
165 *PostCode
= (UINT8
) ((((Value
& EFI_STATUS_CODE_CLASS_MASK
) >> 24) << 5) |
166 (((Value
& EFI_STATUS_CODE_SUBCLASS_MASK
) >> 16) & 0x1f));
174 Extracts ASSERT() information from a status code structure.
176 Converts the status code specified by CodeType, Value, and Data to the ASSERT()
177 arguments specified by Filename, Description, and LineNumber. If CodeType is
178 an EFI_ERROR_CODE, and CodeType has a severity of EFI_ERROR_UNRECOVERED, and
179 Value has an operation mask of EFI_SW_EC_ILLEGAL_SOFTWARE_STATE, extract
180 Filename, Description, and LineNumber from the optional data area of the
181 status code buffer specified by Data. The optional data area of Data contains
182 a Null-terminated ASCII string for the FileName, followed by a Null-terminated
183 ASCII string for the Description, followed by a 32-bit LineNumber. If the
184 ASSERT() information could be extracted from Data, then return TRUE.
185 Otherwise, FALSE is returned.
187 If Data is NULL, then ASSERT().
188 If Filename is NULL, then ASSERT().
189 If Description is NULL, then ASSERT().
190 If LineNumber is NULL, then ASSERT().
192 @param CodeType The type of status code being converted.
193 @param Value The status code value being converted.
194 @param Data Pointer to status code data buffer.
195 @param Filename Pointer to the source file name that generated the ASSERT().
196 @param Description Pointer to the description of the ASSERT().
197 @param LineNumber Pointer to source line number that generated the ASSERT().
199 @retval TRUE The status code specified by CodeType, Value, and Data was
200 converted ASSERT() arguments specified by Filename, Description,
202 @retval FALSE The status code specified by CodeType, Value, and Data could
203 not be converted to ASSERT() arguments.
208 ReportStatusCodeExtractAssertInfo (
209 IN EFI_STATUS_CODE_TYPE CodeType
,
210 IN EFI_STATUS_CODE_VALUE Value
,
211 IN CONST EFI_STATUS_CODE_DATA
*Data
,
212 OUT CHAR8
**Filename
,
213 OUT CHAR8
**Description
,
214 OUT UINT32
*LineNumber
217 EFI_DEBUG_ASSERT_DATA
*AssertData
;
219 ASSERT (Data
!= NULL
);
220 ASSERT (Filename
!= NULL
);
221 ASSERT (Description
!= NULL
);
222 ASSERT (LineNumber
!= NULL
);
224 if (((CodeType
& EFI_STATUS_CODE_TYPE_MASK
) == EFI_ERROR_CODE
) &&
225 ((CodeType
& EFI_STATUS_CODE_SEVERITY_MASK
) == EFI_ERROR_UNRECOVERED
) &&
226 ((Value
& EFI_STATUS_CODE_OPERATION_MASK
) == EFI_SW_EC_ILLEGAL_SOFTWARE_STATE
)) {
227 AssertData
= (EFI_DEBUG_ASSERT_DATA
*)(Data
+ 1);
228 *Filename
= (CHAR8
*)(AssertData
+ 1);
229 *Description
= *Filename
+ AsciiStrLen (*Filename
) + 1;
230 *LineNumber
= AssertData
->LineNumber
;
238 Extracts DEBUG() information from a status code structure.
240 Converts the status code specified by Data to the DEBUG() arguments specified
241 by ErrorLevel, Marker, and Format. If type GUID in Data is
242 EFI_STATUS_CODE_DATA_TYPE_DEBUG_GUID, then extract ErrorLevel, Marker, and
243 Format from the optional data area of the status code buffer specified by Data.
244 The optional data area of Data contains a 32-bit ErrorLevel followed by Marker
245 which is 12 UINTN parameters, followed by a Null-terminated ASCII string for
246 the Format. If the DEBUG() information could be extracted from Data, then
247 return TRUE. Otherwise, FALSE is returned.
249 If Data is NULL, then ASSERT().
250 If ErrorLevel is NULL, then ASSERT().
251 If Marker is NULL, then ASSERT().
252 If Format is NULL, then ASSERT().
254 @param Data Pointer to status code data buffer.
255 @param ErrorLevel Pointer to error level mask for a debug message.
256 @param Marker Pointer to the variable argument list associated with Format.
257 @param Format Pointer to a Null-terminated ASCII format string of a
260 @retval TRUE The status code specified by Data was converted DEBUG() arguments
261 specified by ErrorLevel, Marker, and Format.
262 @retval FALSE The status code specified by Data could not be converted to
268 ReportStatusCodeExtractDebugInfo (
269 IN CONST EFI_STATUS_CODE_DATA
*Data
,
270 OUT UINT32
*ErrorLevel
,
271 OUT BASE_LIST
*Marker
,
275 EFI_DEBUG_INFO
*DebugInfo
;
277 ASSERT (Data
!= NULL
);
278 ASSERT (ErrorLevel
!= NULL
);
279 ASSERT (Marker
!= NULL
);
280 ASSERT (Format
!= NULL
);
283 // If the GUID type is not EFI_STATUS_CODE_DATA_TYPE_DEBUG_GUID then return FALSE
285 if (!CompareGuid (&Data
->Type
, &gEfiStatusCodeDataTypeDebugGuid
)) {
290 // Retrieve the debug information from the status code record
292 DebugInfo
= (EFI_DEBUG_INFO
*)(Data
+ 1);
294 *ErrorLevel
= DebugInfo
->ErrorLevel
;
297 // The first 12 * sizeof (UINT64) bytes following EFI_DEBUG_INFO are for variable arguments
298 // of format in DEBUG string. Its address is returned in Marker and has to be 64-bit aligned.
299 // It must be noticed that EFI_DEBUG_INFO follows EFI_STATUS_CODE_DATA, whose size is
300 // 20 bytes. The size of EFI_DEBUG_INFO is 4 bytes, so we can ensure that Marker
301 // returned is 64-bit aligned.
302 // 64-bit aligned is a must, otherwise retrieving 64-bit parameter from BASE_LIST will
303 // cause unalignment exception.
305 *Marker
= (BASE_LIST
) (DebugInfo
+ 1);
306 *Format
= (CHAR8
*)(((UINT64
*)*Marker
) + 12);
313 Reports a status code.
315 Reports the status code specified by the parameters Type and Value. Status
316 code also require an instance, caller ID, and extended data. This function
317 passed in a zero instance, NULL extended data, and a caller ID of
318 gEfiCallerIdGuid, which is the GUID for the module.
320 ReportStatusCode()must actively prevent recusrsion. If ReportStatusCode()
321 is called while processing another any other Report Status Code Library function,
322 then ReportStatusCode() must return immediately.
324 @param Type Status code type.
325 @param Value Status code value.
327 @retval EFI_SUCCESS The status code was reported.
328 @retval EFI_DEVICE_ERROR There status code could not be reported due to a
330 @retval EFI_UNSUPPORTED Report status code is not supported
336 IN EFI_STATUS_CODE_TYPE Type
,
337 IN EFI_STATUS_CODE_VALUE Value
340 return InternalReportStatusCode (Type
, Value
, 0, &gEfiCallerIdGuid
, NULL
);
345 Reports a status code with a Device Path Protocol as the extended data.
347 Allocates and fills in the extended data section of a status code with the
348 Device Path Protocol specified by DevicePath. This function is responsible
349 for allocating a buffer large enough for the standard header and the device
350 path. The standard header is filled in with a GUID of
351 gEfiStatusCodeSpecificDataGuid. The status code is reported with a zero
352 instance and a caller ID of gEfiCallerIdGuid.
354 ReportStatusCodeWithDevicePath()must actively prevent recursion. If
355 ReportStatusCodeWithDevicePath() is called while processing another any other
356 Report Status Code Library function, then ReportStatusCodeWithDevicePath()
357 must return EFI_DEVICE_ERROR immediately.
359 If DevicePath is NULL, then ASSERT().
361 @param Type Status code type.
362 @param Value Status code value.
363 @param DevicePath Pointer to the Device Path Protocol to be reported.
365 @retval EFI_SUCCESS The status code was reported with the extended
366 data specified by DevicePath.
367 @retval EFI_OUT_OF_RESOURCES There were not enough resources to allocate the
368 extended data section.
369 @retval EFI_UNSUPPORTED Report status code is not supported
374 ReportStatusCodeWithDevicePath (
375 IN EFI_STATUS_CODE_TYPE Type
,
376 IN EFI_STATUS_CODE_VALUE Value
,
377 IN CONST EFI_DEVICE_PATH_PROTOCOL
*DevicePath
380 ASSERT (DevicePath
!= NULL
);
381 return ReportStatusCodeWithExtendedData (
385 GetDevicePathSize (DevicePath
)
391 Reports a status code with an extended data buffer.
393 Allocates and fills in the extended data section of a status code with the
394 extended data specified by ExtendedData and ExtendedDataSize. ExtendedData
395 is assumed to be one of the data structures specified in Related Definitions.
396 These data structure do not have the standard header, so this function is
397 responsible for allocating a buffer large enough for the standard header and
398 the extended data passed into this function. The standard header is filled
399 in with a GUID of gEfiStatusCodeSpecificDataGuid. The status code is reported
400 with a zero instance and a caller ID of gEfiCallerIdGuid.
402 ReportStatusCodeWithExtendedData()must actively prevent recursion. If
403 ReportStatusCodeWithExtendedData() is called while processing another any other
404 Report Status Code Library function, then ReportStatusCodeWithExtendedData()
405 must return EFI_DEVICE_ERROR immediately.
407 If ExtendedData is NULL, then ASSERT().
408 If ExtendedDataSize is 0, then ASSERT().
410 @param Type Status code type.
411 @param Value Status code value.
412 @param ExtendedData Pointer to the extended data buffer to be reported.
413 @param ExtendedDataSize The size, in bytes, of the extended data buffer to
416 @retval EFI_SUCCESS The status code was reported with the extended
417 data specified by ExtendedData and ExtendedDataSize.
418 @retval EFI_OUT_OF_RESOURCES There were not enough resources to allocate the
419 extended data section.
420 @retval EFI_UNSUPPORTED Report status code is not supported
425 ReportStatusCodeWithExtendedData (
426 IN EFI_STATUS_CODE_TYPE Type
,
427 IN EFI_STATUS_CODE_VALUE Value
,
428 IN CONST VOID
*ExtendedData
,
429 IN UINTN ExtendedDataSize
432 ASSERT (ExtendedData
!= NULL
);
433 ASSERT (ExtendedDataSize
!= 0);
434 return ReportStatusCodeEx (
447 Reports a status code with full parameters.
449 The function reports a status code. If ExtendedData is NULL and ExtendedDataSize
450 is 0, then an extended data buffer is not reported. If ExtendedData is not
451 NULL and ExtendedDataSize is not 0, then an extended data buffer is allocated.
452 ExtendedData is assumed not have the standard status code header, so this function
453 is responsible for allocating a buffer large enough for the standard header and
454 the extended data passed into this function. The standard header is filled in
455 with a GUID specified by ExtendedDataGuid. If ExtendedDataGuid is NULL, then a
456 GUID of gEfiStatusCodeSpecificDataGuid is used. The status code is reported with
457 an instance specified by Instance and a caller ID specified by CallerId. If
458 CallerId is NULL, then a caller ID of gEfiCallerIdGuid is used.
460 ReportStatusCodeEx()must actively prevent recursion. If
461 ReportStatusCodeEx() is called while processing another any
462 other Report Status Code Library function, then
463 ReportStatusCodeEx() must return EFI_DEVICE_ERROR immediately.
465 If ExtendedData is NULL and ExtendedDataSize is not zero, then ASSERT().
466 If ExtendedData is not NULL and ExtendedDataSize is zero, then ASSERT().
468 @param Type Status code type.
469 @param Value Status code value.
470 @param Instance Status code instance number.
471 @param CallerId Pointer to a GUID that identifies the caller of this
472 function. If this parameter is NULL, then a caller
473 ID of gEfiCallerIdGuid is used.
474 @param ExtendedDataGuid Pointer to the GUID for the extended data buffer.
475 If this parameter is NULL, then a the status code
476 standard header is filled in with
477 gEfiStatusCodeSpecificDataGuid.
478 @param ExtendedData Pointer to the extended data buffer. This is an
479 optional parameter that may be NULL.
480 @param ExtendedDataSize The size, in bytes, of the extended data buffer.
482 @retval EFI_SUCCESS The status code was reported.
483 @retval EFI_OUT_OF_RESOURCES There were not enough resources to allocate
484 the extended data section if it was specified.
485 @retval EFI_UNSUPPORTED Report status code is not supported
491 IN EFI_STATUS_CODE_TYPE Type
,
492 IN EFI_STATUS_CODE_VALUE Value
,
494 IN CONST EFI_GUID
*CallerId OPTIONAL
,
495 IN CONST EFI_GUID
*ExtendedDataGuid OPTIONAL
,
496 IN CONST VOID
*ExtendedData OPTIONAL
,
497 IN UINTN ExtendedDataSize
501 EFI_STATUS_CODE_DATA
*StatusCodeData
;
503 UINT64 Buffer
[(MAX_EXTENDED_DATA_SIZE
/ sizeof (UINT64
)) + 1];
505 ASSERT (!((ExtendedData
== NULL
) && (ExtendedDataSize
!= 0)));
506 ASSERT (!((ExtendedData
!= NULL
) && (ExtendedDataSize
== 0)));
509 (gBS
->AllocatePool
== NULL
) || (gBS
->FreePool
== NULL
) ||
510 (gBS
->RaiseTPL
== NULL
) || (gBS
->RestoreTPL
== NULL
)
512 return EFI_UNSUPPORTED
;
516 // Retrieve the current TPL
518 Tpl
= gBS
->RaiseTPL (TPL_HIGH_LEVEL
);
519 gBS
->RestoreTPL (Tpl
);
521 StatusCodeData
= NULL
;
522 if (Tpl
<= TPL_NOTIFY
) {
524 // Allocate space for the Status Code Header and its buffer
526 gBS
->AllocatePool (EfiBootServicesData
, sizeof (EFI_STATUS_CODE_DATA
) + ExtendedDataSize
, (VOID
**)&StatusCodeData
);
529 if (StatusCodeData
== NULL
) {
531 // If a buffer could not be allocated, then see if the local variable Buffer can be used
533 if (ExtendedDataSize
> (MAX_EXTENDED_DATA_SIZE
- sizeof (EFI_STATUS_CODE_DATA
))) {
535 // The local variable Buffer not large enough to hold the extended data associated
536 // with the status code being reported.
538 DEBUG ((EFI_D_ERROR
, "Status code extended data is too large to be reported!\n"));
539 return EFI_OUT_OF_RESOURCES
;
541 StatusCodeData
= (EFI_STATUS_CODE_DATA
*)Buffer
;
545 // Fill in the extended data header
547 StatusCodeData
->HeaderSize
= (UINT16
) sizeof (EFI_STATUS_CODE_DATA
);
548 StatusCodeData
->Size
= (UINT16
) ExtendedDataSize
;
549 if (ExtendedDataGuid
== NULL
) {
550 ExtendedDataGuid
= &gEfiStatusCodeSpecificDataGuid
;
552 CopyGuid (&StatusCodeData
->Type
, ExtendedDataGuid
);
555 // Fill in the extended data buffer
557 if (ExtendedData
!= NULL
) {
558 CopyMem (StatusCodeData
+ 1, ExtendedData
, ExtendedDataSize
);
562 // Report the status code
564 if (CallerId
== NULL
) {
565 CallerId
= &gEfiCallerIdGuid
;
567 Status
= InternalReportStatusCode (Type
, Value
, Instance
, CallerId
, StatusCodeData
);
570 // Free the allocated buffer
572 if (StatusCodeData
!= (EFI_STATUS_CODE_DATA
*)Buffer
) {
573 gBS
->FreePool (StatusCodeData
);
581 Returns TRUE if status codes of type EFI_PROGRESS_CODE are enabled
583 This function returns TRUE if the REPORT_STATUS_CODE_PROPERTY_PROGRESS_CODE_ENABLED
584 bit of PcdReportStatusCodeProperyMask is set. Otherwise FALSE is returned.
586 @retval TRUE The REPORT_STATUS_CODE_PROPERTY_PROGRESS_CODE_ENABLED bit of
587 PcdReportStatusCodeProperyMask is set.
588 @retval FALSE The REPORT_STATUS_CODE_PROPERTY_PROGRESS_CODE_ENABLED bit of
589 PcdReportStatusCodeProperyMask is clear.
594 ReportProgressCodeEnabled (
598 return (BOOLEAN
) ((PcdGet8 (PcdReportStatusCodePropertyMask
) & REPORT_STATUS_CODE_PROPERTY_PROGRESS_CODE_ENABLED
) != 0);
603 Returns TRUE if status codes of type EFI_ERROR_CODE are enabled
605 This function returns TRUE if the REPORT_STATUS_CODE_PROPERTY_ERROR_CODE_ENABLED
606 bit of PcdReportStatusCodeProperyMask is set. Otherwise FALSE is returned.
608 @retval TRUE The REPORT_STATUS_CODE_PROPERTY_ERROR_CODE_ENABLED bit of
609 PcdReportStatusCodeProperyMask is set.
610 @retval FALSE The REPORT_STATUS_CODE_PROPERTY_ERROR_CODE_ENABLED bit of
611 PcdReportStatusCodeProperyMask is clear.
616 ReportErrorCodeEnabled (
620 return (BOOLEAN
) ((PcdGet8 (PcdReportStatusCodePropertyMask
) & REPORT_STATUS_CODE_PROPERTY_ERROR_CODE_ENABLED
) != 0);
625 Returns TRUE if status codes of type EFI_DEBUG_CODE are enabled
627 This function returns TRUE if the REPORT_STATUS_CODE_PROPERTY_DEBUG_CODE_ENABLED
628 bit of PcdReportStatusCodeProperyMask is set. Otherwise FALSE is returned.
630 @retval TRUE The REPORT_STATUS_CODE_PROPERTY_DEBUG_CODE_ENABLED bit of
631 PcdReportStatusCodeProperyMask is set.
632 @retval FALSE The REPORT_STATUS_CODE_PROPERTY_DEBUG_CODE_ENABLED bit of
633 PcdReportStatusCodeProperyMask is clear.
638 ReportDebugCodeEnabled (
642 return (BOOLEAN
) ((PcdGet8 (PcdReportStatusCodePropertyMask
) & REPORT_STATUS_CODE_PROPERTY_DEBUG_CODE_ENABLED
) != 0);