MdeModulePkg/Include/Ppi/Capsule.h

   1 /** @file
   2   Defines the APIs that enable PEI services to work with
   3   the underlying capsule capabilities of the platform.
   4
   5 Copyright (c) 2006 - 2010, Intel Corporation. All rights reserved.<BR>
   6
   7 This program and the accompanying materials
   8 are licensed and made available under the terms and conditions
   9 of the BSD License which accompanies this distribution.  The
  10 full text of the license may be found at
  11 http://opensource.org/licenses/bsd-license.php
  12
  13 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  14 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  15
  16 **/
  17
  18 #ifndef _PEI_CAPSULE_PPI_H_
  19 #define _PEI_CAPSULE_PPI_H_
  20
  21 ///
  22 /// Global ID for the PEI_CAPSULE_PPI.
  23 ///
  24 #define PEI_CAPSULE_PPI_GUID \
  25   { \
  26     0x3acf33ee, 0xd892, 0x40f4, {0xa2, 0xfc, 0x38, 0x54, 0xd2, 0xe1, 0x32, 0x3d } \
  27   }
  28
  29 ///
  30 /// Forward declaration for the PEI_CAPSULE_PPI.
  31 ///
  32 typedef struct _PEI_CAPSULE_PPI PEI_CAPSULE_PPI;
  33
  34 /**
  35   Upon determining that there is a capsule to operate on, this service
  36   will use a series of EFI_CAPSULE_BLOCK_DESCRIPTOR entries to determine
  37   the current location of the various capsule fragments and coalesce them
  38   into a contiguous region of system memory.
  39
  40   @param[in]  PeiServices   Pointer to the PEI Services Table.
  41   @param[out] MemoryBase    Pointer to the base of a block of memory into which the buffers will be coalesced.
  42                             On output, this variable will hold the base address
  43                             of a coalesced capsule.
  44   @param[out] MemorySize    Size of the memory region pointed to by MemoryBase.
  45                             On output, this variable will contain the size of the
  46                             coalesced capsule.
  47
  48   @retval EFI_NOT_FOUND          If: boot modecould not be determined, or the
  49                                  boot mode is not flash-update, or the capsule descriptors were not found.
  50   @retval EFI_BUFFER_TOO_SMALL   The capsule could not be coalesced in the provided memory region.
  51   @retval EFI_SUCCESS            There was no capsule, or the capsule was processed successfully.
  52
  53 **/
  54 typedef
  55 EFI_STATUS
  56 (EFIAPI *PEI_CAPSULE_COALESCE)(
  57   IN EFI_PEI_SERVICES  **PeiServices,
  58   IN OUT VOID          **MemoryBase,
  59   IN OUT UINTN         *MemSize
  60   );
  61
  62 /**
  63   Determine if a capsule needs to be processed.
  64   The means by which the presence of a capsule is determined is platform
  65   specific. For example, an implementation could be driven by the presence
  66   of a Capsule EFI Variable containing a list of EFI_CAPSULE_BLOCK_DESCRIPTOR
  67   entries. If present, return EFI_SUCCESS, otherwise return EFI_NOT_FOUND.
  68
  69   @param[in] PeiServices   Pointer to the PEI Services Table.
  70
  71   @retval EFI_SUCCESS     If a capsule is available.
  72   @retval EFI_NOT_FOUND   No capsule detected.
  73
  74 **/
  75 typedef
  76 EFI_STATUS
  77 (EFIAPI *PEI_CAPSULE_CHECK_CAPSULE_UPDATE)(
  78   IN EFI_PEI_SERVICES  **PeiServices
  79   );
  80
  81 /**
  82   The Capsule PPI service that gets called after memory is available. The
  83   capsule coalesce function, which must be called first, returns a base
  84   address and size. Once the memory init PEIM has discovered memory,
  85   it should call this function and pass in the base address and size
  86   returned by the Coalesce() function. Then this function can create a
  87   capsule HOB and return.
  88
  89   @par Notes:
  90     This function assumes it will not be called until the
  91     actual capsule update.
  92
  93   @param[in] PeiServices   Pointer to the PEI Services Table.
  94   @param[in] CapsuleBase   Address returned by the capsule coalesce function.
  95   @param[in] CapsuleSize   Value returned by the capsule coalesce function.
  96
  97   @retval EFI_VOLUME_CORRUPTED   CapsuleBase does not appear to point to a
  98                                  coalesced capsule.
  99   @retval EFI_SUCCESS            Capsule HOB was created successfully.
 100
 101 **/
 102 typedef
 103 EFI_STATUS
 104 (EFIAPI *PEI_CAPSULE_CREATE_STATE)(
 105   IN EFI_PEI_SERVICES  **PeiServices,
 106   IN VOID              *CapsuleBase,
 107   IN UINTN             CapsuleSize
 108   );
 109
 110 ///
 111 /// This PPI provides several services in PEI to work with the underlying
 112 /// capsule capabilities of the platform.  These services include the ability
 113 /// for PEI to coalesce a capsule from a scattered set of memory locations
 114 /// into a contiguous space in memory, detect if a capsule is present for
 115 /// processing, and once memory is available, create a HOB for the capsule.
 116 ///
 117 struct _PEI_CAPSULE_PPI {
 118   PEI_CAPSULE_COALESCE              Coalesce;
 119   PEI_CAPSULE_CHECK_CAPSULE_UPDATE  CheckCapsuleUpdate;
 120   PEI_CAPSULE_CREATE_STATE          CreateState;
 121 };
 122
 123 extern EFI_GUID gPeiCapsulePpiGuid;
 124
 125 #endif // #ifndef _PEI_CAPSULE_PPI_H_