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