[mirror_edk2.git] / UnitTestFrameworkPkg / Library / UnitTestLib / UnitTestLib.c

/**\r
  Implement UnitTestLib\r
\r
  Copyright (c) Microsoft Corporation.\r
  Copyright (c) 2022, Intel Corporation. All rights reserved.<BR>\r
  SPDX-License-Identifier: BSD-2-Clause-Patent\r
**/\r
\r
#include <Uefi.h>\r
#include <Library/UnitTestLib.h>\r
#include <Library/BaseLib.h>\r
#include <Library/BaseMemoryLib.h>\r
#include <Library/MemoryAllocationLib.h>\r
#include <Library/DebugLib.h>\r
#include <Library/UnitTestPersistenceLib.h>\r
#include <Library/UnitTestResultReportLib.h>\r
\r
///\r
/// Forward declaration of prototype\r
///\r
STATIC\r
VOID\r
UpdateTestFromSave (\r
  IN OUT UNIT_TEST              *Test,\r
  IN     UNIT_TEST_SAVE_HEADER  *SavedState\r
  );\r
\r
/**\r
  This function will determine whether the short name violates any rules that would\r
  prevent it from being used as a reporting name or as a serialization name.\r
\r
  Example: If the name cannot be serialized to a filesystem file name.\r
\r
  @param[in]  ShortTitleString  A pointer to the short title string to be evaluated.\r
\r
  @retval  TRUE   The string is acceptable.\r
  @retval  FALSE  The string should not be used.\r
\r
**/\r
STATIC\r
BOOLEAN\r
IsFrameworkShortNameValid (\r
  IN CHAR8  *ShortTitleString\r
  )\r
{\r
  // TODO: Finish this function.\r
  return TRUE;\r
}\r
\r
STATIC\r
CHAR8 *\r
AllocateAndCopyString (\r
  IN CHAR8  *StringToCopy\r
  )\r
{\r
  CHAR8  *NewString;\r
  UINTN  NewStringLength;\r
\r
  NewString       = NULL;\r
  NewStringLength = AsciiStrnLenS (StringToCopy, UNIT_TEST_MAX_STRING_LENGTH) + 1;\r
  NewString       = AllocatePool (NewStringLength * sizeof (CHAR8));\r
  if (NewString != NULL) {\r
    AsciiStrCpyS (NewString, NewStringLength, StringToCopy);\r
  }\r
\r
  return NewString;\r
}\r
\r
STATIC\r
VOID\r
SetFrameworkFingerprint (\r
  OUT UINT8                *Fingerprint,\r
  IN  UNIT_TEST_FRAMEWORK  *Framework\r
  )\r
{\r
  UINT32  NewFingerprint;\r
\r
  // For this one we'll just use the title and version as the unique fingerprint.\r
  NewFingerprint = CalculateCrc32 (Framework->Title, (AsciiStrLen (Framework->Title) * sizeof (CHAR8)));\r
  NewFingerprint = (NewFingerprint >> 8) ^ CalculateCrc32 (Framework->VersionString, (AsciiStrLen (Framework->VersionString) * sizeof (CHAR8)));\r
\r
  CopyMem (Fingerprint, &NewFingerprint, UNIT_TEST_FINGERPRINT_SIZE);\r
  return;\r
}\r
\r
STATIC\r
VOID\r
SetSuiteFingerprint (\r
  OUT UINT8                *Fingerprint,\r
  IN  UNIT_TEST_FRAMEWORK  *Framework,\r
  IN  UNIT_TEST_SUITE      *Suite\r
  )\r
{\r
  UINT32  NewFingerprint;\r
\r
  // For this one, we'll use the fingerprint from the framework, and the title of the suite.\r
  NewFingerprint = CalculateCrc32 (&Framework->Fingerprint[0], UNIT_TEST_FINGERPRINT_SIZE);\r
  NewFingerprint = (NewFingerprint >> 8) ^ CalculateCrc32 (Suite->Title, (AsciiStrLen (Suite->Title) * sizeof (CHAR8)));\r
  NewFingerprint = (NewFingerprint >> 8) ^ CalculateCrc32 (Suite->Name, (AsciiStrLen (Suite->Name) * sizeof (CHAR8)));\r
\r
  CopyMem (Fingerprint, &NewFingerprint, UNIT_TEST_FINGERPRINT_SIZE);\r
  return;\r
}\r
\r
STATIC\r
VOID\r
SetTestFingerprint (\r
  OUT UINT8            *Fingerprint,\r
  IN  UNIT_TEST_SUITE  *Suite,\r
  IN  UNIT_TEST        *Test\r
  )\r
{\r
  UINT32  NewFingerprint;\r
\r
  // For this one, we'll use the fingerprint from the suite, and the description and classname of the test.\r
  NewFingerprint = CalculateCrc32 (&Suite->Fingerprint[0], UNIT_TEST_FINGERPRINT_SIZE);\r
  NewFingerprint = (NewFingerprint >> 8) ^ CalculateCrc32 (Test->Description, (AsciiStrLen (Test->Description) * sizeof (CHAR8)));\r
  NewFingerprint = (NewFingerprint >> 8) ^ CalculateCrc32 (Test->Name, (AsciiStrLen (Test->Name) * sizeof (CHAR8)));\r
\r
  CopyMem (Fingerprint, &NewFingerprint, UNIT_TEST_FINGERPRINT_SIZE);\r
  return;\r
}\r
\r
STATIC\r
BOOLEAN\r
CompareFingerprints (\r
  IN UINT8  *FingerprintA,\r
  IN UINT8  *FingerprintB\r
  )\r
{\r
  return (CompareMem (FingerprintA, FingerprintB, UNIT_TEST_FINGERPRINT_SIZE) == 0);\r
}\r
\r
/**\r
  Cleanup a test framework.\r
\r
  After tests are run, this will teardown the entire framework and free all\r
  allocated data within.\r
\r
  @param[in]  FrameworkHandle  A handle to the current running framework that\r
                               dispatched the test.  Necessary for recording\r
                               certain test events with the framework.\r
\r
  @retval  EFI_SUCCESS            All resources associated with framework were\r
                                  freed.\r
  @retval  EFI_INVALID_PARAMETER  FrameworkHandle is NULL.\r
**/\r
EFI_STATUS\r
EFIAPI\r
FreeUnitTestFramework (\r
  IN UNIT_TEST_FRAMEWORK_HANDLE  FrameworkHandle\r
  )\r
{\r
  // TODO: Finish this function.\r
  return EFI_SUCCESS;\r
}\r
\r
STATIC\r
EFI_STATUS\r
FreeUnitTestSuiteEntry (\r
  IN UNIT_TEST_SUITE_LIST_ENTRY  *SuiteEntry\r
  )\r
{\r
  // TODO: Finish this function.\r
  return EFI_SUCCESS;\r
}\r
\r
STATIC\r
EFI_STATUS\r
FreeUnitTestTestEntry (\r
  IN UNIT_TEST_LIST_ENTRY  *TestEntry\r
  )\r
{\r
  // TODO: Finish this function.\r
  return EFI_SUCCESS;\r
}\r
\r
/**\r
  Method to Initialize the Unit Test framework.  This function registers the\r
  test name and also initializes the internal state of the test framework to\r
  receive any new suites and tests.\r
\r
  @param[out]  FrameworkHandle  Unit test framework to be created.\r
  @param[in]   Title            Null-terminated ASCII string that is the user\r
                                friendly name of the framework. String is\r
                                copied.\r
  @param[in]   ShortTitle       Null-terminated ASCII short string that is the\r
                                short name of the framework with no spaces.\r
                                String is copied.\r
  @param[in]   VersionString    Null-terminated ASCII version string for the\r
                                framework. String is copied.\r
\r
  @retval  EFI_SUCCESS            The unit test framework was initialized.\r
  @retval  EFI_INVALID_PARAMETER  FrameworkHandle is NULL.\r
  @retval  EFI_INVALID_PARAMETER  Title is NULL.\r
  @retval  EFI_INVALID_PARAMETER  ShortTitle is NULL.\r
  @retval  EFI_INVALID_PARAMETER  VersionString is NULL.\r
  @retval  EFI_INVALID_PARAMETER  ShortTitle is invalid.\r
  @retval  EFI_OUT_OF_RESOURCES   There are not enough resources available to\r
                                  initialize the unit test framework.\r
**/\r
EFI_STATUS\r
EFIAPI\r
InitUnitTestFramework (\r
  OUT UNIT_TEST_FRAMEWORK_HANDLE  *FrameworkHandle,\r
  IN  CHAR8                       *Title,\r
  IN  CHAR8                       *ShortTitle,\r
  IN  CHAR8                       *VersionString\r
  )\r
{\r
  EFI_STATUS                  Status;\r
  UNIT_TEST_FRAMEWORK_HANDLE  NewFrameworkHandle;\r
  UNIT_TEST_FRAMEWORK         *NewFramework;\r
  UINTN                       SaveStateSize;\r
\r
  Status       = EFI_SUCCESS;\r
  NewFramework = NULL;\r
\r
  //\r
  // First, check all pointers and make sure nothing's broked.\r
  //\r
  if ((FrameworkHandle == NULL) || (Title == NULL) ||\r
      (ShortTitle == NULL) || (VersionString == NULL))\r
  {\r
    return EFI_INVALID_PARAMETER;\r
  }\r
\r
  //\r
  // Next, determine whether all of the strings are good to use.\r
  //\r
  if (!IsFrameworkShortNameValid (ShortTitle)) {\r
    return EFI_INVALID_PARAMETER;\r
  }\r
\r
  //\r
  // Next, set aside some space to start messing with the framework.\r
  //\r
  NewFramework = AllocateZeroPool (sizeof (UNIT_TEST_FRAMEWORK));\r
  if (NewFramework == NULL) {\r
    return EFI_OUT_OF_RESOURCES;\r
  }\r
\r
  //\r
  // Next, set up all the test data.\r
  //\r
  NewFrameworkHandle          = (UNIT_TEST_FRAMEWORK_HANDLE)NewFramework;\r
  NewFramework->Title         = AllocateAndCopyString (Title);\r
  NewFramework->ShortTitle    = AllocateAndCopyString (ShortTitle);\r
  NewFramework->VersionString = AllocateAndCopyString (VersionString);\r
  NewFramework->Log           = NULL;\r
  NewFramework->CurrentTest   = NULL;\r
  NewFramework->SavedState    = NULL;\r
  if ((NewFramework->Title == NULL) ||\r
      (NewFramework->ShortTitle == NULL) ||\r
      (NewFramework->VersionString == NULL))\r
  {\r
    Status = EFI_OUT_OF_RESOURCES;\r
    goto Exit;\r
  }\r
\r
  InitializeListHead (&(NewFramework->TestSuiteList));\r
\r
  //\r
  // Create the framework fingerprint.\r
  //\r
  SetFrameworkFingerprint (&NewFramework->Fingerprint[0], NewFramework);\r
\r
  //\r
  // If there is a persisted context, load it now.\r
  //\r
  if (DoesCacheExist (NewFrameworkHandle)) {\r
    Status = LoadUnitTestCache (NewFrameworkHandle, (VOID **)(&NewFramework->SavedState), &SaveStateSize);\r
    if (EFI_ERROR (Status)) {\r
      //\r
      // Don't actually report it as an error, but emit a warning.\r
      //\r
      DEBUG ((DEBUG_ERROR, "%a - Cache was detected, but failed to load.\n", __FUNCTION__));\r
      Status = EFI_SUCCESS;\r
    }\r
  }\r
\r
Exit:\r
  //\r
  // If we're good, then let's copy the framework.\r
  //\r
  if (!EFI_ERROR (Status)) {\r
    *FrameworkHandle = NewFrameworkHandle;\r
  } else {\r
    //\r
    // Otherwise, we need to undo this horrible thing that we've done.\r
    //\r
    FreeUnitTestFramework (NewFrameworkHandle);\r
  }\r
\r
  return Status;\r
}\r
\r
/**\r
  Registers a Unit Test Suite in the Unit Test Framework.\r
  At least one test suite must be registered, because all test cases must be\r
  within a unit test suite.\r
\r
  @param[out]  SuiteHandle      Unit test suite to create\r
  @param[in]   FrameworkHandle  Unit test framework to add unit test suite to\r
  @param[in]   Title            Null-terminated ASCII string that is the user\r
                                friendly name of the test suite.  String is\r
                                copied.\r
  @param[in]   Name             Null-terminated ASCII string that is the short\r
                                name of the test suite with no spaces.  String\r
                                is copied.\r
  @param[in]   Setup            Setup function, runs before suite.  This is an\r
                                optional parameter that may be NULL.\r
  @param[in]   Teardown         Teardown function, runs after suite.  This is an\r
                                optional parameter that may be NULL.\r
\r
  @retval  EFI_SUCCESS            The unit test suite was created.\r
  @retval  EFI_INVALID_PARAMETER  SuiteHandle is NULL.\r
  @retval  EFI_INVALID_PARAMETER  FrameworkHandle is NULL.\r
  @retval  EFI_INVALID_PARAMETER  Title is NULL.\r
  @retval  EFI_INVALID_PARAMETER  Name is NULL.\r
  @retval  EFI_OUT_OF_RESOURCES   There are not enough resources available to\r
                                  initialize the unit test suite.\r
**/\r
EFI_STATUS\r
EFIAPI\r
CreateUnitTestSuite (\r
  OUT UNIT_TEST_SUITE_HANDLE      *SuiteHandle,\r
  IN  UNIT_TEST_FRAMEWORK_HANDLE  FrameworkHandle,\r
  IN  CHAR8                       *Title,\r
  IN  CHAR8                       *Name,\r
  IN  UNIT_TEST_SUITE_SETUP       Setup     OPTIONAL,\r
  IN  UNIT_TEST_SUITE_TEARDOWN    Teardown  OPTIONAL\r
  )\r
{\r
  EFI_STATUS                  Status;\r
  UNIT_TEST_SUITE_LIST_ENTRY  *NewSuiteEntry;\r
  UNIT_TEST_FRAMEWORK         *Framework;\r
\r
  Status    = EFI_SUCCESS;\r
  Framework = (UNIT_TEST_FRAMEWORK *)FrameworkHandle;\r
\r
  //\r
  // First, let's check to make sure that our parameters look good.\r
  //\r
  if ((SuiteHandle == NULL) || (Framework == NULL) || (Title == NULL) || (Name == NULL)) {\r
    return EFI_INVALID_PARAMETER;\r
  }\r
\r
  //\r
  // Create the new entry.\r
  //\r
  NewSuiteEntry = AllocateZeroPool (sizeof (UNIT_TEST_SUITE_LIST_ENTRY));\r
  if (NewSuiteEntry == NULL) {\r
    return EFI_OUT_OF_RESOURCES;\r
  }\r
\r
  //\r
  // Copy the fields we think we need.\r
  //\r
  NewSuiteEntry->UTS.NumTests        = 0;\r
  NewSuiteEntry->UTS.Title           = AllocateAndCopyString (Title);\r
  NewSuiteEntry->UTS.Name            = AllocateAndCopyString (Name);\r
  NewSuiteEntry->UTS.Setup           = Setup;\r
  NewSuiteEntry->UTS.Teardown        = Teardown;\r
  NewSuiteEntry->UTS.ParentFramework = FrameworkHandle;\r
  InitializeListHead (&(NewSuiteEntry->Entry));             // List entry for sibling suites.\r
  InitializeListHead (&(NewSuiteEntry->UTS.TestCaseList));  // List entry for child tests.\r
  if (NewSuiteEntry->UTS.Title == NULL) {\r
    Status = EFI_OUT_OF_RESOURCES;\r
    goto Exit;\r
  }\r
\r
  if (NewSuiteEntry->UTS.Name == NULL) {\r
    Status = EFI_OUT_OF_RESOURCES;\r
    goto Exit;\r
  }\r
\r
  //\r
  // Create the suite fingerprint.\r
  //\r
  SetSuiteFingerprint (&NewSuiteEntry->UTS.Fingerprint[0], Framework, &NewSuiteEntry->UTS);\r
\r
Exit:\r
  //\r
  // If everything is going well, add the new suite to the tail list for the framework.\r
  //\r
  if (!EFI_ERROR (Status)) {\r
    InsertTailList (&(Framework->TestSuiteList), (LIST_ENTRY *)NewSuiteEntry);\r
    *SuiteHandle = (UNIT_TEST_SUITE_HANDLE)(&NewSuiteEntry->UTS);\r
  } else {\r
    //\r
    // Otherwise, make with the destruction.\r
    //\r
    FreeUnitTestSuiteEntry (NewSuiteEntry);\r
  }\r
\r
  return Status;\r
}\r
\r
/**\r
  Adds test case to Suite\r
\r
  @param[in]  SuiteHandle   Unit test suite to add test to.\r
  @param[in]  Description   Null-terminated ASCII string that is the user\r
                            friendly description of a test.  String is copied.\r
  @param[in]  Name          Null-terminated ASCII string that is the short name\r
                            of the test with no spaces.  String is copied.\r
  @param[in]  Function      Unit test function.\r
  @param[in]  Prerequisite  Prerequisite function, runs before test.  This is\r
                            an optional parameter that may be NULL.\r
  @param[in]  CleanUp       Clean up function, runs after test.  This is an\r
                            optional parameter that may be NULL.\r
  @param[in]  Context       Pointer to context.    This is an optional parameter\r
                            that may be NULL.\r
\r
  @retval  EFI_SUCCESS            The unit test case was added to Suite.\r
  @retval  EFI_INVALID_PARAMETER  SuiteHandle is NULL.\r
  @retval  EFI_INVALID_PARAMETER  Description is NULL.\r
  @retval  EFI_INVALID_PARAMETER  Name is NULL.\r
  @retval  EFI_INVALID_PARAMETER  Function is NULL.\r
  @retval  EFI_OUT_OF_RESOURCES   There are not enough resources available to\r
                                  add the unit test case to Suite.\r
**/\r
EFI_STATUS\r
EFIAPI\r
AddTestCase (\r
  IN UNIT_TEST_SUITE_HANDLE  SuiteHandle,\r
  IN CHAR8                   *Description,\r
  IN CHAR8                   *Name,\r
  IN UNIT_TEST_FUNCTION      Function,\r
  IN UNIT_TEST_PREREQUISITE  Prerequisite  OPTIONAL,\r
  IN UNIT_TEST_CLEANUP       CleanUp       OPTIONAL,\r
  IN UNIT_TEST_CONTEXT       Context       OPTIONAL\r
  )\r
{\r
  EFI_STATUS            Status;\r
  UNIT_TEST_LIST_ENTRY  *NewTestEntry;\r
  UNIT_TEST_FRAMEWORK   *ParentFramework;\r
  UNIT_TEST_SUITE       *Suite;\r
\r
  Status = EFI_SUCCESS;\r
  Suite  = (UNIT_TEST_SUITE *)SuiteHandle;\r
\r
  //\r
  // First, let's check to make sure that our parameters look good.\r
  //\r
  if ((Suite == NULL) || (Description == NULL) || (Name == NULL) || (Function == NULL)) {\r
    return EFI_INVALID_PARAMETER;\r
  }\r
\r
  ParentFramework = (UNIT_TEST_FRAMEWORK *)Suite->ParentFramework;\r
  //\r
  // Create the new entry.\r
  NewTestEntry = AllocateZeroPool (sizeof (UNIT_TEST_LIST_ENTRY));\r
  if (NewTestEntry == NULL) {\r
    return EFI_OUT_OF_RESOURCES;\r
  }\r
\r
  //\r
  // Copy the fields we think we need.\r
  NewTestEntry->UT.Description       = AllocateAndCopyString (Description);\r
  NewTestEntry->UT.Name              = AllocateAndCopyString (Name);\r
  NewTestEntry->UT.FailureType       = FAILURETYPE_NOFAILURE;\r
  NewTestEntry->UT.FailureMessage[0] = '\0';\r
  NewTestEntry->UT.Log               = NULL;\r
  NewTestEntry->UT.Prerequisite      = Prerequisite;\r
  NewTestEntry->UT.CleanUp           = CleanUp;\r
  NewTestEntry->UT.RunTest           = Function;\r
  NewTestEntry->UT.Context           = Context;\r
  NewTestEntry->UT.Result            = UNIT_TEST_PENDING;\r
  NewTestEntry->UT.ParentSuite       = SuiteHandle;\r
  InitializeListHead (&(NewTestEntry->Entry));  // List entry for sibling tests.\r
  if (NewTestEntry->UT.Description == NULL) {\r
    Status = EFI_OUT_OF_RESOURCES;\r
    goto Exit;\r
  }\r
\r
  if (NewTestEntry->UT.Name == NULL) {\r
    Status = EFI_OUT_OF_RESOURCES;\r
    goto Exit;\r
  }\r
\r
  //\r
  // Create the test fingerprint.\r
  //\r
  SetTestFingerprint (&NewTestEntry->UT.Fingerprint[0], Suite, &NewTestEntry->UT);\r
\r
  // TODO: Make sure that duplicate fingerprints cannot be created.\r
\r
  //\r
  // If there is saved test data, update this record.\r
  //\r
  if (ParentFramework->SavedState != NULL) {\r
    UpdateTestFromSave (&NewTestEntry->UT, ParentFramework->SavedState);\r
  }\r
\r
Exit:\r
  //\r
  // If everything is going well, add the new suite to the tail list for the framework.\r
  //\r
  if (!EFI_ERROR (Status)) {\r
    InsertTailList (&(Suite->TestCaseList), (LIST_ENTRY *)NewTestEntry);\r
    Suite->NumTests++;\r
  } else {\r
    //\r
    // Otherwise, make with the destruction.\r
    //\r
    FreeUnitTestTestEntry (NewTestEntry);\r
  }\r
\r
  return Status;\r
}\r
\r
STATIC\r
VOID\r
UpdateTestFromSave (\r
  IN OUT UNIT_TEST              *Test,\r
  IN     UNIT_TEST_SAVE_HEADER  *SavedState\r
  )\r
{\r
  UNIT_TEST_SAVE_TEST     *CurrentTest;\r
  UNIT_TEST_SAVE_TEST     *MatchingTest;\r
  UINT8                   *FloatingPointer;\r
  UNIT_TEST_SAVE_CONTEXT  *SavedContext;\r
  UINTN                   Index;\r
\r
  //\r
  // First, evaluate the inputs.\r
  //\r
  if ((Test == NULL) || (SavedState == NULL)) {\r
    return;\r
  }\r
\r
  if (SavedState->TestCount == 0) {\r
    return;\r
  }\r
\r
  //\r
  // Next, determine whether a matching test can be found.\r
  // Start at the beginning.\r
  //\r
  MatchingTest    = NULL;\r
  FloatingPointer = (UINT8 *)SavedState + sizeof (*SavedState);\r
  for (Index = 0; Index < SavedState->TestCount; Index++) {\r
    CurrentTest = (UNIT_TEST_SAVE_TEST *)FloatingPointer;\r
    if (CompareFingerprints (&Test->Fingerprint[0], &CurrentTest->Fingerprint[0])) {\r
      MatchingTest = CurrentTest;\r
      //\r
      // If there's a saved context, it's important that we iterate through the entire list.\r
      //\r
      if (!SavedState->HasSavedContext) {\r
        break;\r
      }\r
    }\r
\r
    //\r
    // If we didn't find it, we have to increment to the next test.\r
    //\r
    FloatingPointer = (UINT8 *)CurrentTest + CurrentTest->Size;\r
  }\r
\r
  //\r
  // If a matching test was found, copy the status.\r
  //\r
  if (MatchingTest) {\r
    //\r
    // Override the test status with the saved status.\r
    //\r
    Test->Result = MatchingTest->Result;\r
\r
    Test->FailureType = MatchingTest->FailureType;\r
    AsciiStrnCpyS (\r
      &Test->FailureMessage[0],\r
      UNIT_TEST_TESTFAILUREMSG_LENGTH,\r
      &MatchingTest->FailureMessage[0],\r
      UNIT_TEST_TESTFAILUREMSG_LENGTH\r
      );\r
\r
    //\r
    // If there is a log string associated, grab that.\r
    // We can tell that there's a log string because the "size" will be larger than\r
    // the structure size.\r
    // IMPORTANT NOTE: There are security implications here.\r
    //                 This data is user-supplied and we're about to play kinda\r
    //                 fast and loose with data buffers.\r
    //\r
    if (MatchingTest->Size > sizeof (UNIT_TEST_SAVE_TEST)) {\r
      UnitTestLogInit (Test, (UINT8 *)MatchingTest->Log, MatchingTest->Size - sizeof (UNIT_TEST_SAVE_TEST));\r
    }\r
  }\r
\r
  //\r
  // If the saved context exists and matches this test, grab it, too.\r
  //\r
  if (SavedState->HasSavedContext) {\r
    //\r
    // If there was a saved context, the "matching test" loop will have placed the FloatingPointer\r
    // at the beginning of the context structure.\r
    //\r
    SavedContext = (UNIT_TEST_SAVE_CONTEXT *)FloatingPointer;\r
    if (((SavedContext->Size - sizeof (UNIT_TEST_SAVE_CONTEXT)) > 0) &&\r
        CompareFingerprints (&Test->Fingerprint[0], &SavedContext->Fingerprint[0]))\r
    {\r
      //\r
      // Override the test context with the saved context.\r
      //\r
      Test->Context = (VOID *)SavedContext->Data;\r
    }\r
  }\r
}\r
\r
STATIC\r
UNIT_TEST_SAVE_HEADER *\r
SerializeState (\r
  IN UNIT_TEST_FRAMEWORK_HANDLE  FrameworkHandle,\r
  IN UNIT_TEST_CONTEXT           ContextToSave       OPTIONAL,\r
  IN UINTN                       ContextToSaveSize\r
  )\r
{\r
  UNIT_TEST_FRAMEWORK     *Framework;\r
  UNIT_TEST_SAVE_HEADER   *Header;\r
  LIST_ENTRY              *SuiteListHead;\r
  LIST_ENTRY              *Suite;\r
  LIST_ENTRY              *TestListHead;\r
  LIST_ENTRY              *Test;\r
  UINT32                  TestCount;\r
  UINT32                  TotalSize;\r
  UINTN                   LogSize;\r
  UNIT_TEST_SAVE_TEST     *TestSaveData;\r
  UNIT_TEST_SAVE_CONTEXT  *TestSaveContext;\r
  UNIT_TEST               *UnitTest;\r
  UINT8                   *FloatingPointer;\r
\r
  Framework = (UNIT_TEST_FRAMEWORK *)FrameworkHandle;\r
  Header    = NULL;\r
\r
  //\r
  // First, let's not make assumptions about the parameters.\r
  //\r
  if ((Framework == NULL) ||\r
      ((ContextToSave != NULL) && (ContextToSaveSize == 0)) ||\r
      (ContextToSaveSize > MAX_UINT32))\r
  {\r
    return NULL;\r
  }\r
\r
  //\r
  // Next, we've gotta figure out the resources that will be required to serialize the\r
  // the framework state so that we can persist it.\r
  // To start with, we're gonna need a header.\r
  //\r
  TotalSize = sizeof (UNIT_TEST_SAVE_HEADER);\r
  //\r
  // Now we need to figure out how many tests there are.\r
  //\r
  TestCount = 0;\r
  //\r
  // Iterate all suites.\r
  //\r
  SuiteListHead = &Framework->TestSuiteList;\r
  for (Suite = GetFirstNode (SuiteListHead); Suite != SuiteListHead; Suite = GetNextNode (SuiteListHead, Suite)) {\r
    //\r
    // Iterate all tests within the suite.\r
    //\r
    TestListHead = &((UNIT_TEST_SUITE_LIST_ENTRY *)Suite)->UTS.TestCaseList;\r
    for (Test = GetFirstNode (TestListHead); Test != TestListHead; Test = GetNextNode (TestListHead, Test)) {\r
      UnitTest = &((UNIT_TEST_LIST_ENTRY *)Test)->UT;\r
      //\r
      // Account for the size of a test structure.\r
      //\r
      TotalSize += sizeof (UNIT_TEST_SAVE_TEST);\r
      //\r
      // If there's a log, make sure to account for the log size.\r
      //\r
      if (UnitTest->Log != NULL) {\r
        //\r
        // The +1 is for the NULL character. Can't forget the NULL character.\r
        //\r
        LogSize = (AsciiStrLen (UnitTest->Log) + 1) * sizeof (CHAR8);\r
        ASSERT (LogSize < MAX_UINT32);\r
        TotalSize += (UINT32)LogSize;\r
      }\r
\r
      //\r
      // Increment the test count.\r
      //\r
      TestCount++;\r
    }\r
  }\r
\r
  //\r
  // If there are no tests, we're done here.\r
  //\r
  if (TestCount == 0) {\r
    return NULL;\r
  }\r
\r
  //\r
  // Add room for the context, if there is one.\r
  //\r
  if (ContextToSave != NULL) {\r
    TotalSize += sizeof (UNIT_TEST_SAVE_CONTEXT) + (UINT32)ContextToSaveSize;\r
  }\r
\r
  //\r
  // Now that we know the size, we need to allocate space for the serialized output.\r
  //\r
  Header = AllocateZeroPool (TotalSize);\r
  if (Header == NULL) {\r
    return NULL;\r
  }\r
\r
  //\r
  // Alright, let's start setting up some data.\r
  //\r
  Header->Version       = UNIT_TEST_PERSISTENCE_LIB_VERSION;\r
  Header->SaveStateSize = TotalSize;\r
  CopyMem (&Header->Fingerprint[0], &Framework->Fingerprint[0], UNIT_TEST_FINGERPRINT_SIZE);\r
  CopyMem (&Header->StartTime, &Framework->StartTime, sizeof (EFI_TIME));\r
  Header->TestCount       = TestCount;\r
  Header->HasSavedContext = FALSE;\r
\r
  //\r
  // Start adding all of the test cases.\r
  // Set the floating pointer to the start of the current test save buffer.\r
  //\r
  FloatingPointer = (UINT8 *)Header + sizeof (UNIT_TEST_SAVE_HEADER);\r
  //\r
  // Iterate all suites.\r
  //\r
  SuiteListHead = &Framework->TestSuiteList;\r
  for (Suite = GetFirstNode (SuiteListHead); Suite != SuiteListHead; Suite = GetNextNode (SuiteListHead, Suite)) {\r
    //\r
    // Iterate all tests within the suite.\r
    //\r
    TestListHead = &((UNIT_TEST_SUITE_LIST_ENTRY *)Suite)->UTS.TestCaseList;\r
    for (Test = GetFirstNode (TestListHead); Test != TestListHead; Test = GetNextNode (TestListHead, Test)) {\r
      TestSaveData = (UNIT_TEST_SAVE_TEST *)FloatingPointer;\r
      UnitTest     = &((UNIT_TEST_LIST_ENTRY *)Test)->UT;\r
\r
      //\r
      // Save the fingerprint.\r
      //\r
      CopyMem (&TestSaveData->Fingerprint[0], &UnitTest->Fingerprint[0], UNIT_TEST_FINGERPRINT_SIZE);\r
\r
      //\r
      // Save the result.\r
      //\r
      TestSaveData->Result      = UnitTest->Result;\r
      TestSaveData->FailureType = UnitTest->FailureType;\r
      AsciiStrnCpyS (&TestSaveData->FailureMessage[0], UNIT_TEST_TESTFAILUREMSG_LENGTH, &UnitTest->FailureMessage[0], UNIT_TEST_TESTFAILUREMSG_LENGTH);\r
\r
      //\r
      // If there is a log, save the log.\r
      //\r
      FloatingPointer += sizeof (UNIT_TEST_SAVE_TEST);\r
      if (UnitTest->Log != NULL) {\r
        //\r
        // The +1 is for the NULL character. Can't forget the NULL character.\r
        //\r
        LogSize = (AsciiStrLen (UnitTest->Log) + 1) * sizeof (CHAR8);\r
        CopyMem (FloatingPointer, UnitTest->Log, LogSize);\r
        FloatingPointer += LogSize;\r
      }\r
\r
      //\r
      // Update the size once the structure is complete.\r
      // NOTE: Should this be a straight cast without validation?\r
      //\r
      TestSaveData->Size = (UINT32)(FloatingPointer - (UINT8 *)TestSaveData);\r
    }\r
  }\r
\r
  //\r
  // If there is a context to save, let's do that now.\r
  //\r
  if ((ContextToSave != NULL) && (Framework->CurrentTest != NULL)) {\r
    TestSaveContext       = (UNIT_TEST_SAVE_CONTEXT *)FloatingPointer;\r
    TestSaveContext->Size = (UINT32)ContextToSaveSize + sizeof (UNIT_TEST_SAVE_CONTEXT);\r
    CopyMem (&TestSaveContext->Fingerprint[0], &Framework->CurrentTest->Fingerprint[0], UNIT_TEST_FINGERPRINT_SIZE);\r
    CopyMem (((UINT8 *)TestSaveContext + sizeof (UNIT_TEST_SAVE_CONTEXT)), ContextToSave, ContextToSaveSize);\r
    Header->HasSavedContext = TRUE;\r
  }\r
\r
  return Header;\r
}\r
\r
/**\r
  Leverages a framework-specific mechanism (see UnitTestPersistenceLib if you're\r
  a framework author) to save the state of the executing framework along with\r
  any allocated data so that the test may be resumed upon reentry. A test case\r
  should pass any needed context (which, to prevent an infinite loop, should be\r
  at least the current execution count) which will be saved by the framework and\r
  passed to the test case upon resume.\r
\r
  This should be called while the current test framework is valid and active. It is\r
  generally called from within a test case prior to quitting or rebooting.\r
\r
  @param[in]  ContextToSave      A buffer of test case-specific data to be saved\r
                                 along with framework state.  Will be passed as\r
                                 "Context" to the test case upon resume.  This\r
                                 is an optional parameter that may be NULL.\r
  @param[in]  ContextToSaveSize  Size of the ContextToSave buffer.\r
\r
  @retval  EFI_SUCCESS            The framework state and context were saved.\r
  @retval  EFI_NOT_FOUND          An active framework handle was not found.\r
  @retval  EFI_INVALID_PARAMETER  ContextToSave is not NULL and\r
                                  ContextToSaveSize is 0.\r
  @retval  EFI_INVALID_PARAMETER  ContextToSave is >= 4GB.\r
  @retval  EFI_OUT_OF_RESOURCES   There are not enough resources available to\r
                                  save the framework and context state.\r
  @retval  EFI_DEVICE_ERROR       The framework and context state could not be\r
                                  saved to a persistent storage device due to a\r
                                  device error.\r
**/\r
EFI_STATUS\r
EFIAPI\r
SaveFrameworkState (\r
  IN UNIT_TEST_CONTEXT  ContextToSave     OPTIONAL,\r
  IN UINTN              ContextToSaveSize\r
  )\r
{\r
  EFI_STATUS                  Status;\r
  UNIT_TEST_FRAMEWORK_HANDLE  FrameworkHandle;\r
  UNIT_TEST_SAVE_HEADER       *Header;\r
\r
  Header          = NULL;\r
  FrameworkHandle = GetActiveFrameworkHandle ();\r
\r
  //\r
  // Return a unique error code if the framework is not set.\r
  //\r
  if (FrameworkHandle == NULL) {\r
    return EFI_NOT_FOUND;\r
  }\r
\r
  //\r
  // First, let's not make assumptions about the parameters.\r
  //\r
  if (((ContextToSave != NULL) && (ContextToSaveSize == 0)) ||\r
      (ContextToSaveSize > MAX_UINT32))\r
  {\r
    return EFI_INVALID_PARAMETER;\r
  }\r
\r
  //\r
  // Now, let's package up all the data for saving.\r
  //\r
  Header = SerializeState (FrameworkHandle, ContextToSave, ContextToSaveSize);\r
  if (Header == NULL) {\r
    return EFI_OUT_OF_RESOURCES;\r
  }\r
\r
  //\r
  // All that should be left to do is save it using the associated persistence lib.\r
  //\r
  Status = SaveUnitTestCache (FrameworkHandle, Header, Header->SaveStateSize);\r
  if (EFI_ERROR (Status)) {\r
    DEBUG ((DEBUG_ERROR, "%a - Could not save state! %r\n", __FUNCTION__, Status));\r
    Status = EFI_DEVICE_ERROR;\r
  }\r
\r
  //\r
  // Free data that was used.\r
  //\r
  FreePool (Header);\r
\r
  return Status;\r
}\r