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) 2015 - 2018, Intel Corporation. All rights reserved.<BR> 6 SPDX-License-Identifier: BSD-2-Clause-Patent 7 8 @par Revision Reference: 9 This PPI is introduced in PI Version 1.4. 10 11 **/ 12 13 #ifndef _PEI_CAPSULE_PPI_H_ 14 #define _PEI_CAPSULE_PPI_H_ 15 16 /// 17 /// Global ID for the EFI_PEI_CAPSULE_PPI. 18 /// 19 #define EFI_PEI_CAPSULE_PPI_GUID \ 20 { \ 21 0x3acf33ee, 0xd892, 0x40f4, {0xa2, 0xfc, 0x38, 0x54, 0xd2, 0xe1, 0x32, 0x3d } \ 22 } 23 24 /// 25 /// Forward declaration for the EFI_PEI_CAPSULE_PPI. 26 /// 27 typedef struct _EFI_PEI_CAPSULE_PPI EFI_PEI_CAPSULE_PPI; 28 29 /// 30 /// Keep name backwards compatible before PI Version 1.4 31 /// 32 typedef struct _EFI_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 mode could 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 *EFI_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 *EFI_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 *EFI_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 _EFI_PEI_CAPSULE_PPI { 118 EFI_PEI_CAPSULE_COALESCE Coalesce; 119 EFI_PEI_CAPSULE_CHECK_CAPSULE_UPDATE CheckCapsuleUpdate; 120 EFI_PEI_CAPSULE_CREATE_STATE CreateState; 121 }; 122 123 /// 124 /// Keep name backwards compatible before PI Version 1.4 125 /// 126 extern EFI_GUID gPeiCapsulePpiGuid; 127 128 extern EFI_GUID gEfiPeiCapsulePpiGuid; 129 130 #endif // #ifndef _PEI_CAPSULE_PPI_H_ 131