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 - 2016, Intel Corporation. All rights reserved.<BR>
8 This program and the accompanying materials
9 are licensed and made available under the terms and conditions of the BSD License
10 which accompanies this distribution. The full text of the license may be found at
11 http://opensource.org/licenses/bsd-license.php
13 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
14 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
19 #include "FwVolBlock.h"
21 FV_MEMMAP_DEVICE_PATH mFvMemmapDevicePathTemplate
= {
27 (UINT8
)(sizeof (MEMMAP_DEVICE_PATH
)),
28 (UINT8
)(sizeof (MEMMAP_DEVICE_PATH
) >> 8)
32 (EFI_PHYSICAL_ADDRESS
) 0,
33 (EFI_PHYSICAL_ADDRESS
) 0,
37 END_ENTIRE_DEVICE_PATH_SUBTYPE
,
39 END_DEVICE_PATH_LENGTH
,
45 FV_PIWG_DEVICE_PATH mFvPIWGDevicePathTemplate
= {
51 (UINT8
)(sizeof (MEDIA_FW_VOL_DEVICE_PATH
)),
52 (UINT8
)(sizeof (MEDIA_FW_VOL_DEVICE_PATH
) >> 8)
59 END_ENTIRE_DEVICE_PATH_SUBTYPE
,
61 END_DEVICE_PATH_LENGTH
,
67 EFI_FW_VOL_BLOCK_DEVICE mFwVolBlock
= {
72 FwVolBlockGetAttributes
,
73 (EFI_FVB_SET_ATTRIBUTES
)FwVolBlockSetAttributes
,
74 FwVolBlockGetPhysicalAddress
,
75 FwVolBlockGetBlockSize
,
77 (EFI_FVB_WRITE
)FwVolBlockWriteBlock
,
78 (EFI_FVB_ERASE_BLOCKS
)FwVolBlockEraseBlock
,
91 Retrieves Volume attributes. No polarity translations are done.
93 @param This Calling context
94 @param Attributes output buffer which contains attributes
96 @retval EFI_SUCCESS The firmware volume attributes were returned.
101 FwVolBlockGetAttributes (
102 IN CONST EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*This
,
103 OUT EFI_FVB_ATTRIBUTES_2
*Attributes
106 EFI_FW_VOL_BLOCK_DEVICE
*FvbDevice
;
108 FvbDevice
= FVB_DEVICE_FROM_THIS (This
);
111 // Since we are read only, it's safe to get attributes data from our in-memory copy.
113 *Attributes
= FvbDevice
->FvbAttributes
& ~EFI_FVB2_WRITE_STATUS
;
121 Modifies the current settings of the firmware volume according to the input parameter.
123 @param This Calling context
124 @param Attributes input buffer which contains attributes
126 @retval EFI_SUCCESS The firmware volume attributes were returned.
127 @retval EFI_INVALID_PARAMETER The attributes requested are in conflict with
128 the capabilities as declared in the firmware
130 @retval EFI_UNSUPPORTED Not supported.
135 FwVolBlockSetAttributes (
136 IN CONST EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*This
,
137 IN CONST EFI_FVB_ATTRIBUTES_2
*Attributes
140 return EFI_UNSUPPORTED
;
146 The EraseBlock() function erases one or more blocks as denoted by the
147 variable argument list. The entire parameter list of blocks must be verified
148 prior to erasing any blocks. If a block is requested that does not exist
149 within the associated firmware volume (it has a larger index than the last
150 block of the firmware volume), the EraseBlock() function must return
151 EFI_INVALID_PARAMETER without modifying the contents of the firmware volume.
153 @param This Calling context
154 @param ... Starting LBA followed by Number of Lba to erase.
155 a -1 to terminate the list.
157 @retval EFI_SUCCESS The erase request was successfully completed.
158 @retval EFI_ACCESS_DENIED The firmware volume is in the WriteDisabled
160 @retval EFI_DEVICE_ERROR The block device is not functioning correctly
161 and could not be written. The firmware device
162 may have been partially erased.
163 @retval EFI_INVALID_PARAMETER One or more of the LBAs listed in the variable
165 @retval EFI_UNSUPPORTED Not supported.
170 FwVolBlockEraseBlock (
171 IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*This
,
175 return EFI_UNSUPPORTED
;
181 Read the specified number of bytes from the block to the input buffer.
183 @param This Indicates the calling context.
184 @param Lba The starting logical block index to read.
185 @param Offset Offset into the block at which to begin reading.
186 @param NumBytes Pointer to a UINT32. At entry, *NumBytes
187 contains the total size of the buffer. At exit,
188 *NumBytes contains the total number of bytes
190 @param Buffer Pinter to a caller-allocated buffer that
191 contains the destine for the read.
193 @retval EFI_SUCCESS The firmware volume was read successfully.
194 @retval EFI_BAD_BUFFER_SIZE The read was attempted across an LBA boundary.
195 @retval EFI_ACCESS_DENIED Access denied.
196 @retval EFI_DEVICE_ERROR The block device is malfunctioning and could not
202 FwVolBlockReadBlock (
203 IN CONST EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*This
,
204 IN CONST EFI_LBA Lba
,
205 IN CONST UINTN Offset
,
206 IN OUT UINTN
*NumBytes
,
210 EFI_FW_VOL_BLOCK_DEVICE
*FvbDevice
;
211 EFI_FIRMWARE_VOLUME_HEADER
*FwVolHeader
;
214 UINTN NumOfBytesRead
;
217 FvbDevice
= FVB_DEVICE_FROM_THIS (This
);
220 // Check if This FW can be read
222 if ((FvbDevice
->FvbAttributes
& EFI_FVB2_READ_STATUS
) == 0) {
223 return EFI_ACCESS_DENIED
;
226 LbaIndex
= (UINTN
) Lba
;
227 if (LbaIndex
>= FvbDevice
->NumBlocks
) {
229 // Invalid Lba, read nothing.
232 return EFI_BAD_BUFFER_SIZE
;
235 if (Offset
> FvbDevice
->LbaCache
[LbaIndex
].Length
) {
237 // all exceed boundary, read nothing.
240 return EFI_BAD_BUFFER_SIZE
;
243 NumOfBytesRead
= *NumBytes
;
244 if (Offset
+ NumOfBytesRead
> FvbDevice
->LbaCache
[LbaIndex
].Length
) {
246 // partial exceed boundary, read data from current postion to end.
248 NumOfBytesRead
= FvbDevice
->LbaCache
[LbaIndex
].Length
- Offset
;
251 LbaStart
= FvbDevice
->LbaCache
[LbaIndex
].Base
;
252 FwVolHeader
= (EFI_FIRMWARE_VOLUME_HEADER
*)((UINTN
) FvbDevice
->BaseAddress
);
253 LbaOffset
= (UINT8
*) FwVolHeader
+ LbaStart
+ Offset
;
256 // Perform read operation
258 CopyMem (Buffer
, LbaOffset
, NumOfBytesRead
);
260 if (NumOfBytesRead
== *NumBytes
) {
264 *NumBytes
= NumOfBytesRead
;
265 return EFI_BAD_BUFFER_SIZE
;
271 Writes the specified number of bytes from the input buffer to the block.
273 @param This Indicates the calling context.
274 @param Lba The starting logical block index to write to.
275 @param Offset Offset into the block at which to begin writing.
276 @param NumBytes Pointer to a UINT32. At entry, *NumBytes
277 contains the total size of the buffer. At exit,
278 *NumBytes contains the total number of bytes
280 @param Buffer Pinter to a caller-allocated buffer that
281 contains the source for the write.
283 @retval EFI_SUCCESS The firmware volume was written successfully.
284 @retval EFI_BAD_BUFFER_SIZE The write was attempted across an LBA boundary.
285 On output, NumBytes contains the total number of
286 bytes actually written.
287 @retval EFI_ACCESS_DENIED The firmware volume is in the WriteDisabled
289 @retval EFI_DEVICE_ERROR The block device is malfunctioning and could not
291 @retval EFI_UNSUPPORTED Not supported.
296 FwVolBlockWriteBlock (
297 IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*This
,
300 IN OUT UINTN
*NumBytes
,
304 return EFI_UNSUPPORTED
;
310 Get Fvb's base address.
312 @param This Indicates the calling context.
313 @param Address Fvb device base address.
315 @retval EFI_SUCCESS Successfully got Fvb's base address.
316 @retval EFI_UNSUPPORTED Not supported.
321 FwVolBlockGetPhysicalAddress (
322 IN CONST EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*This
,
323 OUT EFI_PHYSICAL_ADDRESS
*Address
326 EFI_FW_VOL_BLOCK_DEVICE
*FvbDevice
;
328 FvbDevice
= FVB_DEVICE_FROM_THIS (This
);
330 if ((FvbDevice
->FvbAttributes
& EFI_FVB2_MEMORY_MAPPED
) != 0) {
331 *Address
= FvbDevice
->BaseAddress
;
335 return EFI_UNSUPPORTED
;
341 Retrieves the size in bytes of a specific block within a firmware volume.
343 @param This Indicates the calling context.
344 @param Lba Indicates the block for which to return the
346 @param BlockSize Pointer to a caller-allocated UINTN in which the
347 size of the block is returned.
348 @param NumberOfBlocks Pointer to a caller-allocated UINTN in which the
349 number of consecutive blocks starting with Lba
350 is returned. All blocks in this range have a
353 @retval EFI_SUCCESS The firmware volume base address is returned.
354 @retval EFI_INVALID_PARAMETER The requested LBA is out of range.
359 FwVolBlockGetBlockSize (
360 IN CONST EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*This
,
361 IN CONST EFI_LBA Lba
,
362 IN OUT UINTN
*BlockSize
,
363 IN OUT UINTN
*NumberOfBlocks
367 EFI_FW_VOL_BLOCK_DEVICE
*FvbDevice
;
368 EFI_FV_BLOCK_MAP_ENTRY
*PtrBlockMapEntry
;
369 EFI_FIRMWARE_VOLUME_HEADER
*FwVolHeader
;
371 FvbDevice
= FVB_DEVICE_FROM_THIS (This
);
374 // Do parameter checking
376 if (Lba
>= FvbDevice
->NumBlocks
) {
377 return EFI_INVALID_PARAMETER
;
380 FwVolHeader
= (EFI_FIRMWARE_VOLUME_HEADER
*)((UINTN
)FvbDevice
->BaseAddress
);
382 PtrBlockMapEntry
= FwVolHeader
->BlockMap
;
385 // Search the block map for the given block
388 while ((PtrBlockMapEntry
->NumBlocks
!= 0) || (PtrBlockMapEntry
->Length
!=0 )) {
389 TotalBlocks
+= PtrBlockMapEntry
->NumBlocks
;
390 if (Lba
< TotalBlocks
) {
400 *BlockSize
= PtrBlockMapEntry
->Length
;
401 *NumberOfBlocks
= TotalBlocks
- (UINTN
)Lba
;
408 Get FVB authentication status
410 @param FvbProtocol FVB protocol.
412 @return Authentication status.
416 GetFvbAuthenticationStatus (
417 IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*FvbProtocol
420 EFI_FW_VOL_BLOCK_DEVICE
*FvbDevice
;
421 UINT32 AuthenticationStatus
;
423 AuthenticationStatus
= 0;
424 FvbDevice
= BASE_CR (FvbProtocol
, EFI_FW_VOL_BLOCK_DEVICE
, FwVolBlockInstance
);
425 if (FvbDevice
->Signature
== FVB_DEVICE_SIGNATURE
) {
426 AuthenticationStatus
= FvbDevice
->AuthenticationStatus
;
429 return AuthenticationStatus
;
433 This routine produces a firmware volume block protocol on a given
436 @param BaseAddress base address of the firmware volume image
437 @param Length length of the firmware volume image
438 @param ParentHandle handle of parent firmware volume, if this image
439 came from an FV image file and section in another firmware
440 volume (ala capsules)
441 @param AuthenticationStatus Authentication status inherited, if this image
442 came from an FV image file and section in another firmware volume.
443 @param FvProtocol Firmware volume block protocol produced.
445 @retval EFI_VOLUME_CORRUPTED Volume corrupted.
446 @retval EFI_OUT_OF_RESOURCES No enough buffer to be allocated.
447 @retval EFI_SUCCESS Successfully produced a FVB protocol on given
452 ProduceFVBProtocolOnBuffer (
453 IN EFI_PHYSICAL_ADDRESS BaseAddress
,
455 IN EFI_HANDLE ParentHandle
,
456 IN UINT32 AuthenticationStatus
,
457 OUT EFI_HANDLE
*FvProtocol OPTIONAL
461 EFI_FW_VOL_BLOCK_DEVICE
*FvbDev
;
462 EFI_FIRMWARE_VOLUME_HEADER
*FwVolHeader
;
467 EFI_FV_BLOCK_MAP_ENTRY
*PtrBlockMapEntry
;
470 FwVolHeader
= (EFI_FIRMWARE_VOLUME_HEADER
*)(UINTN
) BaseAddress
;
472 // Validate FV Header, if not as expected, return
474 if (FwVolHeader
->Signature
!= EFI_FVH_SIGNATURE
) {
475 return EFI_VOLUME_CORRUPTED
;
479 // If EFI_FVB2_WEAK_ALIGNMENT is set in the volume header then the first byte of the volume
480 // can be aligned on any power-of-two boundary. A weakly aligned volume can not be moved from
481 // its initial linked location and maintain its alignment.
483 if ((FwVolHeader
->Attributes
& EFI_FVB2_WEAK_ALIGNMENT
) != EFI_FVB2_WEAK_ALIGNMENT
) {
485 // Get FvHeader alignment
487 FvAlignment
= 1 << ((FwVolHeader
->Attributes
& EFI_FVB2_ALIGNMENT
) >> 16);
489 // FvAlignment must be greater than or equal to 8 bytes of the minimum FFS alignment value.
491 if (FvAlignment
< 8) {
494 if ((UINTN
)BaseAddress
% FvAlignment
!= 0) {
496 // FvImage buffer is not at its required alignment.
500 "Unaligned FvImage found at 0x%lx:0x%lx, the required alignment is 0x%x\n",
505 return EFI_VOLUME_CORRUPTED
;
510 // Allocate EFI_FW_VOL_BLOCK_DEVICE
512 FvbDev
= AllocateCopyPool (sizeof (EFI_FW_VOL_BLOCK_DEVICE
), &mFwVolBlock
);
513 if (FvbDev
== NULL
) {
514 return EFI_OUT_OF_RESOURCES
;
517 FvbDev
->BaseAddress
= BaseAddress
;
518 FvbDev
->FvbAttributes
= FwVolHeader
->Attributes
;
519 FvbDev
->FwVolBlockInstance
.ParentHandle
= ParentHandle
;
520 if (ParentHandle
!= NULL
) {
521 FvbDev
->AuthenticationStatus
= AuthenticationStatus
;
525 // Init the block caching fields of the device
526 // First, count the number of blocks
528 FvbDev
->NumBlocks
= 0;
529 for (PtrBlockMapEntry
= FwVolHeader
->BlockMap
;
530 PtrBlockMapEntry
->NumBlocks
!= 0;
531 PtrBlockMapEntry
++) {
532 FvbDev
->NumBlocks
+= PtrBlockMapEntry
->NumBlocks
;
536 // Second, allocate the cache
538 if (FvbDev
->NumBlocks
>= (MAX_ADDRESS
/ sizeof (LBA_CACHE
))) {
539 CoreFreePool (FvbDev
);
540 return EFI_OUT_OF_RESOURCES
;
542 FvbDev
->LbaCache
= AllocatePool (FvbDev
->NumBlocks
* sizeof (LBA_CACHE
));
543 if (FvbDev
->LbaCache
== NULL
) {
544 CoreFreePool (FvbDev
);
545 return EFI_OUT_OF_RESOURCES
;
549 // Last, fill in the cache with the linear address of the blocks
553 for (PtrBlockMapEntry
= FwVolHeader
->BlockMap
;
554 PtrBlockMapEntry
->NumBlocks
!= 0; PtrBlockMapEntry
++) {
555 for (BlockIndex2
= 0; BlockIndex2
< PtrBlockMapEntry
->NumBlocks
; BlockIndex2
++) {
556 FvbDev
->LbaCache
[BlockIndex
].Base
= LinearOffset
;
557 FvbDev
->LbaCache
[BlockIndex
].Length
= PtrBlockMapEntry
->Length
;
558 LinearOffset
+= PtrBlockMapEntry
->Length
;
564 // Judget whether FV name guid is produced in Fv extension header
566 if (FwVolHeader
->ExtHeaderOffset
== 0) {
568 // FV does not contains extension header, then produce MEMMAP_DEVICE_PATH
570 FvbDev
->DevicePath
= (EFI_DEVICE_PATH_PROTOCOL
*) AllocateCopyPool (sizeof (FV_MEMMAP_DEVICE_PATH
), &mFvMemmapDevicePathTemplate
);
571 if (FvbDev
->DevicePath
== NULL
) {
573 return EFI_OUT_OF_RESOURCES
;
575 ((FV_MEMMAP_DEVICE_PATH
*) FvbDev
->DevicePath
)->MemMapDevPath
.StartingAddress
= BaseAddress
;
576 ((FV_MEMMAP_DEVICE_PATH
*) FvbDev
->DevicePath
)->MemMapDevPath
.EndingAddress
= BaseAddress
+ FwVolHeader
->FvLength
- 1;
579 // FV contains extension header, then produce MEDIA_FW_VOL_DEVICE_PATH
581 FvbDev
->DevicePath
= (EFI_DEVICE_PATH_PROTOCOL
*) AllocateCopyPool (sizeof (FV_PIWG_DEVICE_PATH
), &mFvPIWGDevicePathTemplate
);
582 if (FvbDev
->DevicePath
== NULL
) {
584 return EFI_OUT_OF_RESOURCES
;
587 &((FV_PIWG_DEVICE_PATH
*)FvbDev
->DevicePath
)->FvDevPath
.FvName
,
588 (GUID
*)(UINTN
)(BaseAddress
+ FwVolHeader
->ExtHeaderOffset
)
594 // Attach FvVolBlock Protocol to new handle
596 Status
= CoreInstallMultipleProtocolInterfaces (
598 &gEfiFirmwareVolumeBlockProtocolGuid
, &FvbDev
->FwVolBlockInstance
,
599 &gEfiDevicePathProtocolGuid
, FvbDev
->DevicePath
,
604 // If they want the handle back, set it.
606 if (FvProtocol
!= NULL
) {
607 *FvProtocol
= FvbDev
->Handle
;
616 This routine consumes FV hobs and produces instances of FW_VOL_BLOCK_PROTOCOL as appropriate.
618 @param ImageHandle The image handle.
619 @param SystemTable The system table.
621 @retval EFI_SUCCESS Successfully initialized firmware volume block
627 FwVolBlockDriverInit (
628 IN EFI_HANDLE ImageHandle
,
629 IN EFI_SYSTEM_TABLE
*SystemTable
632 EFI_PEI_HOB_POINTERS FvHob
;
635 // Core Needs Firmware Volumes to function
637 FvHob
.Raw
= GetHobList ();
638 while ((FvHob
.Raw
= GetNextHob (EFI_HOB_TYPE_FV
, FvHob
.Raw
)) != NULL
) {
640 // Produce an FVB protocol for it
642 ProduceFVBProtocolOnBuffer (FvHob
.FirmwareVolume
->BaseAddress
, FvHob
.FirmwareVolume
->Length
, NULL
, 0, NULL
);
643 FvHob
.Raw
= GET_NEXT_HOB (FvHob
);
652 This DXE service routine is used to process a firmware volume. In
653 particular, it can be called by BDS to process a single firmware
654 volume found in a capsule.
656 Caution: The caller need validate the input firmware volume to follow
658 DxeCore will trust the input data and process firmware volume directly.
660 @param FvHeader pointer to a firmware volume header
661 @param Size the size of the buffer pointed to by FvHeader
662 @param FVProtocolHandle the handle on which a firmware volume protocol
663 was produced for the firmware volume passed in.
665 @retval EFI_OUT_OF_RESOURCES if an FVB could not be produced due to lack of
667 @retval EFI_VOLUME_CORRUPTED if the volume was corrupted
668 @retval EFI_SUCCESS a firmware volume protocol was produced for the
674 CoreProcessFirmwareVolume (
677 OUT EFI_HANDLE
*FVProtocolHandle
683 *FVProtocolHandle
= NULL
;
684 Status
= ProduceFVBProtocolOnBuffer (
685 (EFI_PHYSICAL_ADDRESS
) (UINTN
) FvHeader
,
692 // Since in our implementation we use register-protocol-notify to put a
693 // FV protocol on the FVB protocol handle, we can't directly verify that
694 // the FV protocol was produced. Therefore here we will check the handle
695 // and make sure an FV protocol is on it. This indicates that all went
696 // well. Otherwise we have to assume that the volume was corrupted
699 if (!EFI_ERROR(Status
)) {
700 ASSERT (*FVProtocolHandle
!= NULL
);
702 Status
= CoreHandleProtocol (*FVProtocolHandle
, &gEfiFirmwareVolume2ProtocolGuid
, (VOID
**) &Ptr
);
703 if (EFI_ERROR(Status
) || (Ptr
== NULL
)) {
704 return EFI_VOLUME_CORRUPTED
;