FmpDevicePkg/FmpDxe/VariableSupport.h

   1 /** @file
   2   UEFI variable support functions for Firmware Management Protocol based
   3   firmware updates.
   4
   5   Copyright (c) 2016, Microsoft Corporation. All rights reserved.<BR>
   6   Copyright (c) 2018 - 2019, Intel Corporation. All rights reserved.<BR>
   7
   8   SPDX-License-Identifier: BSD-2-Clause-Patent
   9
  10 **/
  11
  12 #ifndef __VARIABLE_SUPPORT_H__
  13 #define __VARIABLE_SUPPORT_H__
  14
  15 ///
  16 /// Default values for FMP Controller State information
  17 ///
  18 #define DEFAULT_VERSION                 0x1
  19 #define DEFAULT_LOWESTSUPPORTEDVERSION  0x0
  20 #define DEFAULT_LASTATTEMPTSTATUS       0x0
  21 #define DEFAULT_LASTATTEMPTVERSION      0x0
  22
  23 ///
  24 /// Base UEFI Variable names for FMP Controller State information stored in
  25 /// separate variables.
  26 ///
  27 #define VARNAME_VERSION             L"FmpVersion"
  28 #define VARNAME_LSV                 L"FmpLsv"
  29 #define VARNAME_LASTATTEMPTSTATUS   L"LastAttemptStatus"
  30 #define VARNAME_LASTATTEMPTVERSION  L"LastAttemptVersion"
  31
  32 ///
  33 /// Base UEFI Variable name for FMP Controller State information stored in a
  34 /// merged UEFI Variable.  If the separate UEFI Variables above are detected,
  35 /// then they are merged into a single variable and the separate variables are
  36 /// deleted.
  37 ///
  38 #define VARNAME_FMPSTATE  L"FmpState"
  39
  40 ///
  41 /// FMP Controller State structure that is used to store the state of
  42 /// a controller in one combined UEFI Variable.
  43 ///
  44 typedef struct {
  45   BOOLEAN    VersionValid;
  46   BOOLEAN    LsvValid;
  47   BOOLEAN    LastAttemptStatusValid;
  48   BOOLEAN    LastAttemptVersionValid;
  49   UINT32     Version;
  50   UINT32     Lsv;
  51   UINT32     LastAttemptStatus;
  52   UINT32     LastAttemptVersion;
  53 } FMP_CONTROLLER_STATE;
  54
  55 /**
  56   Generate the names of the UEFI Variables used to store state information for
  57   a managed controller.  The UEFI Variables names are a combination of a base
  58   name and an optional hardware instance value as a 16 character hex value.  If
  59   the hardware instance value is 0, then the 16 character hex value is not
  60   included.  These storage for the UEFI Variable names are allocated using the
  61   UEFI Boot Service AllocatePool() and the pointers are stored in the Private.
  62   The following are examples of variable names produces for hardware instance
  63   value 0 and value 0x1234567812345678.
  64
  65     FmpVersion
  66     FmpLsv
  67     LastAttemptStatus
  68     LastAttemptVersion
  69     FmpDxe
  70
  71     FmpVersion1234567812345678
  72     FmpLsv1234567812345678
  73     LastAttemptStatus1234567812345678
  74     LastAttemptVersion1234567812345678
  75     FmpDxe1234567812345678
  76
  77   @param[in,out] Private  Private context structure for the managed controller.
  78 **/
  79 VOID
  80 GenerateFmpVariableNames (
  81   IN OUT FIRMWARE_MANAGEMENT_PRIVATE_DATA  *Private
  82   );
  83
  84 /**
  85   Returns the value used to fill in the Version field of the
  86   EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()
  87   service of the Firmware Management Protocol.  The value is read from a UEFI
  88   variable.  If the UEFI variables does not exist, then a default version value
  89   is returned.
  90
  91   UEFI Variable accessed: GUID = gEfiCallerIdGuid, Name = L"FmpDxe"
  92
  93   @param[in] Private  Private context structure for the managed controller.
  94
  95   @return  The version of the firmware image in the firmware device.
  96 **/
  97 UINT32
  98 GetVersionFromVariable (
  99   IN FIRMWARE_MANAGEMENT_PRIVATE_DATA  *Private
 100   );
 101
 102 /**
 103   Returns the value used to fill in the LowestSupportedVersion field of the
 104   EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()
 105   service of the Firmware Management Protocol.  The value is read from a UEFI
 106   variable.  If the UEFI variables does not exist, then a default lowest
 107   supported version value is returned.
 108
 109   UEFI Variable accessed: GUID = gEfiCallerIdGuid, Name = L"FmpDxe"
 110
 111   @param[in] Private  Private context structure for the managed controller.
 112
 113   @return  The lowest supported version of the firmware image in the firmware
 114            device.
 115 **/
 116 UINT32
 117 GetLowestSupportedVersionFromVariable (
 118   IN FIRMWARE_MANAGEMENT_PRIVATE_DATA  *Private
 119   );
 120
 121 /**
 122   Returns the value used to fill in the LastAttemptStatus field of the
 123   EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()
 124   service of the Firmware Management Protocol.  The value is read from a UEFI
 125   variable.  If the UEFI variables does not exist, then a default last attempt
 126   status value is returned.
 127
 128   UEFI Variable accessed: GUID = gEfiCallerIdGuid, Name = L"FmpDxe"
 129
 130   @param[in] Private  Private context structure for the managed controller.
 131
 132   @return  The last attempt status value for the most recent capsule update.
 133 **/
 134 UINT32
 135 GetLastAttemptStatusFromVariable (
 136   IN FIRMWARE_MANAGEMENT_PRIVATE_DATA  *Private
 137   );
 138
 139 /**
 140   Returns the value used to fill in the LastAttemptVersion field of the
 141   EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()
 142   service of the Firmware Management Protocol.  The value is read from a UEFI
 143   variable.  If the UEFI variables does not exist, then a default last attempt
 144   version value is returned.
 145
 146   UEFI Variable accessed: GUID = gEfiCallerIdGuid, Name = L"FmpDxe"
 147
 148   @param[in] Private  Private context structure for the managed controller.
 149
 150   @return  The last attempt version value for the most recent capsule update.
 151 **/
 152 UINT32
 153 GetLastAttemptVersionFromVariable (
 154   IN FIRMWARE_MANAGEMENT_PRIVATE_DATA  *Private
 155   );
 156
 157 /**
 158   Saves the version current of the firmware image in the firmware device to a
 159   UEFI variable.
 160
 161   UEFI Variable accessed: GUID = gEfiCallerIdGuid, Name = L"FmpDxe"
 162
 163   @param[in] Private  Private context structure for the managed controller.
 164   @param[in] Version  The version of the firmware image in the firmware device.
 165 **/
 166 VOID
 167 SetVersionInVariable (
 168   IN FIRMWARE_MANAGEMENT_PRIVATE_DATA  *Private,
 169   IN UINT32                            Version
 170   );
 171
 172 /**
 173   Saves the lowest supported version current of the firmware image in the
 174   firmware device to a UEFI variable.
 175
 176   UEFI Variable accessed: GUID = gEfiCallerIdGuid, Name = L"FmpDxe"
 177
 178   @param[in] Private                 Private context structure for the managed
 179                                      controller.
 180   @param[in] LowestSupportedVersion  The lowest supported version of the
 181                                      firmware image in the firmware device.
 182 **/
 183 VOID
 184 SetLowestSupportedVersionInVariable (
 185   IN FIRMWARE_MANAGEMENT_PRIVATE_DATA  *Private,
 186   IN UINT32                            LowestSupportedVersion
 187   );
 188
 189 /**
 190   Saves the last attempt status value of the most recent FMP capsule update to a
 191   UEFI variable.
 192
 193   UEFI Variable accessed: GUID = gEfiCallerIdGuid, Name = L"FmpDxe"
 194
 195   @param[in] Private            Private context structure for the managed
 196                                 controller.
 197   @param[in] LastAttemptStatus  The last attempt status of the most recent FMP
 198                                 capsule update.
 199 **/
 200 VOID
 201 SetLastAttemptStatusInVariable (
 202   IN FIRMWARE_MANAGEMENT_PRIVATE_DATA  *Private,
 203   IN UINT32                            LastAttemptStatus
 204   );
 205
 206 /**
 207   Saves the last attempt version value of the most recent FMP capsule update to
 208   a UEFI variable.
 209
 210   UEFI Variable accessed: GUID = gEfiCallerIdGuid, Name = L"FmpDxe"
 211
 212   @param[in] Private             Private context structure for the managed
 213                                  controller.
 214   @param[in] LastAttemptVersion  The last attempt version value of the most
 215                                  recent FMP capsule update.
 216 **/
 217 VOID
 218 SetLastAttemptVersionInVariable (
 219   IN FIRMWARE_MANAGEMENT_PRIVATE_DATA  *Private,
 220   IN UINT32                            LastAttemptVersion
 221   );
 222
 223 /**
 224   Locks all the UEFI Variables that use gEfiCallerIdGuid of the currently
 225   executing module.
 226
 227   @param[in] Private  Private context structure for the managed controller.
 228
 229   @retval  EFI_SUCCESS      All UEFI variables are locked.
 230   @retval  EFI_UNSUPPORTED  Variable Lock Protocol not found.
 231   @retval  Other            One of the UEFI variables could not be locked.
 232 **/
 233 EFI_STATUS
 234 LockAllFmpVariables (
 235   IN FIRMWARE_MANAGEMENT_PRIVATE_DATA  *Private
 236   );
 237
 238 #endif