UnitTestFrameworkPkg/Include/Library/UnitTestPersistenceLib.h

   1 /** @file
   2   This header file describes a library that contains functions to save and
   3   restore unit test internal state, in case the test needs to pause and resume
   4   (eg. a reboot-based test).
   5
   6   Copyright (c) Microsoft Corporation.<BR>
   7   Copyright (c) 2019 - 2022, Intel Corporation. All rights reserved.<BR>
   8   SPDX-License-Identifier: BSD-2-Clause-Patent
   9
  10 **/
  11
  12 #ifndef _UNIT_TEST_PERSISTENCE_LIB_H_
  13 #define _UNIT_TEST_PERSISTENCE_LIB_H_
  14
  15 #include <Library/UnitTestLib.h>
  16
  17 #define UNIT_TEST_PERSISTENCE_LIB_VERSION  1
  18
  19 /**
  20   Determines whether a persistence cache already exists for
  21   the given framework.
  22
  23   @param[in]  FrameworkHandle   A pointer to the framework that is being persisted.
  24
  25   @retval     TRUE
  26   @retval     FALSE   Cache doesn't exist or an error occurred.
  27
  28 **/
  29 BOOLEAN
  30 EFIAPI
  31 DoesCacheExist (
  32   IN UNIT_TEST_FRAMEWORK_HANDLE  FrameworkHandle
  33   );
  34
  35 /**
  36   Will save the data associated with an internal Unit Test Framework
  37   state in a manner that can persist a Unit Test Application quit or
  38   even a system reboot.
  39
  40   @param[in]  FrameworkHandle   A pointer to the framework that is being persisted.
  41   @param[in]  SaveData          A pointer to the buffer containing the serialized
  42                                 framework internal state.
  43   @param[in]  SaveStateSize     The size of SaveData in bytes.
  44
  45   @retval     EFI_SUCCESS   Data is persisted and the test can be safely quit.
  46   @retval     Others        Data is not persisted and test cannot be resumed upon exit.
  47
  48 **/
  49 EFI_STATUS
  50 EFIAPI
  51 SaveUnitTestCache (
  52   IN UNIT_TEST_FRAMEWORK_HANDLE  FrameworkHandle,
  53   IN VOID                        *SaveData,
  54   IN UINTN                       SaveStateSize
  55   );
  56
  57 /**
  58   Will retrieve any cached state associated with the given framework.
  59   Will allocate a buffer to hold the loaded data.
  60
  61   @param[in]  FrameworkHandle   A pointer to the framework that is being persisted.
  62   @param[out] SaveData          A pointer pointer that will be updated with the address
  63                                 of the loaded data buffer.
  64   @param[out] SaveStateSize     Return the size of SaveData in bytes.
  65
  66   @retval     EFI_SUCCESS       Data has been loaded successfully and SaveData is updated
  67                                 with a pointer to the buffer.
  68   @retval     Others            An error has occurred and no data has been loaded. SaveData
  69                                 is set to NULL.
  70
  71 **/
  72 EFI_STATUS
  73 EFIAPI
  74 LoadUnitTestCache (
  75   IN  UNIT_TEST_FRAMEWORK_HANDLE  FrameworkHandle,
  76   OUT VOID                        **SaveData,
  77   OUT UINTN                       *SaveStateSize
  78   );
  79
  80 #endif