2 Implementations for Firmware Volume Block protocol.
4 It consumes FV HOBs and creates read-lonly Firmare Volume Block protocol
5 instances for each of them.
7 Copyright (c) 2006 - 2008, Intel Corporation. <BR>
8 All rights reserved. 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
,
90 Retrieves Volume attributes. No polarity translations are done.
92 @param This Calling context
93 @param Attributes output buffer which contains attributes
95 @retval EFI_SUCCESS The firmware volume attributes were returned.
100 FwVolBlockGetAttributes (
101 IN CONST EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*This
,
102 OUT EFI_FVB_ATTRIBUTES_2
*Attributes
105 EFI_FW_VOL_BLOCK_DEVICE
*FvbDevice
;
107 FvbDevice
= FVB_DEVICE_FROM_THIS (This
);
110 // Since we are read only, it's safe to get attributes data from our in-memory copy.
112 *Attributes
= FvbDevice
->FvbAttributes
& ~EFI_FVB2_WRITE_STATUS
;
120 Modifies the current settings of the firmware volume according to the input parameter.
122 @param This Calling context
123 @param Attributes input buffer which contains attributes
125 @retval EFI_SUCCESS The firmware volume attributes were returned.
126 @retval EFI_INVALID_PARAMETER The attributes requested are in conflict with
127 the capabilities as declared in the firmware
129 @retval EFI_UNSUPPORTED Not supported.
134 FwVolBlockSetAttributes (
135 IN CONST EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*This
,
136 IN CONST EFI_FVB_ATTRIBUTES_2
*Attributes
139 return EFI_UNSUPPORTED
;
145 The EraseBlock() function erases one or more blocks as denoted by the
146 variable argument list. The entire parameter list of blocks must be verified
147 prior to erasing any blocks. If a block is requested that does not exist
148 within the associated firmware volume (it has a larger index than the last
149 block of the firmware volume), the EraseBlock() function must return
150 EFI_INVALID_PARAMETER without modifying the contents of the firmware volume.
152 @param This Calling context
153 @param ... Starting LBA followed by Number of Lba to erase.
154 a -1 to terminate the list.
156 @retval EFI_SUCCESS The erase request was successfully completed.
157 @retval EFI_ACCESS_DENIED The firmware volume is in the WriteDisabled
159 @retval EFI_DEVICE_ERROR The block device is not functioning correctly
160 and could not be written. The firmware device
161 may have been partially erased.
162 @retval EFI_INVALID_PARAMETER One or more of the LBAs listed in the variable
164 @retval EFI_UNSUPPORTED Not supported.
169 FwVolBlockEraseBlock (
170 IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*This
,
174 return EFI_UNSUPPORTED
;
180 Read the specified number of bytes from the block to the input buffer.
182 @param This Indicates the calling context.
183 @param Lba The starting logical block index to read.
184 @param Offset Offset into the block at which to begin reading.
185 @param NumBytes Pointer to a UINT32. At entry, *NumBytes
186 contains the total size of the buffer. At exit,
187 *NumBytes contains the total number of bytes
189 @param Buffer Pinter to a caller-allocated buffer that
190 contains the destine for the read.
192 @retval EFI_SUCCESS The firmware volume was read successfully.
193 @retval EFI_BAD_BUFFER_SIZE The read was attempted across an LBA boundary.
194 @retval EFI_ACCESS_DENIED Access denied.
195 @retval EFI_DEVICE_ERROR The block device is malfunctioning and could not
201 FwVolBlockReadBlock (
202 IN CONST EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*This
,
203 IN CONST EFI_LBA Lba
,
204 IN CONST UINTN Offset
,
205 IN OUT UINTN
*NumBytes
,
209 EFI_FW_VOL_BLOCK_DEVICE
*FvbDevice
;
210 EFI_FIRMWARE_VOLUME_HEADER
*FwVolHeader
;
213 UINTN NumOfBytesRead
;
216 FvbDevice
= FVB_DEVICE_FROM_THIS (This
);
219 // Check if This FW can be read
221 if ((FvbDevice
->FvbAttributes
& EFI_FVB2_READ_STATUS
) == 0) {
222 return EFI_ACCESS_DENIED
;
225 LbaIndex
= (UINTN
) Lba
;
226 if (LbaIndex
>= FvbDevice
->NumBlocks
) {
228 // Invalid Lba, read nothing.
231 return EFI_BAD_BUFFER_SIZE
;
234 if (Offset
> FvbDevice
->LbaCache
[LbaIndex
].Length
) {
236 // all exceed boundry, read nothing.
239 return EFI_BAD_BUFFER_SIZE
;
242 NumOfBytesRead
= *NumBytes
;
243 if (Offset
+ NumOfBytesRead
> FvbDevice
->LbaCache
[LbaIndex
].Length
) {
245 // partial exceed boundry, read data from current postion to end.
247 NumOfBytesRead
= FvbDevice
->LbaCache
[LbaIndex
].Length
- Offset
;
250 LbaStart
= FvbDevice
->LbaCache
[LbaIndex
].Base
;
251 FwVolHeader
= (EFI_FIRMWARE_VOLUME_HEADER
*)((UINTN
) FvbDevice
->BaseAddress
);
252 LbaOffset
= (UINT8
*) FwVolHeader
+ LbaStart
+ Offset
;
255 // Perform read operation
257 CopyMem (Buffer
, LbaOffset
, NumOfBytesRead
);
259 if (NumOfBytesRead
== *NumBytes
) {
263 *NumBytes
= NumOfBytesRead
;
264 return EFI_BAD_BUFFER_SIZE
;
270 Writes the specified number of bytes from the input buffer to the block.
272 @param This Indicates the calling context.
273 @param Lba The starting logical block index to write to.
274 @param Offset Offset into the block at which to begin writing.
275 @param NumBytes Pointer to a UINT32. At entry, *NumBytes
276 contains the total size of the buffer. At exit,
277 *NumBytes contains the total number of bytes
279 @param Buffer Pinter to a caller-allocated buffer that
280 contains the source for the write.
282 @retval EFI_SUCCESS The firmware volume was written successfully.
283 @retval EFI_BAD_BUFFER_SIZE The write was attempted across an LBA boundary.
284 On output, NumBytes contains the total number of
285 bytes actually written.
286 @retval EFI_ACCESS_DENIED The firmware volume is in the WriteDisabled
288 @retval EFI_DEVICE_ERROR The block device is malfunctioning and could not
290 @retval EFI_UNSUPPORTED Not supported.
295 FwVolBlockWriteBlock (
296 IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*This
,
299 IN OUT UINTN
*NumBytes
,
303 return EFI_UNSUPPORTED
;
309 Get Fvb's base address.
311 @param This Indicates the calling context.
312 @param Address Fvb device base address.
314 @retval EFI_SUCCESS Successfully got Fvb's base address.
315 @retval EFI_UNSUPPORTED Not supported.
320 FwVolBlockGetPhysicalAddress (
321 IN CONST EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*This
,
322 OUT EFI_PHYSICAL_ADDRESS
*Address
325 EFI_FW_VOL_BLOCK_DEVICE
*FvbDevice
;
327 FvbDevice
= FVB_DEVICE_FROM_THIS (This
);
329 if ((FvbDevice
->FvbAttributes
& EFI_FVB2_MEMORY_MAPPED
) != 0) {
330 *Address
= FvbDevice
->BaseAddress
;
334 return EFI_UNSUPPORTED
;
340 Retrieves the size in bytes of a specific block within a firmware volume.
342 @param This Indicates the calling context.
343 @param Lba Indicates the block for which to return the
345 @param BlockSize Pointer to a caller-allocated UINTN in which the
346 size of the block is returned.
347 @param NumberOfBlocks Pointer to a caller-allocated UINTN in which the
348 number of consecutive blocks starting with Lba
349 is returned. All blocks in this range have a
352 @retval EFI_SUCCESS The firmware volume base address is returned.
353 @retval EFI_INVALID_PARAMETER The requested LBA is out of range.
358 FwVolBlockGetBlockSize (
359 IN CONST EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*This
,
360 IN CONST EFI_LBA Lba
,
361 IN OUT UINTN
*BlockSize
,
362 IN OUT UINTN
*NumberOfBlocks
366 EFI_FW_VOL_BLOCK_DEVICE
*FvbDevice
;
367 EFI_FV_BLOCK_MAP_ENTRY
*PtrBlockMapEntry
;
368 EFI_FIRMWARE_VOLUME_HEADER
*FwVolHeader
;
370 FvbDevice
= FVB_DEVICE_FROM_THIS (This
);
373 // Do parameter checking
375 if (Lba
>= FvbDevice
->NumBlocks
) {
376 return EFI_INVALID_PARAMETER
;
379 FwVolHeader
= (EFI_FIRMWARE_VOLUME_HEADER
*)((UINTN
)FvbDevice
->BaseAddress
);
381 PtrBlockMapEntry
= FwVolHeader
->BlockMap
;
384 // Search the block map for the given block
387 while ((PtrBlockMapEntry
->NumBlocks
!= 0) || (PtrBlockMapEntry
->Length
!=0 )) {
388 TotalBlocks
+= PtrBlockMapEntry
->NumBlocks
;
389 if (Lba
< TotalBlocks
) {
399 *BlockSize
= PtrBlockMapEntry
->Length
;
400 *NumberOfBlocks
= TotalBlocks
- (UINTN
)Lba
;
408 This routine produces a firmware volume block protocol on a given
411 @param BaseAddress base address of the firmware volume image
412 @param Length length of the firmware volume image
413 @param ParentHandle handle of parent firmware volume, if this image
414 came from an FV image file in another firmware
415 volume (ala capsules)
416 @param FvProtocol Firmware volume block protocol produced.
418 @retval EFI_VOLUME_CORRUPTED Volume corrupted.
419 @retval EFI_OUT_OF_RESOURCES No enough buffer to be allocated.
420 @retval EFI_SUCCESS Successfully produced a FVB protocol on given
425 ProduceFVBProtocolOnBuffer (
426 IN EFI_PHYSICAL_ADDRESS BaseAddress
,
428 IN EFI_HANDLE ParentHandle
,
429 OUT EFI_HANDLE
*FvProtocol OPTIONAL
433 EFI_FW_VOL_BLOCK_DEVICE
*FvbDev
;
434 EFI_FIRMWARE_VOLUME_HEADER
*FwVolHeader
;
439 EFI_FV_BLOCK_MAP_ENTRY
*PtrBlockMapEntry
;
442 FwVolHeader
= (EFI_FIRMWARE_VOLUME_HEADER
*)(UINTN
) BaseAddress
;
444 // Validate FV Header, if not as expected, return
446 if (FwVolHeader
->Signature
!= EFI_FVH_SIGNATURE
) {
447 return EFI_VOLUME_CORRUPTED
;
450 // Get FvHeader alignment
452 FvAlignment
= 1 << ((FwVolHeader
->Attributes
& EFI_FVB2_ALIGNMENT
) >> 16);
454 // FvAlignment must be greater than or equal to 8 bytes of the minimum FFS alignment value.
456 if (FvAlignment
< 8) {
459 if ((UINTN
)BaseAddress
% FvAlignment
!= 0) {
461 // FvImage buffer is not at its required alignment.
463 return EFI_VOLUME_CORRUPTED
;
466 // Allocate EFI_FW_VOL_BLOCK_DEVICE
468 FvbDev
= AllocateCopyPool (sizeof (EFI_FW_VOL_BLOCK_DEVICE
), &mFwVolBlock
);
469 if (FvbDev
== NULL
) {
470 return EFI_OUT_OF_RESOURCES
;
473 FvbDev
->BaseAddress
= BaseAddress
;
474 FvbDev
->FvbAttributes
= FwVolHeader
->Attributes
;
475 FvbDev
->FwVolBlockInstance
.ParentHandle
= ParentHandle
;
478 // Init the block caching fields of the device
479 // First, count the number of blocks
481 FvbDev
->NumBlocks
= 0;
482 for (PtrBlockMapEntry
= FwVolHeader
->BlockMap
;
483 PtrBlockMapEntry
->NumBlocks
!= 0;
484 PtrBlockMapEntry
++) {
485 FvbDev
->NumBlocks
+= PtrBlockMapEntry
->NumBlocks
;
488 // Second, allocate the cache
490 FvbDev
->LbaCache
= AllocatePool (FvbDev
->NumBlocks
* sizeof (LBA_CACHE
));
491 if (FvbDev
->LbaCache
== NULL
) {
492 CoreFreePool (FvbDev
);
493 return EFI_OUT_OF_RESOURCES
;
497 // Last, fill in the cache with the linear address of the blocks
501 for (PtrBlockMapEntry
= FwVolHeader
->BlockMap
;
502 PtrBlockMapEntry
->NumBlocks
!= 0; PtrBlockMapEntry
++) {
503 for (BlockIndex2
= 0; BlockIndex2
< PtrBlockMapEntry
->NumBlocks
; BlockIndex2
++) {
504 FvbDev
->LbaCache
[BlockIndex
].Base
= LinearOffset
;
505 FvbDev
->LbaCache
[BlockIndex
].Length
= PtrBlockMapEntry
->Length
;
506 LinearOffset
+= PtrBlockMapEntry
->Length
;
512 // Judget whether FV name guid is produced in Fv extension header
514 if (FwVolHeader
->ExtHeaderOffset
== 0) {
516 // FV does not contains extension header, then produce MEMMAP_DEVICE_PATH
518 FvbDev
->DevicePath
= (EFI_DEVICE_PATH_PROTOCOL
*) AllocateCopyPool (sizeof (FV_MEMMAP_DEVICE_PATH
), &mFvMemmapDevicePathTemplate
);
519 if (FvbDev
->DevicePath
== NULL
) {
521 return EFI_OUT_OF_RESOURCES
;
523 ((FV_MEMMAP_DEVICE_PATH
*) FvbDev
->DevicePath
)->MemMapDevPath
.StartingAddress
= BaseAddress
;
524 ((FV_MEMMAP_DEVICE_PATH
*) FvbDev
->DevicePath
)->MemMapDevPath
.EndingAddress
= BaseAddress
+ FwVolHeader
->FvLength
- 1;
527 // FV contains extension header, then produce MEDIA_FW_VOL_DEVICE_PATH
529 FvbDev
->DevicePath
= (EFI_DEVICE_PATH_PROTOCOL
*) AllocateCopyPool (sizeof (FV_PIWG_DEVICE_PATH
), &mFvPIWGDevicePathTemplate
);
530 if (FvbDev
->DevicePath
== NULL
) {
532 return EFI_OUT_OF_RESOURCES
;
535 &((FV_PIWG_DEVICE_PATH
*)FvbDev
->DevicePath
)->FvDevPath
.FvName
,
536 (GUID
*)(UINTN
)(BaseAddress
+ FwVolHeader
->ExtHeaderOffset
)
542 // Attach FvVolBlock Protocol to new handle
544 Status
= CoreInstallMultipleProtocolInterfaces (
546 &gEfiFirmwareVolumeBlockProtocolGuid
, &FvbDev
->FwVolBlockInstance
,
547 &gEfiDevicePathProtocolGuid
, FvbDev
->DevicePath
,
552 // If they want the handle back, set it.
554 if (FvProtocol
!= NULL
) {
555 *FvProtocol
= FvbDev
->Handle
;
564 This routine consumes FV hobs and produces instances of FW_VOL_BLOCK_PROTOCOL as appropriate.
566 @param ImageHandle The image handle.
567 @param SystemTable The system table.
569 @retval EFI_SUCCESS Successfully initialized firmware volume block
575 FwVolBlockDriverInit (
576 IN EFI_HANDLE ImageHandle
,
577 IN EFI_SYSTEM_TABLE
*SystemTable
580 EFI_PEI_HOB_POINTERS FvHob
;
583 // Core Needs Firmware Volumes to function
585 FvHob
.Raw
= GetHobList ();
586 while ((FvHob
.Raw
= GetNextHob (EFI_HOB_TYPE_FV
, FvHob
.Raw
)) != NULL
) {
588 // Produce an FVB protocol for it
590 ProduceFVBProtocolOnBuffer (FvHob
.FirmwareVolume
->BaseAddress
, FvHob
.FirmwareVolume
->Length
, NULL
, NULL
);
591 FvHob
.Raw
= GET_NEXT_HOB (FvHob
);
600 This DXE service routine is used to process a firmware volume. In
601 particular, it can be called by BDS to process a single firmware
602 volume found in a capsule.
604 @param FvHeader pointer to a firmware volume header
605 @param Size the size of the buffer pointed to by FvHeader
606 @param FVProtocolHandle the handle on which a firmware volume protocol
607 was produced for the firmware volume passed in.
609 @retval EFI_OUT_OF_RESOURCES if an FVB could not be produced due to lack of
611 @retval EFI_VOLUME_CORRUPTED if the volume was corrupted
612 @retval EFI_SUCCESS a firmware volume protocol was produced for the
618 CoreProcessFirmwareVolume (
621 OUT EFI_HANDLE
*FVProtocolHandle
627 *FVProtocolHandle
= NULL
;
628 Status
= ProduceFVBProtocolOnBuffer (
629 (EFI_PHYSICAL_ADDRESS
) (UINTN
) FvHeader
,
635 // Since in our implementation we use register-protocol-notify to put a
636 // FV protocol on the FVB protocol handle, we can't directly verify that
637 // the FV protocol was produced. Therefore here we will check the handle
638 // and make sure an FV protocol is on it. This indicates that all went
639 // well. Otherwise we have to assume that the volume was corrupted
642 if (!EFI_ERROR(Status
)) {
644 Status
= CoreHandleProtocol (*FVProtocolHandle
, &gEfiFirmwareVolume2ProtocolGuid
, (VOID
**) &Ptr
);
645 if (EFI_ERROR(Status
) || (Ptr
== NULL
)) {
646 return EFI_VOLUME_CORRUPTED
;