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