OvmfPkg/Library/PlatformBmPrintScLib/StatusCodeHandler.c

   1 /** @file
   2   Register a status code handler for printing the Boot Manager's LoadImage()
   3   and StartImage() preparations, and return codes, to the UEFI console.
   4
   5   This feature enables users that are not accustomed to analyzing the firmware
   6   log to glean some information about UEFI boot option processing (loading and
   7   starting).
   8
   9   This library instance filters out (ignores) status codes that are not
  10   reported by the containing firmware module. The intent is to link this
  11   library instance into BdsDxe via PlatformBootManagerLib (which BdsDxe depends
  12   upon), then catch only those status codes that BdsDxe reports (which happens
  13   via UefiBootManagerLib). Status codes reported by other modules (such as
  14   UiApp), via UefiBootManagerLib or otherwise, are meant to be ignored.
  15
  16   Copyright (C) 2019, Red Hat, Inc.
  17
  18   SPDX-License-Identifier: BSD-2-Clause-Patent
  19 **/
  20
  21 #include <Library/BaseMemoryLib.h>
  22 #include <Library/DebugLib.h>
  23 #include <Library/DevicePathLib.h>
  24 #include <Library/MemoryAllocationLib.h>
  25 #include <Library/PcdLib.h>
  26 #include <Library/PrintLib.h>
  27 #include <Library/UefiBootManagerLib.h>
  28 #include <Library/UefiBootServicesTableLib.h>
  29 #include <Library/UefiLib.h>
  30 #include <Library/UefiRuntimeServicesTableLib.h>
  31
  32 #include <Protocol/ReportStatusCodeHandler.h>
  33
  34 #include <Guid/GlobalVariable.h>
  35 #include <Guid/StatusCodeDataTypeId.h>
  36
  37 #include <Pi/PiStatusCode.h>
  38
  39
  40 //
  41 // Convenience variables for the status codes that are relevant for LoadImage()
  42 // and StartImage() preparations and return codes.
  43 //
  44 STATIC EFI_STATUS_CODE_VALUE mLoadPrep;
  45 STATIC EFI_STATUS_CODE_VALUE mLoadFail;
  46 STATIC EFI_STATUS_CODE_VALUE mStartPrep;
  47 STATIC EFI_STATUS_CODE_VALUE mStartFail;
  48
  49
  50 /**
  51   Handle status codes reported through ReportStatusCodeLib /
  52   EFI_STATUS_CODE_PROTOCOL.ReportStatusCode(). Format matching status codes to
  53   the system console.
  54
  55   The highest TPL at which this handler can be registered with
  56   EFI_RSC_HANDLER_PROTOCOL.Register() is TPL_CALLBACK. That's because
  57   HandleStatusCode() uses the UEFI variable services.
  58
  59   The parameter list of this function precisely matches that of
  60   EFI_STATUS_CODE_PROTOCOL.ReportStatusCode().
  61
  62   The return status of this function is ignored by the caller, but the function
  63   still returns sensible codes:
  64
  65   @retval EFI_SUCCESS               The status code has been processed; either
  66                                     as a no-op, due to filtering, or by
  67                                     formatting it to the system console.
  68
  69   @retval EFI_INVALID_PARAMETER     Unknown or malformed contents have been
  70                                     detected in Data.
  71
  72   @retval EFI_INCOMPATIBLE_VERSION  Unexpected UEFI variable behavior has been
  73                                     encountered.
  74
  75   @return                           Error codes propagated from underlying
  76                                     services.
  77 **/
  78 STATIC
  79 EFI_STATUS
  80 EFIAPI
  81 HandleStatusCode (
  82   IN EFI_STATUS_CODE_TYPE  CodeType,
  83   IN EFI_STATUS_CODE_VALUE Value,
  84   IN UINT32                Instance,
  85   IN EFI_GUID              *CallerId,
  86   IN EFI_STATUS_CODE_DATA  *Data
  87   )
  88 {
  89   UINTN                        VariableSize;
  90   UINT16                       BootCurrent;
  91   EFI_STATUS                   Status;
  92   CHAR16                       BootOptionName[ARRAY_SIZE (L"Boot####")];
  93   EFI_BOOT_MANAGER_LOAD_OPTION BmBootOption;
  94   BOOLEAN                      DevPathStringIsDynamic;
  95   CHAR16                       *DevPathString;
  96
  97   //
  98   // Ignore all status codes that are irrelevant for LoadImage() and
  99   // StartImage() preparations and return codes.
 100   //
 101   if (Value != mLoadPrep && Value != mLoadFail &&
 102       Value != mStartPrep && Value != mStartFail) {
 103     return EFI_SUCCESS;
 104   }
 105   //
 106   // Ignore status codes that are not reported by the same containing module.
 107   //
 108   if (!CompareGuid (CallerId, &gEfiCallerIdGuid)) {
 109     return EFI_SUCCESS;
 110   }
 111
 112   //
 113   // Sanity-check Data in case of failure reports.
 114   //
 115   if ((Value == mLoadFail || Value == mStartFail) &&
 116       (Data == NULL ||
 117        Data->HeaderSize != sizeof *Data ||
 118        Data->Size != sizeof (EFI_RETURN_STATUS_EXTENDED_DATA) - sizeof *Data ||
 119        !CompareGuid (&Data->Type, &gEfiStatusCodeSpecificDataGuid))) {
 120     DEBUG ((DEBUG_ERROR, "%a:%a: malformed Data\n", gEfiCallerBaseName,
 121       __FUNCTION__));
 122     return EFI_INVALID_PARAMETER;
 123   }
 124
 125   //
 126   // Get the number of the Boot#### option that the status code applies to.
 127   //
 128   VariableSize = sizeof BootCurrent;
 129   Status = gRT->GetVariable (EFI_BOOT_CURRENT_VARIABLE_NAME,
 130                   &gEfiGlobalVariableGuid, NULL /* Attributes */,
 131                   &VariableSize, &BootCurrent);
 132   if (EFI_ERROR (Status)) {
 133     DEBUG ((DEBUG_ERROR, "%a:%a: failed to get %g:\"%s\": %r\n",
 134       gEfiCallerBaseName, __FUNCTION__, &gEfiGlobalVariableGuid,
 135       EFI_BOOT_CURRENT_VARIABLE_NAME, Status));
 136     return Status;
 137   }
 138   if (VariableSize != sizeof BootCurrent) {
 139     DEBUG ((DEBUG_ERROR, "%a:%a: got %Lu bytes for %g:\"%s\", expected %Lu\n",
 140       gEfiCallerBaseName, __FUNCTION__, (UINT64)VariableSize,
 141       &gEfiGlobalVariableGuid, EFI_BOOT_CURRENT_VARIABLE_NAME,
 142       (UINT64)sizeof BootCurrent));
 143     return EFI_INCOMPATIBLE_VERSION;
 144   }
 145
 146   //
 147   // Get the Boot#### option that the status code applies to.
 148   //
 149   UnicodeSPrint (BootOptionName, sizeof BootOptionName, L"Boot%04x",
 150     BootCurrent);
 151   Status = EfiBootManagerVariableToLoadOption (BootOptionName, &BmBootOption);
 152   if (EFI_ERROR (Status)) {
 153     DEBUG ((DEBUG_ERROR,
 154       "%a:%a: EfiBootManagerVariableToLoadOption(\"%s\"): %r\n",
 155       gEfiCallerBaseName, __FUNCTION__, BootOptionName, Status));
 156     return Status;
 157   }
 158
 159   //
 160   // Format the device path.
 161   //
 162   DevPathStringIsDynamic = TRUE;
 163   DevPathString = ConvertDevicePathToText (
 164                     BmBootOption.FilePath,
 165                     FALSE,                 // DisplayOnly
 166                     FALSE                  // AllowShortcuts
 167                     );
 168   if (DevPathString == NULL) {
 169     DevPathStringIsDynamic = FALSE;
 170     DevPathString = L"<out of memory while formatting device path>";
 171   }
 172
 173   //
 174   // Print the message to the console.
 175   //
 176   if (Value == mLoadPrep || Value == mStartPrep) {
 177     Print (
 178       L"%a: %a %s \"%s\" from %s\n",
 179       gEfiCallerBaseName,
 180       Value == mLoadPrep ? "loading" : "starting",
 181       BootOptionName,
 182       BmBootOption.Description,
 183       DevPathString
 184       );
 185   } else {
 186     Print (
 187       L"%a: failed to %a %s \"%s\" from %s: %r\n",
 188       gEfiCallerBaseName,
 189       Value == mLoadFail ? "load" : "start",
 190       BootOptionName,
 191       BmBootOption.Description,
 192       DevPathString,
 193       ((EFI_RETURN_STATUS_EXTENDED_DATA *)Data)->ReturnStatus
 194       );
 195   }
 196
 197   //
 198   // Done.
 199   //
 200   if (DevPathStringIsDynamic) {
 201     FreePool (DevPathString);
 202   }
 203   EfiBootManagerFreeLoadOption (&BmBootOption);
 204   return EFI_SUCCESS;
 205 }
 206
 207
 208 /**
 209   Unregister HandleStatusCode() at ExitBootServices().
 210
 211   (See EFI_RSC_HANDLER_PROTOCOL in Volume 3 of the Platform Init spec.)
 212
 213   @param[in] Event    Event whose notification function is being invoked.
 214
 215   @param[in] Context  Pointer to EFI_RSC_HANDLER_PROTOCOL, originally looked up
 216                       when HandleStatusCode() was registered.
 217 **/
 218 STATIC
 219 VOID
 220 EFIAPI
 221 UnregisterAtExitBootServices (
 222   IN EFI_EVENT Event,
 223   IN VOID      *Context
 224   )
 225 {
 226   EFI_RSC_HANDLER_PROTOCOL *StatusCodeRouter;
 227
 228   StatusCodeRouter = Context;
 229   StatusCodeRouter->Unregister (HandleStatusCode);
 230 }
 231
 232
 233 /**
 234   Register a status code handler for printing the Boot Manager's LoadImage()
 235   and StartImage() preparations, and return codes, to the UEFI console.
 236
 237   @retval EFI_SUCCESS  The status code handler has been successfully
 238                        registered.
 239
 240   @return              Error codes propagated from boot services and from
 241                        EFI_RSC_HANDLER_PROTOCOL.
 242 **/
 243 EFI_STATUS
 244 EFIAPI
 245 PlatformBmPrintScRegisterHandler (
 246   VOID
 247   )
 248 {
 249   EFI_STATUS               Status;
 250   EFI_RSC_HANDLER_PROTOCOL *StatusCodeRouter;
 251   EFI_EVENT                ExitBootEvent;
 252
 253   Status = gBS->LocateProtocol (&gEfiRscHandlerProtocolGuid,
 254                   NULL /* Registration */, (VOID **)&StatusCodeRouter);
 255   ASSERT_EFI_ERROR (Status);
 256   if (EFI_ERROR (Status)) {
 257     return Status;
 258   }
 259
 260   //
 261   // Set the EFI_STATUS_CODE_VALUE convenience variables.
 262   //
 263   mLoadPrep  = PcdGet32 (PcdProgressCodeOsLoaderLoad);
 264   mLoadFail  = (EFI_SOFTWARE_DXE_BS_DRIVER |
 265                 EFI_SW_DXE_BS_EC_BOOT_OPTION_LOAD_ERROR);
 266   mStartPrep = PcdGet32 (PcdProgressCodeOsLoaderStart);
 267   mStartFail = (EFI_SOFTWARE_DXE_BS_DRIVER |
 268                 EFI_SW_DXE_BS_EC_BOOT_OPTION_FAILED);
 269
 270   //
 271   // Register the handler callback.
 272   //
 273   Status = StatusCodeRouter->Register (HandleStatusCode, TPL_CALLBACK);
 274   if (EFI_ERROR (Status)) {
 275     DEBUG ((DEBUG_ERROR, "%a:%a: failed to register status code handler: %r\n",
 276       gEfiCallerBaseName, __FUNCTION__, Status));
 277     return Status;
 278   }
 279
 280   //
 281   // Status code reporting and routing/handling extend into OS runtime. Since
 282   // we don't want our handler to survive the BDS phase, we have to unregister
 283   // the callback at ExitBootServices(). (See EFI_RSC_HANDLER_PROTOCOL in
 284   // Volume 3 of the Platform Init spec.)
 285   //
 286   Status = gBS->CreateEvent (
 287                   EVT_SIGNAL_EXIT_BOOT_SERVICES, // Type
 288                   TPL_CALLBACK,                  // NotifyTpl
 289                   UnregisterAtExitBootServices,  // NotifyFunction
 290                   StatusCodeRouter,              // NotifyContext
 291                   &ExitBootEvent                 // Event
 292                   );
 293   if (EFI_ERROR (Status)) {
 294     //
 295     // We have to unregister the callback right now, and fail the function.
 296     //
 297     DEBUG ((DEBUG_ERROR, "%a:%a: failed to create ExitBootServices() event: "
 298       "%r\n", gEfiCallerBaseName, __FUNCTION__, Status));
 299     StatusCodeRouter->Unregister (HandleStatusCode);
 300     return Status;
 301   }
 302
 303   return EFI_SUCCESS;
 304 }