MdeModulePkg/Universal/Variable/RuntimeDxe/Variable.h

   1 /** @file
   2   The internal header file includes the common header files, defines
   3   internal structure and functions used by Variable modules.
   4
   5 Copyright (c) 2006 - 2019, Intel Corporation. All rights reserved.<BR>
   6 SPDX-License-Identifier: BSD-2-Clause-Patent
   7
   8 **/
   9
  10 #ifndef _VARIABLE_H_
  11 #define _VARIABLE_H_
  12
  13 #include <PiDxe.h>
  14 #include <Protocol/VariableWrite.h>
  15 #include <Protocol/FaultTolerantWrite.h>
  16 #include <Protocol/FirmwareVolumeBlock.h>
  17 #include <Protocol/Variable.h>
  18 #include <Protocol/VariableLock.h>
  19 #include <Protocol/VarCheck.h>
  20 #include <Library/PcdLib.h>
  21 #include <Library/HobLib.h>
  22 #include <Library/UefiDriverEntryPoint.h>
  23 #include <Library/DxeServicesTableLib.h>
  24 #include <Library/UefiRuntimeLib.h>
  25 #include <Library/DebugLib.h>
  26 #include <Library/BaseMemoryLib.h>
  27 #include <Library/UefiBootServicesTableLib.h>
  28 #include <Library/UefiLib.h>
  29 #include <Library/BaseLib.h>
  30 #include <Library/SynchronizationLib.h>
  31 #include <Library/MemoryAllocationLib.h>
  32 #include <Library/AuthVariableLib.h>
  33 #include <Library/VarCheckLib.h>
  34 #include <Guid/GlobalVariable.h>
  35 #include <Guid/EventGroup.h>
  36 #include <Guid/VariableFormat.h>
  37 #include <Guid/SystemNvDataGuid.h>
  38 #include <Guid/FaultTolerantWrite.h>
  39 #include <Guid/VarErrorFlag.h>
  40
  41 #include "PrivilegePolymorphic.h"
  42
  43 #define NV_STORAGE_VARIABLE_BASE (EFI_PHYSICAL_ADDRESS) \
  44                                    (PcdGet64 (PcdFlashNvStorageVariableBase64) != 0 ? \
  45                                     PcdGet64 (PcdFlashNvStorageVariableBase64) : \
  46                                     PcdGet32 (PcdFlashNvStorageVariableBase))
  47
  48 #define EFI_VARIABLE_ATTRIBUTES_MASK (EFI_VARIABLE_NON_VOLATILE | \
  49                                       EFI_VARIABLE_BOOTSERVICE_ACCESS | \
  50                                       EFI_VARIABLE_RUNTIME_ACCESS | \
  51                                       EFI_VARIABLE_HARDWARE_ERROR_RECORD | \
  52                                       EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS | \
  53                                       EFI_VARIABLE_APPEND_WRITE)
  54
  55 ///
  56 /// The size of a 3 character ISO639 language code.
  57 ///
  58 #define ISO_639_2_ENTRY_SIZE    3
  59
  60 typedef enum {
  61   VariableStoreTypeVolatile,
  62   VariableStoreTypeHob,
  63   VariableStoreTypeNv,
  64   VariableStoreTypeMax
  65 } VARIABLE_STORE_TYPE;
  66
  67 typedef struct {
  68   UINT32                  PendingUpdateOffset;
  69   UINT32                  PendingUpdateLength;
  70   VARIABLE_STORE_HEADER   *Store;
  71 } VARIABLE_RUNTIME_CACHE;
  72
  73 typedef struct {
  74   BOOLEAN                 *ReadLock;
  75   BOOLEAN                 *PendingUpdate;
  76   BOOLEAN                 *HobFlushComplete;
  77   VARIABLE_RUNTIME_CACHE  VariableRuntimeHobCache;
  78   VARIABLE_RUNTIME_CACHE  VariableRuntimeNvCache;
  79   VARIABLE_RUNTIME_CACHE  VariableRuntimeVolatileCache;
  80 } VARIABLE_RUNTIME_CACHE_CONTEXT;
  81
  82 typedef struct {
  83   VARIABLE_HEADER *CurrPtr;
  84   //
  85   // If both ADDED and IN_DELETED_TRANSITION variable are present,
  86   // InDeletedTransitionPtr will point to the IN_DELETED_TRANSITION one.
  87   // Otherwise, CurrPtr will point to the ADDED or IN_DELETED_TRANSITION one,
  88   // and InDeletedTransitionPtr will be NULL at the same time.
  89   //
  90   VARIABLE_HEADER *InDeletedTransitionPtr;
  91   VARIABLE_HEADER *EndPtr;
  92   VARIABLE_HEADER *StartPtr;
  93   BOOLEAN         Volatile;
  94 } VARIABLE_POINTER_TRACK;
  95
  96 typedef struct {
  97   EFI_PHYSICAL_ADDRESS            HobVariableBase;
  98   EFI_PHYSICAL_ADDRESS            VolatileVariableBase;
  99   EFI_PHYSICAL_ADDRESS            NonVolatileVariableBase;
 100   VARIABLE_RUNTIME_CACHE_CONTEXT  VariableRuntimeCacheContext;
 101   EFI_LOCK                        VariableServicesLock;
 102   UINT32                          ReentrantState;
 103   BOOLEAN                         AuthFormat;
 104   BOOLEAN                         AuthSupport;
 105   BOOLEAN                         EmuNvMode;
 106 } VARIABLE_GLOBAL;
 107
 108 typedef struct {
 109   VARIABLE_GLOBAL VariableGlobal;
 110   UINTN           VolatileLastVariableOffset;
 111   UINTN           NonVolatileLastVariableOffset;
 112   UINTN           CommonVariableSpace;
 113   UINTN           CommonMaxUserVariableSpace;
 114   UINTN           CommonRuntimeVariableSpace;
 115   UINTN           CommonVariableTotalSize;
 116   UINTN           CommonUserVariableTotalSize;
 117   UINTN           HwErrVariableTotalSize;
 118   UINTN           MaxVariableSize;
 119   UINTN           MaxAuthVariableSize;
 120   UINTN           MaxVolatileVariableSize;
 121   UINTN           ScratchBufferSize;
 122   CHAR8           *PlatformLangCodes;
 123   CHAR8           *LangCodes;
 124   CHAR8           *PlatformLang;
 125   CHAR8           Lang[ISO_639_2_ENTRY_SIZE + 1];
 126   EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *FvbInstance;
 127 } VARIABLE_MODULE_GLOBAL;
 128
 129 /**
 130   Flush the HOB variable to flash.
 131
 132   @param[in] VariableName       Name of variable has been updated or deleted.
 133   @param[in] VendorGuid         Guid of variable has been updated or deleted.
 134
 135 **/
 136 VOID
 137 FlushHobVariableToFlash (
 138   IN CHAR16                     *VariableName,
 139   IN EFI_GUID                   *VendorGuid
 140   );
 141
 142 /**
 143   Writes a buffer to variable storage space, in the working block.
 144
 145   This function writes a buffer to variable storage space into a firmware
 146   volume block device. The destination is specified by the parameter
 147   VariableBase. Fault Tolerant Write protocol is used for writing.
 148
 149   @param  VariableBase   Base address of the variable to write.
 150   @param  VariableBuffer Point to the variable data buffer.
 151
 152   @retval EFI_SUCCESS    The function completed successfully.
 153   @retval EFI_NOT_FOUND  Fail to locate Fault Tolerant Write protocol.
 154   @retval EFI_ABORTED    The function could not complete successfully.
 155
 156 **/
 157 EFI_STATUS
 158 FtwVariableSpace (
 159   IN EFI_PHYSICAL_ADDRESS   VariableBase,
 160   IN VARIABLE_STORE_HEADER  *VariableBuffer
 161   );
 162
 163 /**
 164   Finds variable in storage blocks of volatile and non-volatile storage areas.
 165
 166   This code finds variable in storage blocks of volatile and non-volatile storage areas.
 167   If VariableName is an empty string, then we just return the first
 168   qualified variable without comparing VariableName and VendorGuid.
 169   If IgnoreRtCheck is TRUE, then we ignore the EFI_VARIABLE_RUNTIME_ACCESS attribute check
 170   at runtime when searching existing variable, only VariableName and VendorGuid are compared.
 171   Otherwise, variables without EFI_VARIABLE_RUNTIME_ACCESS are not visible at runtime.
 172
 173   @param[in]   VariableName           Name of the variable to be found.
 174   @param[in]   VendorGuid             Vendor GUID to be found.
 175   @param[out]  PtrTrack               VARIABLE_POINTER_TRACK structure for output,
 176                                       including the range searched and the target position.
 177   @param[in]   Global                 Pointer to VARIABLE_GLOBAL structure, including
 178                                       base of volatile variable storage area, base of
 179                                       NV variable storage area, and a lock.
 180   @param[in]   IgnoreRtCheck          Ignore EFI_VARIABLE_RUNTIME_ACCESS attribute
 181                                       check at runtime when searching variable.
 182
 183   @retval EFI_INVALID_PARAMETER       If VariableName is not an empty string, while
 184                                       VendorGuid is NULL.
 185   @retval EFI_SUCCESS                 Variable successfully found.
 186   @retval EFI_NOT_FOUND               Variable not found
 187
 188 **/
 189 EFI_STATUS
 190 FindVariable (
 191   IN  CHAR16                  *VariableName,
 192   IN  EFI_GUID                *VendorGuid,
 193   OUT VARIABLE_POINTER_TRACK  *PtrTrack,
 194   IN  VARIABLE_GLOBAL         *Global,
 195   IN  BOOLEAN                 IgnoreRtCheck
 196   );
 197
 198 /**
 199   This function is to check if the remaining variable space is enough to set
 200   all Variables from argument list successfully. The purpose of the check
 201   is to keep the consistency of the Variables to be in variable storage.
 202
 203   Note: Variables are assumed to be in same storage.
 204   The set sequence of Variables will be same with the sequence of VariableEntry from argument list,
 205   so follow the argument sequence to check the Variables.
 206
 207   @param[in] Attributes         Variable attributes for Variable entries.
 208   @param[in] Marker             VA_LIST style variable argument list.
 209                                 The variable argument list with type VARIABLE_ENTRY_CONSISTENCY *.
 210                                 A NULL terminates the list. The VariableSize of
 211                                 VARIABLE_ENTRY_CONSISTENCY is the variable data size as input.
 212                                 It will be changed to variable total size as output.
 213
 214   @retval TRUE                  Have enough variable space to set the Variables successfully.
 215   @retval FALSE                 No enough variable space to set the Variables successfully.
 216
 217 **/
 218 BOOLEAN
 219 EFIAPI
 220 CheckRemainingSpaceForConsistencyInternal (
 221   IN UINT32                     Attributes,
 222   IN VA_LIST                    Marker
 223   );
 224
 225 /**
 226   Update the variable region with Variable information. If EFI_VARIABLE_AUTHENTICATED_WRITE_ACCESS is set,
 227   index of associated public key is needed.
 228
 229   @param[in] VariableName       Name of variable.
 230   @param[in] VendorGuid         Guid of variable.
 231   @param[in] Data               Variable data.
 232   @param[in] DataSize           Size of data. 0 means delete.
 233   @param[in] Attributes         Attributes of the variable.
 234   @param[in] KeyIndex           Index of associated public key.
 235   @param[in] MonotonicCount     Value of associated monotonic count.
 236   @param[in, out] Variable      The variable information that is used to keep track of variable usage.
 237
 238   @param[in] TimeStamp          Value of associated TimeStamp.
 239
 240   @retval EFI_SUCCESS           The update operation is success.
 241   @retval EFI_OUT_OF_RESOURCES  Variable region is full, cannot write other data into this region.
 242
 243 **/
 244 EFI_STATUS
 245 UpdateVariable (
 246   IN      CHAR16          *VariableName,
 247   IN      EFI_GUID        *VendorGuid,
 248   IN      VOID            *Data,
 249   IN      UINTN           DataSize,
 250   IN      UINT32          Attributes OPTIONAL,
 251   IN      UINT32          KeyIndex  OPTIONAL,
 252   IN      UINT64          MonotonicCount  OPTIONAL,
 253   IN OUT  VARIABLE_POINTER_TRACK *Variable,
 254   IN      EFI_TIME        *TimeStamp  OPTIONAL
 255   );
 256
 257
 258 /**
 259   Return TRUE if ExitBootServices () has been called.
 260
 261   @retval TRUE If ExitBootServices () has been called.
 262 **/
 263 BOOLEAN
 264 AtRuntime (
 265   VOID
 266   );
 267
 268 /**
 269   Initializes a basic mutual exclusion lock.
 270
 271   This function initializes a basic mutual exclusion lock to the released state
 272   and returns the lock.  Each lock provides mutual exclusion access at its task
 273   priority level.  Since there is no preemption or multiprocessor support in EFI,
 274   acquiring the lock only consists of raising to the locks TPL.
 275   If Lock is NULL, then ASSERT().
 276   If Priority is not a valid TPL value, then ASSERT().
 277
 278   @param  Lock       A pointer to the lock data structure to initialize.
 279   @param  Priority   EFI TPL is associated with the lock.
 280
 281   @return The lock.
 282
 283 **/
 284 EFI_LOCK *
 285 InitializeLock (
 286   IN OUT EFI_LOCK  *Lock,
 287   IN EFI_TPL        Priority
 288   );
 289
 290
 291 /**
 292   Acquires lock only at boot time. Simply returns at runtime.
 293
 294   This is a temperary function that will be removed when
 295   EfiAcquireLock() in UefiLib can handle the call in UEFI
 296   Runtimer driver in RT phase.
 297   It calls EfiAcquireLock() at boot time, and simply returns
 298   at runtime.
 299
 300   @param  Lock         A pointer to the lock to acquire.
 301
 302 **/
 303 VOID
 304 AcquireLockOnlyAtBootTime (
 305   IN EFI_LOCK  *Lock
 306   );
 307
 308
 309 /**
 310   Releases lock only at boot time. Simply returns at runtime.
 311
 312   This is a temperary function which will be removed when
 313   EfiReleaseLock() in UefiLib can handle the call in UEFI
 314   Runtimer driver in RT phase.
 315   It calls EfiReleaseLock() at boot time and simply returns
 316   at runtime.
 317
 318   @param  Lock         A pointer to the lock to release.
 319
 320 **/
 321 VOID
 322 ReleaseLockOnlyAtBootTime (
 323   IN EFI_LOCK  *Lock
 324   );
 325
 326 /**
 327   Retrieve the FVB protocol interface by HANDLE.
 328
 329   @param[in]  FvBlockHandle     The handle of FVB protocol that provides services for
 330                                 reading, writing, and erasing the target block.
 331   @param[out] FvBlock           The interface of FVB protocol
 332
 333   @retval EFI_SUCCESS           The interface information for the specified protocol was returned.
 334   @retval EFI_UNSUPPORTED       The device does not support the FVB protocol.
 335   @retval EFI_INVALID_PARAMETER FvBlockHandle is not a valid EFI_HANDLE or FvBlock is NULL.
 336
 337 **/
 338 EFI_STATUS
 339 GetFvbByHandle (
 340   IN  EFI_HANDLE                          FvBlockHandle,
 341   OUT EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  **FvBlock
 342   );
 343
 344 /**
 345   Function returns an array of handles that support the FVB protocol
 346   in a buffer allocated from pool.
 347
 348   @param[out]  NumberHandles    The number of handles returned in Buffer.
 349   @param[out]  Buffer           A pointer to the buffer to return the requested
 350                                 array of  handles that support FVB protocol.
 351
 352   @retval EFI_SUCCESS           The array of handles was returned in Buffer, and the number of
 353                                 handles in Buffer was returned in NumberHandles.
 354   @retval EFI_NOT_FOUND         No FVB handle was found.
 355   @retval EFI_OUT_OF_RESOURCES  There is not enough pool memory to store the matching results.
 356   @retval EFI_INVALID_PARAMETER NumberHandles is NULL or Buffer is NULL.
 357
 358 **/
 359 EFI_STATUS
 360 GetFvbCountAndBuffer (
 361   OUT UINTN                               *NumberHandles,
 362   OUT EFI_HANDLE                          **Buffer
 363   );
 364
 365 /**
 366   Initializes variable store area for non-volatile and volatile variable.
 367
 368   @retval EFI_SUCCESS           Function successfully executed.
 369   @retval EFI_OUT_OF_RESOURCES  Fail to allocate enough memory resource.
 370
 371 **/
 372 EFI_STATUS
 373 VariableCommonInitialize (
 374   VOID
 375   );
 376
 377 /**
 378   This function reclaims variable storage if free size is below the threshold.
 379
 380 **/
 381 VOID
 382 ReclaimForOS(
 383   VOID
 384   );
 385
 386 /**
 387   Get maximum variable size, covering both non-volatile and volatile variables.
 388
 389   @return Maximum variable size.
 390
 391 **/
 392 UINTN
 393 GetMaxVariableSize (
 394   VOID
 395   );
 396
 397 /**
 398   Initializes variable write service.
 399
 400   @retval EFI_SUCCESS          Function successfully executed.
 401   @retval Others               Fail to initialize the variable service.
 402
 403 **/
 404 EFI_STATUS
 405 VariableWriteServiceInitialize (
 406   VOID
 407   );
 408
 409 /**
 410   Retrieve the SMM Fault Tolerent Write protocol interface.
 411
 412   @param[out] FtwProtocol       The interface of SMM Ftw protocol
 413
 414   @retval EFI_SUCCESS           The SMM SAR protocol instance was found and returned in SarProtocol.
 415   @retval EFI_NOT_FOUND         The SMM SAR protocol instance was not found.
 416   @retval EFI_INVALID_PARAMETER SarProtocol is NULL.
 417
 418 **/
 419 EFI_STATUS
 420 GetFtwProtocol (
 421   OUT VOID                                **FtwProtocol
 422   );
 423
 424 /**
 425   Get the proper fvb handle and/or fvb protocol by the given Flash address.
 426
 427   @param[in] Address        The Flash address.
 428   @param[out] FvbHandle     In output, if it is not NULL, it points to the proper FVB handle.
 429   @param[out] FvbProtocol   In output, if it is not NULL, it points to the proper FVB protocol.
 430
 431 **/
 432 EFI_STATUS
 433 GetFvbInfoByAddress (
 434   IN  EFI_PHYSICAL_ADDRESS                Address,
 435   OUT EFI_HANDLE                          *FvbHandle OPTIONAL,
 436   OUT EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  **FvbProtocol OPTIONAL
 437   );
 438
 439 /**
 440
 441   This code finds variable in storage blocks (Volatile or Non-Volatile).
 442
 443   Caution: This function may receive untrusted input.
 444   This function may be invoked in SMM mode, and datasize and data are external input.
 445   This function will do basic validation, before parse the data.
 446
 447   @param VariableName               Name of Variable to be found.
 448   @param VendorGuid                 Variable vendor GUID.
 449   @param Attributes                 Attribute value of the variable found.
 450   @param DataSize                   Size of Data found. If size is less than the
 451                                     data, this value contains the required size.
 452   @param Data                       The buffer to return the contents of the variable. May be NULL
 453                                     with a zero DataSize in order to determine the size buffer needed.
 454
 455   @return EFI_INVALID_PARAMETER     Invalid parameter.
 456   @return EFI_SUCCESS               Find the specified variable.
 457   @return EFI_NOT_FOUND             Not found.
 458   @return EFI_BUFFER_TO_SMALL       DataSize is too small for the result.
 459
 460 **/
 461 EFI_STATUS
 462 EFIAPI
 463 VariableServiceGetVariable (
 464   IN      CHAR16            *VariableName,
 465   IN      EFI_GUID          *VendorGuid,
 466   OUT     UINT32            *Attributes OPTIONAL,
 467   IN OUT  UINTN             *DataSize,
 468   OUT     VOID              *Data OPTIONAL
 469   );
 470
 471 /**
 472
 473   This code Finds the Next available variable.
 474
 475   Caution: This function may receive untrusted input.
 476   This function may be invoked in SMM mode. This function will do basic validation, before parse the data.
 477
 478   @param VariableNameSize           The size of the VariableName buffer. The size must be large
 479                                     enough to fit input string supplied in VariableName buffer.
 480   @param VariableName               Pointer to variable name.
 481   @param VendorGuid                 Variable Vendor Guid.
 482
 483   @retval EFI_SUCCESS               The function completed successfully.
 484   @retval EFI_NOT_FOUND             The next variable was not found.
 485   @retval EFI_BUFFER_TOO_SMALL      The VariableNameSize is too small for the result.
 486                                     VariableNameSize has been updated with the size needed to complete the request.
 487   @retval EFI_INVALID_PARAMETER     VariableNameSize is NULL.
 488   @retval EFI_INVALID_PARAMETER     VariableName is NULL.
 489   @retval EFI_INVALID_PARAMETER     VendorGuid is NULL.
 490   @retval EFI_INVALID_PARAMETER     The input values of VariableName and VendorGuid are not a name and
 491                                     GUID of an existing variable.
 492   @retval EFI_INVALID_PARAMETER     Null-terminator is not found in the first VariableNameSize bytes of
 493                                     the input VariableName buffer.
 494
 495 **/
 496 EFI_STATUS
 497 EFIAPI
 498 VariableServiceGetNextVariableName (
 499   IN OUT  UINTN             *VariableNameSize,
 500   IN OUT  CHAR16            *VariableName,
 501   IN OUT  EFI_GUID          *VendorGuid
 502   );
 503
 504 /**
 505
 506   This code sets variable in storage blocks (Volatile or Non-Volatile).
 507
 508   Caution: This function may receive untrusted input.
 509   This function may be invoked in SMM mode, and datasize and data are external input.
 510   This function will do basic validation, before parse the data.
 511   This function will parse the authentication carefully to avoid security issues, like
 512   buffer overflow, integer overflow.
 513   This function will check attribute carefully to avoid authentication bypass.
 514
 515   @param VariableName                     Name of Variable to be found.
 516   @param VendorGuid                       Variable vendor GUID.
 517   @param Attributes                       Attribute value of the variable found
 518   @param DataSize                         Size of Data found. If size is less than the
 519                                           data, this value contains the required size.
 520   @param Data                             Data pointer.
 521
 522   @return EFI_INVALID_PARAMETER           Invalid parameter.
 523   @return EFI_SUCCESS                     Set successfully.
 524   @return EFI_OUT_OF_RESOURCES            Resource not enough to set variable.
 525   @return EFI_NOT_FOUND                   Not found.
 526   @return EFI_WRITE_PROTECTED             Variable is read-only.
 527
 528 **/
 529 EFI_STATUS
 530 EFIAPI
 531 VariableServiceSetVariable (
 532   IN CHAR16                  *VariableName,
 533   IN EFI_GUID                *VendorGuid,
 534   IN UINT32                  Attributes,
 535   IN UINTN                   DataSize,
 536   IN VOID                    *Data
 537   );
 538
 539 /**
 540
 541   This code returns information about the EFI variables.
 542
 543   Caution: This function may receive untrusted input.
 544   This function may be invoked in SMM mode. This function will do basic validation, before parse the data.
 545
 546   @param Attributes                     Attributes bitmask to specify the type of variables
 547                                         on which to return information.
 548   @param MaximumVariableStorageSize     Pointer to the maximum size of the storage space available
 549                                         for the EFI variables associated with the attributes specified.
 550   @param RemainingVariableStorageSize   Pointer to the remaining size of the storage space available
 551                                         for EFI variables associated with the attributes specified.
 552   @param MaximumVariableSize            Pointer to the maximum size of an individual EFI variables
 553                                         associated with the attributes specified.
 554
 555   @return EFI_SUCCESS                   Query successfully.
 556
 557 **/
 558 EFI_STATUS
 559 EFIAPI
 560 VariableServiceQueryVariableInfoInternal (
 561   IN  UINT32                 Attributes,
 562   OUT UINT64                 *MaximumVariableStorageSize,
 563   OUT UINT64                 *RemainingVariableStorageSize,
 564   OUT UINT64                 *MaximumVariableSize
 565   );
 566
 567 /**
 568
 569   This code returns information about the EFI variables.
 570
 571   Caution: This function may receive untrusted input.
 572   This function may be invoked in SMM mode. This function will do basic validation, before parse the data.
 573
 574   @param Attributes                     Attributes bitmask to specify the type of variables
 575                                         on which to return information.
 576   @param MaximumVariableStorageSize     Pointer to the maximum size of the storage space available
 577                                         for the EFI variables associated with the attributes specified.
 578   @param RemainingVariableStorageSize   Pointer to the remaining size of the storage space available
 579                                         for EFI variables associated with the attributes specified.
 580   @param MaximumVariableSize            Pointer to the maximum size of an individual EFI variables
 581                                         associated with the attributes specified.
 582
 583   @return EFI_INVALID_PARAMETER         An invalid combination of attribute bits was supplied.
 584   @return EFI_SUCCESS                   Query successfully.
 585   @return EFI_UNSUPPORTED               The attribute is not supported on this platform.
 586
 587 **/
 588 EFI_STATUS
 589 EFIAPI
 590 VariableServiceQueryVariableInfo (
 591   IN  UINT32                 Attributes,
 592   OUT UINT64                 *MaximumVariableStorageSize,
 593   OUT UINT64                 *RemainingVariableStorageSize,
 594   OUT UINT64                 *MaximumVariableSize
 595   );
 596
 597 /**
 598   Mark a variable that will become read-only after leaving the DXE phase of execution.
 599
 600   @param[in] This          The VARIABLE_LOCK_PROTOCOL instance.
 601   @param[in] VariableName  A pointer to the variable name that will be made read-only subsequently.
 602   @param[in] VendorGuid    A pointer to the vendor GUID that will be made read-only subsequently.
 603
 604   @retval EFI_SUCCESS           The variable specified by the VariableName and the VendorGuid was marked
 605                                 as pending to be read-only.
 606   @retval EFI_INVALID_PARAMETER VariableName or VendorGuid is NULL.
 607                                 Or VariableName is an empty string.
 608   @retval EFI_ACCESS_DENIED     EFI_END_OF_DXE_EVENT_GROUP_GUID or EFI_EVENT_GROUP_READY_TO_BOOT has
 609                                 already been signaled.
 610   @retval EFI_OUT_OF_RESOURCES  There is not enough resource to hold the lock request.
 611 **/
 612 EFI_STATUS
 613 EFIAPI
 614 VariableLockRequestToLock (
 615   IN CONST EDKII_VARIABLE_LOCK_PROTOCOL *This,
 616   IN       CHAR16                       *VariableName,
 617   IN       EFI_GUID                     *VendorGuid
 618   );
 619
 620 /**
 621   Register SetVariable check handler.
 622
 623   @param[in] Handler            Pointer to check handler.
 624
 625   @retval EFI_SUCCESS           The SetVariable check handler was registered successfully.
 626   @retval EFI_INVALID_PARAMETER Handler is NULL.
 627   @retval EFI_ACCESS_DENIED     EFI_END_OF_DXE_EVENT_GROUP_GUID or EFI_EVENT_GROUP_READY_TO_BOOT has
 628                                 already been signaled.
 629   @retval EFI_OUT_OF_RESOURCES  There is not enough resource for the SetVariable check handler register request.
 630   @retval EFI_UNSUPPORTED       This interface is not implemented.
 631                                 For example, it is unsupported in VarCheck protocol if both VarCheck and SmmVarCheck protocols are present.
 632
 633 **/
 634 EFI_STATUS
 635 EFIAPI
 636 VarCheckRegisterSetVariableCheckHandler (
 637   IN VAR_CHECK_SET_VARIABLE_CHECK_HANDLER   Handler
 638   );
 639
 640 /**
 641   Variable property set.
 642
 643   @param[in] Name               Pointer to the variable name.
 644   @param[in] Guid               Pointer to the vendor GUID.
 645   @param[in] VariableProperty   Pointer to the input variable property.
 646
 647   @retval EFI_SUCCESS           The property of variable specified by the Name and Guid was set successfully.
 648   @retval EFI_INVALID_PARAMETER Name, Guid or VariableProperty is NULL, or Name is an empty string,
 649                                 or the fields of VariableProperty are not valid.
 650   @retval EFI_ACCESS_DENIED     EFI_END_OF_DXE_EVENT_GROUP_GUID or EFI_EVENT_GROUP_READY_TO_BOOT has
 651                                 already been signaled.
 652   @retval EFI_OUT_OF_RESOURCES  There is not enough resource for the variable property set request.
 653
 654 **/
 655 EFI_STATUS
 656 EFIAPI
 657 VarCheckVariablePropertySet (
 658   IN CHAR16                         *Name,
 659   IN EFI_GUID                       *Guid,
 660   IN VAR_CHECK_VARIABLE_PROPERTY    *VariableProperty
 661   );
 662
 663 /**
 664   Variable property get.
 665
 666   @param[in]  Name              Pointer to the variable name.
 667   @param[in]  Guid              Pointer to the vendor GUID.
 668   @param[out] VariableProperty  Pointer to the output variable property.
 669
 670   @retval EFI_SUCCESS           The property of variable specified by the Name and Guid was got successfully.
 671   @retval EFI_INVALID_PARAMETER Name, Guid or VariableProperty is NULL, or Name is an empty string.
 672   @retval EFI_NOT_FOUND         The property of variable specified by the Name and Guid was not found.
 673
 674 **/
 675 EFI_STATUS
 676 EFIAPI
 677 VarCheckVariablePropertyGet (
 678   IN CHAR16                         *Name,
 679   IN EFI_GUID                       *Guid,
 680   OUT VAR_CHECK_VARIABLE_PROPERTY   *VariableProperty
 681   );
 682
 683 /**
 684   Initialize variable quota.
 685
 686 **/
 687 VOID
 688 InitializeVariableQuota (
 689   VOID
 690   );
 691
 692 extern VARIABLE_MODULE_GLOBAL       *mVariableModuleGlobal;
 693 extern EFI_FIRMWARE_VOLUME_HEADER   *mNvFvHeaderCache;
 694 extern VARIABLE_STORE_HEADER        *mNvVariableCache;
 695 extern VARIABLE_INFO_ENTRY          *gVariableInfo;
 696 extern BOOLEAN                      mEndOfDxe;
 697 extern VAR_CHECK_REQUEST_SOURCE     mRequestSource;
 698
 699 extern AUTH_VAR_LIB_CONTEXT_OUT     mAuthContextOut;
 700
 701 /**
 702   Finds variable in storage blocks of volatile and non-volatile storage areas.
 703
 704   This code finds variable in storage blocks of volatile and non-volatile storage areas.
 705   If VariableName is an empty string, then we just return the first
 706   qualified variable without comparing VariableName and VendorGuid.
 707
 708   @param[in]  VariableName          Name of the variable to be found.
 709   @param[in]  VendorGuid            Variable vendor GUID to be found.
 710   @param[out] AuthVariableInfo      Pointer to AUTH_VARIABLE_INFO structure for
 711                                     output of the variable found.
 712
 713   @retval EFI_INVALID_PARAMETER     If VariableName is not an empty string,
 714                                     while VendorGuid is NULL.
 715   @retval EFI_SUCCESS               Variable successfully found.
 716   @retval EFI_NOT_FOUND             Variable not found
 717
 718 **/
 719 EFI_STATUS
 720 EFIAPI
 721 VariableExLibFindVariable (
 722   IN  CHAR16                *VariableName,
 723   IN  EFI_GUID              *VendorGuid,
 724   OUT AUTH_VARIABLE_INFO    *AuthVariableInfo
 725   );
 726
 727 /**
 728   Finds next variable in storage blocks of volatile and non-volatile storage areas.
 729
 730   This code finds next variable in storage blocks of volatile and non-volatile storage areas.
 731   If VariableName is an empty string, then we just return the first
 732   qualified variable without comparing VariableName and VendorGuid.
 733
 734   @param[in]  VariableName          Name of the variable to be found.
 735   @param[in]  VendorGuid            Variable vendor GUID to be found.
 736   @param[out] AuthVariableInfo      Pointer to AUTH_VARIABLE_INFO structure for
 737                                     output of the next variable.
 738
 739   @retval EFI_INVALID_PARAMETER     If VariableName is not an empty string,
 740                                     while VendorGuid is NULL.
 741   @retval EFI_SUCCESS               Variable successfully found.
 742   @retval EFI_NOT_FOUND             Variable not found
 743
 744 **/
 745 EFI_STATUS
 746 EFIAPI
 747 VariableExLibFindNextVariable (
 748   IN  CHAR16                *VariableName,
 749   IN  EFI_GUID              *VendorGuid,
 750   OUT AUTH_VARIABLE_INFO    *AuthVariableInfo
 751   );
 752
 753 /**
 754   Update the variable region with Variable information.
 755
 756   @param[in] AuthVariableInfo       Pointer AUTH_VARIABLE_INFO structure for
 757                                     input of the variable.
 758
 759   @retval EFI_SUCCESS               The update operation is success.
 760   @retval EFI_INVALID_PARAMETER     Invalid parameter.
 761   @retval EFI_WRITE_PROTECTED       Variable is write-protected.
 762   @retval EFI_OUT_OF_RESOURCES      There is not enough resource.
 763
 764 **/
 765 EFI_STATUS
 766 EFIAPI
 767 VariableExLibUpdateVariable (
 768   IN AUTH_VARIABLE_INFO     *AuthVariableInfo
 769   );
 770
 771 /**
 772   Get scratch buffer.
 773
 774   @param[in, out] ScratchBufferSize Scratch buffer size. If input size is greater than
 775                                     the maximum supported buffer size, this value contains
 776                                     the maximum supported buffer size as output.
 777   @param[out]     ScratchBuffer     Pointer to scratch buffer address.
 778
 779   @retval EFI_SUCCESS       Get scratch buffer successfully.
 780   @retval EFI_UNSUPPORTED   If input size is greater than the maximum supported buffer size.
 781
 782 **/
 783 EFI_STATUS
 784 EFIAPI
 785 VariableExLibGetScratchBuffer (
 786   IN OUT UINTN      *ScratchBufferSize,
 787   OUT    VOID       **ScratchBuffer
 788   );
 789
 790 /**
 791   This function is to check if the remaining variable space is enough to set
 792   all Variables from argument list successfully. The purpose of the check
 793   is to keep the consistency of the Variables to be in variable storage.
 794
 795   Note: Variables are assumed to be in same storage.
 796   The set sequence of Variables will be same with the sequence of VariableEntry from argument list,
 797   so follow the argument sequence to check the Variables.
 798
 799   @param[in] Attributes         Variable attributes for Variable entries.
 800   @param ...                    The variable argument list with type VARIABLE_ENTRY_CONSISTENCY *.
 801                                 A NULL terminates the list. The VariableSize of
 802                                 VARIABLE_ENTRY_CONSISTENCY is the variable data size as input.
 803                                 It will be changed to variable total size as output.
 804
 805   @retval TRUE                  Have enough variable space to set the Variables successfully.
 806   @retval FALSE                 No enough variable space to set the Variables successfully.
 807
 808 **/
 809 BOOLEAN
 810 EFIAPI
 811 VariableExLibCheckRemainingSpaceForConsistency (
 812   IN UINT32                     Attributes,
 813   ...
 814   );
 815
 816 /**
 817   Return TRUE if at OS runtime.
 818
 819   @retval TRUE If at OS runtime.
 820   @retval FALSE If at boot time.
 821
 822 **/
 823 BOOLEAN
 824 EFIAPI
 825 VariableExLibAtRuntime (
 826   VOID
 827   );
 828
 829 #endif