FmpDevicePkg/Include/Library/FmpDependencyLib.h

   1 /** @file
   2   Fmp Capsule Dependency support functions for Firmware Management Protocol based
   3   firmware updates.
   4
   5   Copyright (c) Microsoft Corporation.<BR>
   6   Copyright (c) 2020, Intel Corporation. All rights reserved.<BR>
   7
   8   SPDX-License-Identifier: BSD-2-Clause-Patent
   9
  10 **/
  11
  12 #ifndef __FMP_DEPENDENCY_LIB__
  13 #define __FMP_DEPENDENCY_LIB__
  14
  15 #include <PiDxe.h>
  16 #include <Protocol/FirmwareManagement.h>
  17
  18 //
  19 // Data struct to store FMP ImageType and version for dependency check.
  20 //
  21 typedef struct {
  22   EFI_GUID    ImageTypeId;
  23   UINT32      Version;
  24 } FMP_DEPEX_CHECK_VERSION_DATA;
  25
  26 /**
  27   Validate the dependency expression and output its size.
  28
  29   @param[in]   Dependencies       Pointer to the EFI_FIRMWARE_IMAGE_DEP.
  30   @param[in]   MaxDepexSize       Max size of the dependency.
  31   @param[out]  DepexSize          Size of dependency.
  32   @param[out]  LastAttemptStatus  An optional pointer to a UINT32 that holds the
  33                                   last attempt status to report back to the caller.
  34                                   If a last attempt status error code is not returned,
  35                                   this function will not modify the LastAttemptStatus value.
  36
  37   @retval TRUE    The dependency expression is valid.
  38   @retval FALSE   The dependency expression is invalid.
  39
  40 **/
  41 BOOLEAN
  42 EFIAPI
  43 ValidateDependency (
  44   IN  EFI_FIRMWARE_IMAGE_DEP  *Dependencies,
  45   IN  UINTN                   MaxDepexSize,
  46   OUT UINT32                  *DepexSize,
  47   OUT UINT32                  *LastAttemptStatus OPTIONAL
  48   );
  49
  50 /**
  51   Get dependency from firmware image.
  52
  53   @param[in]  Image               Points to the firmware image.
  54   @param[in]  ImageSize           Size, in bytes, of the firmware image.
  55   @param[out] DepexSize           Size, in bytes, of the dependency.
  56   @param[out] LastAttemptStatus   An optional pointer to a UINT32 that holds the
  57                                   last attempt status to report back to the caller.
  58                                   If a last attempt status error code is not returned,
  59                                   this function will not modify the LastAttemptStatus value.
  60   @retval  The pointer to dependency.
  61   @retval  Null
  62
  63 **/
  64 EFI_FIRMWARE_IMAGE_DEP *
  65 EFIAPI
  66 GetImageDependency (
  67   IN  EFI_FIRMWARE_IMAGE_AUTHENTICATION  *Image,
  68   IN  UINTN                              ImageSize,
  69   OUT UINT32                             *DepexSize,
  70   OUT UINT32                             *LastAttemptStatus  OPTIONAL
  71   );
  72
  73 /**
  74   Evaluate the dependencies. The caller must search all the Fmp instances and
  75   gather their versions into FmpVersions parameter. If there is PUSH_GUID opcode
  76   in dependency expression with no FmpVersions provided, the dependency will
  77   evaluate to FALSE.
  78
  79   @param[in]   Dependencies       Dependency expressions.
  80   @param[in]   DependenciesSize   Size of Dependency expressions.
  81   @param[in]   FmpVersions        Array of Fmp ImageTypeId and version. This
  82                                   parameter is optional and can be set to NULL.
  83   @param[in]   FmpVersionsCount   Element count of the array. When FmpVersions
  84                                   is NULL, FmpVersionsCount must be 0.
  85   @param[out]  LastAttemptStatus  An optional pointer to a UINT32 that holds the
  86                                   last attempt status to report back to the caller.
  87                                   This function will set the value to LAST_ATTEMPT_STATUS_SUCCESS
  88                                   if an error code is not set.
  89
  90   @retval TRUE    Dependency expressions evaluate to TRUE.
  91   @retval FALSE   Dependency expressions evaluate to FALSE.
  92
  93 **/
  94 BOOLEAN
  95 EFIAPI
  96 EvaluateDependency (
  97   IN  EFI_FIRMWARE_IMAGE_DEP        *Dependencies,
  98   IN  UINTN                         DependenciesSize,
  99   IN  FMP_DEPEX_CHECK_VERSION_DATA  *FmpVersions       OPTIONAL,
 100   IN  UINTN                         FmpVersionsCount,
 101   OUT UINT32                        *LastAttemptStatus OPTIONAL
 102   );
 103
 104 #endif