2 This is an instance of the Unit Test Persistence Lib that will utilize
3 the filesystem that a test application is running from to save a serialized
4 version of the internal test state in case the test needs to quit and restore.
6 Copyright (c) Microsoft Corporation.<BR>
7 SPDX-License-Identifier: BSD-2-Clause-Patent
11 #include <Library/UnitTestPersistenceLib.h>
12 #include <Library/BaseLib.h>
13 #include <Library/DebugLib.h>
14 #include <Library/MemoryAllocationLib.h>
15 #include <Library/UefiBootServicesTableLib.h>
16 #include <Library/DevicePathLib.h>
17 #include <Library/ShellLib.h>
18 #include <Protocol/LoadedImage.h>
20 #define CACHE_FILE_SUFFIX L"_Cache.dat"
23 Generate the device path to the cache file.
25 @param[in] FrameworkHandle A pointer to the framework that is being persisted.
27 @retval !NULL A pointer to the EFI_FILE protocol instance for the filesystem.
28 @retval NULL Filesystem could not be found or an error occurred.
32 EFI_DEVICE_PATH_PROTOCOL
*
33 GetCacheFileDevicePath (
34 IN UNIT_TEST_FRAMEWORK_HANDLE FrameworkHandle
38 UNIT_TEST_FRAMEWORK
*Framework
;
39 EFI_LOADED_IMAGE_PROTOCOL
*LoadedImage
;
41 CHAR16
*CacheFilePath
;
43 UINTN DirectorySlashOffset
;
44 UINTN CacheFilePathLength
;
45 EFI_DEVICE_PATH_PROTOCOL
*CacheFileDevicePath
;
47 Framework
= (UNIT_TEST_FRAMEWORK
*)FrameworkHandle
;
51 CacheFileDevicePath
= NULL
;
54 // First, we need to get some information from the loaded image.
56 Status
= gBS
->HandleProtocol (
58 &gEfiLoadedImageProtocolGuid
,
61 if (EFI_ERROR (Status
)) {
62 DEBUG ((DEBUG_WARN
, "%a - Failed to locate DevicePath for loaded image. %r\n", __FUNCTION__
, Status
));
67 // Before we can start, change test name from ASCII to Unicode.
69 CacheFilePathLength
= AsciiStrLen (Framework
->ShortTitle
) + 1;
70 TestName
= AllocatePool (CacheFilePathLength
);
74 AsciiStrToUnicodeStrS (Framework
->ShortTitle
, TestName
, CacheFilePathLength
);
77 // Now we should have the device path of the root device and a file path for the rest.
78 // In order to target the directory for the test application, we must process
79 // the file path a little.
81 // NOTE: This may not be necessary... Path processing functions exist...
82 // PathCleanUpDirectories (FileNameCopy);
83 // if (PathRemoveLastItem (FileNameCopy)) {
85 AppPath
= ConvertDevicePathToText (LoadedImage
->FilePath
, TRUE
, TRUE
); // NOTE: This must be freed.
86 DirectorySlashOffset
= StrLen (AppPath
);
88 // Make sure we didn't get any weird data.
90 if (DirectorySlashOffset
== 0) {
91 DEBUG ((DEBUG_ERROR
, "%a - Weird 0-length string when processing app path.\n", __FUNCTION__
));
96 // Now that we know we have a decent string, let's take a deeper look.
99 if (AppPath
[DirectorySlashOffset
] == L
'\\') {
102 DirectorySlashOffset
--;
103 } while (DirectorySlashOffset
> 0);
106 // After that little maneuver, DirectorySlashOffset should be pointing at the last '\' in AppString.
107 // That would be the path to the parent directory that the test app is executing from.
108 // Let's check and make sure that's right.
110 if (AppPath
[DirectorySlashOffset
] != L
'\\') {
111 DEBUG ((DEBUG_ERROR
, "%a - Could not find a single directory separator in app path.\n", __FUNCTION__
));
116 // Now we know some things, we're ready to produce our output string, I think.
118 CacheFilePathLength
= DirectorySlashOffset
+ 1;
119 CacheFilePathLength
+= StrLen (TestName
);
120 CacheFilePathLength
+= StrLen (CACHE_FILE_SUFFIX
);
121 CacheFilePathLength
+= 1; // Don't forget the NULL terminator.
122 CacheFilePath
= AllocateZeroPool (CacheFilePathLength
* sizeof (CHAR16
));
123 if (!CacheFilePath
) {
128 // Let's produce our final path string, shall we?
130 StrnCpyS (CacheFilePath
, CacheFilePathLength
, AppPath
, DirectorySlashOffset
+ 1); // Copy the path for the parent directory.
131 StrCatS (CacheFilePath
, CacheFilePathLength
, TestName
); // Copy the base name for the test cache.
132 StrCatS (CacheFilePath
, CacheFilePathLength
, CACHE_FILE_SUFFIX
); // Copy the file suffix.
135 // Finally, try to create the device path for the thing thing.
137 CacheFileDevicePath
= FileDevicePath (LoadedImage
->DeviceHandle
, CacheFilePath
);
141 // Free allocated buffers.
143 if (AppPath
!= NULL
) {
146 if (CacheFilePath
!= NULL
) {
147 FreePool (CacheFilePath
);
149 if (TestName
!= NULL
) {
153 return CacheFileDevicePath
;
157 Determines whether a persistence cache already exists for
160 @param[in] FrameworkHandle A pointer to the framework that is being persisted.
163 @retval FALSE Cache doesn't exist or an error occurred.
169 IN UNIT_TEST_FRAMEWORK_HANDLE FrameworkHandle
172 EFI_DEVICE_PATH_PROTOCOL
*FileDevicePath
;
174 SHELL_FILE_HANDLE FileHandle
;
177 // NOTE: This devpath is allocated and must be freed.
179 FileDevicePath
= GetCacheFileDevicePath (FrameworkHandle
);
182 // Check to see whether the file exists. If the file can be opened for
183 // reading, it exists. Otherwise, probably not.
185 Status
= ShellOpenFileByDevicePath (
191 if (!EFI_ERROR (Status
)) {
192 ShellCloseFile (&FileHandle
);
195 if (FileDevicePath
!= NULL
) {
196 FreePool (FileDevicePath
);
199 DEBUG ((DEBUG_VERBOSE
, "%a - Returning %d\n", __FUNCTION__
, !EFI_ERROR (Status
)));
201 return (!EFI_ERROR (Status
));
205 Will save the data associated with an internal Unit Test Framework
206 state in a manner that can persist a Unit Test Application quit or
207 even a system reboot.
209 @param[in] FrameworkHandle A pointer to the framework that is being persisted.
210 @param[in] SaveData A pointer to the buffer containing the serialized
211 framework internal state.
213 @retval EFI_SUCCESS Data is persisted and the test can be safely quit.
214 @retval Others Data is not persisted and test cannot be resumed upon exit.
220 IN UNIT_TEST_FRAMEWORK_HANDLE FrameworkHandle
,
221 IN UNIT_TEST_SAVE_HEADER
*SaveData
224 EFI_DEVICE_PATH_PROTOCOL
*FileDevicePath
;
226 SHELL_FILE_HANDLE FileHandle
;
230 // Check the inputs for sanity.
232 if (FrameworkHandle
== NULL
|| SaveData
== NULL
) {
233 return EFI_INVALID_PARAMETER
;
237 // Determine the path for the cache file.
238 // NOTE: This devpath is allocated and must be freed.
240 FileDevicePath
= GetCacheFileDevicePath (FrameworkHandle
);
243 //First lets open the file if it exists so we can delete it...This is the work around for truncation
245 Status
= ShellOpenFileByDevicePath (
248 (EFI_FILE_MODE_READ
| EFI_FILE_MODE_WRITE
),
252 if (!EFI_ERROR (Status
)) {
254 // If file handle above was opened it will be closed by the delete.
256 Status
= ShellDeleteFile (&FileHandle
);
257 if (EFI_ERROR (Status
)) {
258 DEBUG ((DEBUG_ERROR
, "%a failed to delete file %r\n", __FUNCTION__
, Status
));
263 // Now that we know the path to the file... let's open it for writing.
265 Status
= ShellOpenFileByDevicePath (
268 (EFI_FILE_MODE_READ
| EFI_FILE_MODE_WRITE
| EFI_FILE_MODE_CREATE
),
271 if (EFI_ERROR (Status
)) {
272 DEBUG ((DEBUG_ERROR
, "%a - Opening file for writing failed! %r\n", __FUNCTION__
, Status
));
277 // Write the data to the file.
279 WriteCount
= SaveData
->SaveStateSize
;
280 DEBUG ((DEBUG_INFO
, "%a - Writing %d bytes to file...\n", __FUNCTION__
, WriteCount
));
281 Status
= ShellWriteFile (
287 if (EFI_ERROR (Status
) || WriteCount
!= SaveData
->SaveStateSize
) {
288 DEBUG ((DEBUG_ERROR
, "%a - Writing to file failed! %r\n", __FUNCTION__
, Status
));
290 DEBUG ((DEBUG_INFO
, "%a - SUCCESS!\n", __FUNCTION__
));
294 // No matter what, we should probably close the file.
296 ShellCloseFile (&FileHandle
);
299 if (FileDevicePath
!= NULL
) {
300 FreePool (FileDevicePath
);
307 Will retrieve any cached state associated with the given framework.
308 Will allocate a buffer to hold the loaded data.
310 @param[in] FrameworkHandle A pointer to the framework that is being persisted.
311 @param[in] SaveData A pointer pointer that will be updated with the address
312 of the loaded data buffer.
314 @retval EFI_SUCCESS Data has been loaded successfully and SaveData is updated
315 with a pointer to the buffer.
316 @retval Others An error has occurred and no data has been loaded. SaveData
323 IN UNIT_TEST_FRAMEWORK_HANDLE FrameworkHandle
,
324 OUT UNIT_TEST_SAVE_HEADER
**SaveData
328 EFI_DEVICE_PATH_PROTOCOL
*FileDevicePath
;
329 SHELL_FILE_HANDLE FileHandle
;
330 BOOLEAN IsFileOpened
;
331 UINT64 LargeFileSize
;
333 UNIT_TEST_SAVE_HEADER
*Buffer
;
335 IsFileOpened
= FALSE
;
339 // Check the inputs for sanity.
341 if (FrameworkHandle
== NULL
|| SaveData
== NULL
) {
342 return EFI_INVALID_PARAMETER
;
346 // Determine the path for the cache file.
347 // NOTE: This devpath is allocated and must be freed.
349 FileDevicePath
= GetCacheFileDevicePath (FrameworkHandle
);
352 // Now that we know the path to the file... let's open it for writing.
354 Status
= ShellOpenFileByDevicePath (
360 if (EFI_ERROR (Status
)) {
361 DEBUG ((DEBUG_ERROR
, "%a - Opening file for writing failed! %r\n", __FUNCTION__
, Status
));
368 // Now that the file is opened, we need to determine how large a buffer we need.
370 Status
= ShellGetFileSize (FileHandle
, &LargeFileSize
);
371 if (EFI_ERROR (Status
)) {
372 DEBUG ((DEBUG_ERROR
, "%a - Failed to determine file size! %r\n", __FUNCTION__
, Status
));
377 // Now that we know the size, let's allocated a buffer to hold the contents.
379 FileSize
= (UINTN
)LargeFileSize
; // You know what... if it's too large, this lib don't care.
380 Buffer
= AllocatePool (FileSize
);
381 if (Buffer
== NULL
) {
382 DEBUG ((DEBUG_ERROR
, "%a - Failed to allocate a pool to hold the file contents! %r\n", __FUNCTION__
, Status
));
383 Status
= EFI_OUT_OF_RESOURCES
;
388 // Finally, let's read the data.
390 Status
= ShellReadFile (FileHandle
, &FileSize
, Buffer
);
391 if (EFI_ERROR (Status
)) {
392 DEBUG ((DEBUG_ERROR
, "%a - Failed to read the file contents! %r\n", __FUNCTION__
, Status
));
397 // Free allocated buffers
399 if (FileDevicePath
!= NULL
) {
400 FreePool (FileDevicePath
);
403 ShellCloseFile (&FileHandle
);
407 // If we're returning an error, make sure
408 // the state is sane.
409 if (EFI_ERROR (Status
) && Buffer
!= NULL
) {