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