2 Firmware Volume Block Protocol Runtime Interface Abstraction
3 And FVB Extension protocol Runtime Interface Abstraction
5 mFvbEntry is an array of Handle Fvb pairs. The Fvb Lib Instance matches the
6 index in the mFvbEntry array. This should be the same sequence as the FVB's
7 were described in the HOB. We have to remember the handle so we can tell if
8 the protocol has been reinstalled and it needs updating.
11 Copyright (c) 2006 - 2008, Intel Corporation
12 All rights reserved. This program and the accompanying materials
13 are licensed and made available under the terms and conditions of the BSD License
14 which accompanies this distribution. The full text of the license may be found at
15 http://opensource.org/licenses/bsd-license.php
17 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
18 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
27 // Event for Set Virtual Map Changed Event
29 EFI_EVENT mSetVirtualMapChangedEvent
= NULL
;
32 // Lib will ASSERT if more FVB devices than this are added to the system.
34 FVB_ENTRY
*mFvbEntry
= NULL
;
35 EFI_EVENT mFvbRegistration
= NULL
;
39 Check whether an address is runtime memory or not.
41 @param Address The Address being checked.
43 @retval TRUE The address is runtime memory.
44 @retval FALSE The address is not runtime memory.
52 UINT8 TmpMemoryMap
[1];
55 UINT32 DescriptorVersion
;
57 EFI_MEMORY_DESCRIPTOR
*MemoryMap
;
58 EFI_MEMORY_DESCRIPTOR
*MemoryMapPtr
;
65 // Get System MemoryMapSize
68 Status
= gBS
->GetMemoryMap (
70 (EFI_MEMORY_DESCRIPTOR
*)TmpMemoryMap
,
75 ASSERT (Status
== EFI_BUFFER_TOO_SMALL
);
77 // Enlarge space here, because we will allocate pool now.
79 MemoryMapSize
+= EFI_PAGE_SIZE
;
80 MemoryMap
= AllocatePool (MemoryMapSize
);
81 ASSERT (MemoryMap
!= NULL
);
84 // Get System MemoryMap
86 Status
= gBS
->GetMemoryMap (
93 ASSERT_EFI_ERROR (Status
);
95 MemoryMapPtr
= MemoryMap
;
97 // Search the request Address
99 for (Index
= 0; Index
< (MemoryMapSize
/ DescriptorSize
); Index
++) {
100 if (((EFI_PHYSICAL_ADDRESS
)(UINTN
)Address
>= MemoryMap
->PhysicalStart
) &&
101 ((EFI_PHYSICAL_ADDRESS
)(UINTN
)Address
< MemoryMap
->PhysicalStart
102 + LShiftU64 (MemoryMap
->NumberOfPages
, EFI_PAGE_SHIFT
))) {
106 if ((MemoryMap
->Attribute
& EFI_MEMORY_RUNTIME
) != 0) {
114 MemoryMap
= (EFI_MEMORY_DESCRIPTOR
*)((UINTN
) MemoryMap
+ DescriptorSize
);
120 FreePool (MemoryMapPtr
);
127 Update mFvbEntry. Add new entry, or update existing entry if Fvb protocol is
130 @param Event The Event that is being processed
131 @param Context Event Context
136 FvbNotificationEvent (
148 BufferSize
= sizeof (Handle
);
149 Status
= gBS
->LocateHandle (
151 &gEfiFirmwareVolumeBlockProtocolGuid
,
156 if (EFI_ERROR (Status
)) {
158 // Exit Path of While Loop....
163 UpdateIndex
= MAX_FVB_COUNT
;
164 for (Index
= 0; Index
< mFvbCount
; Index
++) {
165 if (mFvbEntry
[Index
].Handle
== Handle
) {
167 // If the handle is already in the table just update the protocol
174 if (UpdateIndex
== MAX_FVB_COUNT
) {
176 // Use the next free slot for a new entry
178 UpdateIndex
= mFvbCount
++;
180 // Check the UpdateIndex whether exceed the maximum value.
182 ASSERT (UpdateIndex
< MAX_FVB_COUNT
);
183 mFvbEntry
[UpdateIndex
].Handle
= Handle
;
186 // The array does not have enough entries
188 ASSERT (UpdateIndex
< MAX_FVB_COUNT
);
191 // Get the interface pointer and if it's ours, skip it
193 Status
= gBS
->HandleProtocol (
195 &gEfiFirmwareVolumeBlockProtocolGuid
,
196 (VOID
**) &mFvbEntry
[UpdateIndex
].Fvb
198 ASSERT_EFI_ERROR (Status
);
200 Status
= gBS
->HandleProtocol (
202 &gEfiFvbExtensionProtocolGuid
,
203 (VOID
**) &mFvbEntry
[UpdateIndex
].FvbExtension
205 if (Status
!= EFI_SUCCESS
) {
206 mFvbEntry
[UpdateIndex
].FvbExtension
= NULL
;
210 // Check the FVB can be accessed in RUNTIME, The FVBs in FVB handle list come from two ways:
211 // 1) Dxe Core. (FVB information is transferred from FV HOB). 2) FVB driver. The FVB produced
212 // Dxe core is used to discovery DXE driver and dispatch. These FVBs can only be accessed in
213 // boot time. FVB driver will discovery all FV in FLASH and these FVBs can be accessed in
214 // runtime. The FVB itself produced by FVB driver is allocated in runtime memory. So we can
215 // determine the what FVB can be accessed in RUNTIME by judging whether FVB itself is allocated
216 // in RUNTIME memory.
218 mFvbEntry
[UpdateIndex
].IsRuntimeAccess
= IsRuntimeMemory (mFvbEntry
[UpdateIndex
].Fvb
);
223 Convert all pointers in mFvbEntry after ExitBootServices.
225 @param Event The Event that is being processed
226 @param Context Event Context
231 FvbVirtualAddressChangeNotifyEvent (
238 if (mFvbEntry
!= NULL
) {
239 for (Index
= 0; Index
< MAX_FVB_COUNT
; Index
++) {
240 if (!mFvbEntry
[Index
].IsRuntimeAccess
) {
244 if (mFvbEntry
[Index
].Fvb
!= NULL
) {
245 EfiConvertPointer (0x0, (VOID
**) &mFvbEntry
[Index
].Fvb
->GetBlockSize
);
246 EfiConvertPointer (0x0, (VOID
**) &mFvbEntry
[Index
].Fvb
->GetPhysicalAddress
);
247 EfiConvertPointer (0x0, (VOID
**) &mFvbEntry
[Index
].Fvb
->GetAttributes
);
248 EfiConvertPointer (0x0, (VOID
**) &mFvbEntry
[Index
].Fvb
->SetAttributes
);
249 EfiConvertPointer (0x0, (VOID
**) &mFvbEntry
[Index
].Fvb
->Read
);
250 EfiConvertPointer (0x0, (VOID
**) &mFvbEntry
[Index
].Fvb
->Write
);
251 EfiConvertPointer (0x0, (VOID
**) &mFvbEntry
[Index
].Fvb
->EraseBlocks
);
252 EfiConvertPointer (0x0, (VOID
**) &mFvbEntry
[Index
].Fvb
);
255 if (mFvbEntry
[Index
].FvbExtension
!= NULL
) {
256 EfiConvertPointer (0x0, (VOID
**) &mFvbEntry
[Index
].FvbExtension
->EraseFvbCustomBlock
);
257 EfiConvertPointer (0x0, (VOID
**) &mFvbEntry
[Index
].FvbExtension
);
261 EfiConvertPointer (0x0, (VOID
**) &mFvbEntry
);
267 Library constructor function entry.
269 @param ImageHandle The handle of image who call this library.
270 @param SystemTable The point of System Table.
272 @retval EFI_SUCESS Success construct this library.
273 @retval Others Fail to construct this library.
278 IN EFI_HANDLE ImageHandle
,
279 IN EFI_SYSTEM_TABLE
*SystemTable
284 mFvbEntry
= AllocateRuntimeZeroPool (sizeof (FVB_ENTRY
) * MAX_FVB_COUNT
);
285 ASSERT (mFvbEntry
!= NULL
);
288 // Register FvbNotificationEvent () notify function.
290 EfiCreateProtocolNotifyEvent (
291 &gEfiFirmwareVolumeBlockProtocolGuid
,
293 FvbNotificationEvent
,
299 // Register SetVirtualAddressMap () notify function
301 Status
= gBS
->CreateEventEx (
304 FvbVirtualAddressChangeNotifyEvent
,
306 &gEfiEventVirtualAddressChangeGuid
,
307 &mSetVirtualMapChangedEvent
309 ASSERT_EFI_ERROR (Status
);
315 // =============================================================================
316 // The following functions wrap Fvb protocol in the Runtime Lib functions.
317 // The Instance translates into Fvb instance. The Fvb order defined by HOBs and
318 // thus the sequence of FVB protocol addition define Instance.
322 Reads specified number of bytes into a buffer from the specified block.
324 The EfiFvbReadBlock() function reads the requested number of bytes from
325 the requested block in the specified firmware volume and stores them in
326 the provided buffer. Implementations should be mindful that the firmware
327 volume might be in the ReadDisabled state. If it is in this state, the
328 EfiFvbReadBlock() function must return the status code EFI_ACCESS_DENIED
329 without modifying the contents of the buffer.
331 The EfiFvbReadBlock() function must also prevent spanning block boundaries.
332 If a read is requested that would span a block boundary, the read must read
333 up to the boundary but not beyond. The output parameter NumBytes must be
334 set to correctly indicate the number of bytes actually read.
335 The caller must be aware that a read may be partially completed.
337 If NumBytes is NULL, then ASSERT().
339 If Buffer is NULL, then ASSERT().
341 @param[in] Instance The FV instance to be read from.
342 @param[in] Lba The logical block address to be read from
343 @param[in] Offset The offset relative to the block, at which to begin reading.
344 @param[in, out] NumBytes Pointer to a UINTN. On input, *NumBytes contains the total
345 size of the buffer. On output, it contains the actual number
347 @param[out] Buffer Pointer to a caller allocated buffer that will be
348 used to hold the data read.
350 @retval EFI_SUCCESS The firmware volume was read successfully and contents are in Buffer.
351 @retval EFI_BAD_BUFFER_SIZE Read attempted across an LBA boundary. On output, NumBytes contains
352 the total number of bytes returned in Buffer.
353 @retval EFI_ACCESS_DENIED The firmware volume is in the ReadDisabled state.
354 @retval EFI_DEVICE_ERROR The block device is not functioning correctly and could not be read.
355 @retval EFI_INVALID_PARAMETER Invalid parameter, Instance is larger than the max FVB number. Lba index
356 is larger than the last block of the firmware volume. Offset is larger
366 IN OUT UINTN
*NumBytes
,
370 ASSERT (NumBytes
!= NULL
);
371 ASSERT (Buffer
!= NULL
);
373 if (Instance
>= mFvbCount
) {
374 return EFI_INVALID_PARAMETER
;
377 if (EfiAtRuntime() && !mFvbEntry
[Instance
].IsRuntimeAccess
) {
378 return EFI_INVALID_PARAMETER
;
381 return mFvbEntry
[Instance
].Fvb
->Read (mFvbEntry
[Instance
].Fvb
, Lba
, Offset
, NumBytes
, Buffer
);
385 Writes specified number of bytes from the input buffer to the block
387 The EfiFvbWriteBlock() function writes the specified number of bytes
388 from the provided buffer to the specified block and offset in the
389 requested firmware volume.
391 If the firmware volume is sticky write, the caller must ensure that
392 all the bits of the specified range to write are in the EFI_FVB_ERASE_POLARITY
393 state before calling the EfiFvbWriteBlock() function, or else the
394 result will be unpredictable. This unpredictability arises because,
395 for a sticky-write firmware volume, a write may negate a bit in the
396 EFI_FVB_ERASE_POLARITY state but it cannot flip it back again. In
397 general, before calling the EfiFvbWriteBlock() function, the caller
398 should call the EfiFvbEraseBlock() function first to erase the specified
399 block to write. A block erase cycle will transition bits from the
400 (NOT)EFI_FVB_ERASE_POLARITY state back to the EFI_FVB_ERASE_POLARITY state.
401 Implementations should be mindful that the firmware volume might be
402 in the WriteDisabled state. If it is in this state, the EfiFvbWriteBlock()
403 function must return the status code EFI_ACCESS_DENIED without modifying
404 the contents of the firmware volume.
406 The EfiFvbWriteBlock() function must also prevent spanning block boundaries.
407 If a write is requested that spans a block boundary, the write must store
408 up to the boundary but not beyond. The output parameter NumBytes must be
409 set to correctly indicate the number of bytes actually written. The caller
410 must be aware that a write may be partially completed.
411 All writes, partial or otherwise, must be fully flushed to the hardware
412 before the EfiFvbWriteBlock() function returns.
414 If NumBytes is NULL, then ASSERT().
416 @param Instance The FV instance to be written to.
417 @param Lba The starting logical block index to write.
418 @param Offset The offset relative to the block to write.
419 @param NumBytes Pointer to a UINTN. On input, *NumBytes contains
420 the total size of the buffer. On output, it contains
421 the actual number of bytes written.
422 @param Buffer Pointer to a caller allocated buffer that contains
423 the source for the write
425 @retval EFI_SUCCESS The firmware volume was written successfully.
426 @retval EFI_BAD_BUFFER_SIZE The write was attempted across an LBA boundary.
427 On output, NumBytes contains the total number of bytes actually written.
428 @retval EFI_ACCESS_DENIED The firmware volume is in the WriteDisabled state.
429 @retval EFI_DEVICE_ERROR The block device is malfunctioning and could not be written.
430 @retval EFI_INVALID_PARAMETER Invalid parameter, Instance is larger than the max FVB number.
431 Lba index is larger than the last block of the firmware volume.
432 Offset is larger than the block size.
440 IN OUT UINTN
*NumBytes
,
444 ASSERT (NumBytes
!= NULL
);
446 if (Instance
>= mFvbCount
) {
447 return EFI_INVALID_PARAMETER
;
450 if (EfiAtRuntime() && !mFvbEntry
[Instance
].IsRuntimeAccess
) {
451 return EFI_INVALID_PARAMETER
;
454 return mFvbEntry
[Instance
].Fvb
->Write (mFvbEntry
[Instance
].Fvb
, Lba
, Offset
, NumBytes
, Buffer
);
459 Erases and initializes a firmware volume block.
461 The EfiFvbEraseBlock() function erases one block specified by Lba.
462 Implementations should be mindful that the firmware volume might
463 be in the WriteDisabled state. If it is in this state, the EfiFvbEraseBlock()
464 function must return the status code EFI_ACCESS_DENIED without
465 modifying the contents of the firmware volume. If Instance is
466 larger than the max FVB number, or Lba index is larger than the
467 last block of the firmware volume, this function return the status
468 code EFI_INVALID_PARAMETER.
470 All calls to EfiFvbEraseBlock() must be fully flushed to the
471 hardware before this function returns.
473 @param[in] Instance The FV instance to be erased.
474 @param[in] Lba The logical block index to be erased from.
476 @retval EFI_SUCCESS The erase request was successfully completed.
477 @retval EFI_ACCESS_DENIED The firmware volume is in the WriteDisabled state.
478 @retval EFI_DEVICE_ERROR The block device is not functioning correctly and
479 could not be written. The firmware device may
480 have been partially erased.
481 @retval EFI_INVALID_PARAMETER Invalid parameter. Instance is larger than the max
482 FVB number. Lba index is larger than the last block
483 of the firmware volume.
493 if (Instance
>= mFvbCount
) {
494 return EFI_INVALID_PARAMETER
;
497 if (EfiAtRuntime() && !mFvbEntry
[Instance
].IsRuntimeAccess
) {
498 return EFI_INVALID_PARAMETER
;
501 return mFvbEntry
[Instance
].Fvb
->EraseBlocks (mFvbEntry
[Instance
].Fvb
, Lba
, 1, EFI_LBA_LIST_TERMINATOR
);
506 Retrieves the attributes and current settings of the specified block,
507 returns resulting attributes in output parameter.
509 The EfiFvbGetAttributes() function retrieves the attributes and current
510 settings of the block specified by Instance. If Instance is larger than
511 the max FVB number, this function returns the status code EFI_INVALID_PARAMETER.
513 If Attributes is NULL, then ASSERT().
515 @param[in] Instance The FV instance to be operated.
516 @param[out] Attributes Pointer to EFI_FVB_ATTRIBUTES_2 in which the
517 attributes and current settings are returned.
519 @retval EFI_EFI_SUCCESS The firmware volume attributes were returned.
520 @retval EFI_INVALID_PARAMETER Invalid parameter. Instance is larger than the max FVB number.
524 EfiFvbGetVolumeAttributes (
526 OUT EFI_FVB_ATTRIBUTES_2
*Attributes
529 ASSERT (Attributes
!= NULL
);
531 if (Instance
>= mFvbCount
) {
532 return EFI_INVALID_PARAMETER
;
535 if (EfiAtRuntime() && !mFvbEntry
[Instance
].IsRuntimeAccess
) {
536 return EFI_INVALID_PARAMETER
;
539 return mFvbEntry
[Instance
].Fvb
->GetAttributes (mFvbEntry
[Instance
].Fvb
, Attributes
);
544 Modify the attributes and current settings of the specified block
545 according to the input parameter.
547 The EfiFvbSetAttributes() function sets configurable firmware volume
548 attributes and returns the new settings of the firmware volume specified
549 by Instance. If Instance is larger than the max FVB number, this function
550 returns the status code EFI_INVALID_PARAMETER.
552 If Attributes is NULL, then ASSERT().
554 @param[in] Instance The FV instance to be operated.
555 @param[in, out]Attributes On input, Attributes is a pointer to EFI_FVB_ATTRIBUTES_2
556 that contains the desired firmware volume settings.
557 On successful return, it contains the new settings of the firmware volume.
559 @retval EFI_EFI_SUCCESS The firmware volume attributes were modified successfully.
560 @retval EFI_INVALID_PARAMETER Invalid parameter. Instance is larger than the max FVB number.
565 EfiFvbSetVolumeAttributes (
567 IN OUT EFI_FVB_ATTRIBUTES_2
*Attributes
570 ASSERT (Attributes
!= NULL
);
572 if (Instance
>= mFvbCount
) {
573 return EFI_INVALID_PARAMETER
;
576 if (EfiAtRuntime() && !mFvbEntry
[Instance
].IsRuntimeAccess
) {
577 return EFI_INVALID_PARAMETER
;
580 return mFvbEntry
[Instance
].Fvb
->SetAttributes (mFvbEntry
[Instance
].Fvb
, Attributes
);
585 Retrieves the physical address of the specified memory mapped FV.
587 Retrieve the base address of a memory-mapped firmware volume specified by Instance.
588 If Instance is larger than the max FVB number, this function returns the status
589 code EFI_INVALID_PARAMETER.
591 If BaseAddress is NULL, then ASSERT().
593 @param[in] Instance The FV instance to be operated.
594 @param[out] BaseAddress Pointer to a caller allocated EFI_PHYSICAL_ADDRESS
595 that on successful return, contains the base address
596 of the firmware volume.
598 @retval EFI_EFI_SUCCESS The firmware volume base address is returned.
599 @retval EFI_INVALID_PARAMETER Invalid parameter. Instance is larger than the max FVB number.
604 EfiFvbGetPhysicalAddress (
606 OUT EFI_PHYSICAL_ADDRESS
*BaseAddress
609 ASSERT (BaseAddress
!= NULL
);
611 if (Instance
>= mFvbCount
) {
612 return EFI_INVALID_PARAMETER
;
615 if (EfiAtRuntime() && !mFvbEntry
[Instance
].IsRuntimeAccess
) {
616 return EFI_INVALID_PARAMETER
;
619 return mFvbEntry
[Instance
].Fvb
->GetPhysicalAddress (mFvbEntry
[Instance
].Fvb
, BaseAddress
);
624 Retrieve the block size of the specified fv.
626 The EfiFvbGetBlockSize() function retrieves the size of the requested block.
627 It also returns the number of additional blocks with the identical size.
628 If Instance is larger than the max FVB number, or Lba index is larger than
629 the last block of the firmware volume, this function return the status code
630 EFI_INVALID_PARAMETER.
632 If BlockSize is NULL, then ASSERT().
634 If NumOfBlocks is NULL, then ASSERT().
636 @param[in] Instance The FV instance to be operated.
637 @param[in] Lba Indicates which block to return the size for.
638 @param[out] BlockSize Pointer to a caller-allocated UINTN in which the
639 size of the block is returned.
640 @param[out] NumOfBlocks Pointer to a caller-allocated UINTN in which the
641 number of consecutive blocks, starting with Lba,
642 is returned. All blocks in this range have a size of BlockSize.
644 @retval EFI_EFI_SUCCESS The firmware volume base address is returned.
645 @retval EFI_INVALID_PARAMETER Invalid parameter. Instance is larger than the max FVB number.
646 Lba index is larger than the last block of the firmware volume.
654 OUT UINTN
*BlockSize
,
655 OUT UINTN
*NumOfBlocks
658 ASSERT (BlockSize
!= NULL
);
659 ASSERT (NumOfBlocks
!= NULL
);
661 if (Instance
>= mFvbCount
) {
662 return EFI_INVALID_PARAMETER
;
665 if (EfiAtRuntime() && !mFvbEntry
[Instance
].IsRuntimeAccess
) {
666 return EFI_INVALID_PARAMETER
;
669 return mFvbEntry
[Instance
].Fvb
->GetBlockSize (mFvbEntry
[Instance
].Fvb
, Lba
, BlockSize
, NumOfBlocks
);
674 Erases and initializes a specified range of a firmware volume.
676 The EfiFvbEraseCustomBlockRange() function erases the specified range in the firmware
677 volume index by Instance. If Instance is larger than the max FVB number, StartLba or
678 LastLba index is larger than the last block of the firmware volume, StartLba > LastLba
679 or StartLba equal to LastLba but OffsetStartLba > OffsetLastLba, this function return
680 the status code EFI_INVALID_PARAMETER.
682 @param[in] Instance The FV instance to be operated.
683 @param[in] StartLba The starting logical block index to be erased.
684 @param[in] OffsetStartLba Offset into the starting block at which to
686 @param[in] LastLba The last logical block index to be erased.
687 @param[in] OffsetLastLba Offset into the last block at which to end erasing.
689 @retval EFI_EFI_SUCCESS Successfully erase custom block range
690 @retval EFI_INVALID_PARAMETER Invalid parameter. Instance is larger than the max FVB number.
691 @retval EFI_UNSUPPORTED Firmware volume block device has no this capability.
696 EfiFvbEraseCustomBlockRange (
699 IN UINTN OffsetStartLba
,
701 IN UINTN OffsetLastLba
704 if (Instance
>= mFvbCount
) {
705 return EFI_INVALID_PARAMETER
;
708 if (EfiAtRuntime() && !mFvbEntry
[Instance
].IsRuntimeAccess
) {
709 return EFI_INVALID_PARAMETER
;
712 if (mFvbEntry
[Instance
].FvbExtension
== NULL
) {
713 return EFI_UNSUPPORTED
;
716 if (mFvbEntry
[Instance
].FvbExtension
->EraseFvbCustomBlock
== NULL
) {
717 return EFI_UNSUPPORTED
;
720 return mFvbEntry
[Instance
].FvbExtension
->EraseFvbCustomBlock (
721 mFvbEntry
[Instance
].FvbExtension
,