2 UEFI PI specification supersedes Inte's Framework Specification.
3 EFI_FIRMWARE_VOLUME_PROTOCOL defined in Intel Framework Pkg is replaced by
4 EFI_FIRMWARE_VOLUME2_PROTOCOL in MdePkg.
5 This module produces FV on top of FV2. This module is used on platform when both of
6 these two conditions are true:
7 1) Framework module consuming FV is present
8 2) And the platform only produces FV2
10 Copyright (c) 2006 - 2008 Intel Corporation. <BR>
11 All rights reserved. This program and the accompanying materials
12 are licensed and made available under the terms and conditions of the BSD License
13 which accompanies this distribution. The full text of the license may be found at
14 http://opensource.org/licenses/bsd-license.php
16 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
17 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
23 #include <Protocol/FirmwareVolume2.h>
24 #include <Protocol/FirmwareVolume.h>
25 #include <Library/BaseLib.h>
26 #include <Library/DebugLib.h>
27 #include <Library/UefiBootServicesTableLib.h>
28 #include <Library/UefiDriverEntryPoint.h>
29 #include <Library/UefiLib.h>
30 #include <Library/MemoryAllocationLib.h>
33 Retrieves attributes, insures positive polarity of attribute bits, returns
34 resulting attributes in output parameter
36 @param This Calling context
37 @param Attributes output buffer which contains attributes
39 @retval EFI_INVALID_PARAMETER
45 FvGetVolumeAttributes (
46 IN EFI_FIRMWARE_VOLUME_PROTOCOL
*This
,
47 OUT FRAMEWORK_EFI_FV_ATTRIBUTES
*Attributes
51 Sets volume attributes
53 @param This Calling context
54 @param Attributes Buffer which contains attributes
56 @retval EFI_INVALID_PARAMETER
57 @retval EFI_DEVICE_ERROR
63 FvSetVolumeAttributes (
64 IN EFI_FIRMWARE_VOLUME_PROTOCOL
*This
,
65 IN OUT FRAMEWORK_EFI_FV_ATTRIBUTES
*Attributes
69 Read the requested file (NameGuid) and returns data in Buffer.
71 @param This Calling context
72 @param NameGuid Filename identifying which file to read
73 @param Buffer Pointer to pointer to buffer in which contents of file are returned.
75 If Buffer is NULL, only type, attributes, and size are returned as
76 there is no output buffer.
78 If Buffer != NULL and *Buffer == NULL, the output buffer is allocated
79 from BS pool by ReadFile
81 If Buffer != NULL and *Buffer != NULL, the output buffer has been
82 allocated by the caller and is being passed in.
83 @param BufferSize Indicates the buffer size passed in, and on output the size
84 required to complete the read
85 @param FoundType Indicates the type of the file who's data is returned
86 @param FileAttributes Indicates the attributes of the file who's data is resturned
87 @param AuthenticationStatus Indicates the authentication status of the data
90 @retval EFI_WARN_BUFFER_TOO_SMALL
92 @retval EFI_DEVICE_ERROR
93 @retval EFI_ACCESS_DENIED
99 IN EFI_FIRMWARE_VOLUME_PROTOCOL
*This
,
100 IN EFI_GUID
*NameGuid
,
101 IN OUT VOID
**Buffer
,
102 IN OUT UINTN
*BufferSize
,
103 OUT EFI_FV_FILETYPE
*FoundType
,
104 OUT EFI_FV_FILE_ATTRIBUTES
*FileAttributes
,
105 OUT UINT32
*AuthenticationStatus
109 Read the requested section from the specified file and returns data in Buffer.
111 @param This Calling context
112 @param NameGuid Filename identifying the file from which to read
113 @param SectionType Indicates what section type to retrieve
114 @param SectionInstance Indicates which instance of SectionType to retrieve
115 @param Buffer Pointer to pointer to buffer in which contents of file are returned.
117 If Buffer is NULL, only type, attributes, and size are returned as
118 there is no output buffer.
120 If Buffer != NULL and *Buffer == NULL, the output buffer is allocated
121 from BS pool by ReadFile
123 If Buffer != NULL and *Buffer != NULL, the output buffer has been
124 allocated by the caller and is being passed in.
125 @param BufferSize Indicates the buffer size passed in, and on output the size
126 required to complete the read
127 @param AuthenticationStatus Indicates the authentication status of the data
130 @retval EFI_WARN_BUFFER_TOO_SMALL
131 @retval EFI_OUT_OF_RESOURCES
132 @retval EFI_NOT_FOUND
133 @retval EFI_DEVICE_ERROR
134 @retval EFI_ACCESS_DENIED
140 IN EFI_FIRMWARE_VOLUME_PROTOCOL
*This
,
141 IN EFI_GUID
*NameGuid
,
142 IN EFI_SECTION_TYPE SectionType
,
143 IN UINTN SectionInstance
,
144 IN OUT VOID
**Buffer
,
145 IN OUT UINTN
*BufferSize
,
146 OUT UINT32
*AuthenticationStatus
150 Write the supplied file (NameGuid) to the FV.
152 @param This Calling context
153 @param NumberOfFiles Indicates the number of file records pointed to by FileData
154 @param WritePolicy Indicates the level of reliability of the write with respect to
155 things like power failure events.
156 @param FileData A pointer to an array of EFI_FV_WRITE_FILE_DATA structures. Each
157 element in the array indicates a file to write, and there are
158 NumberOfFiles elements in the input array.
161 @retval EFI_OUT_OF_RESOURCES
162 @retval EFI_DEVICE_ERROR
163 @retval EFI_WRITE_PROTECTED
164 @retval EFI_NOT_FOUND
165 @retval EFI_INVALID_PARAMETER
171 IN EFI_FIRMWARE_VOLUME_PROTOCOL
*This
,
172 IN UINT32 NumberOfFiles
,
173 IN FRAMEWORK_EFI_FV_WRITE_POLICY WritePolicy
,
174 IN FRAMEWORK_EFI_FV_WRITE_FILE_DATA
*FileData
178 Given the input key, search for the next matching file in the volume.
180 @param This Calling context
181 @param Key Pointer to a caller allocated buffer that contains an implementation
182 specific key that is used to track where to begin searching on
184 @param FileType Indicates the file type to filter for
185 @param NameGuid Guid filename of the file found
186 @param Attributes Attributes of the file found
187 @param Size Size in bytes of the file found
190 @retval EFI_NOT_FOUND
191 @retval EFI_DEVICE_ERROR
192 @retval EFI_ACCESS_DENIED
198 IN EFI_FIRMWARE_VOLUME_PROTOCOL
*This
,
200 IN OUT EFI_FV_FILETYPE
*FileType
,
201 OUT EFI_GUID
*NameGuid
,
202 OUT EFI_FV_FILE_ATTRIBUTES
*Attributes
,
206 #define FIRMWARE_VOLUME_PRIVATE_DATA_SIGNATURE SIGNATURE_32 ('f', 'v', 't', 'h')
210 EFI_FIRMWARE_VOLUME_PROTOCOL FirmwareVolume
;
211 EFI_FIRMWARE_VOLUME2_PROTOCOL
*FirmwareVolume2
;
212 } FIRMWARE_VOLUME_PRIVATE_DATA
;
214 #define FIRMWARE_VOLUME_PRIVATE_DATA_FROM_THIS(a) CR (a, FIRMWARE_VOLUME_PRIVATE_DATA, FirmwareVolume, FIRMWARE_VOLUME_PRIVATE_DATA_SIGNATURE)
217 // Firmware Volume Protocol template
219 EFI_EVENT mFvRegistration
;
221 FIRMWARE_VOLUME_PRIVATE_DATA gFirmwareVolumePrivateDataTemplate
= {
222 FIRMWARE_VOLUME_PRIVATE_DATA_SIGNATURE
,
224 FvGetVolumeAttributes
,
225 FvSetVolumeAttributes
,
242 FvNotificationEvent (
250 FIRMWARE_VOLUME_PRIVATE_DATA
*Private
;
251 EFI_FIRMWARE_VOLUME_PROTOCOL
*FirmwareVolume
;
254 BufferSize
= sizeof (Handle
);
255 Status
= gBS
->LocateHandle (
257 &gEfiFirmwareVolume2ProtocolGuid
,
262 if (EFI_ERROR (Status
)) {
264 // Exit Path of While Loop....
270 // Skip this handle if the Firmware Volume Protocol is already installed
272 Status
= gBS
->HandleProtocol (
274 &gEfiFirmwareVolumeProtocolGuid
,
275 (VOID
**)&FirmwareVolume
277 if (!EFI_ERROR (Status
)) {
282 // Allocate private data structure
284 Private
= AllocateCopyPool (sizeof (FIRMWARE_VOLUME_PRIVATE_DATA
), &gFirmwareVolumePrivateDataTemplate
);
285 if (Private
== NULL
) {
290 // Retrieve the Firmware Volume2 Protocol
292 Status
= gBS
->HandleProtocol (
294 &gEfiFirmwareVolume2ProtocolGuid
,
295 (VOID
**)&Private
->FirmwareVolume2
297 ASSERT_EFI_ERROR (Status
);
300 // Fill in rest of private data structure
302 Private
->FirmwareVolume
.KeySize
= Private
->FirmwareVolume2
->KeySize
;
303 Private
->FirmwareVolume
.ParentHandle
= Private
->FirmwareVolume2
->ParentHandle
;
306 // Install Firmware Volume Protocol onto same handle
308 Status
= gBS
->InstallMultipleProtocolInterfaces (
310 &gEfiFirmwareVolumeProtocolGuid
,
311 &Private
->FirmwareVolume
,
314 ASSERT_EFI_ERROR (Status
);
320 The user Entry Point for DXE driver. The user code starts with this function
321 as the real entry point for the image goes into a library that calls this
324 @param[in] ImageHandle The firmware allocated handle for the EFI image.
325 @param[in] SystemTable A pointer to the EFI System Table.
327 @retval EFI_SUCCESS The entry point is executed successfully.
328 @retval other Some error occurs when executing this entry point.
333 InitializeFirmwareVolume2 (
334 IN EFI_HANDLE ImageHandle
,
335 IN EFI_SYSTEM_TABLE
*SystemTable
338 EfiCreateProtocolNotifyEvent (
339 &gEfiFirmwareVolume2ProtocolGuid
,
349 Convert FV attrbiutes to FV2 attributes.
351 @param Fv2Attributes FV2 attributes.
353 @return FV attributes.
356 FRAMEWORK_EFI_FV_ATTRIBUTES
357 Fv2AttributesToFvAttributes (
358 IN EFI_FV_ATTRIBUTES Fv2Attributes
362 // Clear those filed that is not defined in Framework FV spec and Alignment conversion.
364 return (Fv2Attributes
& 0x1ff) | ((UINTN
) EFI_FV_ALIGNMENT_2
<< RShiftU64((Fv2Attributes
& EFI_FV2_ALIGNMENT
), 16));
368 Retrieves attributes, insures positive polarity of attribute bits, returns
369 resulting attributes in output parameter
371 @param This Calling context
372 @param Attributes output buffer which contains attributes
374 @retval EFI_INVALID_PARAMETER
380 FvGetVolumeAttributes (
381 IN EFI_FIRMWARE_VOLUME_PROTOCOL
*This
,
382 OUT FRAMEWORK_EFI_FV_ATTRIBUTES
*Attributes
386 FIRMWARE_VOLUME_PRIVATE_DATA
*Private
;
387 EFI_FIRMWARE_VOLUME2_PROTOCOL
*FirmwareVolume2
;
389 Private
= FIRMWARE_VOLUME_PRIVATE_DATA_FROM_THIS (This
);
390 FirmwareVolume2
= Private
->FirmwareVolume2
;
392 Status
= FirmwareVolume2
->GetVolumeAttributes (
396 if (!EFI_ERROR (Status
)) {
397 *Attributes
= Fv2AttributesToFvAttributes (*Attributes
);
403 Sets volume attributes
405 @param This Calling context
406 @param Attributes Buffer which contains attributes
408 @retval EFI_INVALID_PARAMETER
409 @retval EFI_DEVICE_ERROR
415 FvSetVolumeAttributes (
416 IN EFI_FIRMWARE_VOLUME_PROTOCOL
*This
,
417 IN OUT FRAMEWORK_EFI_FV_ATTRIBUTES
*Attributes
420 FIRMWARE_VOLUME_PRIVATE_DATA
*Private
;
421 EFI_FIRMWARE_VOLUME2_PROTOCOL
*FirmwareVolume2
;
422 EFI_FV_ATTRIBUTES Fv2Attributes
;
425 Private
= FIRMWARE_VOLUME_PRIVATE_DATA_FROM_THIS (This
);
426 FirmwareVolume2
= Private
->FirmwareVolume2
;
428 Fv2Attributes
= (*Attributes
& 0x1ff);
429 Status
= FirmwareVolume2
->SetVolumeAttributes (
434 *Attributes
= Fv2AttributesToFvAttributes (Fv2Attributes
);
440 Read the requested file (NameGuid) and returns data in Buffer.
442 @param This Calling context
443 @param NameGuid Filename identifying which file to read
444 @param Buffer Pointer to pointer to buffer in which contents of file are returned.
446 If Buffer is NULL, only type, attributes, and size are returned as
447 there is no output buffer.
449 If Buffer != NULL and *Buffer == NULL, the output buffer is allocated
450 from BS pool by ReadFile
452 If Buffer != NULL and *Buffer != NULL, the output buffer has been
453 allocated by the caller and is being passed in.
454 @param BufferSize Indicates the buffer size passed in, and on output the size
455 required to complete the read
456 @param FoundType Indicates the type of the file who's data is returned
457 @param FileAttributes Indicates the attributes of the file who's data is resturned
458 @param AuthenticationStatus Indicates the authentication status of the data
461 @retval EFI_WARN_BUFFER_TOO_SMALL
462 @retval EFI_NOT_FOUND
463 @retval EFI_DEVICE_ERROR
464 @retval EFI_ACCESS_DENIED
470 IN EFI_FIRMWARE_VOLUME_PROTOCOL
*This
,
471 IN EFI_GUID
*NameGuid
,
472 IN OUT VOID
**Buffer
,
473 IN OUT UINTN
*BufferSize
,
474 OUT EFI_FV_FILETYPE
*FoundType
,
475 OUT EFI_FV_FILE_ATTRIBUTES
*FileAttributes
,
476 OUT UINT32
*AuthenticationStatus
479 FIRMWARE_VOLUME_PRIVATE_DATA
*Private
;
480 EFI_FIRMWARE_VOLUME2_PROTOCOL
*FirmwareVolume2
;
483 Private
= FIRMWARE_VOLUME_PRIVATE_DATA_FROM_THIS (This
);
484 FirmwareVolume2
= Private
->FirmwareVolume2
;
486 Status
= FirmwareVolume2
->ReadFile (
497 // For Framework FV attrbutes, only alignment fields are valid.
499 *FileAttributes
= *FileAttributes
& EFI_FV_FILE_ATTRIB_ALIGNMENT
;
505 Read the requested section from the specified file and returns data in Buffer.
507 @param This Calling context
508 @param NameGuid Filename identifying the file from which to read
509 @param SectionType Indicates what section type to retrieve
510 @param SectionInstance Indicates which instance of SectionType to retrieve
511 @param Buffer Pointer to pointer to buffer in which contents of file are returned.
513 If Buffer is NULL, only type, attributes, and size are returned as
514 there is no output buffer.
516 If Buffer != NULL and *Buffer == NULL, the output buffer is allocated
517 from BS pool by ReadFile
519 If Buffer != NULL and *Buffer != NULL, the output buffer has been
520 allocated by the caller and is being passed in.
521 @param BufferSize Indicates the buffer size passed in, and on output the size
522 required to complete the read
523 @param AuthenticationStatus Indicates the authentication status of the data
526 @retval EFI_WARN_BUFFER_TOO_SMALL
527 @retval EFI_OUT_OF_RESOURCES
528 @retval EFI_NOT_FOUND
529 @retval EFI_DEVICE_ERROR
530 @retval EFI_ACCESS_DENIED
536 IN EFI_FIRMWARE_VOLUME_PROTOCOL
*This
,
537 IN EFI_GUID
*NameGuid
,
538 IN EFI_SECTION_TYPE SectionType
,
539 IN UINTN SectionInstance
,
540 IN OUT VOID
**Buffer
,
541 IN OUT UINTN
*BufferSize
,
542 OUT UINT32
*AuthenticationStatus
545 FIRMWARE_VOLUME_PRIVATE_DATA
*Private
;
546 EFI_FIRMWARE_VOLUME2_PROTOCOL
*FirmwareVolume2
;
548 Private
= FIRMWARE_VOLUME_PRIVATE_DATA_FROM_THIS (This
);
549 FirmwareVolume2
= Private
->FirmwareVolume2
;
551 return FirmwareVolume2
->ReadSection (
563 Write the supplied file (NameGuid) to the FV.
565 @param This Calling context
566 @param NumberOfFiles Indicates the number of file records pointed to by FileData
567 @param WritePolicy Indicates the level of reliability of the write with respect to
568 things like power failure events.
569 @param FileData A pointer to an array of EFI_FV_WRITE_FILE_DATA structures. Each
570 element in the array indicates a file to write, and there are
571 NumberOfFiles elements in the input array.
574 @retval EFI_OUT_OF_RESOURCES
575 @retval EFI_DEVICE_ERROR
576 @retval EFI_WRITE_PROTECTED
577 @retval EFI_NOT_FOUND
578 @retval EFI_INVALID_PARAMETER
584 IN EFI_FIRMWARE_VOLUME_PROTOCOL
*This
,
585 IN UINT32 NumberOfFiles
,
586 IN FRAMEWORK_EFI_FV_WRITE_POLICY WritePolicy
,
587 IN FRAMEWORK_EFI_FV_WRITE_FILE_DATA
*FileData
590 FIRMWARE_VOLUME_PRIVATE_DATA
*Private
;
591 EFI_FIRMWARE_VOLUME2_PROTOCOL
*FirmwareVolume2
;
592 EFI_FV_WRITE_FILE_DATA
*PiFileData
;
596 Private
= FIRMWARE_VOLUME_PRIVATE_DATA_FROM_THIS (This
);
597 FirmwareVolume2
= Private
->FirmwareVolume2
;
599 PiFileData
= AllocateCopyPool (sizeof (EFI_FV_WRITE_FILE_DATA
), FileData
);
602 // Framework Spec assume firmware files are Memory-Mapped.
604 for (Index
= 0; Index
< NumberOfFiles
; Index
++) {
605 PiFileData
[Index
].FileAttributes
|= EFI_FV_FILE_ATTRIB_MEMORY_MAPPED
;
608 Status
= FirmwareVolume2
->WriteFile (
612 (EFI_FV_WRITE_FILE_DATA
*)FileData
615 FreePool (PiFileData
);
620 Given the input key, search for the next matching file in the volume.
622 @param This Calling context
623 @param Key Pointer to a caller allocated buffer that contains an implementation
624 specific key that is used to track where to begin searching on
626 @param FileType Indicates the file type to filter for
627 @param NameGuid Guid filename of the file found
628 @param Attributes Attributes of the file found
629 @param Size Size in bytes of the file found
632 @retval EFI_NOT_FOUND
633 @retval EFI_DEVICE_ERROR
634 @retval EFI_ACCESS_DENIED
640 IN EFI_FIRMWARE_VOLUME_PROTOCOL
*This
,
642 IN OUT EFI_FV_FILETYPE
*FileType
,
643 OUT EFI_GUID
*NameGuid
,
644 OUT EFI_FV_FILE_ATTRIBUTES
*Attributes
,
648 FIRMWARE_VOLUME_PRIVATE_DATA
*Private
;
649 EFI_FIRMWARE_VOLUME2_PROTOCOL
*FirmwareVolume2
;
652 Private
= FIRMWARE_VOLUME_PRIVATE_DATA_FROM_THIS (This
);
653 FirmwareVolume2
= Private
->FirmwareVolume2
;
655 Status
= FirmwareVolume2
->GetNextFile (
665 // For Framework FV attrbutes, only alignment fields are valid.
667 *Attributes
= *Attributes
& EFI_FV_FILE_ATTRIB_ALIGNMENT
;