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