PrmPkg/Test/UnitTest/Library/UefiBootServicesTableLibUnitTest/UefiBootServicesTableLibUnitTest.h

   1 /** @file
   2   An internal header file for the Unit Test instance of the UEFI Boot Services Table Library.
   3
   4   This file includes common header files, defines internal structure and functions used by
   5   the library implementation.
   6
   7 Copyright (c) Microsoft Corporation
   8 SPDX-License-Identifier: BSD-2-Clause-Patent
   9
  10 **/
  11
  12 #ifndef UEFI_BOOT_SERVICES_TABLE_LIB_UNIT_TEST_H_
  13 #define UEFI_BOOT_SERVICES_TABLE_LIB_UNIT_TEST_H_
  14
  15 #include <Uefi.h>
  16
  17 #include <Pi/PiMultiPhase.h>
  18 #include <Library/BaseLib.h>
  19 #include <Library/BaseMemoryLib.h>
  20 #include <Library/DebugLib.h>
  21 #include <Library/MemoryAllocationLib.h>
  22 #include <Library/UnitTestLib.h>
  23 #include <Library/UefiBootServicesTableLib.h>
  24
  25 /**
  26   Raise the task priority level to the new level.
  27   High level is implemented by disabling processor interrupts.
  28
  29   @param  NewTpl  New task priority level
  30
  31   @return The previous task priority level
  32
  33 **/
  34 EFI_TPL
  35 EFIAPI
  36 UnitTestRaiseTpl (
  37   IN EFI_TPL      NewTpl
  38   );
  39
  40
  41
  42 /**
  43   Lowers the task priority to the previous value.   If the new
  44   priority unmasks events at a higher priority, they are dispatched.
  45
  46   @param  NewTpl  New, lower, task priority
  47
  48 **/
  49 VOID
  50 EFIAPI
  51 UnitTestRestoreTpl (
  52   IN EFI_TPL NewTpl
  53   );
  54
  55 /**
  56   Allocates pages from the memory map.
  57
  58   @param  Type                   The type of allocation to perform
  59   @param  MemoryType             The type of memory to turn the allocated pages
  60                                  into
  61   @param  NumberOfPages          The number of pages to allocate
  62   @param  Memory                 A pointer to receive the base allocated memory
  63                                  address
  64
  65   @return Status. On success, Memory is filled in with the base address allocated
  66   @retval EFI_INVALID_PARAMETER  Parameters violate checking rules defined in
  67                                  spec.
  68   @retval EFI_NOT_FOUND          Could not allocate pages match the requirement.
  69   @retval EFI_OUT_OF_RESOURCES   No enough pages to allocate.
  70   @retval EFI_SUCCESS            Pages successfully allocated.
  71
  72 **/
  73 EFI_STATUS
  74 EFIAPI
  75 UnitTestAllocatePages (
  76   IN EFI_ALLOCATE_TYPE      Type,
  77   IN EFI_MEMORY_TYPE        MemoryType,
  78   IN UINTN                  NumberOfPages,
  79   IN OUT EFI_PHYSICAL_ADDRESS  *Memory
  80   );
  81
  82 /**
  83   Frees previous allocated pages.
  84
  85   @param  Memory                 Base address of memory being freed
  86   @param  NumberOfPages          The number of pages to free
  87
  88   @retval EFI_NOT_FOUND          Could not find the entry that covers the range
  89   @retval EFI_INVALID_PARAMETER  Address not aligned
  90   @return EFI_SUCCESS         -Pages successfully freed.
  91
  92 **/
  93 EFI_STATUS
  94 EFIAPI
  95 UnitTestFreePages (
  96   IN EFI_PHYSICAL_ADDRESS   Memory,
  97   IN UINTN                  NumberOfPages
  98   );
  99
 100 /**
 101   This function returns a copy of the current memory map. The map is an array of
 102   memory descriptors, each of which describes a contiguous block of memory.
 103
 104   @param  MemoryMapSize          A pointer to the size, in bytes, of the
 105                                  MemoryMap buffer. On input, this is the size of
 106                                  the buffer allocated by the caller.  On output,
 107                                  it is the size of the buffer returned by the
 108                                  firmware  if the buffer was large enough, or the
 109                                  size of the buffer needed  to contain the map if
 110                                  the buffer was too small.
 111   @param  MemoryMap              A pointer to the buffer in which firmware places
 112                                  the current memory map.
 113   @param  MapKey                 A pointer to the location in which firmware
 114                                  returns the key for the current memory map.
 115   @param  DescriptorSize         A pointer to the location in which firmware
 116                                  returns the size, in bytes, of an individual
 117                                  EFI_MEMORY_DESCRIPTOR.
 118   @param  DescriptorVersion      A pointer to the location in which firmware
 119                                  returns the version number associated with the
 120                                  EFI_MEMORY_DESCRIPTOR.
 121
 122   @retval EFI_SUCCESS            The memory map was returned in the MemoryMap
 123                                  buffer.
 124   @retval EFI_BUFFER_TOO_SMALL   The MemoryMap buffer was too small. The current
 125                                  buffer size needed to hold the memory map is
 126                                  returned in MemoryMapSize.
 127   @retval EFI_INVALID_PARAMETER  One of the parameters has an invalid value.
 128
 129 **/
 130 EFI_STATUS
 131 EFIAPI
 132 UnitTestGetMemoryMap (
 133   IN OUT UINTN                  *MemoryMapSize,
 134   IN OUT EFI_MEMORY_DESCRIPTOR  *MemoryMap,
 135   OUT UINTN                     *MapKey,
 136   OUT UINTN                     *DescriptorSize,
 137   OUT UINT32                    *DescriptorVersion
 138   );
 139
 140
 141
 142 /**
 143   Allocate pool of a particular type.
 144
 145   @param  PoolType               Type of pool to allocate
 146   @param  Size                   The amount of pool to allocate
 147   @param  Buffer                 The address to return a pointer to the allocated
 148                                  pool
 149
 150   @retval EFI_INVALID_PARAMETER  PoolType not valid or Buffer is NULL
 151   @retval EFI_OUT_OF_RESOURCES   Size exceeds max pool size or allocation failed.
 152   @retval EFI_SUCCESS            Pool successfully allocated.
 153
 154 **/
 155 EFI_STATUS
 156 EFIAPI
 157 UnitTestAllocatePool (
 158   IN EFI_MEMORY_TYPE  PoolType,
 159   IN UINTN            Size,
 160   OUT VOID            **Buffer
 161   );
 162
 163 /**
 164   Frees pool.
 165
 166   @param  Buffer                 The allocated pool entry to free
 167
 168   @retval EFI_INVALID_PARAMETER  Buffer is not a valid value.
 169   @retval EFI_SUCCESS            Pool successfully freed.
 170
 171 **/
 172 EFI_STATUS
 173 EFIAPI
 174 UnitTestFreePool (
 175   IN VOID        *Buffer
 176   );
 177
 178 /**
 179   Frees pool.
 180
 181   @param  Buffer                 The allocated pool entry to free
 182   @param  PoolType               Pointer to pool type
 183
 184   @retval EFI_INVALID_PARAMETER  Buffer is not a valid value.
 185   @retval EFI_SUCCESS            Pool successfully freed.
 186
 187 **/
 188 EFI_STATUS
 189 EFIAPI
 190 UnitTestInternalFreePool (
 191   IN VOID               *Buffer,
 192   OUT EFI_MEMORY_TYPE   *PoolType OPTIONAL
 193   );
 194
 195 /**
 196   Creates an event.
 197
 198   @param  Type                   The type of event to create and its mode and
 199                                  attributes
 200   @param  NotifyTpl              The task priority level of event notifications
 201   @param  NotifyFunction         Pointer to the events notification function
 202   @param  NotifyContext          Pointer to the notification functions context;
 203                                  corresponds to parameter "Context" in the
 204                                  notification function
 205   @param  Event                  Pointer to the newly created event if the call
 206                                  succeeds; undefined otherwise
 207
 208   @retval EFI_SUCCESS            The event structure was created
 209   @retval EFI_INVALID_PARAMETER  One of the parameters has an invalid value
 210   @retval EFI_OUT_OF_RESOURCES   The event could not be allocated
 211
 212 **/
 213 EFI_STATUS
 214 EFIAPI
 215 UnitTestCreateEvent (
 216   IN UINT32                   Type,
 217   IN EFI_TPL                  NotifyTpl,
 218   IN EFI_EVENT_NOTIFY         NotifyFunction, OPTIONAL
 219   IN VOID                     *NotifyContext, OPTIONAL
 220   OUT EFI_EVENT               *Event
 221   );
 222
 223 /**
 224   Sets the type of timer and the trigger time for a timer event.
 225
 226   @param  UserEvent              The timer event that is to be signaled at the
 227                                  specified time
 228   @param  Type                   The type of time that is specified in
 229                                  TriggerTime
 230   @param  TriggerTime            The number of 100ns units until the timer
 231                                  expires
 232
 233   @retval EFI_SUCCESS            The event has been set to be signaled at the
 234                                  requested time
 235   @retval EFI_INVALID_PARAMETER  Event or Type is not valid
 236
 237 **/
 238 EFI_STATUS
 239 EFIAPI
 240 UnitTestSetTimer (
 241   IN EFI_EVENT            UserEvent,
 242   IN EFI_TIMER_DELAY      Type,
 243   IN UINT64               TriggerTime
 244   );
 245
 246 /**
 247   Stops execution until an event is signaled.
 248
 249   @param  NumberOfEvents         The number of events in the UserEvents array
 250   @param  UserEvents             An array of EFI_EVENT
 251   @param  UserIndex              Pointer to the index of the event which
 252                                  satisfied the wait condition
 253
 254   @retval EFI_SUCCESS            The event indicated by Index was signaled.
 255   @retval EFI_INVALID_PARAMETER  The event indicated by Index has a notification
 256                                  function or Event was not a valid type
 257   @retval EFI_UNSUPPORTED        The current TPL is not TPL_APPLICATION
 258
 259 **/
 260 EFI_STATUS
 261 EFIAPI
 262 UnitTestWaitForEvent (
 263   IN UINTN        NumberOfEvents,
 264   IN EFI_EVENT    *UserEvents,
 265   OUT UINTN       *UserIndex
 266   );
 267
 268 /**
 269   Signals the event.  Queues the event to be notified if needed.
 270
 271   @param  UserEvent              The event to signal .
 272
 273   @retval EFI_INVALID_PARAMETER  Parameters are not valid.
 274   @retval EFI_SUCCESS            The event was signaled.
 275
 276 **/
 277 EFI_STATUS
 278 EFIAPI
 279 UnitTestSignalEvent (
 280   IN EFI_EVENT    UserEvent
 281   );
 282
 283 /**
 284   Closes an event and frees the event structure.
 285
 286   @param  UserEvent              Event to close
 287
 288   @retval EFI_INVALID_PARAMETER  Parameters are not valid.
 289   @retval EFI_SUCCESS            The event has been closed
 290
 291 **/
 292 EFI_STATUS
 293 EFIAPI
 294 UnitTestCloseEvent (
 295   IN EFI_EVENT    UserEvent
 296   );
 297
 298 /**
 299   Check the status of an event.
 300
 301   @param  UserEvent              The event to check
 302
 303   @retval EFI_SUCCESS            The event is in the signaled state
 304   @retval EFI_NOT_READY          The event is not in the signaled state
 305   @retval EFI_INVALID_PARAMETER  Event is of type EVT_NOTIFY_SIGNAL
 306
 307 **/
 308 EFI_STATUS
 309 EFIAPI
 310 UnitTestCheckEvent (
 311   IN EFI_EVENT        UserEvent
 312   );
 313
 314 /**
 315   Wrapper function to UnitTestInstallProtocolInterfaceNotify.  This is the public API which
 316   Calls the private one which contains a BOOLEAN parameter for notifications
 317
 318   @param  UserHandle             The handle to install the protocol handler on,
 319                                  or NULL if a new handle is to be allocated
 320   @param  Protocol               The protocol to add to the handle
 321   @param  InterfaceType          Indicates whether Interface is supplied in
 322                                  native form.
 323   @param  Interface              The interface for the protocol being added
 324
 325   @return Status code
 326
 327 **/
 328 EFI_STATUS
 329 EFIAPI
 330 UnitTestInstallProtocolInterface (
 331   IN OUT EFI_HANDLE     *UserHandle,
 332   IN EFI_GUID           *Protocol,
 333   IN EFI_INTERFACE_TYPE InterfaceType,
 334   IN VOID               *Interface
 335   );
 336
 337 /**
 338   Reinstall a protocol interface on a device handle.  The OldInterface for Protocol is replaced by the NewInterface.
 339
 340   @param  UserHandle             Handle on which the interface is to be
 341                                  reinstalled
 342   @param  Protocol               The numeric ID of the interface
 343   @param  OldInterface           A pointer to the old interface
 344   @param  NewInterface           A pointer to the new interface
 345
 346   @retval EFI_SUCCESS            The protocol interface was installed
 347   @retval EFI_NOT_FOUND          The OldInterface on the handle was not found
 348   @retval EFI_INVALID_PARAMETER  One of the parameters has an invalid value
 349
 350 **/
 351 EFI_STATUS
 352 EFIAPI
 353 UnitTestReinstallProtocolInterface (
 354   IN EFI_HANDLE     UserHandle,
 355   IN EFI_GUID       *Protocol,
 356   IN VOID           *OldInterface,
 357   IN VOID           *NewInterface
 358   );
 359
 360 /**
 361   Uninstalls all instances of a protocol:interfacer from a handle.
 362   If the last protocol interface is remove from the handle, the
 363   handle is freed.
 364
 365   @param  UserHandle             The handle to remove the protocol handler from
 366   @param  Protocol               The protocol, of protocol:interface, to remove
 367   @param  Interface              The interface, of protocol:interface, to remove
 368
 369   @retval EFI_INVALID_PARAMETER  Protocol is NULL.
 370   @retval EFI_SUCCESS            Protocol interface successfully uninstalled.
 371
 372 **/
 373 EFI_STATUS
 374 EFIAPI
 375 UnitTestUninstallProtocolInterface (
 376   IN EFI_HANDLE       UserHandle,
 377   IN EFI_GUID         *Protocol,
 378   IN VOID             *Interface
 379   );
 380
 381 /**
 382   Queries a handle to determine if it supports a specified protocol.
 383
 384   @param  UserHandle             The handle being queried.
 385   @param  Protocol               The published unique identifier of the protocol.
 386   @param  Interface              Supplies the address where a pointer to the
 387                                  corresponding Protocol Interface is returned.
 388
 389   @return The requested protocol interface for the handle
 390
 391 **/
 392 EFI_STATUS
 393 EFIAPI
 394 UnitTestHandleProtocol (
 395   IN EFI_HANDLE       UserHandle,
 396   IN EFI_GUID         *Protocol,
 397   OUT VOID            **Interface
 398   );
 399
 400 /**
 401   Add a new protocol notification record for the request protocol.
 402
 403   @param  Protocol               The requested protocol to add the notify
 404                                  registration
 405   @param  Event                  The event to signal
 406   @param  Registration           Returns the registration record
 407
 408   @retval EFI_INVALID_PARAMETER  Invalid parameter
 409   @retval EFI_SUCCESS            Successfully returned the registration record
 410                                  that has been added
 411
 412 **/
 413 EFI_STATUS
 414 EFIAPI
 415 UnitTestRegisterProtocolNotify (
 416   IN EFI_GUID       *Protocol,
 417   IN EFI_EVENT      Event,
 418   OUT  VOID         **Registration
 419   );
 420
 421 /**
 422   Locates the requested handle(s) and returns them in Buffer.
 423
 424   @param  SearchType             The type of search to perform to locate the
 425                                  handles
 426   @param  Protocol               The protocol to search for
 427   @param  SearchKey              Dependant on SearchType
 428   @param  BufferSize             On input the size of Buffer.  On output the
 429                                  size of data returned.
 430   @param  Buffer                 The buffer to return the results in
 431
 432   @retval EFI_BUFFER_TOO_SMALL   Buffer too small, required buffer size is
 433                                  returned in BufferSize.
 434   @retval EFI_INVALID_PARAMETER  Invalid parameter
 435   @retval EFI_SUCCESS            Successfully found the requested handle(s) and
 436                                  returns them in Buffer.
 437
 438 **/
 439 EFI_STATUS
 440 EFIAPI
 441 UnitTestLocateHandle (
 442   IN EFI_LOCATE_SEARCH_TYPE   SearchType,
 443   IN EFI_GUID                 *Protocol   OPTIONAL,
 444   IN VOID                     *SearchKey  OPTIONAL,
 445   IN OUT UINTN                *BufferSize,
 446   OUT EFI_HANDLE              *Buffer
 447   );
 448
 449 /**
 450   Locates the handle to a device on the device path that best matches the specified protocol.
 451
 452   @param  Protocol               The protocol to search for.
 453   @param  DevicePath             On input, a pointer to a pointer to the device
 454                                  path. On output, the device path pointer is
 455                                  modified to point to the remaining part of the
 456                                  devicepath.
 457   @param  Device                 A pointer to the returned device handle.
 458
 459   @retval EFI_SUCCESS            The resulting handle was returned.
 460   @retval EFI_NOT_FOUND          No handles matched the search.
 461   @retval EFI_INVALID_PARAMETER  One of the parameters has an invalid value.
 462
 463 **/
 464 EFI_STATUS
 465 EFIAPI
 466 UnitTestLocateDevicePath (
 467   IN EFI_GUID                       *Protocol,
 468   IN OUT EFI_DEVICE_PATH_PROTOCOL   **DevicePath,
 469   OUT EFI_HANDLE                    *Device
 470   );
 471
 472 /**
 473   Boot Service called to add, modify, or remove a system configuration table from
 474   the EFI System Table.
 475
 476   @param  Guid           Pointer to the GUID for the entry to add, update, or
 477                          remove
 478   @param  Table          Pointer to the configuration table for the entry to add,
 479                          update, or remove, may be NULL.
 480
 481   @return EFI_SUCCESS               Guid, Table pair added, updated, or removed.
 482   @return EFI_INVALID_PARAMETER     Input GUID not valid.
 483   @return EFI_NOT_FOUND             Attempted to delete non-existant entry
 484   @return EFI_OUT_OF_RESOURCES      Not enough memory available
 485
 486 **/
 487 EFI_STATUS
 488 EFIAPI
 489 UnitTestInstallConfigurationTable (
 490   IN EFI_GUID *Guid,
 491   IN VOID     *Table
 492   );
 493
 494 /**
 495   Loads an EFI image into memory and returns a handle to the image.
 496
 497   @param  BootPolicy              If TRUE, indicates that the request originates
 498                                   from the boot manager, and that the boot
 499                                   manager is attempting to load FilePath as a
 500                                   boot selection.
 501   @param  ParentImageHandle       The caller's image handle.
 502   @param  FilePath                The specific file path from which the image is
 503                                   loaded.
 504   @param  SourceBuffer            If not NULL, a pointer to the memory location
 505                                   containing a copy of the image to be loaded.
 506   @param  SourceSize              The size in bytes of SourceBuffer.
 507   @param  ImageHandle             Pointer to the returned image handle that is
 508                                   created when the image is successfully loaded.
 509
 510   @retval EFI_SUCCESS             The image was loaded into memory.
 511   @retval EFI_NOT_FOUND           The FilePath was not found.
 512   @retval EFI_INVALID_PARAMETER   One of the parameters has an invalid value.
 513   @retval EFI_UNSUPPORTED         The image type is not supported, or the device
 514                                   path cannot be parsed to locate the proper
 515                                   protocol for loading the file.
 516   @retval EFI_OUT_OF_RESOURCES    Image was not loaded due to insufficient
 517                                   resources.
 518   @retval EFI_LOAD_ERROR          Image was not loaded because the image format was corrupt or not
 519                                   understood.
 520   @retval EFI_DEVICE_ERROR        Image was not loaded because the device returned a read error.
 521   @retval EFI_ACCESS_DENIED       Image was not loaded because the platform policy prohibits the
 522                                   image from being loaded. NULL is returned in *ImageHandle.
 523   @retval EFI_SECURITY_VIOLATION  Image was loaded and an ImageHandle was created with a
 524                                   valid EFI_LOADED_IMAGE_PROTOCOL. However, the current
 525                                   platform policy specifies that the image should not be started.
 526
 527 **/
 528 EFI_STATUS
 529 EFIAPI
 530 UnitTestLoadImage (
 531   IN BOOLEAN                    BootPolicy,
 532   IN EFI_HANDLE                 ParentImageHandle,
 533   IN EFI_DEVICE_PATH_PROTOCOL   *FilePath,
 534   IN VOID                       *SourceBuffer   OPTIONAL,
 535   IN UINTN                      SourceSize,
 536   OUT EFI_HANDLE                *ImageHandle
 537   );
 538
 539 /**
 540   Transfer control to a loaded image's entry point.
 541
 542   @param  ImageHandle             Handle of image to be started.
 543   @param  ExitDataSize            Pointer of the size to ExitData
 544   @param  ExitData                Pointer to a pointer to a data buffer that
 545                                   includes a Null-terminated string,
 546                                   optionally followed by additional binary data.
 547                                   The string is a description that the caller may
 548                                   use to further indicate the reason for the
 549                                   image's exit.
 550
 551   @retval EFI_INVALID_PARAMETER   Invalid parameter
 552   @retval EFI_OUT_OF_RESOURCES    No enough buffer to allocate
 553   @retval EFI_SECURITY_VIOLATION  The current platform policy specifies that the image should not be started.
 554   @retval EFI_SUCCESS             Successfully transfer control to the image's
 555                                   entry point.
 556
 557 **/
 558 EFI_STATUS
 559 EFIAPI
 560 UnitTestStartImage (
 561   IN EFI_HANDLE  ImageHandle,
 562   OUT UINTN      *ExitDataSize,
 563   OUT CHAR16     **ExitData  OPTIONAL
 564   );
 565
 566 /**
 567   Terminates the currently loaded EFI image and returns control to boot services.
 568
 569   @param  ImageHandle             Handle that identifies the image. This
 570                                   parameter is passed to the image on entry.
 571   @param  Status                  The image's exit code.
 572   @param  ExitDataSize            The size, in bytes, of ExitData. Ignored if
 573                                   ExitStatus is EFI_SUCCESS.
 574   @param  ExitData                Pointer to a data buffer that includes a
 575                                   Null-terminated Unicode string, optionally
 576                                   followed by additional binary data. The string
 577                                   is a description that the caller may use to
 578                                   further indicate the reason for the image's
 579                                   exit.
 580
 581   @retval EFI_INVALID_PARAMETER   Image handle is NULL or it is not current
 582                                   image.
 583   @retval EFI_SUCCESS             Successfully terminates the currently loaded
 584                                   EFI image.
 585   @retval EFI_ACCESS_DENIED       Should never reach there.
 586   @retval EFI_OUT_OF_RESOURCES    Could not allocate pool
 587
 588 **/
 589 EFI_STATUS
 590 EFIAPI
 591 UnitTestExit (
 592   IN EFI_HANDLE  ImageHandle,
 593   IN EFI_STATUS  Status,
 594   IN UINTN       ExitDataSize,
 595   IN CHAR16      *ExitData  OPTIONAL
 596   );
 597
 598 /**
 599   Unloads an image.
 600
 601   @param  ImageHandle             Handle that identifies the image to be
 602                                   unloaded.
 603
 604   @retval EFI_SUCCESS             The image has been unloaded.
 605   @retval EFI_UNSUPPORTED         The image has been started, and does not support
 606                                   unload.
 607   @retval EFI_INVALID_PARAMPETER  ImageHandle is not a valid image handle.
 608
 609 **/
 610 EFI_STATUS
 611 EFIAPI
 612 UnitTestUnloadImage (
 613   IN EFI_HANDLE  ImageHandle
 614   );
 615
 616 /**
 617   Terminates all boot services.
 618
 619   @param  ImageHandle            Handle that identifies the exiting image.
 620   @param  MapKey                 Key to the latest memory map.
 621
 622   @retval EFI_SUCCESS            Boot Services terminated
 623   @retval EFI_INVALID_PARAMETER  MapKey is incorrect.
 624
 625 **/
 626 EFI_STATUS
 627 EFIAPI
 628 UnitTestExitBootServices (
 629   IN EFI_HANDLE   ImageHandle,
 630   IN UINTN        MapKey
 631   );
 632
 633 /**
 634   Returns a monotonically increasing count for the platform.
 635
 636   @param[out]  Count            The pointer to returned value.
 637
 638   @retval EFI_SUCCESS           The next monotonic count was returned.
 639   @retval EFI_INVALID_PARAMETER Count is NULL.
 640   @retval EFI_DEVICE_ERROR      The device is not functioning properly.
 641
 642 **/
 643 EFI_STATUS
 644 EFIAPI
 645 UnitTestGetNextMonotonicCount (
 646   OUT UINT64                  *Count
 647   );
 648
 649 /**
 650   Introduces a fine-grained stall.
 651
 652   @param  Microseconds           The number of microseconds to stall execution.
 653
 654   @retval EFI_SUCCESS            Execution was stalled for at least the requested
 655                                  amount of microseconds.
 656   @retval EFI_NOT_AVAILABLE_YET  gMetronome is not available yet
 657
 658 **/
 659 EFI_STATUS
 660 EFIAPI
 661 UnitTestStall (
 662   IN UINTN            Microseconds
 663   );
 664
 665 /**
 666   Sets the system's watchdog timer.
 667
 668   @param  Timeout         The number of seconds to set the watchdog timer to.
 669                           A value of zero disables the timer.
 670   @param  WatchdogCode    The numeric code to log on a watchdog timer timeout
 671                           event. The firmware reserves codes 0x0000 to 0xFFFF.
 672                           Loaders and operating systems may use other timeout
 673                           codes.
 674   @param  DataSize        The size, in bytes, of WatchdogData.
 675   @param  WatchdogData    A data buffer that includes a Null-terminated Unicode
 676                           string, optionally followed by additional binary data.
 677                           The string is a description that the call may use to
 678                           further indicate the reason to be logged with a
 679                           watchdog event.
 680
 681   @return EFI_SUCCESS               Timeout has been set
 682   @return EFI_NOT_AVAILABLE_YET     WatchdogTimer is not available yet
 683   @return EFI_UNSUPPORTED           System does not have a timer (currently not used)
 684   @return EFI_DEVICE_ERROR          Could not complete due to hardware error
 685
 686 **/
 687 EFI_STATUS
 688 EFIAPI
 689 UnitTestSetWatchdogTimer (
 690   IN UINTN    Timeout,
 691   IN UINT64   WatchdogCode,
 692   IN UINTN    DataSize,
 693   IN CHAR16   *WatchdogData OPTIONAL
 694   );
 695
 696 /**
 697   Connects one or more drivers to a controller.
 698
 699   @param  ControllerHandle      The handle of the controller to which driver(s) are to be connected.
 700   @param  DriverImageHandle     A pointer to an ordered list handles that support the
 701                                 EFI_DRIVER_BINDING_PROTOCOL.
 702   @param  RemainingDevicePath   A pointer to the device path that specifies a child of the
 703                                 controller specified by ControllerHandle.
 704   @param  Recursive             If TRUE, then ConnectController() is called recursively
 705                                 until the entire tree of controllers below the controller specified
 706                                 by ControllerHandle have been created. If FALSE, then
 707                                 the tree of controllers is only expanded one level.
 708
 709   @retval EFI_SUCCESS           1) One or more drivers were connected to ControllerHandle.
 710                                 2) No drivers were connected to ControllerHandle, but
 711                                 RemainingDevicePath is not NULL, and it is an End Device
 712                                 Path Node.
 713   @retval EFI_INVALID_PARAMETER ControllerHandle is NULL.
 714   @retval EFI_NOT_FOUND         1) There are no EFI_DRIVER_BINDING_PROTOCOL instances
 715                                 present in the system.
 716                                 2) No drivers were connected to ControllerHandle.
 717   @retval EFI_SECURITY_VIOLATION
 718                                 The user has no permission to start UEFI device drivers on the device path
 719                                 associated with the ControllerHandle or specified by the RemainingDevicePath.
 720
 721 **/
 722 EFI_STATUS
 723 EFIAPI
 724 UnitTestConnectController (
 725   IN  EFI_HANDLE                ControllerHandle,
 726   IN  EFI_HANDLE                *DriverImageHandle    OPTIONAL,
 727   IN  EFI_DEVICE_PATH_PROTOCOL  *RemainingDevicePath  OPTIONAL,
 728   IN  BOOLEAN                   Recursive
 729   );
 730
 731 /**
 732   Disconnects a controller from a driver
 733
 734   @param  ControllerHandle                      ControllerHandle The handle of
 735                                                 the controller from which
 736                                                 driver(s)  are to be
 737                                                 disconnected.
 738   @param  DriverImageHandle                     DriverImageHandle The driver to
 739                                                 disconnect from ControllerHandle.
 740   @param  ChildHandle                           ChildHandle The handle of the
 741                                                 child to destroy.
 742
 743   @retval EFI_SUCCESS                           One or more drivers were
 744                                                 disconnected from the controller.
 745   @retval EFI_SUCCESS                           On entry, no drivers are managing
 746                                                 ControllerHandle.
 747   @retval EFI_SUCCESS                           DriverImageHandle is not NULL,
 748                                                 and on entry DriverImageHandle is
 749                                                 not managing ControllerHandle.
 750   @retval EFI_INVALID_PARAMETER                 ControllerHandle is NULL.
 751   @retval EFI_INVALID_PARAMETER                 DriverImageHandle is not NULL,
 752                                                 and it is not a valid EFI_HANDLE.
 753   @retval EFI_INVALID_PARAMETER                 ChildHandle is not NULL, and it
 754                                                 is not a valid EFI_HANDLE.
 755   @retval EFI_OUT_OF_RESOURCES                  There are not enough resources
 756                                                 available to disconnect any
 757                                                 drivers from ControllerHandle.
 758   @retval EFI_DEVICE_ERROR                      The controller could not be
 759                                                 disconnected because of a device
 760                                                 error.
 761
 762 **/
 763 EFI_STATUS
 764 EFIAPI
 765 UnitTestDisconnectController (
 766   IN  EFI_HANDLE  ControllerHandle,
 767   IN  EFI_HANDLE  DriverImageHandle  OPTIONAL,
 768   IN  EFI_HANDLE  ChildHandle        OPTIONAL
 769   );
 770
 771 /**
 772   Locates the installed protocol handler for the handle, and
 773   invokes it to obtain the protocol interface. Usage information
 774   is registered in the protocol data base.
 775
 776   @param  UserHandle             The handle to obtain the protocol interface on
 777   @param  Protocol               The ID of the protocol
 778   @param  Interface              The location to return the protocol interface
 779   @param  ImageHandle            The handle of the Image that is opening the
 780                                  protocol interface specified by Protocol and
 781                                  Interface.
 782   @param  ControllerHandle       The controller handle that is requiring this
 783                                  interface.
 784   @param  Attributes             The open mode of the protocol interface
 785                                  specified by Handle and Protocol.
 786
 787   @retval EFI_INVALID_PARAMETER  Protocol is NULL.
 788   @retval EFI_SUCCESS            Get the protocol interface.
 789
 790 **/
 791 EFI_STATUS
 792 EFIAPI
 793 UnitTestOpenProtocol (
 794   IN  EFI_HANDLE                UserHandle,
 795   IN  EFI_GUID                  *Protocol,
 796   OUT VOID                      **Interface OPTIONAL,
 797   IN  EFI_HANDLE                ImageHandle,
 798   IN  EFI_HANDLE                ControllerHandle,
 799   IN  UINT32                    Attributes
 800   );
 801
 802 /**
 803   Closes a protocol on a handle that was opened using OpenProtocol().
 804
 805   @param  UserHandle             The handle for the protocol interface that was
 806                                  previously opened with OpenProtocol(), and is
 807                                  now being closed.
 808   @param  Protocol               The published unique identifier of the protocol.
 809                                  It is the caller's responsibility to pass in a
 810                                  valid GUID.
 811   @param  AgentHandle            The handle of the agent that is closing the
 812                                  protocol interface.
 813   @param  ControllerHandle       If the agent that opened a protocol is a driver
 814                                  that follows the EFI Driver Model, then this
 815                                  parameter is the controller handle that required
 816                                  the protocol interface. If the agent does not
 817                                  follow the EFI Driver Model, then this parameter
 818                                  is optional and may be NULL.
 819
 820   @retval EFI_SUCCESS            The protocol instance was closed.
 821   @retval EFI_INVALID_PARAMETER  Handle, AgentHandle or ControllerHandle is not a
 822                                  valid EFI_HANDLE.
 823   @retval EFI_NOT_FOUND          Can not find the specified protocol or
 824                                  AgentHandle.
 825
 826 **/
 827 EFI_STATUS
 828 EFIAPI
 829 UnitTestCloseProtocol (
 830   IN  EFI_HANDLE                UserHandle,
 831   IN  EFI_GUID                  *Protocol,
 832   IN  EFI_HANDLE                AgentHandle,
 833   IN  EFI_HANDLE                ControllerHandle
 834   );
 835
 836 /**
 837   Return information about Opened protocols in the system
 838
 839   @param  UserHandle             The handle to close the protocol interface on
 840   @param  Protocol               The ID of the protocol
 841   @param  EntryBuffer            A pointer to a buffer of open protocol
 842                                  information in the form of
 843                                  EFI_OPEN_PROTOCOL_INFORMATION_ENTRY structures.
 844   @param  EntryCount             Number of EntryBuffer entries
 845
 846 **/
 847 EFI_STATUS
 848 EFIAPI
 849 UnitTestOpenProtocolInformation (
 850   IN  EFI_HANDLE                          UserHandle,
 851   IN  EFI_GUID                            *Protocol,
 852   OUT EFI_OPEN_PROTOCOL_INFORMATION_ENTRY **EntryBuffer,
 853   OUT UINTN                               *EntryCount
 854   );
 855
 856 /**
 857   Retrieves the list of protocol interface GUIDs that are installed on a handle in a buffer allocated
 858   from pool.
 859
 860   @param  UserHandle             The handle from which to retrieve the list of
 861                                  protocol interface GUIDs.
 862   @param  ProtocolBuffer         A pointer to the list of protocol interface GUID
 863                                  pointers that are installed on Handle.
 864   @param  ProtocolBufferCount    A pointer to the number of GUID pointers present
 865                                  in ProtocolBuffer.
 866
 867   @retval EFI_SUCCESS            The list of protocol interface GUIDs installed
 868                                  on Handle was returned in ProtocolBuffer. The
 869                                  number of protocol interface GUIDs was returned
 870                                  in ProtocolBufferCount.
 871   @retval EFI_INVALID_PARAMETER  Handle is NULL.
 872   @retval EFI_INVALID_PARAMETER  Handle is not a valid EFI_HANDLE.
 873   @retval EFI_INVALID_PARAMETER  ProtocolBuffer is NULL.
 874   @retval EFI_INVALID_PARAMETER  ProtocolBufferCount is NULL.
 875   @retval EFI_OUT_OF_RESOURCES   There is not enough pool memory to store the
 876                                  results.
 877
 878 **/
 879 EFI_STATUS
 880 EFIAPI
 881 UnitTestProtocolsPerHandle (
 882   IN EFI_HANDLE       UserHandle,
 883   OUT EFI_GUID        ***ProtocolBuffer,
 884   OUT UINTN           *ProtocolBufferCount
 885   );
 886
 887 /**
 888   Function returns an array of handles that support the requested protocol
 889   in a buffer allocated from pool. This is a version of UnitTestLocateHandle()
 890   that allocates a buffer for the caller.
 891
 892   @param  SearchType             Specifies which handle(s) are to be returned.
 893   @param  Protocol               Provides the protocol to search by.    This
 894                                  parameter is only valid for SearchType
 895                                  ByProtocol.
 896   @param  SearchKey              Supplies the search key depending on the
 897                                  SearchType.
 898   @param  NumberHandles          The number of handles returned in Buffer.
 899   @param  Buffer                 A pointer to the buffer to return the requested
 900                                  array of  handles that support Protocol.
 901
 902   @retval EFI_SUCCESS            The result array of handles was returned.
 903   @retval EFI_NOT_FOUND          No handles match the search.
 904   @retval EFI_OUT_OF_RESOURCES   There is not enough pool memory to store the
 905                                  matching results.
 906   @retval EFI_INVALID_PARAMETER  One or more parameters are not valid.
 907
 908 **/
 909 EFI_STATUS
 910 EFIAPI
 911 UnitTestLocateHandleBuffer (
 912   IN EFI_LOCATE_SEARCH_TYPE       SearchType,
 913   IN EFI_GUID                     *Protocol OPTIONAL,
 914   IN VOID                         *SearchKey OPTIONAL,
 915   IN OUT UINTN                    *NumberHandles,
 916   OUT EFI_HANDLE                  **Buffer
 917   );
 918
 919 /**
 920   Return the first Protocol Interface that matches the Protocol GUID. If
 921   Registration is passed in, return a Protocol Instance that was just add
 922   to the system. If Registration is NULL return the first Protocol Interface
 923   you find.
 924
 925   @param  Protocol               The protocol to search for
 926   @param  Registration           Optional Registration Key returned from
 927                                  RegisterProtocolNotify()
 928   @param  Interface              Return the Protocol interface (instance).
 929
 930   @retval EFI_SUCCESS            If a valid Interface is returned
 931   @retval EFI_INVALID_PARAMETER  Invalid parameter
 932   @retval EFI_NOT_FOUND          Protocol interface not found
 933
 934 **/
 935 EFI_STATUS
 936 EFIAPI
 937 UnitTestLocateProtocol (
 938   IN  EFI_GUID  *Protocol,
 939   IN  VOID      *Registration OPTIONAL,
 940   OUT VOID      **Interface
 941   );
 942
 943 /**
 944   Installs a list of protocol interface into the boot services environment.
 945   This function calls InstallProtocolInterface() in a loop. If any error
 946   occurs all the protocols added by this function are removed. This is
 947   basically a lib function to save space.
 948
 949   @param  Handle                 The handle to install the protocol handlers on,
 950                                  or NULL if a new handle is to be allocated
 951   @param  ...                    EFI_GUID followed by protocol instance. A NULL
 952                                  terminates the  list. The pairs are the
 953                                  arguments to InstallProtocolInterface(). All the
 954                                  protocols are added to Handle.
 955
 956   @retval EFI_SUCCESS            All the protocol interface was installed.
 957   @retval EFI_OUT_OF_RESOURCES   There was not enough memory in pool to install all the protocols.
 958   @retval EFI_ALREADY_STARTED    A Device Path Protocol instance was passed in that is already present in
 959                                  the handle database.
 960   @retval EFI_INVALID_PARAMETER  Handle is NULL.
 961   @retval EFI_INVALID_PARAMETER  Protocol is already installed on the handle specified by Handle.
 962
 963 **/
 964 EFI_STATUS
 965 EFIAPI
 966 UnitTestInstallMultipleProtocolInterfaces (
 967   IN OUT EFI_HANDLE           *Handle,
 968   ...
 969   );
 970
 971 /**
 972   Uninstalls a list of protocol interface in the boot services environment.
 973   This function calls UninstallProtocolInterface() in a loop. This is
 974   basically a lib function to save space.
 975
 976   @param  Handle                 The handle to uninstall the protocol
 977   @param  ...                    EFI_GUID followed by protocol instance. A NULL
 978                                  terminates the  list. The pairs are the
 979                                  arguments to UninstallProtocolInterface(). All
 980                                  the protocols are added to Handle.
 981
 982   @return Status code
 983
 984 **/
 985 EFI_STATUS
 986 EFIAPI
 987 UnitTestUninstallMultipleProtocolInterfaces (
 988   IN EFI_HANDLE           Handle,
 989   ...
 990   );
 991
 992 /**
 993   Computes and returns a 32-bit CRC for a data buffer.
 994
 995   @param[in]   Data             A pointer to the buffer on which the 32-bit CRC is to be computed.
 996   @param[in]   DataSize         The number of bytes in the buffer Data.
 997   @param[out]  Crc32            The 32-bit CRC that was computed for the data buffer specified by Data
 998                                 and DataSize.
 999
1000   @retval EFI_SUCCESS           The 32-bit CRC was computed for the data buffer and returned in
1001                                 Crc32.
1002   @retval EFI_INVALID_PARAMETER Data is NULL.
1003   @retval EFI_INVALID_PARAMETER Crc32 is NULL.
1004   @retval EFI_INVALID_PARAMETER DataSize is 0.
1005
1006 **/
1007 EFI_STATUS
1008 EFIAPI
1009 UnitTestCalculateCrc32 (
1010   IN  VOID                              *Data,
1011   IN  UINTN                             DataSize,
1012   OUT UINT32                            *Crc32
1013   );
1014
1015 /**
1016   Creates an event in a group.
1017
1018   @param  Type                   The type of event to create and its mode and
1019                                  attributes
1020   @param  NotifyTpl              The task priority level of event notifications
1021   @param  NotifyFunction         Pointer to the events notification function
1022   @param  NotifyContext          Pointer to the notification functions context;
1023                                  corresponds to parameter "Context" in the
1024                                  notification function
1025   @param  EventGroup             GUID for EventGroup if NULL act the same as
1026                                  gBS->CreateEvent().
1027   @param  Event                  Pointer to the newly created event if the call
1028                                  succeeds; undefined otherwise
1029
1030   @retval EFI_SUCCESS            The event structure was created
1031   @retval EFI_INVALID_PARAMETER  One of the parameters has an invalid value
1032   @retval EFI_OUT_OF_RESOURCES   The event could not be allocated
1033
1034 **/
1035 EFI_STATUS
1036 EFIAPI
1037 UnitTestCreateEventEx (
1038   IN UINT32                   Type,
1039   IN EFI_TPL                  NotifyTpl,
1040   IN EFI_EVENT_NOTIFY         NotifyFunction, OPTIONAL
1041   IN CONST VOID               *NotifyContext, OPTIONAL
1042   IN CONST EFI_GUID           *EventGroup,    OPTIONAL
1043   OUT EFI_EVENT               *Event
1044   );
1045
1046 #endif