[PATCH 2/5] MdeModulePkg: introduce the EDKII_OS_LOADER_DETAIL status code payload

[Laszlo Ersek <lersek@redhat.com>]

The EfiBootManagerBoot() function in UefiBootManagerLib is the central
function for loading and starting Boot#### options. The library is built
into multiple drivers and applications (such as BdsDxe and UiApp),
therefore it is careful not to print anything to the system console. All
progress information is reported via DEBUG messages and progress/status
codes.

Individual platforms can customize how they handle the status codes
reported. However, the codes currently reported about LoadImage() and
StartImage() invocations are simple constants. Even if a platform displays
them on some end-user accessible device -- because end-users are generally
clueless of debug log capturing --, the information contained is
insufficient for even rudimentary bug reporting.

Introduce:

- a new, common debug code that is similar to:

  - PcdProgressCodeOsLoaderLoad             (LoadImage() preparation),
  - EFI_SW_DXE_BS_EC_BOOT_OPTION_LOAD_ERROR (LoadImage() error),
  - PcdProgressCodeOsLoaderStart            (StartImage() preparation),
  - EFI_SW_DXE_BS_EC_BOOT_OPTION_FAILED     (StartImage() error),

  under which more details will be possible to convey about the same set
  of events;

- a new status code payload structure (somewhat similar to
  EDKII_SET_VARIABLE_STATUS from
  "Include/Guid/StatusCodeDataTypeVariable.h"), for defining the wire
  format of said details.

Cc: Ard Biesheuvel <ard.biesheuvel@linaro.org>
Cc: Jordan Justen <jordan.l.justen@intel.com>
Cc: Ruiyu Ni <ruiyu.ni@intel.com>
Cc: Eric Dong <eric.dong@intel.com>
Cc: Star Zeng <star.zeng@intel.com>
Ref: https://bugzilla.redhat.com/show_bug.cgi?id=1515418
Contributed-under: TianoCore Contribution Agreement 1.1
Signed-off-by: Laszlo Ersek <lersek@redhat.com>
---
 MdeModulePkg/MdeModulePkg.dec                                |   9 ++
 MdeModulePkg/MdeModulePkg.uni                                |   7 ++
 MdeModulePkg/Include/Guid/StatusCodeDataTypeOsLoaderDetail.h | 109 ++++++++++++++++++++
 3 files changed, 125 insertions(+)

diff --git a/MdeModulePkg/MdeModulePkg.dec b/MdeModulePkg/MdeModulePkg.dec
index 856d67aceb21..6ba95dedc20d 100644
--- a/MdeModulePkg/MdeModulePkg.dec
+++ b/MdeModulePkg/MdeModulePkg.dec
@@ -383,24 +383,27 @@ [Guids]
   gEdkiiNonDiscoverableAmbaDeviceGuid = { 0x94440339, 0xCC93, 0x4506, {0xB4, 0xC6, 0xEE, 0x8D, 0x0F, 0x4C, 0xA1, 0x91 } }
   gEdkiiNonDiscoverableEhciDeviceGuid = { 0xEAEE5615, 0x0CFD, 0x45FC, {0x87, 0x69, 0xA0, 0xD8, 0x56, 0x95, 0xAF, 0x85 } }
   gEdkiiNonDiscoverableNvmeDeviceGuid = { 0xC5F25542, 0x2A79, 0x4A26, {0x81, 0xBB, 0x4E, 0xA6, 0x32, 0x33, 0xB3, 0x09 } }
   gEdkiiNonDiscoverableOhciDeviceGuid = { 0xB20005B0, 0xBB2D, 0x496F, {0x86, 0x9C, 0x23, 0x0B, 0x44, 0x79, 0xE7, 0xD1 } }
   gEdkiiNonDiscoverableSdhciDeviceGuid = { 0x1DD1D619, 0xF9B8, 0x463E, {0x86, 0x81, 0xD1, 0xDC, 0x7C, 0x07, 0xB7, 0x2C } }
   gEdkiiNonDiscoverableUfsDeviceGuid = { 0x2EA77912, 0x80A8, 0x4947, {0xBE, 0x69, 0xCD, 0xD0, 0x0A, 0xFB, 0xE5, 0x56 } }
   gEdkiiNonDiscoverableUhciDeviceGuid = { 0xA8CDA0A2, 0x4F37, 0x4A1B, {0x8E, 0x10, 0x8E, 0xF3, 0xCC, 0x3B, 0xF3, 0xA8 } }
   gEdkiiNonDiscoverableXhciDeviceGuid = { 0xB1BE0BC5, 0x6C28, 0x442D, {0xAA, 0x37, 0x15, 0x1B, 0x42, 0x57, 0xBD, 0x78 } }
 
   ## Include/Guid/PlatformHasAcpi.h
   gEdkiiPlatformHasAcpiGuid = { 0xf0966b41, 0xc23f, 0x41b9, { 0x96, 0x04, 0x0f, 0xf7, 0xe1, 0x11, 0x96, 0x5a } }
 
