2 Implementations for Firmware Volume Block protocol.
4 It consumes FV HOBs and creates read-only Firmare Volume Block protocol
5 instances for each of them.
7 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
8 SPDX-License-Identifier: BSD-2-Clause-Patent
13 #include "FwVolBlock.h"
15 FV_MEMMAP_DEVICE_PATH mFvMemmapDevicePathTemplate
= {
21 (UINT8
)(sizeof (MEMMAP_DEVICE_PATH
)),
22 (UINT8
)(sizeof (MEMMAP_DEVICE_PATH
) >> 8)
26 (EFI_PHYSICAL_ADDRESS
) 0,
27 (EFI_PHYSICAL_ADDRESS
) 0,
31 END_ENTIRE_DEVICE_PATH_SUBTYPE
,
33 END_DEVICE_PATH_LENGTH
,
39 FV_PIWG_DEVICE_PATH mFvPIWGDevicePathTemplate
= {
45 (UINT8
)(sizeof (MEDIA_FW_VOL_DEVICE_PATH
)),
46 (UINT8
)(sizeof (MEDIA_FW_VOL_DEVICE_PATH
) >> 8)
53 END_ENTIRE_DEVICE_PATH_SUBTYPE
,
55 END_DEVICE_PATH_LENGTH
,
61 EFI_FW_VOL_BLOCK_DEVICE mFwVolBlock
= {
66 FwVolBlockGetAttributes
,
67 (EFI_FVB_SET_ATTRIBUTES
)FwVolBlockSetAttributes
,
68 FwVolBlockGetPhysicalAddress
,
69 FwVolBlockGetBlockSize
,
71 (EFI_FVB_WRITE
)FwVolBlockWriteBlock
,
72 (EFI_FVB_ERASE_BLOCKS
)FwVolBlockEraseBlock
,
85 Retrieves Volume attributes. No polarity translations are done.
87 @param This Calling context
88 @param Attributes output buffer which contains attributes
90 @retval EFI_SUCCESS The firmware volume attributes were returned.
95 FwVolBlockGetAttributes (
96 IN CONST EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*This
,
97 OUT EFI_FVB_ATTRIBUTES_2
*Attributes
100 EFI_FW_VOL_BLOCK_DEVICE
*FvbDevice
;
102 FvbDevice
= FVB_DEVICE_FROM_THIS (This
);
105 // Since we are read only, it's safe to get attributes data from our in-memory copy.
107 *Attributes
= FvbDevice
->FvbAttributes
& ~EFI_FVB2_WRITE_STATUS
;
115 Modifies the current settings of the firmware volume according to the input parameter.
117 @param This Calling context
118 @param Attributes input buffer which contains attributes
120 @retval EFI_SUCCESS The firmware volume attributes were returned.
121 @retval EFI_INVALID_PARAMETER The attributes requested are in conflict with
122 the capabilities as declared in the firmware
124 @retval EFI_UNSUPPORTED Not supported.
129 FwVolBlockSetAttributes (
130 IN CONST EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*This
,
131 IN CONST EFI_FVB_ATTRIBUTES_2
*Attributes
134 return EFI_UNSUPPORTED
;
140 The EraseBlock() function erases one or more blocks as denoted by the
141 variable argument list. The entire parameter list of blocks must be verified
142 prior to erasing any blocks. If a block is requested that does not exist
143 within the associated firmware volume (it has a larger index than the last
144 block of the firmware volume), the EraseBlock() function must return
145 EFI_INVALID_PARAMETER without modifying the contents of the firmware volume.
147 @param This Calling context
148 @param ... Starting LBA followed by Number of Lba to erase.
149 a -1 to terminate the list.
151 @retval EFI_SUCCESS The erase request was successfully completed.
152 @retval EFI_ACCESS_DENIED The firmware volume is in the WriteDisabled
154 @retval EFI_DEVICE_ERROR The block device is not functioning correctly
155 and could not be written. The firmware device
156 may have been partially erased.
157 @retval EFI_INVALID_PARAMETER One or more of the LBAs listed in the variable
159 @retval EFI_UNSUPPORTED Not supported.
164 FwVolBlockEraseBlock (
165 IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*This
,
169 return EFI_UNSUPPORTED
;
175 Read the specified number of bytes from the block to the input buffer.
177 @param This Indicates the calling context.
178 @param Lba The starting logical block index to read.
179 @param Offset Offset into the block at which to begin reading.
180 @param NumBytes Pointer to a UINT32. At entry, *NumBytes
181 contains the total size of the buffer. At exit,
182 *NumBytes contains the total number of bytes
184 @param Buffer Pinter to a caller-allocated buffer that
185 contains the destine for the read.
187 @retval EFI_SUCCESS The firmware volume was read successfully.
188 @retval EFI_BAD_BUFFER_SIZE The read was attempted across an LBA boundary.
189 @retval EFI_ACCESS_DENIED Access denied.
190 @retval EFI_DEVICE_ERROR The block device is malfunctioning and could not
196 FwVolBlockReadBlock (
197 IN CONST EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*This
,
198 IN CONST EFI_LBA Lba
,
199 IN CONST UINTN Offset
,
200 IN OUT UINTN
*NumBytes
,
204 EFI_FW_VOL_BLOCK_DEVICE
*FvbDevice
;
205 EFI_FIRMWARE_VOLUME_HEADER
*FwVolHeader
;
208 UINTN NumOfBytesRead
;
211 FvbDevice
= FVB_DEVICE_FROM_THIS (This
);
214 // Check if This FW can be read
216 if ((FvbDevice
->FvbAttributes
& EFI_FVB2_READ_STATUS
) == 0) {
217 return EFI_ACCESS_DENIED
;
220 LbaIndex
= (UINTN
) Lba
;
221 if (LbaIndex
>= FvbDevice
->NumBlocks
) {
223 // Invalid Lba, read nothing.
226 return EFI_BAD_BUFFER_SIZE
;
229 if (Offset
> FvbDevice
->LbaCache
[LbaIndex
].Length
) {
231 // all exceed boundary, read nothing.
234 return EFI_BAD_BUFFER_SIZE
;
237 NumOfBytesRead
= *NumBytes
;
238 if (Offset
+ NumOfBytesRead
> FvbDevice
->LbaCache
[LbaIndex
].Length
) {
240 // partial exceed boundary, read data from current postion to end.
242 NumOfBytesRead
= FvbDevice
->LbaCache
[LbaIndex
].Length
- Offset
;
245 LbaStart
= FvbDevice
->LbaCache
[LbaIndex
].Base
;
246 FwVolHeader
= (EFI_FIRMWARE_VOLUME_HEADER
*)((UINTN
) FvbDevice
->BaseAddress
);
247 LbaOffset
= (UINT8
*) FwVolHeader
+ LbaStart
+ Offset
;
250 // Perform read operation
252 CopyMem (Buffer
, LbaOffset
, NumOfBytesRead
);
254 if (NumOfBytesRead
== *NumBytes
) {
258 *NumBytes
= NumOfBytesRead
;
259 return EFI_BAD_BUFFER_SIZE
;
265 Writes the specified number of bytes from the input buffer to the block.
267 @param This Indicates the calling context.
268 @param Lba The starting logical block index to write to.
269 @param Offset Offset into the block at which to begin writing.
270 @param NumBytes Pointer to a UINT32. At entry, *NumBytes
271 contains the total size of the buffer. At exit,
272 *NumBytes contains the total number of bytes
274 @param Buffer Pinter to a caller-allocated buffer that
275 contains the source for the write.
277 @retval EFI_SUCCESS The firmware volume was written successfully.
278 @retval EFI_BAD_BUFFER_SIZE The write was attempted across an LBA boundary.
279 On output, NumBytes contains the total number of
280 bytes actually written.
281 @retval EFI_ACCESS_DENIED The firmware volume is in the WriteDisabled
283 @retval EFI_DEVICE_ERROR The block device is malfunctioning and could not
285 @retval EFI_UNSUPPORTED Not supported.
290 FwVolBlockWriteBlock (
291 IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*This
,
294 IN OUT UINTN
*NumBytes
,
298 return EFI_UNSUPPORTED
;
304 Get Fvb's base address.
306 @param This Indicates the calling context.
307 @param Address Fvb device base address.
309 @retval EFI_SUCCESS Successfully got Fvb's base address.
310 @retval EFI_UNSUPPORTED Not supported.
315 FwVolBlockGetPhysicalAddress (
316 IN CONST EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*This
,
317 OUT EFI_PHYSICAL_ADDRESS
*Address
320 EFI_FW_VOL_BLOCK_DEVICE
*FvbDevice
;
322 FvbDevice
= FVB_DEVICE_FROM_THIS (This
);
324 if ((FvbDevice
->FvbAttributes
& EFI_FVB2_MEMORY_MAPPED
) != 0) {
325 *Address
= FvbDevice
->BaseAddress
;
329 return EFI_UNSUPPORTED
;
335 Retrieves the size in bytes of a specific block within a firmware volume.
337 @param This Indicates the calling context.
338 @param Lba Indicates the block for which to return the
340 @param BlockSize Pointer to a caller-allocated UINTN in which the
341 size of the block is returned.
342 @param NumberOfBlocks Pointer to a caller-allocated UINTN in which the
343 number of consecutive blocks starting with Lba
344 is returned. All blocks in this range have a
347 @retval EFI_SUCCESS The firmware volume base address is returned.
348 @retval EFI_INVALID_PARAMETER The requested LBA is out of range.
353 FwVolBlockGetBlockSize (
354 IN CONST EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*This
,
355 IN CONST EFI_LBA Lba
,
356 IN OUT UINTN
*BlockSize
,
357 IN OUT UINTN
*NumberOfBlocks
361 EFI_FW_VOL_BLOCK_DEVICE
*FvbDevice
;
362 EFI_FV_BLOCK_MAP_ENTRY
*PtrBlockMapEntry
;
363 EFI_FIRMWARE_VOLUME_HEADER
*FwVolHeader
;
365 FvbDevice
= FVB_DEVICE_FROM_THIS (This
);
368 // Do parameter checking
370 if (Lba
>= FvbDevice
->NumBlocks
) {
371 return EFI_INVALID_PARAMETER
;
374 FwVolHeader
= (EFI_FIRMWARE_VOLUME_HEADER
*)((UINTN
)FvbDevice
->BaseAddress
);
376 PtrBlockMapEntry
= FwVolHeader
->BlockMap
;
379 // Search the block map for the given block
382 while ((PtrBlockMapEntry
->NumBlocks
!= 0) || (PtrBlockMapEntry
->Length
!=0 )) {
383 TotalBlocks
+= PtrBlockMapEntry
->NumBlocks
;
384 if (Lba
< TotalBlocks
) {
394 *BlockSize
= PtrBlockMapEntry
->Length
;
395 *NumberOfBlocks
= TotalBlocks
- (UINTN
)Lba
;
402 Get FVB authentication status
404 @param FvbProtocol FVB protocol.
406 @return Authentication status.
410 GetFvbAuthenticationStatus (
411 IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvbProtocol
414 EFI_FW_VOL_BLOCK_DEVICE
*FvbDevice
;
415 UINT32 AuthenticationStatus
;
417 AuthenticationStatus
= 0;
418 FvbDevice
= BASE_CR (FvbProtocol
, EFI_FW_VOL_BLOCK_DEVICE
, FwVolBlockInstance
);
419 if (FvbDevice
->Signature
== FVB_DEVICE_SIGNATURE
) {
420 AuthenticationStatus
= FvbDevice
->AuthenticationStatus
;
423 return AuthenticationStatus
;
427 This routine produces a firmware volume block protocol on a given
430 @param BaseAddress base address of the firmware volume image
431 @param Length length of the firmware volume image
432 @param ParentHandle handle of parent firmware volume, if this image
433 came from an FV image file and section in another firmware
434 volume (ala capsules)
435 @param AuthenticationStatus Authentication status inherited, if this image
436 came from an FV image file and section in another firmware volume.
437 @param FvProtocol Firmware volume block protocol produced.
439 @retval EFI_VOLUME_CORRUPTED Volume corrupted.
440 @retval EFI_OUT_OF_RESOURCES No enough buffer to be allocated.
441 @retval EFI_SUCCESS Successfully produced a FVB protocol on given
446 ProduceFVBProtocolOnBuffer (
447 IN EFI_PHYSICAL_ADDRESS BaseAddress
,
449 IN EFI_HANDLE ParentHandle
,
450 IN UINT32 AuthenticationStatus
,
451 OUT EFI_HANDLE
*FvProtocol OPTIONAL
455 EFI_FW_VOL_BLOCK_DEVICE
*FvbDev
;
456 EFI_FIRMWARE_VOLUME_HEADER
*FwVolHeader
;
461 EFI_FV_BLOCK_MAP_ENTRY
*PtrBlockMapEntry
;
464 FwVolHeader
= (EFI_FIRMWARE_VOLUME_HEADER
*)(UINTN
) BaseAddress
;
466 // Validate FV Header, if not as expected, return
468 if (FwVolHeader
->Signature
!= EFI_FVH_SIGNATURE
) {
469 return EFI_VOLUME_CORRUPTED
;
473 // If EFI_FVB2_WEAK_ALIGNMENT is set in the volume header then the first byte of the volume
474 // can be aligned on any power-of-two boundary. A weakly aligned volume can not be moved from
475 // its initial linked location and maintain its alignment.
477 if ((FwVolHeader
->Attributes
& EFI_FVB2_WEAK_ALIGNMENT
) != EFI_FVB2_WEAK_ALIGNMENT
) {
479 // Get FvHeader alignment
481 FvAlignment
= 1 << ((FwVolHeader
->Attributes
& EFI_FVB2_ALIGNMENT
) >> 16);
483 // FvAlignment must be greater than or equal to 8 bytes of the minimum FFS alignment value.
485 if (FvAlignment
< 8) {
488 if ((UINTN
)BaseAddress
% FvAlignment
!= 0) {
490 // FvImage buffer is not at its required alignment.
494 "Unaligned FvImage found at 0x%lx:0x%lx, the required alignment is 0x%x\n",
499 return EFI_VOLUME_CORRUPTED
;
504 // Allocate EFI_FW_VOL_BLOCK_DEVICE
506 FvbDev
= AllocateCopyPool (sizeof (EFI_FW_VOL_BLOCK_DEVICE
), &mFwVolBlock
);
507 if (FvbDev
== NULL
) {
508 return EFI_OUT_OF_RESOURCES
;
511 FvbDev
->BaseAddress
= BaseAddress
;
512 FvbDev
->FvbAttributes
= FwVolHeader
->Attributes
;
513 FvbDev
->FwVolBlockInstance
.ParentHandle
= ParentHandle
;
514 FvbDev
->AuthenticationStatus
= AuthenticationStatus
;
517 // Init the block caching fields of the device
518 // First, count the number of blocks
520 FvbDev
->NumBlocks
= 0;
521 for (PtrBlockMapEntry
= FwVolHeader
->BlockMap
;
522 PtrBlockMapEntry
->NumBlocks
!= 0;
523 PtrBlockMapEntry
++) {
524 FvbDev
->NumBlocks
+= PtrBlockMapEntry
->NumBlocks
;
528 // Second, allocate the cache
530 if (FvbDev
->NumBlocks
>= (MAX_ADDRESS
/ sizeof (LBA_CACHE
))) {
531 CoreFreePool (FvbDev
);
532 return EFI_OUT_OF_RESOURCES
;
534 FvbDev
->LbaCache
= AllocatePool (FvbDev
->NumBlocks
* sizeof (LBA_CACHE
));
535 if (FvbDev
->LbaCache
== NULL
) {
536 CoreFreePool (FvbDev
);
537 return EFI_OUT_OF_RESOURCES
;
541 // Last, fill in the cache with the linear address of the blocks
545 for (PtrBlockMapEntry
= FwVolHeader
->BlockMap
;
546 PtrBlockMapEntry
->NumBlocks
!= 0; PtrBlockMapEntry
++) {
547 for (BlockIndex2
= 0; BlockIndex2
< PtrBlockMapEntry
->NumBlocks
; BlockIndex2
++) {
548 FvbDev
->LbaCache
[BlockIndex
].Base
= LinearOffset
;
549 FvbDev
->LbaCache
[BlockIndex
].Length
= PtrBlockMapEntry
->Length
;
550 LinearOffset
+= PtrBlockMapEntry
->Length
;
556 // Judget whether FV name guid is produced in Fv extension header
558 if (FwVolHeader
->ExtHeaderOffset
== 0) {
560 // FV does not contains extension header, then produce MEMMAP_DEVICE_PATH
562 FvbDev
->DevicePath
= (EFI_DEVICE_PATH_PROTOCOL
*) AllocateCopyPool (sizeof (FV_MEMMAP_DEVICE_PATH
), &mFvMemmapDevicePathTemplate
);
563 if (FvbDev
->DevicePath
== NULL
) {
565 return EFI_OUT_OF_RESOURCES
;
567 ((FV_MEMMAP_DEVICE_PATH
*) FvbDev
->DevicePath
)->MemMapDevPath
.StartingAddress
= BaseAddress
;
568 ((FV_MEMMAP_DEVICE_PATH
*) FvbDev
->DevicePath
)->MemMapDevPath
.EndingAddress
= BaseAddress
+ FwVolHeader
->FvLength
- 1;
571 // FV contains extension header, then produce MEDIA_FW_VOL_DEVICE_PATH
573 FvbDev
->DevicePath
= (EFI_DEVICE_PATH_PROTOCOL
*) AllocateCopyPool (sizeof (FV_PIWG_DEVICE_PATH
), &mFvPIWGDevicePathTemplate
);
574 if (FvbDev
->DevicePath
== NULL
) {
576 return EFI_OUT_OF_RESOURCES
;
579 &((FV_PIWG_DEVICE_PATH
*)FvbDev
->DevicePath
)->FvDevPath
.FvName
,
580 (GUID
*)(UINTN
)(BaseAddress
+ FwVolHeader
->ExtHeaderOffset
)
586 // Attach FvVolBlock Protocol to new handle
588 Status
= CoreInstallMultipleProtocolInterfaces (
590 &gEfiFirmwareVolumeBlockProtocolGuid
, &FvbDev
->FwVolBlockInstance
,
591 &gEfiDevicePathProtocolGuid
, FvbDev
->DevicePath
,
596 // If they want the handle back, set it.
598 if (FvProtocol
!= NULL
) {
599 *FvProtocol
= FvbDev
->Handle
;
608 This routine consumes FV hobs and produces instances of FW_VOL_BLOCK_PROTOCOL as appropriate.
610 @param ImageHandle The image handle.
611 @param SystemTable The system table.
613 @retval EFI_SUCCESS Successfully initialized firmware volume block
619 FwVolBlockDriverInit (
620 IN EFI_HANDLE ImageHandle
,
621 IN EFI_SYSTEM_TABLE
*SystemTable
624 EFI_PEI_HOB_POINTERS FvHob
;
625 EFI_PEI_HOB_POINTERS Fv3Hob
;
626 UINT32 AuthenticationStatus
;
629 // Core Needs Firmware Volumes to function
631 FvHob
.Raw
= GetHobList ();
632 while ((FvHob
.Raw
= GetNextHob (EFI_HOB_TYPE_FV
, FvHob
.Raw
)) != NULL
) {
633 AuthenticationStatus
= 0;
635 // Get the authentication status propagated from PEI-phase to DXE.
637 Fv3Hob
.Raw
= GetHobList ();
638 while ((Fv3Hob
.Raw
= GetNextHob (EFI_HOB_TYPE_FV3
, Fv3Hob
.Raw
)) != NULL
) {
639 if ((Fv3Hob
.FirmwareVolume3
->BaseAddress
== FvHob
.FirmwareVolume
->BaseAddress
) &&
640 (Fv3Hob
.FirmwareVolume3
->Length
== FvHob
.FirmwareVolume
->Length
)) {
641 AuthenticationStatus
= Fv3Hob
.FirmwareVolume3
->AuthenticationStatus
;
644 Fv3Hob
.Raw
= GET_NEXT_HOB (Fv3Hob
);
647 // Produce an FVB protocol for it
649 ProduceFVBProtocolOnBuffer (FvHob
.FirmwareVolume
->BaseAddress
, FvHob
.FirmwareVolume
->Length
, NULL
, AuthenticationStatus
, NULL
);
650 FvHob
.Raw
= GET_NEXT_HOB (FvHob
);
659 This DXE service routine is used to process a firmware volume. In
660 particular, it can be called by BDS to process a single firmware
661 volume found in a capsule.
663 Caution: The caller need validate the input firmware volume to follow
665 DxeCore will trust the input data and process firmware volume directly.
667 @param FvHeader pointer to a firmware volume header
668 @param Size the size of the buffer pointed to by FvHeader
669 @param FVProtocolHandle the handle on which a firmware volume protocol
670 was produced for the firmware volume passed in.
672 @retval EFI_OUT_OF_RESOURCES if an FVB could not be produced due to lack of
674 @retval EFI_VOLUME_CORRUPTED if the volume was corrupted
675 @retval EFI_SUCCESS a firmware volume protocol was produced for the
681 CoreProcessFirmwareVolume (
684 OUT EFI_HANDLE
*FVProtocolHandle
690 *FVProtocolHandle
= NULL
;
691 Status
= ProduceFVBProtocolOnBuffer (
692 (EFI_PHYSICAL_ADDRESS
) (UINTN
) FvHeader
,
699 // Since in our implementation we use register-protocol-notify to put a
700 // FV protocol on the FVB protocol handle, we can't directly verify that
701 // the FV protocol was produced. Therefore here we will check the handle
702 // and make sure an FV protocol is on it. This indicates that all went
703 // well. Otherwise we have to assume that the volume was corrupted
706 if (!EFI_ERROR(Status
)) {
707 ASSERT (*FVProtocolHandle
!= NULL
);
709 Status
= CoreHandleProtocol (*FVProtocolHandle
, &gEfiFirmwareVolume2ProtocolGuid
, (VOID
**) &Ptr
);
710 if (EFI_ERROR(Status
) || (Ptr
== NULL
)) {
711 return EFI_VOLUME_CORRUPTED
;