3 Firmware Volume Block Protocol Runtime Interface Abstraction
4 And FVB Extension protocol Runtime Interface Abstraction
6 mFvbEntry is an array of Handle Fvb pairs. The Fvb Lib Instance matches the
7 index in the mFvbEntry array. This should be the same sequence as the FVB's
8 were described in the HOB. We have to remember the handle so we can tell if
9 the protocol has been reinstalled and it needs updateing.
11 If you are using any of these lib functions.you must first call FvbInitialize ().
13 Copyright (c) 2006 - 2008, Intel Corporation
14 All rights reserved. This program and the accompanying materials
15 are licensed and made available under the terms and conditions of the BSD License
16 which accompanies this distribution. The full text of the license may be found at
17 http://opensource.org/licenses/bsd-license.php
19 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
20 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
28 // Event for Set Virtual Map Changed Event
30 STATIC EFI_EVENT mSetVirtualMapChangedEvent
= NULL
;
33 // Lib will ASSERT if more FVB devices than this are added to the system.
35 STATIC FVB_ENTRY
*mFvbEntry
;
36 STATIC EFI_EVENT mFvbRegistration
;
37 STATIC UINTN mFvbCount
;
40 Check whether an address is runtime memory or not.
42 @param Address The Address being checked.
44 @retval TRUE The address is runtime memory.
45 @retval FALSE The address is not runtime memory.
53 UINT8 TmpMemoryMap
[1];
56 UINT32 DescriptorVersion
;
58 EFI_MEMORY_DESCRIPTOR
*MemoryMap
;
59 EFI_MEMORY_DESCRIPTOR
*MemoryMapPtr
;
66 // Get System MemoryMapSize
69 Status
= gBS
->GetMemoryMap (
71 (EFI_MEMORY_DESCRIPTOR
*)TmpMemoryMap
,
76 ASSERT (Status
== EFI_BUFFER_TOO_SMALL
);
78 // Enlarge space here, because we will allocate pool now.
80 MemoryMapSize
+= EFI_PAGE_SIZE
;
81 Status
= gBS
->AllocatePool (
86 ASSERT_EFI_ERROR (Status
);
89 // Get System MemoryMap
91 Status
= gBS
->GetMemoryMap (
98 ASSERT_EFI_ERROR (Status
);
100 MemoryMapPtr
= MemoryMap
;
102 // Search the request Address
104 for (Index
= 0; Index
< (MemoryMapSize
/ DescriptorSize
); Index
++) {
105 if (((EFI_PHYSICAL_ADDRESS
)(UINTN
)Address
>= MemoryMap
->PhysicalStart
) &&
106 ((EFI_PHYSICAL_ADDRESS
)(UINTN
)Address
< MemoryMap
->PhysicalStart
107 + LShiftU64 (MemoryMap
->NumberOfPages
, EFI_PAGE_SHIFT
))) {
111 if (MemoryMap
->Attribute
& EFI_MEMORY_RUNTIME
) {
119 MemoryMap
= (EFI_MEMORY_DESCRIPTOR
*)((UINTN
)MemoryMap
+ DescriptorSize
);
125 gBS
->FreePool (MemoryMapPtr
);
131 Update mFvbEntry. Add new entry, or update existing entry if Fvb protocol is
134 @param Event The Event that is being processed
135 @param Context Event Context
141 FvbNotificationEvent (
153 BufferSize
= sizeof (Handle
);
154 Status
= gBS
->LocateHandle (
156 &gEfiFirmwareVolumeBlockProtocolGuid
,
161 if (EFI_ERROR (Status
)) {
163 // Exit Path of While Loop....
168 UpdateIndex
= MAX_FVB_COUNT
;
169 for (Index
= 0; Index
< mFvbCount
; Index
++) {
170 if (mFvbEntry
[Index
].Handle
== Handle
) {
172 // If the handle is already in the table just update the protocol
179 if (UpdateIndex
== MAX_FVB_COUNT
) {
181 // Use the next free slot for a new entry
183 UpdateIndex
= mFvbCount
++;
185 // Check the UpdateIndex whether exceed the maximum value.
187 ASSERT (UpdateIndex
< MAX_FVB_COUNT
);
188 mFvbEntry
[UpdateIndex
].Handle
= Handle
;
191 // The array does not have enough entries
193 ASSERT (UpdateIndex
< MAX_FVB_COUNT
);
196 // Get the interface pointer and if it's ours, skip it
198 Status
= gBS
->HandleProtocol (
200 &gEfiFirmwareVolumeBlockProtocolGuid
,
201 (VOID
**) &mFvbEntry
[UpdateIndex
].Fvb
203 ASSERT_EFI_ERROR (Status
);
205 Status
= gBS
->HandleProtocol (
207 &gEfiFvbExtensionProtocolGuid
,
208 (VOID
**) &mFvbEntry
[UpdateIndex
].FvbExtension
210 if (Status
!= EFI_SUCCESS
) {
211 mFvbEntry
[UpdateIndex
].FvbExtension
= NULL
;
215 // Check the FVB can be accessed in RUNTIME, The FVBs in FVB handle list comes
217 // 1) Dxe Core. (FVB information is transferred from FV HOB).
219 // The FVB produced Dxe core is used for discoverying DXE driver and dispatch. These
220 // FVBs can only be accessed in boot time.
221 // FVB driver will discovery all FV in FLASH and these FVBs can be accessed in runtime.
222 // The FVB itself produced by FVB driver is allocated in runtime memory. So we can
223 // determine the what FVB can be accessed in RUNTIME by judging whether FVB itself is allocated
224 // in RUNTIME memory.
226 mFvbEntry
[UpdateIndex
].IsRuntimeAccess
= IsRuntimeMemory (mFvbEntry
[UpdateIndex
].Fvb
);
231 Convert all pointers in mFvbEntry after ExitBootServices.
233 @param Event The Event that is being processed
234 @param Context Event Context
239 FvbVirtualAddressChangeNotifyEvent (
245 if (mFvbEntry
!= NULL
) {
246 for (Index
= 0; Index
< MAX_FVB_COUNT
; Index
++) {
247 if (!mFvbEntry
[Index
].IsRuntimeAccess
) {
251 if (NULL
!= mFvbEntry
[Index
].Fvb
) {
252 EfiConvertPointer (0x0, (VOID
**) &mFvbEntry
[Index
].Fvb
->GetBlockSize
);
253 EfiConvertPointer (0x0, (VOID
**) &mFvbEntry
[Index
].Fvb
->GetPhysicalAddress
);
254 EfiConvertPointer (0x0, (VOID
**) &mFvbEntry
[Index
].Fvb
->GetAttributes
);
255 EfiConvertPointer (0x0, (VOID
**) &mFvbEntry
[Index
].Fvb
->SetAttributes
);
256 EfiConvertPointer (0x0, (VOID
**) &mFvbEntry
[Index
].Fvb
->Read
);
257 EfiConvertPointer (0x0, (VOID
**) &mFvbEntry
[Index
].Fvb
->Write
);
258 EfiConvertPointer (0x0, (VOID
**) &mFvbEntry
[Index
].Fvb
->EraseBlocks
);
259 EfiConvertPointer (0x0, (VOID
**) &mFvbEntry
[Index
].Fvb
);
262 if (NULL
!= mFvbEntry
[Index
].FvbExtension
) {
263 EfiConvertPointer (0x0, (VOID
**) &mFvbEntry
[Index
].FvbExtension
->EraseFvbCustomBlock
);
264 EfiConvertPointer (0x0, (VOID
**) &mFvbEntry
[Index
].FvbExtension
);
268 EfiConvertPointer (0x0, (VOID
**) &mFvbEntry
);
273 Library constructor function entry.
275 @param ImageHandle The handle of image who call this libary.
276 @param SystemTable The point of System Table.
278 @retval EFI_SUCESS Sucess construct this library.
279 @retval Others Fail to contruct this libary.
284 IN EFI_HANDLE ImageHandle
,
285 IN EFI_SYSTEM_TABLE
*SystemTable
291 Status
= gBS
->AllocatePool (
292 EfiRuntimeServicesData
,
293 (UINTN
) sizeof (FVB_ENTRY
) * MAX_FVB_COUNT
,
297 if (EFI_ERROR (Status
)) {
301 ZeroMem (mFvbEntry
, sizeof (FVB_ENTRY
) * MAX_FVB_COUNT
);
303 EfiCreateProtocolNotifyEvent (
304 &gEfiFirmwareVolumeBlockProtocolGuid
,
306 FvbNotificationEvent
,
312 // Register SetVirtualAddressMap () notify function
314 Status
= gBS
->CreateEvent (
315 EVT_SIGNAL_VIRTUAL_ADDRESS_CHANGE
,
317 FvbVirtualAddressChangeNotifyEvent
,
319 &mSetVirtualMapChangedEvent
321 ASSERT_EFI_ERROR (Status
);
327 // =============================================================================
328 // The following functions wrap Fvb protocol in the Runtime Lib functions.
329 // The Instance translates into Fvb instance. The Fvb order defined by HOBs and
330 // thus the sequence of FVB protocol addition define Instance.
332 // EfiFvbInitialize () must be called before any of the following functions
334 // =============================================================================
338 Reads specified number of bytes into a buffer from the specified block.
340 The EfiFvbReadBlock() function reads the requested number of bytes from
341 the requested block in the specified firmware volume and stores them in
342 the provided buffer. Implementations should be mindful that the firmware
343 volume might be in the ReadDisabled state. If it is in this state, the
344 EfiFvbReadBlock() function must return the status code EFI_ACCESS_DENIED
345 without modifying the contents of the buffer.
347 The EfiFvbReadBlock() function must also prevent spanning block boundaries.
348 If a read is requested that would span a block boundary, the read must read
349 up to the boundary but not beyond. The output parameter NumBytes must be
350 set to correctly indicate the number of bytes actually read.
351 The caller must be aware that a read may be partially completed.
353 If NumBytes is NULL, then ASSERT().
355 If Buffer is NULL, then ASSERT().
357 @param[in] Instance The FV instance to be read from.
358 @param[in] Lba The logical block address to be read from
359 @param[in] Offset The offset relative to the block, at which to begin reading.
360 @param[in, out] NumBytes Pointer to a UINTN. On input, *NumBytes contains the total
361 size of the buffer. On output, it contains the actual number
363 @param[out] Buffer Pointer to a caller allocated buffer that will be
364 used to hold the data read.
366 @retval EFI_SUCCESS The firmware volume was read successfully and contents are in Buffer.
367 @retval EFI_BAD_BUFFER_SIZE Read attempted across an LBA boundary. On output, NumBytes contains the total number of bytes returned in Buffer.
368 @retval EFI_ACCESS_DENIED The firmware volume is in the ReadDisabled state.
369 @retval EFI_DEVICE_ERROR The block device is not functioning correctly and could not be read.
370 @retval EFI_INVALID_PARAMETER Invalid parameter, Instance is larger than the max FVB number. Lba index is larger than the last block of the firmware volume. Offset is larger than the block size.
378 IN OUT UINTN
*NumBytes
,
382 ASSERT (NumBytes
!= NULL
);
383 ASSERT (Buffer
!= NULL
);
385 if (Instance
>= mFvbCount
) {
386 return EFI_INVALID_PARAMETER
;
389 if (EfiAtRuntime() && !mFvbEntry
[Instance
].IsRuntimeAccess
) {
390 return EFI_INVALID_PARAMETER
;
393 return mFvbEntry
[Instance
].Fvb
->Read (mFvbEntry
[Instance
].Fvb
, Lba
, Offset
, NumBytes
, Buffer
);
397 Writes specified number of bytes from the input buffer to the block
399 The EfiFvbWriteBlock() function writes the specified number of bytes
400 from the provided buffer to the specified block and offset in the
401 requested firmware volume.
403 If the firmware volume is sticky write, the caller must ensure that
404 all the bits of the specified range to write are in the EFI_FVB_ERASE_POLARITY
405 state before calling the EfiFvbWriteBlock() function, or else the
406 result will be unpredictable. This unpredictability arises because,
407 for a sticky-write firmware volume, a write may negate a bit in the
408 EFI_FVB_ERASE_POLARITY state but it cannot flip it back again. In
409 general, before calling the EfiFvbWriteBlock() function, the caller
410 should call the EfiFvbEraseBlock() function first to erase the specified
411 block to write. A block erase cycle will transition bits from the
412 (NOT)EFI_FVB_ERASE_POLARITY state back to the EFI_FVB_ERASE_POLARITY state.
413 Implementations should be mindful that the firmware volume might be
414 in the WriteDisabled state. If it is in this state, the EfiFvbWriteBlock()
415 function must return the status code EFI_ACCESS_DENIED without modifying
416 the contents of the firmware volume.
418 The EfiFvbWriteBlock() function must also prevent spanning block boundaries.
419 If a write is requested that spans a block boundary, the write must store
420 up to the boundary but not beyond. The output parameter NumBytes must be
421 set to correctly indicate the number of bytes actually written. The caller
422 must be aware that a write may be partially completed.
423 All writes, partial or otherwise, must be fully flushed to the hardware
424 before the EfiFvbWriteBlock() function returns.
426 If NumBytes is NULL, then ASSERT().
428 @param Instance The FV instance to be written to
429 @param Lba The starting logical block index to write to
430 @param Offset The offset relative to the block, at which to begin writting.
431 @param NumBytes Pointer to a UINTN. On input, *NumBytes contains
432 the total size of the buffer. On output, it contains
433 the actual number of bytes written.
434 @param Buffer Pointer to a caller allocated buffer that contains
435 the source for the write
437 @retval EFI_SUCCESS The firmware volume was written successfully.
438 @retval EFI_BAD_BUFFER_SIZE The write was attempted across an LBA boundary.
439 On output, NumBytes contains the total number of bytes actually written.
440 @retval EFI_ACCESS_DENIED The firmware volume is in the WriteDisabled state.
441 @retval EFI_DEVICE_ERROR The block device is malfunctioning and could not be written.
442 @retval EFI_INVALID_PARAMETER Invalid parameter, Instance is larger than the max FVB number.
443 Lba index is larger than the last block of the firmware volume.
444 Offset is larger than the block size.
451 IN OUT UINTN
*NumBytes
,
455 ASSERT (NumBytes
!= NULL
);
457 if (Instance
>= mFvbCount
) {
458 return EFI_INVALID_PARAMETER
;
461 if (EfiAtRuntime() && !mFvbEntry
[Instance
].IsRuntimeAccess
) {
462 return EFI_INVALID_PARAMETER
;
465 return mFvbEntry
[Instance
].Fvb
->Write (mFvbEntry
[Instance
].Fvb
, Lba
, Offset
, NumBytes
, Buffer
);
469 Erases and initializes a firmware volume block.
471 The EfiFvbEraseBlock() function erases one block specified by Lba.
472 Implementations should be mindful that the firmware volume might
473 be in the WriteDisabled state. If it is in this state, the EfiFvbEraseBlock()
474 function must return the status code EFI_ACCESS_DENIED without
475 modifying the contents of the firmware volume. If Instance is
476 larger than the max FVB number, or Lba index is larger than the
477 last block of the firmware volume, this function return the status
478 code EFI_INVALID_PARAMETER.
480 All calls to EfiFvbEraseBlock() must be fully flushed to the
481 hardware before this function returns.
483 @param[in] Instance The FV instance to be erased.
484 @param[in] Lba The logical block index to be erased from.
486 @retval EFI_SUCCESS The erase request was successfully completed.
487 @retval EFI_ACCESS_DENIED The firmware volume is in the WriteDisabled state.
488 @retval EFI_DEVICE_ERROR The block device is not functioning correctly and
489 could not be written. The firmware device may
490 have been partially erased.
491 @retval EFI_INVALID_PARAMETER Invalid parameter. Instance is larger than the max
492 FVB number. Lba index is larger than the last block
493 of the firmware volume.
502 if (Instance
>= mFvbCount
) {
503 return EFI_INVALID_PARAMETER
;
506 if (EfiAtRuntime() && !mFvbEntry
[Instance
].IsRuntimeAccess
) {
507 return EFI_INVALID_PARAMETER
;
510 return mFvbEntry
[Instance
].Fvb
->EraseBlocks (mFvbEntry
[Instance
].Fvb
, Lba
, 1, EFI_LBA_LIST_TERMINATOR
);
514 Retrieves the attributes and current settings of the specified block,
515 returns resulting attributes in output parameter.
517 The EfiFvbGetAttributes() function retrieves the attributes and current
518 settings of the block specified by Instance. If Instance is larger than
519 the max FVB number, this function returns the status code EFI_INVALID_PARAMETER.
521 If Attributes is NULL, then ASSERT().
523 @param[in] Instance The FV instance to be operated.
524 @param[out] Attributes Pointer to EFI_FVB_ATTRIBUTES_2 in which the
525 attributes and current settings are returned.
527 @retval EFI_EFI_SUCCESS The firmware volume attributes were returned.
528 @retval EFI_INVALID_PARAMETER Invalid parameter. Instance is larger than the max FVB number.
531 EfiFvbGetVolumeAttributes (
533 OUT EFI_FVB_ATTRIBUTES_2
*Attributes
536 ASSERT (Attributes
!= NULL
);
538 if (Instance
>= mFvbCount
) {
539 return EFI_INVALID_PARAMETER
;
542 if (EfiAtRuntime() && !mFvbEntry
[Instance
].IsRuntimeAccess
) {
543 return EFI_INVALID_PARAMETER
;
546 return mFvbEntry
[Instance
].Fvb
->GetAttributes (mFvbEntry
[Instance
].Fvb
, Attributes
);
550 Modify the attributes and current settings of the specified block
551 according to the input parameter.
553 The EfiFvbSetAttributes() function sets configurable firmware volume
554 attributes and returns the new settings of the firmware volume specified
555 by Instance. If Instance is larger than the max FVB number, this function
556 returns the status code EFI_INVALID_PARAMETER.
558 If Attributes is NULL, then ASSERT().
560 @param[in] Instance The FV instance to be operated.
561 @param[in, out]Attributes On input, Attributes is a pointer to EFI_FVB_ATTRIBUTES_2
562 that contains the desired firmware volume settings.
563 On successful return, it contains the new settings of the firmware volume.
565 @retval EFI_EFI_SUCCESS The firmware volume attributes were modified successfully.
566 @retval EFI_INVALID_PARAMETER Invalid parameter. Instance is larger than the max FVB number.
570 EfiFvbSetVolumeAttributes (
572 IN OUT EFI_FVB_ATTRIBUTES_2
*Attributes
575 ASSERT (Attributes
!= NULL
);
577 if (Instance
>= mFvbCount
) {
578 return EFI_INVALID_PARAMETER
;
581 if (EfiAtRuntime() && !mFvbEntry
[Instance
].IsRuntimeAccess
) {
582 return EFI_INVALID_PARAMETER
;
585 return mFvbEntry
[Instance
].Fvb
->SetAttributes (mFvbEntry
[Instance
].Fvb
, Attributes
);
589 Retrieves the physical address of the specified memory mapped FV.
591 Retrieve the base address of a memory-mapped firmware volume specified by Instance.
592 If Instance is larger than the max FVB number, this function returns the status
593 code EFI_INVALID_PARAMETER.
595 If BaseAddress is NULL, then ASSERT().
597 @param[in] Instance The FV instance to be operated.
598 @param[out] BaseAddress Pointer to a caller allocated EFI_PHYSICAL_ADDRESS
599 that on successful return, contains the base address
600 of the firmware volume.
602 @retval EFI_EFI_SUCCESS The firmware volume base address is returned.
603 @retval EFI_INVALID_PARAMETER Invalid parameter. Instance is larger than the max FVB number.
607 EfiFvbGetPhysicalAddress (
609 OUT EFI_PHYSICAL_ADDRESS
*BaseAddress
612 ASSERT (BaseAddress
!= NULL
);
614 if (Instance
>= mFvbCount
) {
615 return EFI_INVALID_PARAMETER
;
618 if (EfiAtRuntime() && !mFvbEntry
[Instance
].IsRuntimeAccess
) {
619 return EFI_INVALID_PARAMETER
;
622 return mFvbEntry
[Instance
].Fvb
->GetPhysicalAddress (mFvbEntry
[Instance
].Fvb
, BaseAddress
);
626 Retrieve the block size of the specified fv.
628 The EfiFvbGetBlockSize() function retrieves the size of the requested block.
629 It also returns the number of additional blocks with the identical size.
630 If Instance is larger than the max FVB number, or Lba index is larger than
631 the last block of the firmware volume, this function return the status code
632 EFI_INVALID_PARAMETER.
634 If BlockSize is NULL, then ASSERT().
636 If NumOfBlocks is NULL, then ASSERT().
638 @param[in] Instance The FV instance to be operated.
639 @param[in] Lba Indicates which block to return the size for.
640 @param[out] BlockSize Pointer to a caller-allocated UINTN in which the
641 size of the block is returned.
642 @param[out] NumOfBlocks Pointer to a caller-allocated UINTN in which the
643 number of consecutive blocks, starting with Lba,
644 is returned. All blocks in this range have a size of BlockSize.
646 @retval EFI_EFI_SUCCESS The firmware volume base address is returned.
647 @retval EFI_INVALID_PARAMETER Invalid parameter. Instance is larger than the max FVB number.
648 Lba index is larger than the last block of the firmware volume.
655 OUT UINTN
*BlockSize
,
656 OUT UINTN
*NumOfBlocks
659 ASSERT (BlockSize
!= NULL
);
660 ASSERT (NumOfBlocks
!= NULL
);
662 if (Instance
>= mFvbCount
) {
663 return EFI_INVALID_PARAMETER
;
666 if (EfiAtRuntime() && !mFvbEntry
[Instance
].IsRuntimeAccess
) {
667 return EFI_INVALID_PARAMETER
;
670 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.
695 EfiFvbEraseCustomBlockRange (
698 IN UINTN OffsetStartLba
,
700 IN UINTN OffsetLastLba
703 if (Instance
>= mFvbCount
) {
704 return EFI_INVALID_PARAMETER
;
707 if (EfiAtRuntime() && !mFvbEntry
[Instance
].IsRuntimeAccess
) {
708 return EFI_INVALID_PARAMETER
;
711 if (!(mFvbEntry
[Instance
].FvbExtension
)) {
712 return EFI_UNSUPPORTED
;
715 if (!(mFvbEntry
[Instance
].FvbExtension
->EraseFvbCustomBlock
)) {
716 return EFI_UNSUPPORTED
;
719 return mFvbEntry
[Instance
].FvbExtension
->EraseFvbCustomBlock (
720 mFvbEntry
[Instance
].FvbExtension
,