+  ## Include/Guid/StatusCodeDataTypeOsLoaderDetail.h
+  gEdkiiStatusCodeDataTypeOsLoaderDetailGuid = { 0xBE4904DC, 0x7EC4, 0x4167, { 0x90, 0x52, 0x38, 0x4D, 0x0B, 0x81, 0x30, 0x0B } }
+
 [Ppis]
   ## Include/Ppi/AtaController.h
   gPeiAtaControllerPpiGuid       = { 0xa45e60d1, 0xc719, 0x44aa, { 0xb0, 0x7a, 0xaa, 0x77, 0x7f, 0x85, 0x90, 0x6d }}
 
   ## Include/Ppi/UsbHostController.h
   gPeiUsbHostControllerPpiGuid   = { 0x652B38A9, 0x77F4, 0x453F, { 0x89, 0xD5, 0xE7, 0xBD, 0xC3, 0x52, 0xFC, 0x53 }}
 
   ## Include/Ppi/Usb2HostController.h
   gPeiUsb2HostControllerPpiGuid  = { 0xfedd6305, 0xe2d7, 0x4ed5, { 0x9f, 0xaa, 0xda, 0x8, 0xe, 0x33, 0x6c, 0x22   }}
 
   ## Include/Ppi/UsbController.h
   gPeiUsbControllerPpiGuid       = { 0x3BC1F6DE, 0x693E, 0x4547, { 0xA3, 0x00, 0x21, 0x82, 0x3C, 0xA4, 0x20, 0xB2 }}
@@ -846,24 +849,30 @@ [PcdsFixedAtBuild]
   ## Progress Code for OS Loader LoadImage start.<BR><BR>
   #  PROGRESS_CODE_OS_LOADER_LOAD   = (EFI_SOFTWARE_DXE_BS_DRIVER | (EFI_OEM_SPECIFIC | 0x00000000)) = 0x03058000<BR>
   # @Prompt Progress Code for OS Loader LoadImage start.
   # @ValidList  0x80000003 | 0x03058000
   gEfiMdeModulePkgTokenSpaceGuid.PcdProgressCodeOsLoaderLoad|0x03058000|UINT32|0x30001030
 
   ## Progress Code for OS Loader StartImage start.<BR><BR>
   #  PROGRESS_CODE_OS_LOADER_START  = (EFI_SOFTWARE_DXE_BS_DRIVER | (EFI_OEM_SPECIFIC | 0x00000001)) = 0x03058001<BR>
   # @Prompt Progress Code for OS Loader StartImage start.
   # @ValidList  0x80000003 | 0x03058001
   gEfiMdeModulePkgTokenSpaceGuid.PcdProgressCodeOsLoaderStart|0x03058001|UINT32|0x30001031
 
+  ## Debug Code for OS Loader Detail.<BR><BR>
+  #  DEBUG_CODE_OS_LOADER_DETAIL = (EFI_SOFTWARE_DXE_BS_DRIVER | (EFI_OEM_SPECIFIC | 0x00000003)) = 0x03058003<BR>
+  # @Prompt Debug Code for OS Loader Detail.
+  # @ValidList  0x80000007 | 0x03058003
+  gEfiMdeModulePkgTokenSpaceGuid.PcdDebugCodeOsLoaderDetail|0x03058003|UINT32|0x3000103B
+
   ## Progress Code for S3 Suspend start.<BR><BR>
   #  PROGRESS_CODE_S3_SUSPEND_START = (EFI_SOFTWARE_SMM_DRIVER | (EFI_OEM_SPECIFIC | 0x00000000))    = 0x03078000<BR>
   # @Prompt Progress Code for S3 Suspend start.
   # @ValidList  0x80000003 | 0x03078000
   gEfiMdeModulePkgTokenSpaceGuid.PcdProgressCodeS3SuspendStart|0x03078000|UINT32|0x30001032
 
   ## Progress Code for S3 Suspend end.<BR><BR>
   #  PROGRESS_CODE_S3_SUSPEND_END   = (EFI_SOFTWARE_SMM_DRIVER | (EFI_OEM_SPECIFIC | 0x00000001))    = 0x03078001<BR>
   # @Prompt Progress Code for S3 Suspend end.
   # @ValidList  0x80000003 | 0x03078001
   gEfiMdeModulePkgTokenSpaceGuid.PcdProgressCodeS3SuspendEnd|0x03078001|UINT32|0x30001033
 
