MdeModulePkg/Universal/Variable/RuntimeDxe/VariableParsing.h

   1 /** @file
   2   Functions in this module are associated with variable parsing operations and
   3   are intended to be usable across variable driver source files.
   4
   5 Copyright (c) 2019, Intel Corporation. All rights reserved.<BR>
   6 SPDX-License-Identifier: BSD-2-Clause-Patent
   7
   8 **/
   9
  10 #ifndef _VARIABLE_PARSING_H_
  11 #define _VARIABLE_PARSING_H_
  12
  13 #include <Guid/ImageAuthentication.h>
  14 #include "Variable.h"
  15
  16 /**
  17
  18   This code checks if variable header is valid or not.
  19
  20   @param[in] Variable           Pointer to the Variable Header.
  21   @param[in] VariableStoreEnd   Pointer to the Variable Store End.
  22
  23   @retval TRUE              Variable header is valid.
  24   @retval FALSE             Variable header is not valid.
  25
  26 **/
  27 BOOLEAN
  28 IsValidVariableHeader (
  29   IN  VARIABLE_HEADER       *Variable,
  30   IN  VARIABLE_HEADER       *VariableStoreEnd
  31   );
  32
  33 /**
  34
  35   This code gets the current status of Variable Store.
  36
  37   @param[in] VarStoreHeader  Pointer to the Variable Store Header.
  38
  39   @retval EfiRaw         Variable store status is raw.
  40   @retval EfiValid       Variable store status is valid.
  41   @retval EfiInvalid     Variable store status is invalid.
  42
  43 **/
  44 VARIABLE_STORE_STATUS
  45 GetVariableStoreStatus (
  46   IN VARIABLE_STORE_HEADER *VarStoreHeader
  47   );
  48
  49 /**
  50   This code gets the size of variable header.
  51
  52   @param[in]  AuthFormat    TRUE indicates authenticated variables are used.
  53                             FALSE indicates authenticated variables are not used.
  54
  55   @return Size of variable header in bytes in type UINTN.
  56
  57 **/
  58 UINTN
  59 GetVariableHeaderSize (
  60   IN  BOOLEAN   AuthFormat
  61   );
  62
  63 /**
  64
  65   This code gets the size of name of variable.
  66
  67   @param[in]  Variable      Pointer to the variable header.
  68   @param[in]  AuthFormat    TRUE indicates authenticated variables are used.
  69                             FALSE indicates authenticated variables are not used.
  70
  71   @return UINTN          Size of variable in bytes.
  72
  73 **/
  74 UINTN
  75 NameSizeOfVariable (
  76   IN  VARIABLE_HEADER   *Variable,
  77   IN  BOOLEAN           AuthFormat
  78   );
  79
  80 /**
  81   This code sets the size of name of variable.
  82
  83   @param[in]  Variable      Pointer to the Variable Header.
  84   @param[in]  NameSize      Name size to set.
  85   @param[in]  AuthFormat    TRUE indicates authenticated variables are used.
  86                             FALSE indicates authenticated variables are not used.
  87
  88 **/
  89 VOID
  90 SetNameSizeOfVariable (
  91   IN VARIABLE_HEADER    *Variable,
  92   IN UINTN              NameSize,
  93   IN BOOLEAN            AuthFormat
  94   );
  95
  96 /**
  97
  98   This code gets the size of variable data.
  99
 100   @param[in]  Variable      Pointer to the Variable Header.
 101   @param[in]  AuthFormat    TRUE indicates authenticated variables are used.
 102                             FALSE indicates authenticated variables are not used.
 103
 104   @return Size of variable in bytes.
 105
 106 **/
 107 UINTN
 108 DataSizeOfVariable (
 109   IN  VARIABLE_HEADER   *Variable,
 110   IN  BOOLEAN           AuthFormat
 111   );
 112
 113 /**
 114   This code sets the size of variable data.
 115
 116   @param[in] Variable   Pointer to the Variable Header.
 117   @param[in] DataSize   Data size to set.
 118   @param[in] AuthFormat TRUE indicates authenticated variables are used.
 119                         FALSE indicates authenticated variables are not used.
 120
 121 **/
 122 VOID
 123 SetDataSizeOfVariable (
 124   IN  VARIABLE_HEADER   *Variable,
 125   IN  UINTN             DataSize,
 126   IN  BOOLEAN           AuthFormat
 127   );
 128
 129 /**
 130
 131   This code gets the pointer to the variable name.
 132
 133   @param[in] Variable     Pointer to the Variable Header.
 134   @param[in] AuthFormat   TRUE indicates authenticated variables are used.
 135                           FALSE indicates authenticated variables are not used.
 136
 137   @return Pointer to Variable Name which is Unicode encoding.
 138
 139 **/
 140 CHAR16 *
 141 GetVariableNamePtr (
 142   IN  VARIABLE_HEADER   *Variable,
 143   IN  BOOLEAN           AuthFormat
 144   );
 145
 146 /**
 147   This code gets the pointer to the variable guid.
 148
 149   @param[in] Variable     Pointer to the Variable Header.
 150   @param[in] AuthFormat   TRUE indicates authenticated variables are used.
 151                           FALSE indicates authenticated variables are not used.
 152
 153   @return A EFI_GUID* pointer to Vendor Guid.
 154
 155 **/
 156 EFI_GUID *
 157 GetVendorGuidPtr (
 158   IN  VARIABLE_HEADER    *Variable,
 159   IN  BOOLEAN            AuthFormat
 160   );
 161
 162 /**
 163
 164   This code gets the pointer to the variable data.
 165
 166   @param[in] Variable     Pointer to the Variable Header.
 167   @param[in] AuthFormat   TRUE indicates authenticated variables are used.
 168                           FALSE indicates authenticated variables are not used.
 169
 170   @return Pointer to Variable Data.
 171
 172 **/
 173 UINT8 *
 174 GetVariableDataPtr (
 175   IN  VARIABLE_HEADER    *Variable,
 176   IN  BOOLEAN            AuthFormat
 177   );
 178
 179 /**
 180   This code gets the variable data offset related to variable header.
 181
 182   @param[in] Variable     Pointer to the Variable Header.
 183   @param[in] AuthFormat   TRUE indicates authenticated variables are used.
 184                           FALSE indicates authenticated variables are not used.
 185
 186   @return Variable Data offset.
 187
 188 **/
 189 UINTN
 190 GetVariableDataOffset (
 191   IN  VARIABLE_HEADER   *Variable,
 192   IN  BOOLEAN           AuthFormat
 193   );
 194
 195 /**
 196
 197   This code gets the pointer to the next variable header.
 198
 199   @param[in] Variable     Pointer to the Variable Header.
 200   @param[in] AuthFormat   TRUE indicates authenticated variables are used.
 201                           FALSE indicates authenticated variables are not used.
 202
 203   @return Pointer to next variable header.
 204
 205 **/
 206 VARIABLE_HEADER *
 207 GetNextVariablePtr (
 208   IN  VARIABLE_HEADER   *Variable,
 209   IN  BOOLEAN           AuthFormat
 210   );
 211
 212 /**
 213
 214   Gets the pointer to the first variable header in given variable store area.
 215
 216   @param[in] VarStoreHeader  Pointer to the Variable Store Header.
 217
 218   @return Pointer to the first variable header.
 219
 220 **/
 221 VARIABLE_HEADER *
 222 GetStartPointer (
 223   IN VARIABLE_STORE_HEADER       *VarStoreHeader
 224   );
 225
 226 /**
 227
 228   Gets the pointer to the end of the variable storage area.
 229
 230   This function gets pointer to the end of the variable storage
 231   area, according to the input variable store header.
 232
 233   @param[in] VarStoreHeader  Pointer to the Variable Store Header.
 234
 235   @return Pointer to the end of the variable storage area.
 236
 237 **/
 238 VARIABLE_HEADER *
 239 GetEndPointer (
 240   IN VARIABLE_STORE_HEADER       *VarStoreHeader
 241   );
 242
 243 /**
 244   Compare two EFI_TIME data.
 245
 246
 247   @param[in] FirstTime       A pointer to the first EFI_TIME data.
 248   @param[in] SecondTime      A pointer to the second EFI_TIME data.
 249
 250   @retval  TRUE              The FirstTime is not later than the SecondTime.
 251   @retval  FALSE             The FirstTime is later than the SecondTime.
 252
 253 **/
 254 BOOLEAN
 255 VariableCompareTimeStampInternal (
 256   IN EFI_TIME               *FirstTime,
 257   IN EFI_TIME               *SecondTime
 258   );
 259
 260 /**
 261   Find the variable in the specified variable store.
 262
 263   @param[in]       VariableName        Name of the variable to be found
 264   @param[in]       VendorGuid          Vendor GUID to be found.
 265   @param[in]       IgnoreRtCheck       Ignore EFI_VARIABLE_RUNTIME_ACCESS attribute
 266                                        check at runtime when searching variable.
 267   @param[in, out]  PtrTrack            Variable Track Pointer structure that contains Variable Information.
 268   @param[in]       AuthFormat          TRUE indicates authenticated variables are used.
 269                                        FALSE indicates authenticated variables are not used.
 270
 271   @retval          EFI_SUCCESS         Variable found successfully
 272   @retval          EFI_NOT_FOUND       Variable not found
 273 **/
 274 EFI_STATUS
 275 FindVariableEx (
 276   IN     CHAR16                  *VariableName,
 277   IN     EFI_GUID                *VendorGuid,
 278   IN     BOOLEAN                 IgnoreRtCheck,
 279   IN OUT VARIABLE_POINTER_TRACK  *PtrTrack,
 280   IN     BOOLEAN                 AuthFormat
 281   );
 282
 283 /**
 284   This code finds the next available variable.
 285
 286   Caution: This function may receive untrusted input.
 287   This function may be invoked in SMM mode. This function will do basic validation, before parse the data.
 288
 289   @param[in]  VariableName      Pointer to variable name.
 290   @param[in]  VendorGuid        Variable Vendor Guid.
 291   @param[in]  VariableStoreList A list of variable stores that should be used to get the next variable.
 292                                 The maximum number of entries is the max value of VARIABLE_STORE_TYPE.
 293   @param[out] VariablePtr       Pointer to variable header address.
 294   @param[in]  AuthFormat        TRUE indicates authenticated variables are used.
 295                                 FALSE indicates authenticated variables are not used.
 296
 297   @retval EFI_SUCCESS           The function completed successfully.
 298   @retval EFI_NOT_FOUND         The next variable was not found.
 299   @retval EFI_INVALID_PARAMETER If VariableName is not an empty string, while VendorGuid is NULL.
 300   @retval EFI_INVALID_PARAMETER The input values of VariableName and VendorGuid are not a name and
 301                                 GUID of an existing variable.
 302
 303 **/
 304 EFI_STATUS
 305 EFIAPI
 306 VariableServiceGetNextVariableInternal (
 307   IN  CHAR16                *VariableName,
 308   IN  EFI_GUID              *VendorGuid,
 309   IN  VARIABLE_STORE_HEADER **VariableStoreList,
 310   OUT VARIABLE_HEADER       **VariablePtr,
 311   IN  BOOLEAN               AuthFormat
 312   );
 313
 314 /**
 315   Routine used to track statistical information about variable usage.
 316   The data is stored in the EFI system table so it can be accessed later.
 317   VariableInfo.efi can dump out the table. Only Boot Services variable
 318   accesses are tracked by this code. The PcdVariableCollectStatistics
 319   build flag controls if this feature is enabled.
 320
 321   A read that hits in the cache will have Read and Cache true for
 322   the transaction. Data is allocated by this routine, but never
 323   freed.
 324
 325   @param[in]      VariableName   Name of the Variable to track.
 326   @param[in]      VendorGuid     Guid of the Variable to track.
 327   @param[in]      Volatile       TRUE if volatile FALSE if non-volatile.
 328   @param[in]      Read           TRUE if GetVariable() was called.
 329   @param[in]      Write          TRUE if SetVariable() was called.
 330   @param[in]      Delete         TRUE if deleted via SetVariable().
 331   @param[in]      Cache          TRUE for a cache hit.
 332   @param[in,out]  VariableInfo   Pointer to a pointer of VARIABLE_INFO_ENTRY structures.
 333
 334 **/
 335 VOID
 336 UpdateVariableInfo (
 337   IN  CHAR16                  *VariableName,
 338   IN  EFI_GUID                *VendorGuid,
 339   IN  BOOLEAN                 Volatile,
 340   IN  BOOLEAN                 Read,
 341   IN  BOOLEAN                 Write,
 342   IN  BOOLEAN                 Delete,
 343   IN  BOOLEAN                 Cache,
 344   IN OUT VARIABLE_INFO_ENTRY  **VariableInfo
 345   );
 346
 347 #endif