1 /** @file 2 Provides services to log status code records. 3 4 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> 5 SPDX-License-Identifier: BSD-2-Clause-Patent 6 7 **/ 8 9 #ifndef __REPORT_STATUS_CODE_LIB_H__ 10 #define __REPORT_STATUS_CODE_LIB_H__ 11 12 #include <Uefi/UefiBaseType.h> 13 #include <Pi/PiStatusCode.h> 14 #include <Protocol/DevicePath.h> 15 16 // 17 // Declare bits for PcdReportStatusCodePropertyMask 18 // 19 #define REPORT_STATUS_CODE_PROPERTY_PROGRESS_CODE_ENABLED 0x00000001 20 #define REPORT_STATUS_CODE_PROPERTY_ERROR_CODE_ENABLED 0x00000002 21 #define REPORT_STATUS_CODE_PROPERTY_DEBUG_CODE_ENABLED 0x00000004 22 23 /** 24 Converts a status code to an 8-bit POST code value. 25 26 Converts the status code specified by CodeType and Value to an 8-bit POST code 27 and returns the 8-bit POST code in PostCode. If CodeType is an 28 EFI_PROGRESS_CODE or CodeType is an EFI_ERROR_CODE, then bits 0..4 of PostCode 29 are set to bits 16..20 of Value, and bits 5..7 of PostCode are set to bits 30 24..26 of Value., and TRUE is returned. Otherwise, FALSE is returned. 31 32 If PostCode is NULL, then ASSERT(). 33 34 @param CodeType The type of status code being converted. 35 @param Value The status code value being converted. 36 @param PostCode A pointer to the 8-bit POST code value to return. 37 38 @retval TRUE The status code specified by CodeType and Value was converted 39 to an 8-bit POST code and returned in PostCode. 40 @retval FALSE The status code specified by CodeType and Value could not be 41 converted to an 8-bit POST code value. 42 43 **/ 44 BOOLEAN 45 EFIAPI 46 CodeTypeToPostCode ( 47 IN EFI_STATUS_CODE_TYPE CodeType, 48 IN EFI_STATUS_CODE_VALUE Value, 49 OUT UINT8 *PostCode 50 ); 51 52 53 /** 54 Extracts ASSERT() information from a status code structure. 55 56 Converts the status code specified by CodeType, Value, and Data to the ASSERT() 57 arguments specified by Filename, Description, and LineNumber. If CodeType is 58 an EFI_ERROR_CODE, and CodeType has a severity of EFI_ERROR_UNRECOVERED, and 59 Value has an operation mask of EFI_SW_EC_ILLEGAL_SOFTWARE_STATE, extract 60 Filename, Description, and LineNumber from the optional data area of the 61 status code buffer specified by Data. The optional data area of Data contains 62 a Null-terminated ASCII string for the FileName, followed by a Null-terminated 63 ASCII string for the Description, followed by a 32-bit LineNumber. If the 64 ASSERT() information could be extracted from Data, then return TRUE. 65 Otherwise, FALSE is returned. 66 67 If Data is NULL, then ASSERT(). 68 If Filename is NULL, then ASSERT(). 69 If Description is NULL, then ASSERT(). 70 If LineNumber is NULL, then ASSERT(). 71 72 @param CodeType The type of status code being converted. 73 @param Value The status code value being converted. 74 @param Data The pointer to status code data buffer. 75 @param Filename The pointer to the source file name that generated the ASSERT(). 76 @param Description The pointer to the description of the ASSERT(). 77 @param LineNumber The pointer to source line number that generated the ASSERT(). 78 79 @retval TRUE The status code specified by CodeType, Value, and Data was 80 converted ASSERT() arguments specified by Filename, Description, 81 and LineNumber. 82 @retval FALSE The status code specified by CodeType, Value, and Data could 83 not be converted to ASSERT() arguments. 84 85 **/ 86 BOOLEAN 87 EFIAPI 88 ReportStatusCodeExtractAssertInfo ( 89 IN EFI_STATUS_CODE_TYPE CodeType, 90 IN EFI_STATUS_CODE_VALUE Value, 91 IN CONST EFI_STATUS_CODE_DATA *Data, 92 OUT CHAR8 **Filename, 93 OUT CHAR8 **Description, 94 OUT UINT32 *LineNumber 95 ); 96 97 98 /** 99 Extracts DEBUG() information from a status code structure. 100 101 Converts the status code specified by Data to the DEBUG() arguments specified 102 by ErrorLevel, Marker, and Format. If type GUID in Data is 103 EFI_STATUS_CODE_DATA_TYPE_DEBUG_GUID, then extract ErrorLevel, Marker, and 104 Format from the optional data area of the status code buffer specified by Data. 105 The optional data area of Data contains a 32-bit ErrorLevel followed by Marker 106 which is 12 UINTN parameters, followed by a Null-terminated ASCII string for 107 the Format. If the DEBUG() information could be extracted from Data, then 108 return TRUE. Otherwise, FALSE is returned. 109 110 If Data is NULL, then ASSERT(). 111 If ErrorLevel is NULL, then ASSERT(). 112 If Marker is NULL, then ASSERT(). 113 If Format is NULL, then ASSERT(). 114 115 @param Data The pointer to status code data buffer. 116 @param ErrorLevel The pointer to error level mask for a debug message. 117 @param Marker The pointer to the variable argument list associated with Format. 118 @param Format The pointer to a Null-terminated ASCII format string of a 119 debug message. 120 121 @retval TRUE The status code specified by Data was converted DEBUG() arguments 122 specified by ErrorLevel, Marker, and Format. 123 @retval FALSE The status code specified by Data could not be converted to 124 DEBUG() arguments. 125 126 **/ 127 BOOLEAN 128 EFIAPI 129 ReportStatusCodeExtractDebugInfo ( 130 IN CONST EFI_STATUS_CODE_DATA *Data, 131 OUT UINT32 *ErrorLevel, 132 OUT BASE_LIST *Marker, 133 OUT CHAR8 **Format 134 ); 135 136 137 /** 138 Reports a status code. 139 140 Reports the status code specified by the parameters Type and Value. Status 141 code also require an instance, caller ID, and extended data. This function 142 passed in a zero instance, NULL extended data, and a caller ID of 143 gEfiCallerIdGuid, which is the GUID for the module. 144 145 ReportStatusCode()must actively prevent recursion. If ReportStatusCode() 146 is called while processing another any other Report Status Code Library function, 147 then ReportStatusCode() must return immediately. 148 149 @param Type Status code type. 150 @param Value Status code value. 151 152 @retval EFI_SUCCESS The status code was reported. 153 @retval EFI_DEVICE_ERROR There status code could not be reported due to a 154 device error. 155 @retval EFI_UNSUPPORTED The report status code is not supported. 156 157 **/ 158 EFI_STATUS 159 EFIAPI 160 ReportStatusCode ( 161 IN EFI_STATUS_CODE_TYPE Type, 162 IN EFI_STATUS_CODE_VALUE Value 163 ); 164 165 166 /** 167 Reports a status code with a Device Path Protocol as the extended data. 168 169 Allocates and fills in the extended data section of a status code with the 170 Device Path Protocol specified by DevicePath. This function is responsible 171 for allocating a buffer large enough for the standard header and the device 172 path. The standard header is filled in with an implementation dependent GUID. 173 The status code is reported with a zero instance and a caller ID of gEfiCallerIdGuid. 174 175 ReportStatusCodeWithDevicePath()must actively prevent recursion. If 176 ReportStatusCodeWithDevicePath() is called while processing another any other 177 Report Status Code Library function, then ReportStatusCodeWithDevicePath() 178 must return EFI_DEVICE_ERROR immediately. 179 180 If DevicePath is NULL, then ASSERT(). 181 182 @param Type The status code type. 183 @param Value The status code value. 184 @param DevicePath The pointer to the Device Path Protocol to be reported. 185 186 @retval EFI_SUCCESS The status code was reported with the extended 187 data specified by DevicePath. 188 @retval EFI_OUT_OF_RESOURCES There were not enough resources to allocate the 189 extended data section. 190 @retval EFI_UNSUPPORTED The report status code is not supported. 191 @retval EFI_DEVICE_ERROR A call to a Report Status Code Library function 192 is already in progress. 193 194 **/ 195 EFI_STATUS 196 EFIAPI 197 ReportStatusCodeWithDevicePath ( 198 IN EFI_STATUS_CODE_TYPE Type, 199 IN EFI_STATUS_CODE_VALUE Value, 200 IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath 201 ); 202 203 204 /** 205 Reports a status code with an extended data buffer. 206 207 Allocates and fills in the extended data section of a status code with the 208 extended data specified by ExtendedData and ExtendedDataSize. ExtendedData 209 is assumed to be one of the data structures specified in Related Definitions. 210 These data structure do not have the standard header, so this function is 211 responsible for allocating a buffer large enough for the standard header and 212 the extended data passed into this function. The standard header is filled 213 in with an implementation dependent GUID. The status code is reported 214 with a zero instance and a caller ID of gEfiCallerIdGuid. 215 216 ReportStatusCodeWithExtendedData()must actively prevent recursion. If 217 ReportStatusCodeWithExtendedData() is called while processing another any other 218 Report Status Code Library function, then ReportStatusCodeWithExtendedData() 219 must return EFI_DEVICE_ERROR immediately. 220 221 If ExtendedData is NULL, then ASSERT(). 222 If ExtendedDataSize is 0, then ASSERT(). 223 224 @param Type The status code type. 225 @param Value The status code value. 226 @param ExtendedData The pointer to the extended data buffer to be reported. 227 @param ExtendedDataSize The size, in bytes, of the extended data buffer to 228 be reported. 229 230 @retval EFI_SUCCESS The status code was reported with the extended 231 data specified by ExtendedData and ExtendedDataSize. 232 @retval EFI_OUT_OF_RESOURCES There were not enough resources to allocate the 233 extended data section. 234 @retval EFI_UNSUPPORTED The report status code is not supported. 235 @retval EFI_DEVICE_ERROR A call to a Report Status Code Library function 236 is already in progress. 237 238 **/ 239 EFI_STATUS 240 EFIAPI 241 ReportStatusCodeWithExtendedData ( 242 IN EFI_STATUS_CODE_TYPE Type, 243 IN EFI_STATUS_CODE_VALUE Value, 244 IN CONST VOID *ExtendedData, 245 IN UINTN ExtendedDataSize 246 ); 247 248 249 /** 250 Reports a status code with full parameters. 251 252 The function reports a status code. If ExtendedData is NULL and ExtendedDataSize 253 is 0, then an extended data buffer is not reported. If ExtendedData is not 254 NULL and ExtendedDataSize is not 0, then an extended data buffer is allocated. 255 ExtendedData is assumed not have the standard status code header, so this function 256 is responsible for allocating a buffer large enough for the standard header and 257 the extended data passed into this function. The standard header is filled in 258 with a GUID specified by ExtendedDataGuid. If ExtendedDataGuid is NULL, then a 259 GUID of gEfiStatusCodeSpecificDataGuid is used. The status code is reported with 260 an instance specified by Instance and a caller ID specified by CallerId. If 261 CallerId is NULL, then a caller ID of gEfiCallerIdGuid is used. 262 263 ReportStatusCodeEx()must actively prevent recursion. If ReportStatusCodeEx() 264 is called while processing another any other Report Status Code Library function, 265 then ReportStatusCodeEx() must return EFI_DEVICE_ERROR immediately. 266 267 If ExtendedData is NULL and ExtendedDataSize is not zero, then ASSERT(). 268 If ExtendedData is not NULL and ExtendedDataSize is zero, then ASSERT(). 269 270 @param Type The status code type. 271 @param Value The status code value. 272 @param Instance The status code instance number. 273 @param CallerId The pointer to a GUID that identifies the caller of this 274 function. If this parameter is NULL, then a caller 275 ID of gEfiCallerIdGuid is used. 276 @param ExtendedDataGuid The pointer to the GUID for the extended data buffer. 277 If this parameter is NULL, then a the status code 278 standard header is filled in with an implementation dependent GUID. 279 @param ExtendedData The pointer to the extended data buffer. This is an 280 optional parameter that may be NULL. 281 @param ExtendedDataSize The size, in bytes, of the extended data buffer. 282 283 @retval EFI_SUCCESS The status code was reported. 284 @retval EFI_OUT_OF_RESOURCES There were not enough resources to allocate 285 the extended data section if it was specified. 286 @retval EFI_UNSUPPORTED The report status code is not supported. 287 @retval EFI_DEVICE_ERROR A call to a Report Status Code Library function 288 is already in progress. 289 290 **/ 291 EFI_STATUS 292 EFIAPI 293 ReportStatusCodeEx ( 294 IN EFI_STATUS_CODE_TYPE Type, 295 IN EFI_STATUS_CODE_VALUE Value, 296 IN UINT32 Instance, 297 IN CONST EFI_GUID *CallerId OPTIONAL, 298 IN CONST EFI_GUID *ExtendedDataGuid OPTIONAL, 299 IN CONST VOID *ExtendedData OPTIONAL, 300 IN UINTN ExtendedDataSize 301 ); 302 303 304 /** 305 Returns TRUE if status codes of type EFI_PROGRESS_CODE are enabled 306 307 This function returns TRUE if the REPORT_STATUS_CODE_PROPERTY_PROGRESS_CODE_ENABLED 308 bit of PcdReportStatusCodeProperyMask is set. Otherwise FALSE is returned. 309 310 @retval TRUE The REPORT_STATUS_CODE_PROPERTY_PROGRESS_CODE_ENABLED bit of 311 PcdReportStatusCodeProperyMask is set. 312 @retval FALSE The REPORT_STATUS_CODE_PROPERTY_PROGRESS_CODE_ENABLED bit of 313 PcdReportStatusCodeProperyMask is clear. 314 315 **/ 316 BOOLEAN 317 EFIAPI 318 ReportProgressCodeEnabled ( 319 VOID 320 ); 321 322 323 /** 324 Returns TRUE if status codes of type EFI_ERROR_CODE are enabled 325 326 This function returns TRUE if the REPORT_STATUS_CODE_PROPERTY_ERROR_CODE_ENABLED 327 bit of PcdReportStatusCodeProperyMask is set. Otherwise, FALSE is returned. 328 329 @retval TRUE The REPORT_STATUS_CODE_PROPERTY_ERROR_CODE_ENABLED bit of 330 PcdReportStatusCodeProperyMask is set. 331 @retval FALSE The REPORT_STATUS_CODE_PROPERTY_ERROR_CODE_ENABLED bit of 332 PcdReportStatusCodeProperyMask is clear. 333 334 **/ 335 BOOLEAN 336 EFIAPI 337 ReportErrorCodeEnabled ( 338 VOID 339 ); 340 341 342 /** 343 Returns TRUE if status codes of type EFI_DEBUG_CODE are enabled 344 345 This function returns TRUE if the REPORT_STATUS_CODE_PROPERTY_DEBUG_CODE_ENABLED 346 bit of PcdReportStatusCodeProperyMask is set. Otherwise FALSE is returned. 347 348 @retval TRUE The REPORT_STATUS_CODE_PROPERTY_DEBUG_CODE_ENABLED bit of 349 PcdReportStatusCodeProperyMask is set. 350 @retval FALSE The REPORT_STATUS_CODE_PROPERTY_DEBUG_CODE_ENABLED bit of 351 PcdReportStatusCodeProperyMask is clear. 352 353 **/ 354 BOOLEAN 355 EFIAPI 356 ReportDebugCodeEnabled ( 357 VOID 358 ); 359 360 361 /** 362 Reports a status code with minimal parameters if the status code type is enabled. 363 364 If the status code type specified by Type is enabled in 365 PcdReportStatusCodeProperyMask, then call ReportStatusCode() passing in Type 366 and Value. 367 368 @param Type The status code type. 369 @param Value The status code value. 370 371 @retval EFI_SUCCESS The status code was reported. 372 @retval EFI_DEVICE_ERROR There status code could not be reported due to a device error. 373 @retval EFI_UNSUPPORTED Report status code is not supported. 374 375 **/ 376 #define REPORT_STATUS_CODE(Type,Value) \ 377 (ReportProgressCodeEnabled() && ((Type) & EFI_STATUS_CODE_TYPE_MASK) == EFI_PROGRESS_CODE) ? \ 378 ReportStatusCode(Type,Value) : \ 379 (ReportErrorCodeEnabled() && ((Type) & EFI_STATUS_CODE_TYPE_MASK) == EFI_ERROR_CODE) ? \ 380 ReportStatusCode(Type,Value) : \ 381 (ReportDebugCodeEnabled() && ((Type) & EFI_STATUS_CODE_TYPE_MASK) == EFI_DEBUG_CODE) ? \ 382 ReportStatusCode(Type,Value) : \ 383 EFI_UNSUPPORTED 384 385 386 /** 387 Reports a status code with a Device Path Protocol as the extended data if the 388 status code type is enabled. 389 390 If the status code type specified by Type is enabled in 391 PcdReportStatusCodeProperyMask, then call ReportStatusCodeWithDevicePath() 392 passing in Type, Value, and DevicePath. 393 394 @param Type The status code type. 395 @param Value The status code value. 396 @param DevicePath Pointer to the Device Path Protocol to be reported. 397 398 @retval EFI_SUCCESS The status code was reported with the extended 399 data specified by DevicePath. 400 @retval EFI_OUT_OF_RESOURCES There were not enough resources to allocate the 401 extended data section. 402 @retval EFI_UNSUPPORTED The report status code is not supported. 403 @retval EFI_DEVICE_ERROR A call to a Report Status Code Library function 404 is already in progress. 405 406 **/ 407 #define REPORT_STATUS_CODE_WITH_DEVICE_PATH(Type,Value,DevicePathParameter) \ 408 (ReportProgressCodeEnabled() && ((Type) & EFI_STATUS_CODE_TYPE_MASK) == EFI_PROGRESS_CODE) ? \ 409 ReportStatusCodeWithDevicePath(Type,Value,DevicePathParameter) : \ 410 (ReportErrorCodeEnabled() && ((Type) & EFI_STATUS_CODE_TYPE_MASK) == EFI_ERROR_CODE) ? \ 411 ReportStatusCodeWithDevicePath(Type,Value,DevicePathParameter) : \ 412 (ReportDebugCodeEnabled() && ((Type) & EFI_STATUS_CODE_TYPE_MASK) == EFI_DEBUG_CODE) ? \ 413 ReportStatusCodeWithDevicePath(Type,Value,DevicePathParameter) : \ 414 EFI_UNSUPPORTED 415 416 417 /** 418 Reports a status code with an extended data buffer if the status code type 419 is enabled. 420 421 If the status code type specified by Type is enabled in 422 PcdReportStatusCodeProperyMask, then call ReportStatusCodeWithExtendedData() 423 passing in Type, Value, ExtendedData, and ExtendedDataSize. 424 425 @param Type The status code type. 426 @param Value The status code value. 427 @param ExtendedData The pointer to the extended data buffer to be reported. 428 @param ExtendedDataSize The size, in bytes, of the extended data buffer to 429 be reported. 430 431 @retval EFI_SUCCESS The status code was reported with the extended 432 data specified by ExtendedData and ExtendedDataSize. 433 @retval EFI_OUT_OF_RESOURCES There were not enough resources to allocate the 434 extended data section. 435 @retval EFI_UNSUPPORTED The report status code is not supported. 436 @retval EFI_DEVICE_ERROR A call to a Report Status Code Library function 437 is already in progress. 438 439 **/ 440 #define REPORT_STATUS_CODE_WITH_EXTENDED_DATA(Type,Value,ExtendedData,ExtendedDataSize) \ 441 (ReportProgressCodeEnabled() && ((Type) & EFI_STATUS_CODE_TYPE_MASK) == EFI_PROGRESS_CODE) ? \ 442 ReportStatusCodeWithExtendedData(Type,Value,ExtendedData,ExtendedDataSize) : \ 443 (ReportErrorCodeEnabled() && ((Type) & EFI_STATUS_CODE_TYPE_MASK) == EFI_ERROR_CODE) ? \ 444 ReportStatusCodeWithExtendedData(Type,Value,ExtendedData,ExtendedDataSize) : \ 445 (ReportDebugCodeEnabled() && ((Type) & EFI_STATUS_CODE_TYPE_MASK) == EFI_DEBUG_CODE) ? \ 446 ReportStatusCodeWithExtendedData(Type,Value,ExtendedData,ExtendedDataSize) : \ 447 EFI_UNSUPPORTED 448 449 /** 450 Reports a status code specifying all parameters if the status code type is enabled. 451 452 If the status code type specified by Type is enabled in 453 PcdReportStatusCodeProperyMask, then call ReportStatusCodeEx() passing in Type, 454 Value, Instance, CallerId, ExtendedDataGuid, ExtendedData, and ExtendedDataSize. 455 456 @param Type The status code type. 457 @param Value The status code value. 458 @param Instance The status code instance number. 459 @param CallerId The pointer to a GUID that identifies the caller of this 460 function. If this parameter is NULL, then a caller 461 ID of gEfiCallerIdGuid is used. 462 @param ExtendedDataGuid Pointer to the GUID for the extended data buffer. 463 If this parameter is NULL, then a the status code 464 standard header is filled in with an implementation dependent GUID. 465 @param ExtendedData Pointer to the extended data buffer. This is an 466 optional parameter that may be NULL. 467 @param ExtendedDataSize The size, in bytes, of the extended data buffer. 468 469 @retval EFI_SUCCESS The status code was reported. 470 @retval EFI_OUT_OF_RESOURCES There were not enough resources to allocate the 471 extended data section if it was specified. 472 @retval EFI_UNSUPPORTED The report status code is not supported. 473 @retval EFI_DEVICE_ERROR A call to a Report Status Code Library function 474 is already in progress. 475 476 **/ 477 #define REPORT_STATUS_CODE_EX(Type,Value,Instance,CallerId,ExtendedDataGuid,ExtendedData,ExtendedDataSize) \ 478 (ReportProgressCodeEnabled() && ((Type) & EFI_STATUS_CODE_TYPE_MASK) == EFI_PROGRESS_CODE) ? \ 479 ReportStatusCodeEx(Type,Value,Instance,CallerId,ExtendedDataGuid,ExtendedData,ExtendedDataSize) : \ 480 (ReportErrorCodeEnabled() && ((Type) & EFI_STATUS_CODE_TYPE_MASK) == EFI_ERROR_CODE) ? \ 481 ReportStatusCodeEx(Type,Value,Instance,CallerId,ExtendedDataGuid,ExtendedData,ExtendedDataSize) : \ 482 (ReportDebugCodeEnabled() && ((Type) & EFI_STATUS_CODE_TYPE_MASK) == EFI_DEBUG_CODE) ? \ 483 ReportStatusCodeEx(Type,Value,Instance,CallerId,ExtendedDataGuid,ExtendedData,ExtendedDataSize) : \ 484 EFI_UNSUPPORTED 485 486 #endif 487