diff --git a/MdeModulePkg/MdeModulePkg.uni b/MdeModulePkg/MdeModulePkg.uni
index 588905a9a1fa..b0872970325c 100644
--- a/MdeModulePkg/MdeModulePkg.uni
+++ b/MdeModulePkg/MdeModulePkg.uni
@@ -35,24 +35,31 @@
 #string STR_gEfiMdeModulePkgTokenSpaceGuid_PcdProgressCodeOsLoaderLoad_PROMPT  #language en-US "Progress Code for OS Loader LoadImage start."
 
 #string STR_gEfiMdeModulePkgTokenSpaceGuid_PcdProgressCodeOsLoaderLoad_HELP  #language en-US "Progress Code for OS Loader LoadImage start.<BR><BR>\n"
                                                                                              "PROGRESS_CODE_OS_LOADER_LOAD   = (EFI_SOFTWARE_DXE_BS_DRIVER | (EFI_OEM_SPECIFIC | 0x00000000)) = 0x03058000<BR>"
 
 #string STR_gEfiMdeModulePkgTokenSpaceGuid_ERR_80000003 #language en-US "Incorrect progress code provided."
 
 #string STR_gEfiMdeModulePkgTokenSpaceGuid_PcdProgressCodeOsLoaderStart_PROMPT  #language en-US "Progress Code for OS Loader StartImage start"
 
 #string STR_gEfiMdeModulePkgTokenSpaceGuid_PcdProgressCodeOsLoaderStart_HELP  #language en-US "Progress Code for OS Loader StartImage start.<BR><BR>\n"
                                                                                               "PROGRESS_CODE_OS_LOADER_START  = (EFI_SOFTWARE_DXE_BS_DRIVER | (EFI_OEM_SPECIFIC | 0x00000001)) = 0x03058001<BR>"
 
+#string STR_gEfiMdeModulePkgTokenSpaceGuid_ERR_80000007 #language en-US "Incorrect debug code provided."
+
+#string STR_gEfiMdeModulePkgTokenSpaceGuid_PcdDebugCodeOsLoaderDetail_PROMPT  #language en-US "Debug Code for OS Loader Detail"
+
+#string STR_gEfiMdeModulePkgTokenSpaceGuid_PcdDebugCodeOsLoaderDetail_HELP  #language en-US "Debug Code for OS Loader Detail.<BR><BR>\n"
+                                                                                            "DEBUG_CODE_OS_LOADER_DETAIL = (EFI_SOFTWARE_DXE_BS_DRIVER | (EFI_OEM_SPECIFIC | 0x00000003)) = 0x03058003<BR>"
+
 #string STR_gEfiMdeModulePkgTokenSpaceGuid_PcdProgressCodeS3SuspendStart_PROMPT  #language en-US "Progress Code for S3 Suspend start"
 
 #string STR_gEfiMdeModulePkgTokenSpaceGuid_PcdProgressCodeS3SuspendStart_HELP  #language en-US "Progress Code for S3 Suspend start.<BR><BR>\n"
                                                                                                "PROGRESS_CODE_S3_SUSPEND_START = (EFI_SOFTWARE_SMM_DRIVER | (EFI_OEM_SPECIFIC | 0x00000000))    = 0x03078000<BR>"
 
 #string STR_gEfiMdeModulePkgTokenSpaceGuid_PcdProgressCodeS3SuspendEnd_PROMPT  #language en-US "Progress Code for S3 Suspend end"
 
 #string STR_gEfiMdeModulePkgTokenSpaceGuid_PcdProgressCodeS3SuspendEnd_HELP  #language en-US "Progress Code for S3 Suspend end.<BR><BR>\n"
                                                                                              "PROGRESS_CODE_S3_SUSPEND_END   = (EFI_SOFTWARE_SMM_DRIVER | (EFI_OEM_SPECIFIC | 0x00000001))    = 0x03078001<BR>"
 
 #string STR_gEfiMdeModulePkgTokenSpaceGuid_PcdErrorCodeSetVariable_PROMPT  #language en-US "Error Code for SetVariable failure"
 
