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   Return TRUE if ExitBootServices () has been called.
 259
 260   @retval TRUE If ExitBootServices () has been called.
 261 **/
 262 BOOLEAN
 263 AtRuntime (
 264   VOID
 265   );
 266
 267 /**
 268   Initializes a basic mutual exclusion lock.
 269
 270   This function initializes a basic mutual exclusion lock to the released state
 271   and returns the lock.  Each lock provides mutual exclusion access at its task
 272   priority level.  Since there is no preemption or multiprocessor support in EFI,
 273   acquiring the lock only consists of raising to the locks TPL.
 274   If Lock is NULL, then ASSERT().
 275   If Priority is not a valid TPL value, then ASSERT().
 276
 277   @param  Lock       A pointer to the lock data structure to initialize.
 278   @param  Priority   EFI TPL is associated with the lock.
 279
 280   @return The lock.
 281
 282 **/
 283 EFI_LOCK *
 284 InitializeLock (
 285   IN OUT EFI_LOCK  *Lock,
 286   IN EFI_TPL       Priority
 287   );
 288
 289 /**
 290   Acquires lock only at boot time. Simply returns at runtime.
 291
 292   This is a temperary function that will be removed when
 293   EfiAcquireLock() in UefiLib can handle the call in UEFI
 294   Runtimer driver in RT phase.
 295   It calls EfiAcquireLock() at boot time, and simply returns
 296   at runtime.
 297
 298   @param  Lock         A pointer to the lock to acquire.
 299
 300 **/
 301 VOID
 302 AcquireLockOnlyAtBootTime (
 303   IN EFI_LOCK  *Lock
 304   );
 305
 306 /**
 307   Releases lock only at boot time. Simply returns at runtime.
 308
 309   This is a temperary function which will be removed when
 310   EfiReleaseLock() in UefiLib can handle the call in UEFI
 311   Runtimer driver in RT phase.
 312   It calls EfiReleaseLock() at boot time and simply returns
 313   at runtime.
 314
 315   @param  Lock         A pointer to the lock to release.
 316
 317 **/
 318 VOID
 319 ReleaseLockOnlyAtBootTime (
 320   IN EFI_LOCK  *Lock
 321   );
 322
 323 /**
 324   Retrieve the FVB protocol interface by HANDLE.
 325
 326   @param[in]  FvBlockHandle     The handle of FVB protocol that provides services for
 327                                 reading, writing, and erasing the target block.
 328   @param[out] FvBlock           The interface of FVB protocol
 329
 330   @retval EFI_SUCCESS           The interface information for the specified protocol was returned.
 331   @retval EFI_UNSUPPORTED       The device does not support the FVB protocol.
 332   @retval EFI_INVALID_PARAMETER FvBlockHandle is not a valid EFI_HANDLE or FvBlock is NULL.
 333
 334 **/
 335 EFI_STATUS
 336 GetFvbByHandle (
 337   IN  EFI_HANDLE                          FvBlockHandle,
 338   OUT EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  **FvBlock
 339   );
 340
 341 /**
 342   Function returns an array of handles that support the FVB protocol
 343   in a buffer allocated from pool.
 344
 345   @param[out]  NumberHandles    The number of handles returned in Buffer.
 346   @param[out]  Buffer           A pointer to the buffer to return the requested
 347                                 array of  handles that support FVB protocol.
 348
 349   @retval EFI_SUCCESS           The array of handles was returned in Buffer, and the number of
 350                                 handles in Buffer was returned in NumberHandles.
 351   @retval EFI_NOT_FOUND         No FVB handle was found.
 352   @retval EFI_OUT_OF_RESOURCES  There is not enough pool memory to store the matching results.
 353   @retval EFI_INVALID_PARAMETER NumberHandles is NULL or Buffer is NULL.
 354
 355 **/
 356 EFI_STATUS
 357 GetFvbCountAndBuffer (
 358   OUT UINTN       *NumberHandles,
 359   OUT EFI_HANDLE  **Buffer
 360   );
 361
 362 /**
 363   Initializes variable store area for non-volatile and volatile variable.
 364
 365   @retval EFI_SUCCESS           Function successfully executed.
 366   @retval EFI_OUT_OF_RESOURCES  Fail to allocate enough memory resource.
 367
 368 **/
 369 EFI_STATUS
 370 VariableCommonInitialize (
 371   VOID
 372   );
 373
 374 /**
 375   This function reclaims variable storage if free size is below the threshold.
 376
 377 **/
 378 VOID
 379 ReclaimForOS (
 380   VOID
 381   );
 382
 383 /**
 384   Get maximum variable size, covering both non-volatile and volatile variables.
 385
 386   @return Maximum variable size.
 387
 388 **/
 389 UINTN
 390 GetMaxVariableSize (
 391   VOID
 392   );
 393
 394 /**
 395   Initializes variable write service.
 396
 397   @retval EFI_SUCCESS          Function successfully executed.
 398   @retval Others               Fail to initialize the variable service.
 399
 400 **/
 401 EFI_STATUS
 402 VariableWriteServiceInitialize (
 403   VOID
 404   );
 405
 406 /**
 407   Retrieve the SMM Fault Tolerent Write protocol interface.
 408
 409   @param[out] FtwProtocol       The interface of SMM Ftw protocol
 410
 411   @retval EFI_SUCCESS           The SMM SAR protocol instance was found and returned in SarProtocol.
 412   @retval EFI_NOT_FOUND         The SMM SAR protocol instance was not found.
 413   @retval EFI_INVALID_PARAMETER SarProtocol is NULL.
 414
 415 **/
 416 EFI_STATUS
 417 GetFtwProtocol (
 418   OUT VOID  **FtwProtocol
 419   );
 420
 421 /**
 422   Get the proper fvb handle and/or fvb protocol by the given Flash address.
 423
 424   @param[in] Address        The Flash address.
 425   @param[out] FvbHandle     In output, if it is not NULL, it points to the proper FVB handle.
 426   @param[out] FvbProtocol   In output, if it is not NULL, it points to the proper FVB protocol.
 427
 428 **/
 429 EFI_STATUS
 430 GetFvbInfoByAddress (
 431   IN  EFI_PHYSICAL_ADDRESS                Address,
 432   OUT EFI_HANDLE                          *FvbHandle OPTIONAL,
 433   OUT EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  **FvbProtocol OPTIONAL
 434   );
 435
 436 /**
 437
 438   This code finds variable in storage blocks (Volatile or Non-Volatile).
 439
 440   Caution: This function may receive untrusted input.
 441   This function may be invoked in SMM mode, and datasize and data are external input.
 442   This function will do basic validation, before parse the data.
 443
 444   @param VariableName               Name of Variable to be found.
 445   @param VendorGuid                 Variable vendor GUID.
 446   @param Attributes                 Attribute value of the variable found.
 447   @param DataSize                   Size of Data found. If size is less than the
 448                                     data, this value contains the required size.
 449   @param Data                       The buffer to return the contents of the variable. May be NULL
 450                                     with a zero DataSize in order to determine the size buffer needed.
 451
 452   @return EFI_INVALID_PARAMETER     Invalid parameter.
 453   @return EFI_SUCCESS               Find the specified variable.
 454   @return EFI_NOT_FOUND             Not found.
 455   @return EFI_BUFFER_TO_SMALL       DataSize is too small for the result.
 456
 457 **/
 458 EFI_STATUS
 459 EFIAPI
 460 VariableServiceGetVariable (
 461   IN      CHAR16    *VariableName,
 462   IN      EFI_GUID  *VendorGuid,
 463   OUT     UINT32    *Attributes OPTIONAL,
 464   IN OUT  UINTN     *DataSize,
 465   OUT     VOID      *Data OPTIONAL
 466   );
 467
 468 /**
 469
 470   This code Finds the Next available variable.
 471
 472   Caution: This function may receive untrusted input.
 473   This function may be invoked in SMM mode. This function will do basic validation, before parse the data.
 474
 475   @param VariableNameSize           The size of the VariableName buffer. The size must be large
 476                                     enough to fit input string supplied in VariableName buffer.
 477   @param VariableName               Pointer to variable name.
 478   @param VendorGuid                 Variable Vendor Guid.
 479
 480   @retval EFI_SUCCESS               The function completed successfully.
 481   @retval EFI_NOT_FOUND             The next variable was not found.
 482   @retval EFI_BUFFER_TOO_SMALL      The VariableNameSize is too small for the result.
 483                                     VariableNameSize has been updated with the size needed to complete the request.
 484   @retval EFI_INVALID_PARAMETER     VariableNameSize is NULL.
 485   @retval EFI_INVALID_PARAMETER     VariableName is NULL.
 486   @retval EFI_INVALID_PARAMETER     VendorGuid is NULL.
 487   @retval EFI_INVALID_PARAMETER     The input values of VariableName and VendorGuid are not a name and
 488                                     GUID of an existing variable.
 489   @retval EFI_INVALID_PARAMETER     Null-terminator is not found in the first VariableNameSize bytes of
 490                                     the input VariableName buffer.
 491
 492 **/
 493 EFI_STATUS
 494 EFIAPI
 495 VariableServiceGetNextVariableName (
 496   IN OUT  UINTN     *VariableNameSize,
 497   IN OUT  CHAR16    *VariableName,
 498   IN OUT  EFI_GUID  *VendorGuid
 499   );
 500
 501 /**
 502
 503   This code sets variable in storage blocks (Volatile or Non-Volatile).
 504
 505   Caution: This function may receive untrusted input.
 506   This function may be invoked in SMM mode, and datasize and data are external input.
 507   This function will do basic validation, before parse the data.
 508   This function will parse the authentication carefully to avoid security issues, like
 509   buffer overflow, integer overflow.
 510   This function will check attribute carefully to avoid authentication bypass.
 511
 512   @param VariableName                     Name of Variable to be found.
 513   @param VendorGuid                       Variable vendor GUID.
 514   @param Attributes                       Attribute value of the variable found
 515   @param DataSize                         Size of Data found. If size is less than the
 516                                           data, this value contains the required size.
 517   @param Data                             Data pointer.
 518
 519   @return EFI_INVALID_PARAMETER           Invalid parameter.
 520   @return EFI_SUCCESS                     Set successfully.
 521   @return EFI_OUT_OF_RESOURCES            Resource not enough to set variable.
 522   @return EFI_NOT_FOUND                   Not found.
 523   @return EFI_WRITE_PROTECTED             Variable is read-only.
 524
 525 **/
 526 EFI_STATUS
 527 EFIAPI
 528 VariableServiceSetVariable (
 529   IN CHAR16    *VariableName,
 530   IN EFI_GUID  *VendorGuid,
 531   IN UINT32    Attributes,
 532   IN UINTN     DataSize,
 533   IN VOID      *Data
 534   );
 535
 536 /**
 537
 538   This code returns information about the EFI variables.
 539
 540   Caution: This function may receive untrusted input.
 541   This function may be invoked in SMM mode. This function will do basic validation, before parse the data.
 542
 543   @param Attributes                     Attributes bitmask to specify the type of variables
 544                                         on which to return information.
 545   @param MaximumVariableStorageSize     Pointer to the maximum size of the storage space available
 546                                         for the EFI variables associated with the attributes specified.
 547   @param RemainingVariableStorageSize   Pointer to the remaining size of the storage space available
 548                                         for EFI variables associated with the attributes specified.
 549   @param MaximumVariableSize            Pointer to the maximum size of an individual EFI variables
 550                                         associated with the attributes specified.
 551
 552   @return EFI_SUCCESS                   Query successfully.
 553
 554 **/
 555 EFI_STATUS
 556 EFIAPI
 557 VariableServiceQueryVariableInfoInternal (
 558   IN  UINT32  Attributes,
 559   OUT UINT64  *MaximumVariableStorageSize,
 560   OUT UINT64  *RemainingVariableStorageSize,
 561   OUT UINT64  *MaximumVariableSize
 562   );
 563
 564 /**
 565
 566   This code returns information about the EFI variables.
 567
 568   Caution: This function may receive untrusted input.
 569   This function may be invoked in SMM mode. This function will do basic validation, before parse the data.
 570
 571   @param Attributes                     Attributes bitmask to specify the type of variables
 572                                         on which to return information.
 573   @param MaximumVariableStorageSize     Pointer to the maximum size of the storage space available
 574                                         for the EFI variables associated with the attributes specified.
 575   @param RemainingVariableStorageSize   Pointer to the remaining size of the storage space available
 576                                         for EFI variables associated with the attributes specified.
 577   @param MaximumVariableSize            Pointer to the maximum size of an individual EFI variables
 578                                         associated with the attributes specified.
 579
 580   @return EFI_INVALID_PARAMETER         An invalid combination of attribute bits was supplied.
 581   @return EFI_SUCCESS                   Query successfully.
 582   @return EFI_UNSUPPORTED               The attribute is not supported on this platform.
 583
 584 **/
 585 EFI_STATUS
 586 EFIAPI
 587 VariableServiceQueryVariableInfo (
 588   IN  UINT32  Attributes,
 589   OUT UINT64  *MaximumVariableStorageSize,
 590   OUT UINT64  *RemainingVariableStorageSize,
 591   OUT UINT64  *MaximumVariableSize
 592   );
 593
 594 /**
 595   Mark a variable that will become read-only after leaving the DXE phase of execution.
 596
 597   @param[in] This          The VARIABLE_LOCK_PROTOCOL instance.
 598   @param[in] VariableName  A pointer to the variable name that will be made read-only subsequently.
 599   @param[in] VendorGuid    A pointer to the vendor GUID that will be made read-only subsequently.
 600
 601   @retval EFI_SUCCESS           The variable specified by the VariableName and the VendorGuid was marked
 602                                 as pending to be read-only.
 603   @retval EFI_INVALID_PARAMETER VariableName or VendorGuid is NULL.
 604                                 Or VariableName is an empty string.
 605   @retval EFI_ACCESS_DENIED     EFI_END_OF_DXE_EVENT_GROUP_GUID or EFI_EVENT_GROUP_READY_TO_BOOT has
 606                                 already been signaled.
 607   @retval EFI_OUT_OF_RESOURCES  There is not enough resource to hold the lock request.
 608 **/
 609 EFI_STATUS
 610 EFIAPI
 611 VariableLockRequestToLock (
 612   IN CONST EDKII_VARIABLE_LOCK_PROTOCOL  *This,
 613   IN       CHAR16                        *VariableName,
 614   IN       EFI_GUID                      *VendorGuid
 615   );
 616
 617 /**
 618   Register SetVariable check handler.
 619
 620   @param[in] Handler            Pointer to check handler.
 621
 622   @retval EFI_SUCCESS           The SetVariable check handler was registered successfully.
 623   @retval EFI_INVALID_PARAMETER Handler is NULL.
 624   @retval EFI_ACCESS_DENIED     EFI_END_OF_DXE_EVENT_GROUP_GUID or EFI_EVENT_GROUP_READY_TO_BOOT has
 625                                 already been signaled.
 626   @retval EFI_OUT_OF_RESOURCES  There is not enough resource for the SetVariable check handler register request.
 627   @retval EFI_UNSUPPORTED       This interface is not implemented.
 628                                 For example, it is unsupported in VarCheck protocol if both VarCheck and SmmVarCheck protocols are present.
 629
 630 **/
 631 EFI_STATUS
 632 EFIAPI
 633 VarCheckRegisterSetVariableCheckHandler (
 634   IN VAR_CHECK_SET_VARIABLE_CHECK_HANDLER  Handler
 635   );
 636
 637 /**
 638   Variable property set.
 639
 640   @param[in] Name               Pointer to the variable name.
 641   @param[in] Guid               Pointer to the vendor GUID.
 642   @param[in] VariableProperty   Pointer to the input variable property.
 643
 644   @retval EFI_SUCCESS           The property of variable specified by the Name and Guid was set successfully.
 645   @retval EFI_INVALID_PARAMETER Name, Guid or VariableProperty is NULL, or Name is an empty string,
 646                                 or the fields of VariableProperty are not valid.
 647   @retval EFI_ACCESS_DENIED     EFI_END_OF_DXE_EVENT_GROUP_GUID or EFI_EVENT_GROUP_READY_TO_BOOT has
 648                                 already been signaled.
 649   @retval EFI_OUT_OF_RESOURCES  There is not enough resource for the variable property set request.
 650
 651 **/
 652 EFI_STATUS
 653 EFIAPI
 654 VarCheckVariablePropertySet (
 655   IN CHAR16                       *Name,
 656   IN EFI_GUID                     *Guid,
 657   IN VAR_CHECK_VARIABLE_PROPERTY  *VariableProperty
 658   );
 659
 660 /**
 661   Variable property get.
 662
 663   @param[in]  Name              Pointer to the variable name.
 664   @param[in]  Guid              Pointer to the vendor GUID.
 665   @param[out] VariableProperty  Pointer to the output variable property.
 666
 667   @retval EFI_SUCCESS           The property of variable specified by the Name and Guid was got successfully.
 668   @retval EFI_INVALID_PARAMETER Name, Guid or VariableProperty is NULL, or Name is an empty string.
 669   @retval EFI_NOT_FOUND         The property of variable specified by the Name and Guid was not found.
 670
 671 **/
 672 EFI_STATUS
 673 EFIAPI
 674 VarCheckVariablePropertyGet (
 675   IN CHAR16                        *Name,
 676   IN EFI_GUID                      *Guid,
 677   OUT VAR_CHECK_VARIABLE_PROPERTY  *VariableProperty
 678   );
 679
 680 /**
 681   Initialize variable quota.
 682
 683 **/
 684 VOID
 685 InitializeVariableQuota (
 686   VOID
 687   );
 688
 689 extern VARIABLE_MODULE_GLOBAL      *mVariableModuleGlobal;
 690 extern EFI_FIRMWARE_VOLUME_HEADER  *mNvFvHeaderCache;
 691 extern VARIABLE_STORE_HEADER       *mNvVariableCache;
 692 extern VARIABLE_INFO_ENTRY         *gVariableInfo;
 693 extern BOOLEAN                     mEndOfDxe;
 694 extern VAR_CHECK_REQUEST_SOURCE    mRequestSource;
 695
 696 extern AUTH_VAR_LIB_CONTEXT_OUT  mAuthContextOut;
 697
 698 /**
 699   Finds variable in storage blocks of volatile and non-volatile storage areas.
 700
 701   This code finds variable in storage blocks of volatile and non-volatile storage areas.
 702   If VariableName is an empty string, then we just return the first
 703   qualified variable without comparing VariableName and VendorGuid.
 704
 705   @param[in]  VariableName          Name of the variable to be found.
 706   @param[in]  VendorGuid            Variable vendor GUID to be found.
 707   @param[out] AuthVariableInfo      Pointer to AUTH_VARIABLE_INFO structure for
 708                                     output of the variable found.
 709
 710   @retval EFI_INVALID_PARAMETER     If VariableName is not an empty string,
 711                                     while VendorGuid is NULL.
 712   @retval EFI_SUCCESS               Variable successfully found.
 713   @retval EFI_NOT_FOUND             Variable not found
 714
 715 **/
 716 EFI_STATUS
 717 EFIAPI
 718 VariableExLibFindVariable (
 719   IN  CHAR16              *VariableName,
 720   IN  EFI_GUID            *VendorGuid,
 721   OUT AUTH_VARIABLE_INFO  *AuthVariableInfo
 722   );
 723
 724 /**
 725   Finds next variable in storage blocks of volatile and non-volatile storage areas.
 726
 727   This code finds next variable in storage blocks of volatile and non-volatile storage areas.
 728   If VariableName is an empty string, then we just return the first
 729   qualified variable without comparing VariableName and VendorGuid.
 730
 731   @param[in]  VariableName          Name of the variable to be found.
 732   @param[in]  VendorGuid            Variable vendor GUID to be found.
 733   @param[out] AuthVariableInfo      Pointer to AUTH_VARIABLE_INFO structure for
 734                                     output of the next variable.
 735
 736   @retval EFI_INVALID_PARAMETER     If VariableName is not an empty string,
 737                                     while VendorGuid is NULL.
 738   @retval EFI_SUCCESS               Variable successfully found.
 739   @retval EFI_NOT_FOUND             Variable not found
 740
 741 **/
 742 EFI_STATUS
 743 EFIAPI
 744 VariableExLibFindNextVariable (
 745   IN  CHAR16              *VariableName,
 746   IN  EFI_GUID            *VendorGuid,
 747   OUT AUTH_VARIABLE_INFO  *AuthVariableInfo
 748   );
 749
 750 /**
 751   Update the variable region with Variable information.
 752
 753   @param[in] AuthVariableInfo       Pointer AUTH_VARIABLE_INFO structure for
 754                                     input of the variable.
 755
 756   @retval EFI_SUCCESS               The update operation is success.
 757   @retval EFI_INVALID_PARAMETER     Invalid parameter.
 758   @retval EFI_WRITE_PROTECTED       Variable is write-protected.
 759   @retval EFI_OUT_OF_RESOURCES      There is not enough resource.
 760
 761 **/
 762 EFI_STATUS
 763 EFIAPI
 764 VariableExLibUpdateVariable (
 765   IN AUTH_VARIABLE_INFO  *AuthVariableInfo
 766   );
 767
 768 /**
 769   Get scratch buffer.
 770
 771   @param[in, out] ScratchBufferSize Scratch buffer size. If input size is greater than
 772                                     the maximum supported buffer size, this value contains
 773                                     the maximum supported buffer size as output.
 774   @param[out]     ScratchBuffer     Pointer to scratch buffer address.
 775
 776   @retval EFI_SUCCESS       Get scratch buffer successfully.
 777   @retval EFI_UNSUPPORTED   If input size is greater than the maximum supported buffer size.
 778
 779 **/
 780 EFI_STATUS
 781 EFIAPI
 782 VariableExLibGetScratchBuffer (
 783   IN OUT UINTN  *ScratchBufferSize,
 784   OUT    VOID   **ScratchBuffer
 785   );
 786
 787 /**
 788   This function is to check if the remaining variable space is enough to set
 789   all Variables from argument list successfully. The purpose of the check
 790   is to keep the consistency of the Variables to be in variable storage.
 791
 792   Note: Variables are assumed to be in same storage.
 793   The set sequence of Variables will be same with the sequence of VariableEntry from argument list,
 794   so follow the argument sequence to check the Variables.
 795
 796   @param[in] Attributes         Variable attributes for Variable entries.
 797   @param ...                    The variable argument list with type VARIABLE_ENTRY_CONSISTENCY *.
 798                                 A NULL terminates the list. The VariableSize of
 799                                 VARIABLE_ENTRY_CONSISTENCY is the variable data size as input.
 800                                 It will be changed to variable total size as output.
 801
 802   @retval TRUE                  Have enough variable space to set the Variables successfully.
 803   @retval FALSE                 No enough variable space to set the Variables successfully.
 804
 805 **/
 806 BOOLEAN
 807 EFIAPI
 808 VariableExLibCheckRemainingSpaceForConsistency (
 809   IN UINT32  Attributes,
 810   ...
 811   );
 812
 813 /**
 814   Return TRUE if at OS runtime.
 815
 816   @retval TRUE If at OS runtime.
 817   @retval FALSE If at boot time.
 818
 819 **/
 820 BOOLEAN
 821 EFIAPI
 822 VariableExLibAtRuntime (
 823   VOID
 824   );
 825
 826 #endif