MdePkg/Include/Ppi/RecoveryModule.h

   1 /** @file
   2   This file declares Recovery Module PPI.  This PPI is used to find and load the
   3   recovery files.
   4
   5   A module that produces this PPI has many roles and is responsible for the following:
   6     -# Calling the driver recovery PPI EFI_PEI_DEVICE_RECOVERY_MODULE_PPI.
   7        GetNumberRecoveryCapsules() to determine if one or more DXE recovery
   8        entities exist.
   9     -# If no capsules exist, then performing appropriate error handling.
  10     -# Allocating a buffer of MaxRecoveryCapsuleSize as determined by
  11        EFI_PEI_DEVICE_RECOVERY_MODULE_PPI.GetRecoveryCapsuleInfo() or
  12        larger.
  13     -# Determining the policy in which DXE recovery capsules are loaded.
  14     -# Calling the driver recovery PPI EFI_PEI_DEVICE_RECOVERY_MODULE_PPI.
  15        LoadRecoveryCapsule() for capsule number x.
  16     -# If the load failed, performing appropriate error handling.
  17     -# Performing security checks for a loaded DXE recovery capsule.
  18     -# If the security checks failed, then logging the failure in a data HOB.
  19     -# If the security checks failed, then determining the next
  20        EFI_PEI_DEVICE_RECOVERY_MODULE_PPI.LoadRecoveryCapsule()capsule number;
  21        otherwise, go to step 11.
  22     -# If more DXE recovery capsules exist, then go to step 5; otherwise, perform
  23        error handling.
  24     -# Decomposing the capsule loaded by EFI_PEI_DEVICE_RECOVERY_MODULE_PPI.
  25        LoadRecoveryCapsule() into its components. It is assumed that the path
  26        parameters are redundant for recovery and Setup parameters are either
  27        redundant or canned.
  28     -# Invalidating all HOB entries for updateable firmware volume entries.
  29        This invalidation prevents possible errant drivers from being executed.
  30     -# Updating the HOB table with the recovery DXE firmware volume information
  31        generated from the capsule decomposition.
  32     -# Returning to the PEI Dispatcher.
  33
  34   Copyright (c) 2007 - 2018, Intel Corporation. All rights reserved.<BR>
  35   SPDX-License-Identifier: BSD-2-Clause-Patent
  36
  37   @par Revision Reference:
  38   This PPI is defined in UEFI Platform Initialization Specification 1.2 Errata B Volume 1:
  39   Pre-EFI Initialization Core Interface
  40
  41 **/
  42
  43 #ifndef __PEI_RECOVERY_MODULE_PPI_H__
  44 #define __PEI_RECOVERY_MODULE_PPI_H__
  45
  46 #define EFI_PEI_RECOVERY_MODULE_PPI_GUID \
  47   { \
  48     0xFB6D9542, 0x612D, 0x4f45, {0x87, 0x2F, 0x5C, 0xFF, 0x52, 0xE9, 0x3D, 0xCF } \
  49   }
  50
  51 typedef struct _EFI_PEI_RECOVERY_MODULE_PPI EFI_PEI_RECOVERY_MODULE_PPI;
  52
  53 /**
  54   Loads a DXE capsule from some media into memory and updates the HOB table
  55   with the DXE firmware volume information.
  56
  57   @param  PeiServices   General-purpose services that are available to every PEIM.
  58   @param  This          Indicates the EFI_PEI_RECOVERY_MODULE_PPI instance.
  59
  60   @retval EFI_SUCCESS        The capsule was loaded correctly.
  61   @retval EFI_DEVICE_ERROR   A device error occurred.
  62   @retval EFI_NOT_FOUND      A recovery DXE capsule cannot be found.
  63
  64 **/
  65 typedef
  66 EFI_STATUS
  67 (EFIAPI *EFI_PEI_LOAD_RECOVERY_CAPSULE)(
  68   IN EFI_PEI_SERVICES             **PeiServices,
  69   IN EFI_PEI_RECOVERY_MODULE_PPI  *This
  70   );
  71
  72 ///
  73 ///  Finds and loads the recovery files.
  74 ///
  75 struct _EFI_PEI_RECOVERY_MODULE_PPI {
  76   EFI_PEI_LOAD_RECOVERY_CAPSULE    LoadRecoveryCapsule; ///< Loads a DXE binary capsule into memory.
  77 };
  78
  79 extern EFI_GUID  gEfiPeiRecoveryModulePpiGuid;
  80
  81 #endif