diff --git a/MdeModulePkg/Include/Guid/StatusCodeDataTypeOsLoaderDetail.h b/MdeModulePkg/Include/Guid/StatusCodeDataTypeOsLoaderDetail.h
new file mode 100644
index 000000000000..061ecef0ad21
--- /dev/null
+++ b/MdeModulePkg/Include/Guid/StatusCodeDataTypeOsLoaderDetail.h
@@ -0,0 +1,109 @@
+/** @file
+  Define the GUID, macros, and the data structure for passing details of OS
+  Loading from the UEFI Boot Manager to the Platform, as debug codes.
+
+  Copyright (C) 2017, Red Hat, Inc.
+
+  This program and the accompanying materials are licensed and made available
+  under the terms and conditions of the BSD License that accompanies this
+  distribution. The full text of the license may be found at
+  http://opensource.org/licenses/bsd-license.php.
+
+  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT
+  WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
+**/
+
+#ifndef _STATUS_CODE_DATA_TYPE_OS_LOADER_DETAIL_H_
+#define _STATUS_CODE_DATA_TYPE_OS_LOADER_DETAIL_H_
+
+#include <Protocol/DevicePath.h>
+#include <Uefi/UefiBaseType.h>
+
+//
+// The GUID for EFI_STATUS_CODE_DATA.Type, in order to identify the trailing
+// payload as EDKII_OS_LOADER_DETAIL.
+//
+// The EFI_STATUS_CODE_VALUE under which to report such data is
+// PcdGet32(PcdDebugCodeOsLoaderDetail).
+//
+#define EDKII_STATUS_CODE_DATA_TYPE_OS_LOADER_DETAIL_GUID \
+  {                                                       \
+    0xBE4904DC,                                           \
+    0x7EC4,                                               \
+    0x4167,                                               \
+    { 0x90, 0x52, 0x38, 0x4D, 0x0B, 0x81, 0x30, 0x0B }    \
+  }
+
+//
+// The UEFI Boot Manager is about to call gBS->LoadImage() on the boot option.
+//
+#define EDKII_OS_LOADER_DETAIL_TYPE_LOAD        0x00000000
+//
+// gBS->LoadImage() failed on the boot option.
+//
+#define EDKII_OS_LOADER_DETAIL_TYPE_LOAD_ERROR  0x00000001
+//
+// The UEFI Boot Manager is about to call gBS->StartImage() on the boot option.
+//
+#define EDKII_OS_LOADER_DETAIL_TYPE_START       0x00000002
+//
+// gBS->StartImage() failed on the boot option.
+//
+#define EDKII_OS_LOADER_DETAIL_TYPE_START_ERROR 0x00000003
+
+//
+// Structure for passing details about the above actions and results. Currently
+// a common structure is used for all of them.
+//
+// The structure can be extended compatibly by adding fields at the end. The
+// presence of such fields can be deduced from the containing
+// EFI_STATUS_CODE_DATA.Size field. Incompatible extensions require a new GUID
+// for the containing EFI_STATUS_CODE_DATA.Type field.
+//
+#pragma pack (1)
+typedef struct {
+  //
+  // EDKII_OS_LOADER_DETAIL_TYPE_* values.
+  //
+  UINT32                      Type;
+  //
+  // The number of the Boot#### UEFI variable from which the OS is being
+  // loaded.
+  //
+  UINT16                      BootOptionNumber;
+  //
+  // The size of Description in bytes, including the terminating L'\0'
+  // character. If DescriptionSize is 0, then Description is absent. The type
+  // of this field is UINT16 because all of EDKII_OS_LOADER_DETAIL has to fit
+  // into EFI_STATUS_CODE_DATA.Size, which has type UINT16.
+  //
+  UINT16                      DescriptionSize;
+  //
+  // The size of DevicePath in bytes, including the terminating end node. If
+  // DevicePathSize is 0, then DevicePath is absent. The type of this field is
+  // UINT16 because all of EDKII_OS_LOADER_DETAIL has to fit into
+  // EFI_STATUS_CODE_DATA.Size, which has type UINT16.
+  //
+  //
+  UINT16                      DevicePathSize;
+  //
+  // Used only for EDKII_OS_LOADER_DETAIL_TYPE_*_ERROR, the following field
+  // reports the failure code.
+  //
+  EFI_STATUS                  Status;
+  //
+  // The human-readable description of the boot option for which the OS is
+  // being loaded. Populated from EFI_LOAD_OPTION.Description.
+  //
+  // CHAR16                   Description[];
+  //
+  // Describes the device and location of the OS image being loaded. Populated
+  // from the first element of the packed EFI_LOAD_OPTION.FilePathList array.
+  //
+  // EFI_DEVICE_PATH_PROTOCOL DevicePath;
+} EDKII_OS_LOADER_DETAIL;
+#pragma pack ()
+
+extern EFI_GUID gEdkiiStatusCodeDataTypeOsLoaderDetailGuid;
+
+#endif // _STATUS_CODE_DATA_TYPE_OS_LOADER_DETAIL_H_
-- 
2.14.1.3.gb7cf6e02401b