MdePkg/Include/Ppi/DeviceRecoveryModule.h

   1 /** @file
   2   This file declares the Device Recovery Module PPI.
   3
   4   The interface of this PPI does the following:
   5     - Reports the number of recovery DXE capsules that exist on the associated device(s)
   6     - Finds the requested firmware binary capsule
   7     - Loads that capsule into memory
   8
   9   A device can be either a group of devices, such as a block device, or an individual device.
  10   The module determines the internal search order, with capsule number 1 as the highest load
  11   priority and number N as the lowest priority.
  12
  13   Copyright (c) 2007 - 2011, Intel Corporation. All rights reserved.<BR>
  14   This program and the accompanying materials
  15   are licensed and made available under the terms and conditions of the BSD License
  16   which accompanies this distribution.  The full text of the license may be found at
  17   http://opensource.org/licenses/bsd-license.php
  18
  19   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  20   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  21
  22   @par Revision Reference:
  23   This PPI is defined in UEFI Platform Initialization Specification 1.2 Volume 1:
  24   Pre-EFI Initalization Core Interface
  25
  26 **/
  27
  28 #ifndef _PEI_DEVICE_RECOVERY_MODULE_PPI_H_
  29 #define _PEI_DEVICE_RECOVERY_MODULE_PPI_H_
  30
  31 #define EFI_PEI_DEVICE_RECOVERY_MODULE_PPI_GUID \
  32   { \
  33     0x0DE2CE25, 0x446A, 0x45a7, {0xBF, 0xC9, 0x37, 0xDA, 0x26, 0x34, 0x4B, 0x37 } \
  34   }
  35
  36 typedef struct _EFI_PEI_DEVICE_RECOVERY_MODULE_PPI EFI_PEI_DEVICE_RECOVERY_MODULE_PPI;
  37
  38 /**
  39   Returns the number of DXE capsules residing on the device.
  40
  41   This function searches for DXE capsules from the associated device and returns
  42   the number and maximum size in bytes of the capsules discovered. Entry 1 is
  43   assumed to be the highest load priority and entry N is assumed to be the lowest
  44   priority.
  45
  46   @param[in]  PeiServices              General-purpose services that are available
  47                                        to every PEIM
  48   @param[in]  This                     Indicates the EFI_PEI_DEVICE_RECOVERY_MODULE_PPI
  49                                        instance.
  50   @param[out] NumberRecoveryCapsules   Pointer to a caller-allocated UINTN. On
  51                                        output, *NumberRecoveryCapsules contains
  52                                        the number of recovery capsule images
  53                                        available for retrieval from this PEIM
  54                                        instance.
  55
  56   @retval EFI_SUCCESS        One or more capsules were discovered.
  57   @retval EFI_DEVICE_ERROR   A device error occurred.
  58   @retval EFI_NOT_FOUND      A recovery DXE capsule cannot be found.
  59
  60 **/
  61 typedef
  62 EFI_STATUS
  63 (EFIAPI *EFI_PEI_DEVICE_GET_NUMBER_RECOVERY_CAPSULE)(
  64   IN  EFI_PEI_SERVICES                    **PeiServices,
  65   IN  EFI_PEI_DEVICE_RECOVERY_MODULE_PPI  *This,
  66   OUT UINTN                               *NumberRecoveryCapsules
  67   );
  68
  69 /**
  70   Returns the size and type of the requested recovery capsule.
  71
  72   This function gets the size and type of the capsule specified by CapsuleInstance.
  73
  74   @param[in]  PeiServices       General-purpose services that are available to every PEIM
  75   @param[in]  This              Indicates the EFI_PEI_DEVICE_RECOVERY_MODULE_PPI
  76                                 instance.
  77   @param[in]  CapsuleInstance   Specifies for which capsule instance to retrieve
  78                                 the information.  This parameter must be between
  79                                 one and the value returned by GetNumberRecoveryCapsules()
  80                                 in NumberRecoveryCapsules.
  81   @param[out] Size              A pointer to a caller-allocated UINTN in which
  82                                 the size of the requested recovery module is
  83                                 returned.
  84   @param[out] CapsuleType       A pointer to a caller-allocated EFI_GUID in which
  85                                 the type of the requested recovery capsule is
  86                                 returned.  The semantic meaning of the value
  87                                 returned is defined by the implementation.
  88
  89   @retval EFI_SUCCESS        One or more capsules were discovered.
  90   @retval EFI_DEVICE_ERROR   A device error occurred.
  91   @retval EFI_NOT_FOUND      A recovery DXE capsule cannot be found.
  92
  93 **/
  94 typedef
  95 EFI_STATUS
  96 (EFIAPI *EFI_PEI_DEVICE_GET_RECOVERY_CAPSULE_INFO)(
  97   IN  EFI_PEI_SERVICES                    **PeiServices,
  98   IN  EFI_PEI_DEVICE_RECOVERY_MODULE_PPI  *This,
  99   IN  UINTN                               CapsuleInstance,
 100   OUT UINTN                               *Size,
 101   OUT EFI_GUID                            *CapsuleType
 102   );
 103
 104 /**
 105   Loads a DXE capsule from some media into memory.
 106
 107   This function, by whatever mechanism, retrieves a DXE capsule from some device
 108   and loads it into memory. Note that the published interface is device neutral.
 109
 110   @param[in]     PeiServices       General-purpose services that are available
 111                                    to every PEIM
 112   @param[in]     This              Indicates the EFI_PEI_DEVICE_RECOVERY_MODULE_PPI
 113                                    instance.
 114   @param[in]     CapsuleInstance   Specifies which capsule instance to retrieve.
 115   @param[out]    Buffer            Specifies a caller-allocated buffer in which
 116                                    the requested recovery capsule will be returned.
 117
 118   @retval EFI_SUCCESS        The capsule was loaded correctly.
 119   @retval EFI_DEVICE_ERROR   A device error occurred.
 120   @retval EFI_NOT_FOUND      A requested recovery DXE capsule cannot be found.
 121
 122 **/
 123 typedef
 124 EFI_STATUS
 125 (EFIAPI *EFI_PEI_DEVICE_LOAD_RECOVERY_CAPSULE)(
 126   IN     EFI_PEI_SERVICES                    **PeiServices,
 127   IN     EFI_PEI_DEVICE_RECOVERY_MODULE_PPI  *This,
 128   IN     UINTN                               CapsuleInstance,
 129   OUT    VOID                                *Buffer
 130   );
 131
 132 ///
 133 /// Presents a standard interface to EFI_PEI_DEVICE_RECOVERY_MODULE_PPI,
 134 /// regardless of the underlying device(s).
 135 ///
 136 struct _EFI_PEI_DEVICE_RECOVERY_MODULE_PPI {
 137   EFI_PEI_DEVICE_GET_NUMBER_RECOVERY_CAPSULE  GetNumberRecoveryCapsules;    ///< Returns the number of DXE capsules residing on the device.
 138   EFI_PEI_DEVICE_GET_RECOVERY_CAPSULE_INFO    GetRecoveryCapsuleInfo;       ///< Returns the size and type of the requested recovery capsule.
 139   EFI_PEI_DEVICE_LOAD_RECOVERY_CAPSULE        LoadRecoveryCapsule;          ///< Loads a DXE capsule from some media into memory.
 140 };
 141
 142 extern EFI_GUID gEfiPeiDeviceRecoveryModulePpiGuid;
 143
 144 #endif  /* _PEI_DEVICE_RECOVERY_MODULE_PPI_H_ */