2 This driver uses the EFI_FIRMWARE_VOLUME2_PROTOCOL to expose files in firmware
3 volumes via the the EFI_SIMPLE_FILESYSTEM_PROTOCOL and EFI_FILE_PROTOCOL.
5 It will expose a single directory, containing one file for each file in the firmware
6 volume. If a file has a UI section, its contents will be used as a filename.
7 Otherwise, a string representation of the GUID will be used.
8 Files of an executable type (That is PEIM, DRIVER, COMBINED_PEIM_DRIVER and APPLICATION)
9 will have ".efi" added to their filename.
11 Its primary intended use is to be able to start EFI applications embedded in FVs
12 from the UEFI shell. It is entirely read-only.
14 Copyright (c) 2014, ARM Limited. All rights reserved.
15 Copyright (c) 2014 - 2016, Intel Corporation. All rights reserved.<BR>
17 This program and the accompanying materials
18 are licensed and made available under the terms and conditions of the BSD License
19 which accompanies this distribution. The full text of the license may be found at
20 http://opensource.org/licenses/bsd-license.php
22 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
23 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
27 #include "FvSimpleFileSystemInternal.h"
29 EFI_UNICODE_COLLATION_PROTOCOL
*mUnicodeCollation
= NULL
;
32 // A Guid string is 32 hex characters with 4 hyphens and a NULL-terminated char: 37 characters total
34 #define GUID_STRING_SIZE (37 * sizeof (CHAR16))
36 #define FVFS_VOLUME_LABEL_PREFIX L"Firmware Volume: "
37 #define FVFS_VOLUME_LABEL_SIZE (sizeof (FVFS_VOLUME_LABEL_PREFIX) + GUID_STRING_SIZE - sizeof (CHAR16))
38 #define FVFS_FALLBACK_VOLUME_LABEL L"Firmware Volume"
41 // Template for EFI_SIMPLE_FILE_SYSTEM_PROTOCOL data structure.
43 EFI_SIMPLE_FILE_SYSTEM_PROTOCOL mSimpleFsTemplate
= {
44 EFI_SIMPLE_FILE_SYSTEM_PROTOCOL_REVISION
,
45 FvSimpleFileSystemOpenVolume
49 // Template for EFI_DRIVER_BINDING_PROTOCOL data structure.
51 EFI_DRIVER_BINDING_PROTOCOL mDriverBinding
= {
52 FvSimpleFileSystemDriverSupported
,
53 FvSimpleFileSystemDriverStart
,
54 FvSimpleFileSystemDriverStop
,
61 Open the root directory on a volume.
63 @param This A pointer to the volume to open the root directory.
64 @param RootFile A pointer to the location to return the opened file handle for the
67 @retval EFI_SUCCESS The device was opened.
68 @retval EFI_UNSUPPORTED This volume does not support the requested file system type.
69 @retval EFI_NO_MEDIA The device has no medium.
70 @retval EFI_DEVICE_ERROR The device reported an error.
71 @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted.
72 @retval EFI_ACCESS_DENIED The service denied access to the file.
73 @retval EFI_OUT_OF_RESOURCES The volume was not opened due to lack of resources.
74 @retval EFI_MEDIA_CHANGED The device has a different medium in it or the medium is no
75 longer supported. Any existing file handles for this volume are
76 no longer valid. To access the files on the new medium, the
77 volume must be reopened with OpenVolume().
82 FvSimpleFileSystemOpenVolume (
83 IN EFI_SIMPLE_FILE_SYSTEM_PROTOCOL
*This
,
84 OUT EFI_FILE_PROTOCOL
**RootFile
88 FV_FILESYSTEM_FILE
*Root
;
91 EFI_FV_FILE_ATTRIBUTES Attributes
;
92 UINT32 Authentication
;
94 EFI_FV_FILETYPE FileType
;
96 FV_FILESYSTEM_INSTANCE
*Instance
;
97 FV_FILESYSTEM_FILE_INFO
*FvFileInfo
;
98 EFI_FIRMWARE_VOLUME2_PROTOCOL
*FvProtocol
;
104 Instance
= FVFS_INSTANCE_FROM_SIMPLE_FS_THIS (This
);
105 Status
= EFI_SUCCESS
;
107 if (Instance
->Root
== NULL
) {
109 // Allocate file structure for root file
111 Root
= AllocateZeroPool (sizeof (FV_FILESYSTEM_FILE
));
113 return EFI_OUT_OF_RESOURCES
;
116 Instance
->Root
= Root
;
117 Root
->Instance
= Instance
;
118 Root
->Signature
= FVFS_FILE_SIGNATURE
;
119 CopyMem (&Root
->FileProtocol
, &mFileSystemTemplate
, sizeof (mFileSystemTemplate
));
120 Root
->FvFileInfo
= AllocateZeroPool (sizeof (FV_FILESYSTEM_FILE_INFO
));
121 if (Root
->FvFileInfo
== NULL
) {
122 return EFI_OUT_OF_RESOURCES
;
124 Root
->FvFileInfo
->FileInfo
.Size
= sizeof (EFI_FILE_INFO
);
125 Root
->FvFileInfo
->FileInfo
.Attribute
= EFI_FILE_DIRECTORY
| EFI_FILE_READ_ONLY
;
128 // Populate the instance's list of files. We consider anything a file that
129 // has a UI_SECTION, which we consider to be its filename.
131 FvProtocol
= Instance
->FvProtocol
;
138 FileType
= EFI_FV_FILETYPE_ALL
;
140 Status
= FvProtocol
->GetNextFile (
148 if (EFI_ERROR (Status
)) {
149 ASSERT (Status
== EFI_NOT_FOUND
);
154 // Get a file's name: If it has a UI section, use that, otherwise use
158 Status
= FvProtocol
->ReadSection (
161 EFI_SECTION_USER_INTERFACE
,
167 if (!EFI_ERROR (Status
)) {
170 Name
= AllocateZeroPool (GUID_STRING_SIZE
);
172 return EFI_OUT_OF_RESOURCES
;
174 NumChars
= UnicodeSPrint (Name
, GUID_STRING_SIZE
, L
"%g", &NameGuid
);
175 ASSERT ((NumChars
+ 1) * sizeof (CHAR16
) == GUID_STRING_SIZE
);
180 // Allocate a file structure and populate it.
182 NameLen
= StrSize (Name
);
183 if (FV_FILETYPE_IS_EXECUTABLE (FileType
)) {
184 NameLen
+= StrSize (L
".efi") - sizeof (CHAR16
);
187 FvFileInfo
= AllocateZeroPool (sizeof (FV_FILESYSTEM_FILE_INFO
) + NameLen
- sizeof (CHAR16
));
188 if (FvFileInfo
== NULL
) {
189 return EFI_OUT_OF_RESOURCES
;
192 FvFileInfo
->Signature
= FVFS_FILE_INFO_SIGNATURE
;
193 InitializeListHead (&FvFileInfo
->Link
);
194 CopyMem (&FvFileInfo
->NameGuid
, &NameGuid
, sizeof (EFI_GUID
));
195 FvFileInfo
->Type
= FileType
;
198 // Add ".efi" to filenames of drivers and applications.
200 DestMax
= NameLen
/ sizeof (CHAR16
);
201 Status
= StrnCpyS (&FvFileInfo
->FileInfo
.FileName
[0], DestMax
, Name
, StrLen (Name
));
202 ASSERT_EFI_ERROR (Status
);
204 if (FV_FILETYPE_IS_EXECUTABLE (FileType
)) {
205 Status
= StrnCatS (&FvFileInfo
->FileInfo
.FileName
[0], DestMax
, L
".efi", StrLen (L
".efi"));
206 ASSERT_EFI_ERROR (Status
);
209 FvFileInfo
->FileInfo
.Size
= sizeof (EFI_FILE_INFO
) + NameLen
- sizeof (CHAR16
);
210 Status
= FvFsGetFileSize (FvProtocol
, FvFileInfo
);
211 ASSERT_EFI_ERROR (Status
);
212 FvFileInfo
->FileInfo
.PhysicalSize
= FvFileInfo
->FileInfo
.FileSize
;
213 FvFileInfo
->FileInfo
.Attribute
= EFI_FILE_READ_ONLY
;
215 InsertHeadList (&Instance
->FileInfoHead
, &FvFileInfo
->Link
);
221 if (Status
== EFI_NOT_FOUND
) {
222 Status
= EFI_SUCCESS
;
226 Instance
->Root
->DirReadNext
= FVFS_GET_FIRST_FILE_INFO (Instance
);
227 *RootFile
= &Instance
->Root
->FileProtocol
;
232 Worker function to initialize Unicode Collation support.
234 It tries to locate Unicode Collation (2) protocol and matches it with current
235 platform language code.
237 @param AgentHandle The handle used to open Unicode Collation (2) protocol.
238 @param ProtocolGuid The pointer to Unicode Collation (2) protocol GUID.
239 @param VariableName The name of the RFC 4646 or ISO 639-2 language variable.
240 @param DefaultLanguage The default language in case the RFC 4646 or ISO 639-2 language is absent.
242 @retval EFI_SUCCESS The Unicode Collation (2) protocol has been successfully located.
243 @retval Others The Unicode Collation (2) protocol has not been located.
247 InitializeUnicodeCollationSupportWorker (
248 IN EFI_HANDLE AgentHandle
,
249 IN EFI_GUID
*ProtocolGuid
,
250 IN CONST CHAR16
*VariableName
,
251 IN CONST CHAR8
*DefaultLanguage
254 EFI_STATUS ReturnStatus
;
259 EFI_UNICODE_COLLATION_PROTOCOL
*Uci
;
260 BOOLEAN Iso639Language
;
264 Status
= gBS
->LocateHandleBuffer (
271 if (EFI_ERROR (Status
)) {
275 Iso639Language
= (BOOLEAN
) (ProtocolGuid
== &gEfiUnicodeCollationProtocolGuid
);
276 GetEfiGlobalVariable2 (VariableName
, (VOID
**) &Language
, NULL
);
278 ReturnStatus
= EFI_UNSUPPORTED
;
279 for (Index
= 0; Index
< NumHandles
; Index
++) {
281 // Open Unicode Collation Protocol
283 Status
= gBS
->OpenProtocol (
289 EFI_OPEN_PROTOCOL_GET_PROTOCOL
291 if (EFI_ERROR (Status
)) {
296 // Find the best matching matching language from the supported languages
297 // of Unicode Collation (2) protocol.
299 BestLanguage
= GetBestLanguage (
300 Uci
->SupportedLanguages
,
302 (Language
== NULL
) ? "" : Language
,
306 if (BestLanguage
!= NULL
) {
307 FreePool (BestLanguage
);
308 mUnicodeCollation
= Uci
;
309 ReturnStatus
= EFI_SUCCESS
;
314 if (Language
!= NULL
) {
324 Initialize Unicode Collation support.
326 It tries to locate Unicode Collation 2 protocol and matches it with current
327 platform language code. If for any reason the first attempt fails, it then tries to
328 use Unicode Collation Protocol.
330 @param AgentHandle The handle used to open Unicode Collation (2) protocol.
332 @retval EFI_SUCCESS The Unicode Collation (2) protocol has been successfully located.
333 @retval Others The Unicode Collation (2) protocol has not been located.
337 InitializeUnicodeCollationSupport (
338 IN EFI_HANDLE AgentHandle
344 Status
= EFI_UNSUPPORTED
;
347 // First try to use RFC 4646 Unicode Collation 2 Protocol.
349 Status
= InitializeUnicodeCollationSupportWorker (
351 &gEfiUnicodeCollation2ProtocolGuid
,
353 (CONST CHAR8
*) PcdGetPtr (PcdUefiVariableDefaultPlatformLang
)
356 // If the attempt to use Unicode Collation 2 Protocol fails, then we fall back
357 // on the ISO 639-2 Unicode Collation Protocol.
359 if (EFI_ERROR (Status
)) {
360 Status
= InitializeUnicodeCollationSupportWorker (
362 &gEfiUnicodeCollationProtocolGuid
,
364 (CONST CHAR8
*) PcdGetPtr (PcdUefiVariableDefaultLang
)
372 Test to see if this driver supports ControllerHandle.
374 @param DriverBinding Protocol instance pointer.
375 @param ControllerHandle Handle of device to test
376 @param RemainingDevicePath Optional parameter use to pick a specific child
379 @retval EFI_SUCCESS This driver supports this device
380 @retval EFI_ALREADY_STARTED This driver is already running on this device
381 @retval other This driver does not support this device
386 FvSimpleFileSystemDriverSupported (
387 IN EFI_DRIVER_BINDING_PROTOCOL
*DriverBinding
,
388 IN EFI_HANDLE ControllerHandle
,
389 IN EFI_DEVICE_PATH_PROTOCOL
*RemainingDevicePath OPTIONAL
392 return gBS
->OpenProtocol (
394 &gEfiFirmwareVolume2ProtocolGuid
,
398 EFI_OPEN_PROTOCOL_TEST_PROTOCOL
403 Start this driver on ControllerHandle by opening a FV protocol and
404 installing a SimpleFileSystem protocol on ControllerHandle.
406 @param DriverBinding Protocol instance pointer.
407 @param ControllerHandle Handle of device to bind driver to
408 @param RemainingDevicePath Optional parameter use to pick a specific child
411 @retval EFI_SUCCESS This driver is added to ControllerHandle
412 @retval EFI_ALREADY_STARTED This driver is already running on ControllerHandle
413 @retval other This driver does not support this device
418 FvSimpleFileSystemDriverStart (
419 IN EFI_DRIVER_BINDING_PROTOCOL
*DriverBinding
,
420 IN EFI_HANDLE ControllerHandle
,
421 IN EFI_DEVICE_PATH_PROTOCOL
*RemainingDevicePath OPTIONAL
425 EFI_FIRMWARE_VOLUME2_PROTOCOL
*FvProtocol
;
426 FV_FILESYSTEM_INSTANCE
*Instance
;
427 EFI_DEVICE_PATH_PROTOCOL
*FvDevicePath
;
431 Status
= InitializeUnicodeCollationSupport (DriverBinding
->DriverBindingHandle
);
432 if (EFI_ERROR (Status
)) {
439 Status
= gBS
->OpenProtocol (
441 &gEfiFirmwareVolume2ProtocolGuid
,
442 (VOID
**) &FvProtocol
,
445 EFI_OPEN_PROTOCOL_BY_DRIVER
447 if (EFI_ERROR (Status
)) {
452 // Create an instance
454 Instance
= AllocateZeroPool (sizeof (FV_FILESYSTEM_INSTANCE
));
455 ASSERT (Instance
!= NULL
);
457 Instance
->Root
= NULL
;
458 Instance
->FvProtocol
= FvProtocol
;
459 Instance
->Signature
= FVFS_INSTANCE_SIGNATURE
;
460 InitializeListHead (&Instance
->FileInfoHead
);
461 InitializeListHead (&Instance
->FileHead
);
462 CopyMem (&Instance
->SimpleFs
, &mSimpleFsTemplate
, sizeof (mSimpleFsTemplate
));
464 Status
= gBS
->InstallProtocolInterface(
466 &gEfiSimpleFileSystemProtocolGuid
,
467 EFI_NATIVE_INTERFACE
,
470 ASSERT_EFI_ERROR (Status
);
473 // Decide on a filesystem volume label, which will include the FV's guid.
474 // Get the device path to find the FV's GUID
476 Instance
->VolumeLabel
= NULL
;
477 Status
= gBS
->OpenProtocol (
479 &gEfiDevicePathProtocolGuid
,
480 (VOID
**) &FvDevicePath
,
483 EFI_OPEN_PROTOCOL_GET_PROTOCOL
485 if (!EFI_ERROR (Status
)) {
487 // Iterate over device path until we find a firmware volume node
489 while (!IsDevicePathEndType (FvDevicePath
)) {
490 if (DevicePathType (FvDevicePath
) == MEDIA_DEVICE_PATH
&&
491 DevicePathSubType (FvDevicePath
) == MEDIA_PIWG_FW_VOL_DP
) {
493 // Allocate the volume label
495 Instance
->VolumeLabel
= AllocateZeroPool (FVFS_VOLUME_LABEL_SIZE
);
497 // Check the allocation was successful
499 if (Instance
->VolumeLabel
!= NULL
) {
501 // Extract the FV's guid
503 FvGuid
= &((MEDIA_FW_VOL_DEVICE_PATH
*) FvDevicePath
)->FvName
;
505 // Build the volume label string
507 NumChars
= UnicodeSPrint (
508 Instance
->VolumeLabel
,
509 FVFS_VOLUME_LABEL_SIZE
,
510 FVFS_VOLUME_LABEL_PREFIX L
"%g",
513 ASSERT ((NumChars
+ 1) * sizeof (CHAR16
) == FVFS_VOLUME_LABEL_SIZE
);
517 FvDevicePath
= NextDevicePathNode (FvDevicePath
);
521 // If we didn't decide on a volume label, set a fallback one
523 if (Instance
->VolumeLabel
== NULL
) {
524 Instance
->VolumeLabel
= AllocateCopyPool (
525 sizeof (FVFS_FALLBACK_VOLUME_LABEL
),
526 FVFS_FALLBACK_VOLUME_LABEL
534 Stop this driver on ControllerHandle by removing SimpleFileSystem protocol and closing
535 the FV protocol on ControllerHandle.
537 @param DriverBinding Protocol instance pointer.
538 @param ControllerHandle Handle of device to stop driver on
539 @param NumberOfChildren Number of Handles in ChildHandleBuffer. If number of
540 children is zero stop the entire bus driver.
541 @param ChildHandleBuffer List of Child Handles to Stop.
543 @retval EFI_SUCCESS This driver is removed ControllerHandle
544 @retval other This driver was not removed from this device
549 FvSimpleFileSystemDriverStop (
550 IN EFI_DRIVER_BINDING_PROTOCOL
*DriverBinding
,
551 IN EFI_HANDLE ControllerHandle
,
552 IN UINTN NumberOfChildren
,
553 IN EFI_HANDLE
*ChildHandleBuffer OPTIONAL
557 FV_FILESYSTEM_INSTANCE
*Instance
;
558 FV_FILESYSTEM_FILE_INFO
*FvFileInfo
;
560 LIST_ENTRY
*DelEntry
;
561 EFI_SIMPLE_FILE_SYSTEM_PROTOCOL
*SimpleFile
;
563 Status
= gBS
->OpenProtocol (
565 &gEfiSimpleFileSystemProtocolGuid
,
566 (VOID
**) &SimpleFile
,
567 DriverBinding
->DriverBindingHandle
,
569 EFI_OPEN_PROTOCOL_GET_PROTOCOL
571 if (EFI_ERROR (Status
)) {
575 Instance
= FVFS_INSTANCE_FROM_SIMPLE_FS_THIS (SimpleFile
);
577 if (IsListEmpty (&Instance
->FileHead
) == FALSE
) {
579 // Not all opened files are closed
581 return EFI_DEVICE_ERROR
;
585 // Close and uninstall protocols.
587 Status
= gBS
->CloseProtocol (
589 &gEfiFirmwareVolume2ProtocolGuid
,
593 ASSERT_EFI_ERROR (Status
);
595 Status
= gBS
->UninstallProtocolInterface (
597 &gEfiSimpleFileSystemProtocolGuid
,
600 ASSERT_EFI_ERROR (Status
);
603 // Free file structures
605 if (!IsListEmpty (&Instance
->FileInfoHead
)) {
607 // Free the Subtask list.
609 for(Entry
= Instance
->FileInfoHead
.ForwardLink
;
610 Entry
!= (&Instance
->FileInfoHead
);
613 Entry
= Entry
->ForwardLink
;
614 FvFileInfo
= FVFS_FILE_INFO_FROM_LINK (DelEntry
);
616 RemoveEntryList (DelEntry
);
617 FreePool (FvFileInfo
);
621 if (Instance
->Root
!= NULL
) {
623 // Root->Name is statically allocated, no need to free.
625 if (Instance
->Root
->FvFileInfo
!= NULL
) {
626 FreePool (Instance
->Root
->FvFileInfo
);
628 FreePool (Instance
->Root
);
634 if (Instance
->VolumeLabel
!= NULL
) {
635 FreePool (Instance
->VolumeLabel
);
643 The user Entry Point for module FvSimpleFileSystem. The user code starts with this function.
645 @param[in] ImageHandle The firmware allocated handle for the EFI image.
646 @param[in] SystemTable A pointer to the EFI System Table.
648 @retval EFI_SUCCESS The entry point is executed successfully.
649 @retval other Some error occurs when executing this entry point.
654 FvSimpleFileSystemEntryPoint (
655 IN EFI_HANDLE ImageHandle
,
656 IN EFI_SYSTEM_TABLE
*SystemTable
662 // Install driver model protocol(s).
664 Status
= EfiLibInstallDriverBindingComponentName2 (
669 &gFvSimpleFileSystemComponentName
,
670 &gFvSimpleFileSystemComponentName2
672 ASSERT_EFI_ERROR (Status
);