UnitTestFrameworkPkg/Library/UnitTestLib/UnitTestLib.c

   1 /**
   2   Implement UnitTestLib
   3
   4   Copyright (c) Microsoft Corporation.
   5   SPDX-License-Identifier: BSD-2-Clause-Patent
   6 **/
   7
   8 #include <Uefi.h>
   9 #include <Library/UnitTestLib.h>
  10 #include <Library/BaseLib.h>
  11 #include <Library/BaseMemoryLib.h>
  12 #include <Library/MemoryAllocationLib.h>
  13 #include <Library/DebugLib.h>
  14 #include <Library/UnitTestPersistenceLib.h>
  15 #include <Library/UnitTestResultReportLib.h>
  16
  17 ///
  18 /// Forward declaration of prototype
  19 ///
  20 STATIC
  21 VOID
  22 UpdateTestFromSave (
  23   IN OUT UNIT_TEST              *Test,
  24   IN     UNIT_TEST_SAVE_HEADER  *SavedState
  25   );
  26
  27 /**
  28   This function will determine whether the short name violates any rules that would
  29   prevent it from being used as a reporting name or as a serialization name.
  30
  31   Example: If the name cannot be serialized to a filesystem file name.
  32
  33   @param[in]  ShortTitleString  A pointer to the short title string to be evaluated.
  34
  35   @retval  TRUE   The string is acceptable.
  36   @retval  FALSE  The string should not be used.
  37
  38 **/
  39 STATIC
  40 BOOLEAN
  41 IsFrameworkShortNameValid (
  42   IN CHAR8  *ShortTitleString
  43   )
  44 {
  45   // TODO: Finish this function.
  46   return TRUE;
  47 }
  48
  49 STATIC
  50 CHAR8*
  51 AllocateAndCopyString (
  52   IN CHAR8  *StringToCopy
  53   )
  54 {
  55   CHAR8  *NewString;
  56   UINTN  NewStringLength;
  57
  58   NewString = NULL;
  59   NewStringLength = AsciiStrnLenS (StringToCopy, UNIT_TEST_MAX_STRING_LENGTH) + 1;
  60   NewString = AllocatePool (NewStringLength * sizeof( CHAR8 ));
  61   if (NewString != NULL) {
  62     AsciiStrCpyS (NewString, NewStringLength, StringToCopy);
  63   }
  64   return NewString;
  65 }
  66
  67 STATIC
  68 VOID
  69 SetFrameworkFingerprint (
  70   OUT UINT8                *Fingerprint,
  71   IN  UNIT_TEST_FRAMEWORK  *Framework
  72   )
  73 {
  74   UINT32  NewFingerprint;
  75
  76   // For this one we'll just use the title and version as the unique fingerprint.
  77   NewFingerprint = CalculateCrc32( Framework->Title, (AsciiStrLen( Framework->Title ) * sizeof( CHAR8 )) );
  78   NewFingerprint = (NewFingerprint >> 8) ^ CalculateCrc32( Framework->VersionString, (AsciiStrLen( Framework->VersionString ) * sizeof( CHAR8 )) );
  79
  80   CopyMem( Fingerprint, &NewFingerprint, UNIT_TEST_FINGERPRINT_SIZE );
  81   return;
  82 }
  83
  84 STATIC
  85 VOID
  86 SetSuiteFingerprint (
  87   OUT UINT8                *Fingerprint,
  88   IN  UNIT_TEST_FRAMEWORK  *Framework,
  89   IN  UNIT_TEST_SUITE      *Suite
  90   )
  91 {
  92   UINT32  NewFingerprint;
  93
  94   // For this one, we'll use the fingerprint from the framework, and the title of the suite.
  95   NewFingerprint = CalculateCrc32( &Framework->Fingerprint[0], UNIT_TEST_FINGERPRINT_SIZE );
  96   NewFingerprint = (NewFingerprint >> 8) ^ CalculateCrc32( Suite->Title, (AsciiStrLen( Suite->Title ) * sizeof( CHAR8 )) );
  97   NewFingerprint = (NewFingerprint >> 8) ^ CalculateCrc32( Suite->Name, (AsciiStrLen(Suite->Name) * sizeof(CHAR8)) );
  98
  99   CopyMem( Fingerprint, &NewFingerprint, UNIT_TEST_FINGERPRINT_SIZE );
 100   return;
 101 }
 102
 103 STATIC
 104 VOID
 105 SetTestFingerprint (
 106   OUT UINT8            *Fingerprint,
 107   IN  UNIT_TEST_SUITE  *Suite,
 108   IN  UNIT_TEST        *Test
 109   )
 110 {
 111   UINT32  NewFingerprint;
 112
 113   // For this one, we'll use the fingerprint from the suite, and the description and classname of the test.
 114   NewFingerprint = CalculateCrc32( &Suite->Fingerprint[0], UNIT_TEST_FINGERPRINT_SIZE );
 115   NewFingerprint = (NewFingerprint >> 8) ^ CalculateCrc32( Test->Description, (AsciiStrLen( Test->Description ) * sizeof( CHAR8 )) );
 116   NewFingerprint = (NewFingerprint >> 8) ^ CalculateCrc32( Test->Name, (AsciiStrLen(Test->Name) * sizeof(CHAR8)) );
 117
 118   CopyMem( Fingerprint, &NewFingerprint, UNIT_TEST_FINGERPRINT_SIZE );
 119   return;
 120 }
 121
 122 STATIC
 123 BOOLEAN
 124 CompareFingerprints (
 125   IN UINT8  *FingerprintA,
 126   IN UINT8  *FingerprintB
 127   )
 128 {
 129   return (CompareMem( FingerprintA, FingerprintB, UNIT_TEST_FINGERPRINT_SIZE ) == 0);
 130 }
 131
 132 /**
 133   Cleanup a test framework.
 134
 135   After tests are run, this will teardown the entire framework and free all
 136   allocated data within.
 137
 138   @param[in]  FrameworkHandle  A handle to the current running framework that
 139                                dispatched the test.  Necessary for recording
 140                                certain test events with the framework.
 141
 142   @retval  EFI_SUCCESS            All resources associated with framework were
 143                                   freed.
 144   @retval  EFI_INVALID_PARAMETER  FrameworkHandle is NULL.
 145 **/
 146 EFI_STATUS
 147 EFIAPI
 148 FreeUnitTestFramework (
 149   IN UNIT_TEST_FRAMEWORK_HANDLE  FrameworkHandle
 150   )
 151 {
 152   // TODO: Finish this function.
 153   return EFI_SUCCESS;
 154 }
 155
 156 STATIC
 157 EFI_STATUS
 158 FreeUnitTestSuiteEntry (
 159   IN UNIT_TEST_SUITE_LIST_ENTRY  *SuiteEntry
 160   )
 161 {
 162   // TODO: Finish this function.
 163   return EFI_SUCCESS;
 164 }
 165
 166 STATIC
 167 EFI_STATUS
 168 FreeUnitTestTestEntry (
 169   IN UNIT_TEST_LIST_ENTRY  *TestEntry
 170   )
 171 {
 172   // TODO: Finish this function.
 173   return EFI_SUCCESS;
 174 }
 175
 176 /**
 177   Method to Initialize the Unit Test framework.  This function registers the
 178   test name and also initializes the internal state of the test framework to
 179   receive any new suites and tests.
 180
 181   @param[out]  FrameworkHandle  Unit test framework to be created.
 182   @param[in]   Title            Null-terminated ASCII string that is the user
 183                                 friendly name of the framework. String is
 184                                 copied.
 185   @param[in]   ShortTitle       Null-terminated ASCII short string that is the
 186                                 short name of the framework with no spaces.
 187                                 String is copied.
 188   @param[in]   VersionString    Null-terminated ASCII version string for the
 189                                 framework. String is copied.
 190
 191   @retval  EFI_SUCCESS            The unit test framework was initialized.
 192   @retval  EFI_INVALID_PARAMETER  FrameworkHandle is NULL.
 193   @retval  EFI_INVALID_PARAMETER  Title is NULL.
 194   @retval  EFI_INVALID_PARAMETER  ShortTitle is NULL.
 195   @retval  EFI_INVALID_PARAMETER  VersionString is NULL.
 196   @retval  EFI_INVALID_PARAMETER  ShortTitle is invalid.
 197   @retval  EFI_OUT_OF_RESOURCES   There are not enough resources available to
 198                                   initialize the unit test framework.
 199 **/
 200 EFI_STATUS
 201 EFIAPI
 202 InitUnitTestFramework (
 203   OUT UNIT_TEST_FRAMEWORK_HANDLE  *FrameworkHandle,
 204   IN  CHAR8                       *Title,
 205   IN  CHAR8                       *ShortTitle,
 206   IN  CHAR8                       *VersionString
 207   )
 208 {
 209   EFI_STATUS                  Status;
 210   UNIT_TEST_FRAMEWORK_HANDLE  NewFrameworkHandle;
 211   UNIT_TEST_FRAMEWORK         *NewFramework;
 212   UNIT_TEST_SAVE_HEADER       *SavedState;
 213
 214   Status       = EFI_SUCCESS;
 215   NewFramework = NULL;
 216
 217   //
 218   // First, check all pointers and make sure nothing's broked.
 219   //
 220   if (FrameworkHandle == NULL || Title == NULL ||
 221       ShortTitle == NULL || VersionString == NULL) {
 222     return EFI_INVALID_PARAMETER;
 223   }
 224
 225   //
 226   // Next, determine whether all of the strings are good to use.
 227   //
 228   if (!IsFrameworkShortNameValid (ShortTitle)) {
 229     return EFI_INVALID_PARAMETER;
 230   }
 231
 232   //
 233   // Next, set aside some space to start messing with the framework.
 234   //
 235   NewFramework = AllocateZeroPool (sizeof (UNIT_TEST_FRAMEWORK));
 236   if (NewFramework == NULL) {
 237     return EFI_OUT_OF_RESOURCES;
 238   }
 239
 240   //
 241   // Next, set up all the test data.
 242   //
 243   NewFrameworkHandle          = (UNIT_TEST_FRAMEWORK_HANDLE)NewFramework;
 244   NewFramework->Title         = AllocateAndCopyString (Title);
 245   NewFramework->ShortTitle    = AllocateAndCopyString (ShortTitle);
 246   NewFramework->VersionString = AllocateAndCopyString (VersionString);
 247   NewFramework->Log           = NULL;
 248   NewFramework->CurrentTest   = NULL;
 249   NewFramework->SavedState    = NULL;
 250   if (NewFramework->Title == NULL ||
 251       NewFramework->ShortTitle == NULL ||
 252       NewFramework->VersionString == NULL) {
 253     Status = EFI_OUT_OF_RESOURCES;
 254     goto Exit;
 255   }
 256   InitializeListHead (&(NewFramework->TestSuiteList));
 257
 258   //
 259   // Create the framework fingerprint.
 260   //
 261   SetFrameworkFingerprint (&NewFramework->Fingerprint[0], NewFramework);
 262
 263   //
 264   // If there is a persisted context, load it now.
 265   //
 266   if (DoesCacheExist (NewFrameworkHandle)) {
 267     SavedState = (UNIT_TEST_SAVE_HEADER *)NewFramework->SavedState;
 268     Status = LoadUnitTestCache (NewFrameworkHandle, &SavedState);
 269     if (EFI_ERROR (Status)) {
 270       //
 271       // Don't actually report it as an error, but emit a warning.
 272       //
 273       DEBUG (( DEBUG_ERROR, "%a - Cache was detected, but failed to load.\n", __FUNCTION__ ));
 274       Status = EFI_SUCCESS;
 275     }
 276   }
 277
 278 Exit:
 279   //
 280   // If we're good, then let's copy the framework.
 281   //
 282   if (!EFI_ERROR (Status)) {
 283     *FrameworkHandle = NewFrameworkHandle;
 284   } else {
 285     //
 286     // Otherwise, we need to undo this horrible thing that we've done.
 287     //
 288     FreeUnitTestFramework (NewFrameworkHandle);
 289   }
 290
 291   return Status;
 292 }
 293
 294 /**
 295   Registers a Unit Test Suite in the Unit Test Framework.
 296   At least one test suite must be registered, because all test cases must be
 297   within a unit test suite.
 298
 299   @param[out]  SuiteHandle      Unit test suite to create
 300   @param[in]   FrameworkHandle  Unit test framework to add unit test suite to
 301   @param[in]   Title            Null-terminated ASCII string that is the user
 302                                 friendly name of the test suite.  String is
 303                                 copied.
 304   @param[in]   Name             Null-terminated ASCII string that is the short
 305                                 name of the test suite with no spaces.  String
 306                                 is copied.
 307   @param[in]   Setup            Setup function, runs before suite.  This is an
 308                                 optional parameter that may be NULL.
 309   @param[in]   Teardown         Teardown function, runs after suite.  This is an
 310                                 optional parameter that may be NULL.
 311
 312   @retval  EFI_SUCCESS            The unit test suite was created.
 313   @retval  EFI_INVALID_PARAMETER  SuiteHandle is NULL.
 314   @retval  EFI_INVALID_PARAMETER  FrameworkHandle is NULL.
 315   @retval  EFI_INVALID_PARAMETER  Title is NULL.
 316   @retval  EFI_INVALID_PARAMETER  Name is NULL.
 317   @retval  EFI_OUT_OF_RESOURCES   There are not enough resources available to
 318                                   initialize the unit test suite.
 319 **/
 320 EFI_STATUS
 321 EFIAPI
 322 CreateUnitTestSuite (
 323   OUT UNIT_TEST_SUITE_HANDLE      *SuiteHandle,
 324   IN  UNIT_TEST_FRAMEWORK_HANDLE  FrameworkHandle,
 325   IN  CHAR8                       *Title,
 326   IN  CHAR8                       *Name,
 327   IN  UNIT_TEST_SUITE_SETUP       Setup     OPTIONAL,
 328   IN  UNIT_TEST_SUITE_TEARDOWN    Teardown  OPTIONAL
 329   )
 330 {
 331   EFI_STATUS                  Status;
 332   UNIT_TEST_SUITE_LIST_ENTRY  *NewSuiteEntry;
 333   UNIT_TEST_FRAMEWORK         *Framework;
 334
 335   Status = EFI_SUCCESS;
 336   Framework = (UNIT_TEST_FRAMEWORK *)FrameworkHandle;
 337
 338   //
 339   // First, let's check to make sure that our parameters look good.
 340   //
 341   if ((SuiteHandle == NULL) || (Framework == NULL) || (Title == NULL) || (Name == NULL)) {
 342     return EFI_INVALID_PARAMETER;
 343   }
 344
 345   //
 346   // Create the new entry.
 347   //
 348   NewSuiteEntry = AllocateZeroPool (sizeof (UNIT_TEST_SUITE_LIST_ENTRY));
 349   if (NewSuiteEntry == NULL) {
 350     return EFI_OUT_OF_RESOURCES;
 351   }
 352
 353   //
 354   // Copy the fields we think we need.
 355   //
 356   NewSuiteEntry->UTS.NumTests         = 0;
 357   NewSuiteEntry->UTS.Title            = AllocateAndCopyString (Title);
 358   NewSuiteEntry->UTS.Name             = AllocateAndCopyString (Name);
 359   NewSuiteEntry->UTS.Setup            = Setup;
 360   NewSuiteEntry->UTS.Teardown         = Teardown;
 361   NewSuiteEntry->UTS.ParentFramework  = FrameworkHandle;
 362   InitializeListHead (&(NewSuiteEntry->Entry));             // List entry for sibling suites.
 363   InitializeListHead (&(NewSuiteEntry->UTS.TestCaseList));  // List entry for child tests.
 364   if (NewSuiteEntry->UTS.Title == NULL) {
 365     Status = EFI_OUT_OF_RESOURCES;
 366     goto Exit;
 367   }
 368
 369   if (NewSuiteEntry->UTS.Name == NULL) {
 370     Status = EFI_OUT_OF_RESOURCES;
 371     goto Exit;
 372   }
 373
 374   //
 375   // Create the suite fingerprint.
 376   //
 377   SetSuiteFingerprint( &NewSuiteEntry->UTS.Fingerprint[0], Framework, &NewSuiteEntry->UTS );
 378
 379 Exit:
 380   //
 381   // If everything is going well, add the new suite to the tail list for the framework.
 382   //
 383   if (!EFI_ERROR( Status )) {
 384     InsertTailList (&(Framework->TestSuiteList), (LIST_ENTRY *)NewSuiteEntry);
 385     *SuiteHandle = (UNIT_TEST_SUITE_HANDLE)(&NewSuiteEntry->UTS);
 386   } else {
 387     //
 388     // Otherwise, make with the destruction.
 389     //
 390     FreeUnitTestSuiteEntry (NewSuiteEntry);
 391   }
 392
 393   return Status;
 394 }
 395
 396 /**
 397   Adds test case to Suite
 398
 399   @param[in]  SuiteHandle   Unit test suite to add test to.
 400   @param[in]  Description   Null-terminated ASCII string that is the user
 401                             friendly description of a test.  String is copied.
 402   @param[in]  Name          Null-terminated ASCII string that is the short name
 403                             of the test with no spaces.  String is copied.
 404   @param[in]  Function      Unit test function.
 405   @param[in]  Prerequisite  Prerequisite function, runs before test.  This is
 406                             an optional parameter that may be NULL.
 407   @param[in]  CleanUp       Clean up function, runs after test.  This is an
 408                             optional parameter that may be NULL.
 409   @param[in]  Context       Pointer to context.    This is an optional parameter
 410                             that may be NULL.
 411
 412   @retval  EFI_SUCCESS            The unit test case was added to Suite.
 413   @retval  EFI_INVALID_PARAMETER  SuiteHandle is NULL.
 414   @retval  EFI_INVALID_PARAMETER  Description is NULL.
 415   @retval  EFI_INVALID_PARAMETER  Name is NULL.
 416   @retval  EFI_INVALID_PARAMETER  Function is NULL.
 417   @retval  EFI_OUT_OF_RESOURCES   There are not enough resources available to
 418                                   add the unit test case to Suite.
 419 **/
 420 EFI_STATUS
 421 EFIAPI
 422 AddTestCase (
 423   IN UNIT_TEST_SUITE_HANDLE  SuiteHandle,
 424   IN CHAR8                   *Description,
 425   IN CHAR8                   *Name,
 426   IN UNIT_TEST_FUNCTION      Function,
 427   IN UNIT_TEST_PREREQUISITE  Prerequisite  OPTIONAL,
 428   IN UNIT_TEST_CLEANUP       CleanUp       OPTIONAL,
 429   IN UNIT_TEST_CONTEXT       Context       OPTIONAL
 430   )
 431 {
 432   EFI_STATUS            Status;
 433   UNIT_TEST_LIST_ENTRY  *NewTestEntry;
 434   UNIT_TEST_FRAMEWORK   *ParentFramework;
 435   UNIT_TEST_SUITE       *Suite;
 436
 437   Status          = EFI_SUCCESS;
 438   Suite           = (UNIT_TEST_SUITE *)SuiteHandle;
 439
 440   //
 441   // First, let's check to make sure that our parameters look good.
 442   //
 443   if ((Suite == NULL) || (Description == NULL) || (Name == NULL) || (Function == NULL)) {
 444     return EFI_INVALID_PARAMETER;
 445   }
 446
 447   ParentFramework = (UNIT_TEST_FRAMEWORK *)Suite->ParentFramework;
 448   //
 449   // Create the new entry.
 450   NewTestEntry = AllocateZeroPool (sizeof( UNIT_TEST_LIST_ENTRY ));
 451   if (NewTestEntry == NULL) {
 452     return EFI_OUT_OF_RESOURCES;
 453   }
 454
 455   //
 456   // Copy the fields we think we need.
 457   NewTestEntry->UT.Description       = AllocateAndCopyString (Description);
 458   NewTestEntry->UT.Name              = AllocateAndCopyString (Name);
 459   NewTestEntry->UT.FailureType       = FAILURETYPE_NOFAILURE;
 460   NewTestEntry->UT.FailureMessage[0] = '\0';
 461   NewTestEntry->UT.Log               = NULL;
 462   NewTestEntry->UT.Prerequisite      = Prerequisite;
 463   NewTestEntry->UT.CleanUp           = CleanUp;
 464   NewTestEntry->UT.RunTest           = Function;
 465   NewTestEntry->UT.Context           = Context;
 466   NewTestEntry->UT.Result            = UNIT_TEST_PENDING;
 467   NewTestEntry->UT.ParentSuite       = SuiteHandle;
 468   InitializeListHead (&(NewTestEntry->Entry));  // List entry for sibling tests.
 469   if (NewTestEntry->UT.Description == NULL) {
 470     Status = EFI_OUT_OF_RESOURCES;
 471     goto Exit;
 472   }
 473   if (NewTestEntry->UT.Name == NULL) {
 474     Status = EFI_OUT_OF_RESOURCES;
 475     goto Exit;
 476   }
 477
 478   //
 479   // Create the test fingerprint.
 480   //
 481   SetTestFingerprint (&NewTestEntry->UT.Fingerprint[0], Suite, &NewTestEntry->UT);
 482
 483   // TODO: Make sure that duplicate fingerprints cannot be created.
 484
 485   //
 486   // If there is saved test data, update this record.
 487   //
 488   if (ParentFramework->SavedState != NULL) {
 489     UpdateTestFromSave (&NewTestEntry->UT, ParentFramework->SavedState);
 490   }
 491
 492 Exit:
 493   //
 494   // If everything is going well, add the new suite to the tail list for the framework.
 495   //
 496   if (!EFI_ERROR (Status)) {
 497     InsertTailList (&(Suite->TestCaseList), (LIST_ENTRY*)NewTestEntry);
 498     Suite->NumTests++;
 499   } else {
 500     //
 501     // Otherwise, make with the destruction.
 502     //
 503     FreeUnitTestTestEntry (NewTestEntry);
 504   }
 505
 506   return Status;
 507 }
 508
 509 STATIC
 510 VOID
 511 UpdateTestFromSave (
 512   IN OUT UNIT_TEST              *Test,
 513   IN     UNIT_TEST_SAVE_HEADER  *SavedState
 514   )
 515 {
 516   UNIT_TEST_SAVE_TEST     *CurrentTest;
 517   UNIT_TEST_SAVE_TEST     *MatchingTest;
 518   UINT8                   *FloatingPointer;
 519   UNIT_TEST_SAVE_CONTEXT  *SavedContext;
 520   UINTN                   Index;
 521
 522   //
 523   // First, evaluate the inputs.
 524   //
 525   if (Test == NULL || SavedState == NULL) {
 526     return;
 527   }
 528   if (SavedState->TestCount == 0) {
 529     return;
 530   }
 531
 532   //
 533   // Next, determine whether a matching test can be found.
 534   // Start at the beginning.
 535   //
 536   MatchingTest    = NULL;
 537   FloatingPointer = (UINT8 *)SavedState + sizeof (*SavedState);
 538   for (Index = 0; Index < SavedState->TestCount; Index++) {
 539     CurrentTest = (UNIT_TEST_SAVE_TEST *)FloatingPointer;
 540     if (CompareFingerprints (&Test->Fingerprint[0], &CurrentTest->Fingerprint[0])) {
 541       MatchingTest = CurrentTest;
 542       //
 543       // If there's a saved context, it's important that we iterate through the entire list.
 544       //
 545       if (!SavedState->HasSavedContext) {
 546         break;
 547       }
 548     }
 549
 550     //
 551     // If we didn't find it, we have to increment to the next test.
 552     //
 553     FloatingPointer = (UINT8 *)CurrentTest + CurrentTest->Size;
 554   }
 555
 556   //
 557   // If a matching test was found, copy the status.
 558   //
 559   if (MatchingTest) {
 560     //
 561     // Override the test status with the saved status.
 562     //
 563     Test->Result = MatchingTest->Result;
 564
 565     Test->FailureType = MatchingTest->FailureType;
 566     AsciiStrnCpyS (
 567       &Test->FailureMessage[0],
 568       UNIT_TEST_TESTFAILUREMSG_LENGTH,
 569       &MatchingTest->FailureMessage[0],
 570       UNIT_TEST_TESTFAILUREMSG_LENGTH
 571       );
 572
 573     //
 574     // If there is a log string associated, grab that.
 575     // We can tell that there's a log string because the "size" will be larger than
 576     // the structure size.
 577     // IMPORTANT NOTE: There are security implications here.
 578     //                 This data is user-supplied and we're about to play kinda
 579     //                 fast and loose with data buffers.
 580     //
 581     if (MatchingTest->Size > sizeof (UNIT_TEST_SAVE_TEST)) {
 582       UnitTestLogInit (Test, (UINT8 *)MatchingTest->Log, MatchingTest->Size - sizeof (UNIT_TEST_SAVE_TEST));
 583     }
 584   }
 585
 586   //
 587   // If the saved context exists and matches this test, grab it, too.
 588   //
 589   if (SavedState->HasSavedContext) {
 590     //
 591     // If there was a saved context, the "matching test" loop will have placed the FloatingPointer
 592     // at the beginning of the context structure.
 593     //
 594     SavedContext = (UNIT_TEST_SAVE_CONTEXT *)FloatingPointer;
 595     if ((SavedContext->Size - sizeof (UNIT_TEST_SAVE_CONTEXT)) > 0 &&
 596         CompareFingerprints (&Test->Fingerprint[0], &SavedContext->Fingerprint[0])) {
 597       //
 598       // Override the test context with the saved context.
 599       //
 600       Test->Context = (VOID*)SavedContext->Data;
 601     }
 602   }
 603 }
 604
 605 STATIC
 606 UNIT_TEST_SAVE_HEADER*
 607 SerializeState (
 608   IN UNIT_TEST_FRAMEWORK_HANDLE  FrameworkHandle,
 609   IN UNIT_TEST_CONTEXT           ContextToSave,      OPTIONAL
 610   IN UINTN                       ContextToSaveSize
 611   )
 612 {
 613   UNIT_TEST_FRAMEWORK     *Framework;
 614   UNIT_TEST_SAVE_HEADER   *Header;
 615   LIST_ENTRY              *SuiteListHead;
 616   LIST_ENTRY              *Suite;
 617   LIST_ENTRY              *TestListHead;
 618   LIST_ENTRY              *Test;
 619   UINT32                  TestCount;
 620   UINT32                  TotalSize;
 621   UINTN                   LogSize;
 622   UNIT_TEST_SAVE_TEST     *TestSaveData;
 623   UNIT_TEST_SAVE_CONTEXT  *TestSaveContext;
 624   UNIT_TEST               *UnitTest;
 625   UINT8                   *FloatingPointer;
 626
 627   Framework = (UNIT_TEST_FRAMEWORK *)FrameworkHandle;
 628   Header    = NULL;
 629
 630   //
 631   // First, let's not make assumptions about the parameters.
 632   //
 633   if (Framework == NULL ||
 634       (ContextToSave != NULL && ContextToSaveSize == 0) ||
 635       ContextToSaveSize > MAX_UINT32) {
 636     return NULL;
 637   }
 638
 639   //
 640   // Next, we've gotta figure out the resources that will be required to serialize the
 641   // the framework state so that we can persist it.
 642   // To start with, we're gonna need a header.
 643   //
 644   TotalSize = sizeof (UNIT_TEST_SAVE_HEADER);
 645   //
 646   // Now we need to figure out how many tests there are.
 647   //
 648   TestCount = 0;
 649   //
 650   // Iterate all suites.
 651   //
 652   SuiteListHead = &Framework->TestSuiteList;
 653   for (Suite = GetFirstNode (SuiteListHead); Suite != SuiteListHead; Suite = GetNextNode (SuiteListHead, Suite)) {
 654     //
 655     // Iterate all tests within the suite.
 656     //
 657     TestListHead = &((UNIT_TEST_SUITE_LIST_ENTRY *)Suite)->UTS.TestCaseList;
 658     for (Test = GetFirstNode (TestListHead); Test != TestListHead; Test = GetNextNode (TestListHead, Test)) {
 659       UnitTest = &((UNIT_TEST_LIST_ENTRY *)Test)->UT;
 660       //
 661       // Account for the size of a test structure.
 662       //
 663       TotalSize += sizeof( UNIT_TEST_SAVE_TEST );
 664       //
 665       // If there's a log, make sure to account for the log size.
 666       //
 667       if (UnitTest->Log != NULL)     {
 668         //
 669         // The +1 is for the NULL character. Can't forget the NULL character.
 670         //
 671         LogSize = (AsciiStrLen (UnitTest->Log) + 1) * sizeof (CHAR8);
 672         ASSERT (LogSize < MAX_UINT32);
 673         TotalSize += (UINT32)LogSize;
 674       }
 675       //
 676       // Increment the test count.
 677       //
 678       TestCount++;
 679     }
 680   }
 681   //
 682   // If there are no tests, we're done here.
 683   //
 684   if (TestCount == 0) {
 685     return NULL;
 686   }
 687   //
 688   // Add room for the context, if there is one.
 689   //
 690   if (ContextToSave != NULL) {
 691     TotalSize += sizeof (UNIT_TEST_SAVE_CONTEXT) + (UINT32)ContextToSaveSize;
 692   }
 693
 694   //
 695   // Now that we know the size, we need to allocate space for the serialized output.
 696   //
 697   Header = AllocateZeroPool (TotalSize);
 698   if (Header == NULL) {
 699     return NULL;
 700   }
 701
 702   //
 703   // Alright, let's start setting up some data.
 704   //
 705   Header->Version         = UNIT_TEST_PERSISTENCE_LIB_VERSION;
 706   Header->SaveStateSize   = TotalSize;
 707   CopyMem (&Header->Fingerprint[0], &Framework->Fingerprint[0], UNIT_TEST_FINGERPRINT_SIZE);
 708   CopyMem (&Header->StartTime, &Framework->StartTime, sizeof (EFI_TIME));
 709   Header->TestCount       = TestCount;
 710   Header->HasSavedContext = FALSE;
 711
 712   //
 713   // Start adding all of the test cases.
 714   // Set the floating pointer to the start of the current test save buffer.
 715   //
 716   FloatingPointer = (UINT8*)Header + sizeof( UNIT_TEST_SAVE_HEADER );
 717   //
 718   // Iterate all suites.
 719   //
 720   SuiteListHead = &Framework->TestSuiteList;
 721   for (Suite = GetFirstNode (SuiteListHead); Suite != SuiteListHead; Suite = GetNextNode (SuiteListHead, Suite)) {
 722     //
 723     // Iterate all tests within the suite.
 724     //
 725     TestListHead = &((UNIT_TEST_SUITE_LIST_ENTRY *)Suite)->UTS.TestCaseList;
 726     for (Test = GetFirstNode (TestListHead); Test != TestListHead; Test = GetNextNode (TestListHead, Test)) {
 727       TestSaveData  = (UNIT_TEST_SAVE_TEST *)FloatingPointer;
 728       UnitTest      = &((UNIT_TEST_LIST_ENTRY *)Test)->UT;
 729
 730       //
 731       // Save the fingerprint.
 732       //
 733       CopyMem (&TestSaveData->Fingerprint[0], &UnitTest->Fingerprint[0], UNIT_TEST_FINGERPRINT_SIZE);
 734
 735       //
 736       // Save the result.
 737       //
 738       TestSaveData->Result = UnitTest->Result;
 739       TestSaveData->FailureType = UnitTest->FailureType;
 740       AsciiStrnCpyS (&TestSaveData->FailureMessage[0], UNIT_TEST_TESTFAILUREMSG_LENGTH, &UnitTest->FailureMessage[0], UNIT_TEST_TESTFAILUREMSG_LENGTH);
 741
 742
 743       //
 744       // If there is a log, save the log.
 745       //
 746       FloatingPointer += sizeof (UNIT_TEST_SAVE_TEST);
 747       if (UnitTest->Log != NULL) {
 748         //
 749         // The +1 is for the NULL character. Can't forget the NULL character.
 750         //
 751         LogSize = (AsciiStrLen (UnitTest->Log) + 1) * sizeof (CHAR8);
 752         CopyMem (FloatingPointer, UnitTest->Log, LogSize);
 753         FloatingPointer += LogSize;
 754       }
 755
 756       //
 757       // Update the size once the structure is complete.
 758       // NOTE: Should this be a straight cast without validation?
 759       //
 760       TestSaveData->Size = (UINT32)(FloatingPointer - (UINT8 *)TestSaveData);
 761     }
 762   }
 763
 764   //
 765   // If there is a context to save, let's do that now.
 766   //
 767   if (ContextToSave != NULL && Framework->CurrentTest != NULL) {
 768     TestSaveContext         = (UNIT_TEST_SAVE_CONTEXT*)FloatingPointer;
 769     TestSaveContext->Size   = (UINT32)ContextToSaveSize + sizeof (UNIT_TEST_SAVE_CONTEXT);
 770     CopyMem (&TestSaveContext->Fingerprint[0], &Framework->CurrentTest->Fingerprint[0], UNIT_TEST_FINGERPRINT_SIZE);
 771     CopyMem (((UINT8 *)TestSaveContext + sizeof (UNIT_TEST_SAVE_CONTEXT)), ContextToSave, ContextToSaveSize);
 772     Header->HasSavedContext = TRUE;
 773   }
 774
 775   return Header;
 776 }
 777
 778 /**
 779   Leverages a framework-specific mechanism (see UnitTestPersistenceLib if you're
 780   a framework author) to save the state of the executing framework along with
 781   any allocated data so that the test may be resumed upon reentry. A test case
 782   should pass any needed context (which, to prevent an infinite loop, should be
 783   at least the current execution count) which will be saved by the framework and
 784   passed to the test case upon resume.
 785
 786   Generally called from within a test case prior to quitting or rebooting.
 787
 788   @param[in]  FrameworkHandle    A handle to the current running framework that
 789                                  dispatched the test.  Necessary for recording
 790                                  certain test events with the framework.
 791   @param[in]  ContextToSave      A buffer of test case-specific data to be saved
 792                                  along with framework state.  Will be passed as
 793                                  "Context" to the test case upon resume.  This
 794                                  is an optional parameter that may be NULL.
 795   @param[in]  ContextToSaveSize  Size of the ContextToSave buffer.
 796
 797   @retval  EFI_SUCCESS            The framework state and context were saved.
 798   @retval  EFI_INVALID_PARAMETER  FrameworkHandle is NULL.
 799   @retval  EFI_INVALID_PARAMETER  ContextToSave is not NULL and
 800                                   ContextToSaveSize is 0.
 801   @retval  EFI_INVALID_PARAMETER  ContextToSave is >= 4GB.
 802   @retval  EFI_OUT_OF_RESOURCES   There are not enough resources available to
 803                                   save the framework and context state.
 804   @retval  EFI_DEVICE_ERROR       The framework and context state could not be
 805                                   saved to a persistent storage device due to a
 806                                   device error.
 807 **/
 808 EFI_STATUS
 809 EFIAPI
 810 SaveFrameworkState (
 811   IN UNIT_TEST_FRAMEWORK_HANDLE  FrameworkHandle,
 812   IN UNIT_TEST_CONTEXT           ContextToSave     OPTIONAL,
 813   IN UINTN                       ContextToSaveSize
 814   )
 815 {
 816   EFI_STATUS             Status;
 817   UNIT_TEST_SAVE_HEADER  *Header;
 818
 819   Header = NULL;
 820
 821   //
 822   // First, let's not make assumptions about the parameters.
 823   //
 824   if (FrameworkHandle == NULL ||
 825       (ContextToSave != NULL && ContextToSaveSize == 0) ||
 826       ContextToSaveSize > MAX_UINT32) {
 827     return EFI_INVALID_PARAMETER;
 828   }
 829
 830   //
 831   // Now, let's package up all the data for saving.
 832   //
 833   Header = SerializeState (FrameworkHandle, ContextToSave, ContextToSaveSize);
 834   if (Header == NULL) {
 835     return EFI_OUT_OF_RESOURCES;
 836   }
 837
 838   //
 839   // All that should be left to do is save it using the associated persistence lib.
 840   //
 841   Status = SaveUnitTestCache (FrameworkHandle, Header);
 842   if (EFI_ERROR (Status)) {
 843     DEBUG ((DEBUG_ERROR, "%a - Could not save state! %r\n", __FUNCTION__, Status));
 844     Status = EFI_DEVICE_ERROR;
 845   }
 846
 847   //
 848   // Free data that was used.
 849   //
 850   FreePool (Header);
 851
 852   return Status;
 853 }