MdeModulePkg/Universal/Variable/RuntimeDxe/Variable.h

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