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
);
201 // Check the FVB can be accessed in RUNTIME, The FVBs in FVB handle list come from two ways:
202 // 1) Dxe Core. (FVB information is transferred from FV HOB). 2) FVB driver. The FVB produced
203 // Dxe core is used to discovery DXE driver and dispatch. These FVBs can only be accessed in
204 // boot time. FVB driver will discovery all FV in FLASH and these FVBs can be accessed in
205 // runtime. The FVB itself produced by FVB driver is allocated in runtime memory. So we can
206 // determine the what FVB can be accessed in RUNTIME by judging whether FVB itself is allocated
207 // in RUNTIME memory.
209 mFvbEntry
[UpdateIndex
].IsRuntimeAccess
= IsRuntimeMemory (mFvbEntry
[UpdateIndex
].Fvb
);
214 Convert all pointers in mFvbEntry after ExitBootServices.
216 @param Event The Event that is being processed
217 @param Context Event Context
222 FvbVirtualAddressChangeNotifyEvent (
229 if (mFvbEntry
!= NULL
) {
230 for (Index
= 0; Index
< MAX_FVB_COUNT
; Index
++) {
231 if (!mFvbEntry
[Index
].IsRuntimeAccess
) {
235 if (mFvbEntry
[Index
].Fvb
!= NULL
) {
236 EfiConvertPointer (0x0, (VOID
**) &mFvbEntry
[Index
].Fvb
->GetBlockSize
);
237 EfiConvertPointer (0x0, (VOID
**) &mFvbEntry
[Index
].Fvb
->GetPhysicalAddress
);
238 EfiConvertPointer (0x0, (VOID
**) &mFvbEntry
[Index
].Fvb
->GetAttributes
);
239 EfiConvertPointer (0x0, (VOID
**) &mFvbEntry
[Index
].Fvb
->SetAttributes
);
240 EfiConvertPointer (0x0, (VOID
**) &mFvbEntry
[Index
].Fvb
->Read
);
241 EfiConvertPointer (0x0, (VOID
**) &mFvbEntry
[Index
].Fvb
->Write
);
242 EfiConvertPointer (0x0, (VOID
**) &mFvbEntry
[Index
].Fvb
->EraseBlocks
);
243 EfiConvertPointer (0x0, (VOID
**) &mFvbEntry
[Index
].Fvb
);
247 EfiConvertPointer (0x0, (VOID
**) &mFvbEntry
);
253 Library constructor function entry.
255 @param ImageHandle The handle of image who call this library.
256 @param SystemTable The point of System Table.
258 @retval EFI_SUCESS Success construct this library.
259 @retval Others Fail to construct this library.
264 IN EFI_HANDLE ImageHandle
,
265 IN EFI_SYSTEM_TABLE
*SystemTable
270 mFvbEntry
= AllocateRuntimeZeroPool (sizeof (FVB_ENTRY
) * MAX_FVB_COUNT
);
271 ASSERT (mFvbEntry
!= NULL
);
274 // Register FvbNotificationEvent () notify function.
276 EfiCreateProtocolNotifyEvent (
277 &gEfiFirmwareVolumeBlockProtocolGuid
,
279 FvbNotificationEvent
,
285 // Register SetVirtualAddressMap () notify function
287 Status
= gBS
->CreateEventEx (
290 FvbVirtualAddressChangeNotifyEvent
,
292 &gEfiEventVirtualAddressChangeGuid
,
293 &mSetVirtualMapChangedEvent
295 ASSERT_EFI_ERROR (Status
);
301 // =============================================================================
302 // The following functions wrap Fvb protocol in the Runtime Lib functions.
303 // The Instance translates into Fvb instance. The Fvb order defined by HOBs and
304 // thus the sequence of FVB protocol addition define Instance.
308 Reads specified number of bytes into a buffer from the specified block.
310 The EfiFvbReadBlock() function reads the requested number of bytes from
311 the requested block in the specified firmware volume and stores them in
312 the provided buffer. Implementations should be mindful that the firmware
313 volume might be in the ReadDisabled state. If it is in this state, the
314 EfiFvbReadBlock() function must return the status code EFI_ACCESS_DENIED
315 without modifying the contents of the buffer.
317 The EfiFvbReadBlock() function must also prevent spanning block boundaries.
318 If a read is requested that would span a block boundary, the read must read
319 up to the boundary but not beyond. The output parameter NumBytes must be
320 set to correctly indicate the number of bytes actually read.
321 The caller must be aware that a read may be partially completed.
323 If NumBytes is NULL, then ASSERT().
325 If Buffer is NULL, then ASSERT().
327 @param[in] Instance The FV instance to be read from.
328 @param[in] Lba The logical block address to be read from
329 @param[in] Offset The offset relative to the block, at which to begin reading.
330 @param[in, out] NumBytes Pointer to a UINTN. On input, *NumBytes contains the total
331 size of the buffer. On output, it contains the actual number
333 @param[out] Buffer Pointer to a caller allocated buffer that will be
334 used to hold the data read.
336 @retval EFI_SUCCESS The firmware volume was read successfully and contents are in Buffer.
337 @retval EFI_BAD_BUFFER_SIZE Read attempted across an LBA boundary. On output, NumBytes contains
338 the total number of bytes returned in Buffer.
339 @retval EFI_ACCESS_DENIED The firmware volume is in the ReadDisabled state.
340 @retval EFI_DEVICE_ERROR The block device is not functioning correctly and could not be read.
341 @retval EFI_INVALID_PARAMETER Invalid parameter, Instance is larger than the max FVB number. Lba index
342 is larger than the last block of the firmware volume. Offset is larger
352 IN OUT UINTN
*NumBytes
,
356 ASSERT (NumBytes
!= NULL
);
357 ASSERT (Buffer
!= NULL
);
359 if (Instance
>= mFvbCount
) {
360 return EFI_INVALID_PARAMETER
;
363 if (EfiAtRuntime() && !mFvbEntry
[Instance
].IsRuntimeAccess
) {
364 return EFI_INVALID_PARAMETER
;
367 return mFvbEntry
[Instance
].Fvb
->Read (mFvbEntry
[Instance
].Fvb
, Lba
, Offset
, NumBytes
, Buffer
);
371 Writes specified number of bytes from the input buffer to the block
373 The EfiFvbWriteBlock() function writes the specified number of bytes
374 from the provided buffer to the specified block and offset in the
375 requested firmware volume.
377 If the firmware volume is sticky write, the caller must ensure that
378 all the bits of the specified range to write are in the EFI_FVB_ERASE_POLARITY
379 state before calling the EfiFvbWriteBlock() function, or else the
380 result will be unpredictable. This unpredictability arises because,
381 for a sticky-write firmware volume, a write may negate a bit in the
382 EFI_FVB_ERASE_POLARITY state but it cannot flip it back again. In
383 general, before calling the EfiFvbWriteBlock() function, the caller
384 should call the EfiFvbEraseBlock() function first to erase the specified
385 block to write. A block erase cycle will transition bits from the
386 (NOT)EFI_FVB_ERASE_POLARITY state back to the EFI_FVB_ERASE_POLARITY state.
387 Implementations should be mindful that the firmware volume might be
388 in the WriteDisabled state. If it is in this state, the EfiFvbWriteBlock()
389 function must return the status code EFI_ACCESS_DENIED without modifying
390 the contents of the firmware volume.
392 The EfiFvbWriteBlock() function must also prevent spanning block boundaries.
393 If a write is requested that spans a block boundary, the write must store
394 up to the boundary but not beyond. The output parameter NumBytes must be
395 set to correctly indicate the number of bytes actually written. The caller
396 must be aware that a write may be partially completed.
397 All writes, partial or otherwise, must be fully flushed to the hardware
398 before the EfiFvbWriteBlock() function returns.
400 If NumBytes is NULL, then ASSERT().
402 @param Instance The FV instance to be written to.
403 @param Lba The starting logical block index to write.
404 @param Offset The offset relative to the block to write.
405 @param NumBytes Pointer to a UINTN. On input, *NumBytes contains
406 the total size of the buffer. On output, it contains
407 the actual number of bytes written.
408 @param Buffer Pointer to a caller allocated buffer that contains
409 the source for the write
411 @retval EFI_SUCCESS The firmware volume was written successfully.
412 @retval EFI_BAD_BUFFER_SIZE The write was attempted across an LBA boundary.
413 On output, NumBytes contains the total number of bytes actually written.
414 @retval EFI_ACCESS_DENIED The firmware volume is in the WriteDisabled state.
415 @retval EFI_DEVICE_ERROR The block device is malfunctioning and could not be written.
416 @retval EFI_INVALID_PARAMETER Invalid parameter, Instance is larger than the max FVB number.
417 Lba index is larger than the last block of the firmware volume.
418 Offset is larger than the block size.
426 IN OUT UINTN
*NumBytes
,
430 ASSERT (NumBytes
!= NULL
);
432 if (Instance
>= mFvbCount
) {
433 return EFI_INVALID_PARAMETER
;
436 if (EfiAtRuntime() && !mFvbEntry
[Instance
].IsRuntimeAccess
) {
437 return EFI_INVALID_PARAMETER
;
440 return mFvbEntry
[Instance
].Fvb
->Write (mFvbEntry
[Instance
].Fvb
, Lba
, Offset
, NumBytes
, Buffer
);
445 Erases and initializes a firmware volume block.
447 The EfiFvbEraseBlock() function erases one block specified by Lba.
448 Implementations should be mindful that the firmware volume might
449 be in the WriteDisabled state. If it is in this state, the EfiFvbEraseBlock()
450 function must return the status code EFI_ACCESS_DENIED without
451 modifying the contents of the firmware volume. If Instance is
452 larger than the max FVB number, or Lba index is larger than the
453 last block of the firmware volume, this function return the status
454 code EFI_INVALID_PARAMETER.
456 All calls to EfiFvbEraseBlock() must be fully flushed to the
457 hardware before this function returns.
459 @param[in] Instance The FV instance to be erased.
460 @param[in] Lba The logical block index to be erased from.
462 @retval EFI_SUCCESS The erase request was successfully completed.
463 @retval EFI_ACCESS_DENIED The firmware volume is in the WriteDisabled state.
464 @retval EFI_DEVICE_ERROR The block device is not functioning correctly and
465 could not be written. The firmware device may
466 have been partially erased.
467 @retval EFI_INVALID_PARAMETER Invalid parameter. Instance is larger than the max
468 FVB number. Lba index is larger than the last block
469 of the firmware volume.
479 if (Instance
>= mFvbCount
) {
480 return EFI_INVALID_PARAMETER
;
483 if (EfiAtRuntime() && !mFvbEntry
[Instance
].IsRuntimeAccess
) {
484 return EFI_INVALID_PARAMETER
;
487 return mFvbEntry
[Instance
].Fvb
->EraseBlocks (mFvbEntry
[Instance
].Fvb
, Lba
, 1, EFI_LBA_LIST_TERMINATOR
);
492 Retrieves the attributes and current settings of the specified block,
493 returns resulting attributes in output parameter.
495 The EfiFvbGetAttributes() function retrieves the attributes and current
496 settings of the block specified by Instance. If Instance is larger than
497 the max FVB number, this function returns the status code EFI_INVALID_PARAMETER.
499 If Attributes is NULL, then ASSERT().
501 @param[in] Instance The FV instance to be operated.
502 @param[out] Attributes Pointer to EFI_FVB_ATTRIBUTES_2 in which the
503 attributes and current settings are returned.
505 @retval EFI_EFI_SUCCESS The firmware volume attributes were returned.
506 @retval EFI_INVALID_PARAMETER Invalid parameter. Instance is larger than the max FVB number.
510 EfiFvbGetVolumeAttributes (
512 OUT EFI_FVB_ATTRIBUTES_2
*Attributes
515 ASSERT (Attributes
!= NULL
);
517 if (Instance
>= mFvbCount
) {
518 return EFI_INVALID_PARAMETER
;
521 if (EfiAtRuntime() && !mFvbEntry
[Instance
].IsRuntimeAccess
) {
522 return EFI_INVALID_PARAMETER
;
525 return mFvbEntry
[Instance
].Fvb
->GetAttributes (mFvbEntry
[Instance
].Fvb
, Attributes
);
530 Modify the attributes and current settings of the specified block
531 according to the input parameter.
533 The EfiFvbSetAttributes() function sets configurable firmware volume
534 attributes and returns the new settings of the firmware volume specified
535 by Instance. If Instance is larger than the max FVB number, this function
536 returns the status code EFI_INVALID_PARAMETER.
538 If Attributes is NULL, then ASSERT().
540 @param[in] Instance The FV instance to be operated.
541 @param[in, out]Attributes On input, Attributes is a pointer to EFI_FVB_ATTRIBUTES_2
542 that contains the desired firmware volume settings.
543 On successful return, it contains the new settings of the firmware volume.
545 @retval EFI_EFI_SUCCESS The firmware volume attributes were modified successfully.
546 @retval EFI_INVALID_PARAMETER Invalid parameter. Instance is larger than the max FVB number.
551 EfiFvbSetVolumeAttributes (
553 IN OUT EFI_FVB_ATTRIBUTES_2
*Attributes
556 ASSERT (Attributes
!= NULL
);
558 if (Instance
>= mFvbCount
) {
559 return EFI_INVALID_PARAMETER
;
562 if (EfiAtRuntime() && !mFvbEntry
[Instance
].IsRuntimeAccess
) {
563 return EFI_INVALID_PARAMETER
;
566 return mFvbEntry
[Instance
].Fvb
->SetAttributes (mFvbEntry
[Instance
].Fvb
, Attributes
);
571 Retrieves the physical address of the specified memory mapped FV.
573 Retrieve the base address of a memory-mapped firmware volume specified by Instance.
574 If Instance is larger than the max FVB number, this function returns the status
575 code EFI_INVALID_PARAMETER.
577 If BaseAddress is NULL, then ASSERT().
579 @param[in] Instance The FV instance to be operated.
580 @param[out] BaseAddress Pointer to a caller allocated EFI_PHYSICAL_ADDRESS
581 that on successful return, contains the base address
582 of the firmware volume.
584 @retval EFI_EFI_SUCCESS The firmware volume base address is returned.
585 @retval EFI_INVALID_PARAMETER Invalid parameter. Instance is larger than the max FVB number.
590 EfiFvbGetPhysicalAddress (
592 OUT EFI_PHYSICAL_ADDRESS
*BaseAddress
595 ASSERT (BaseAddress
!= NULL
);
597 if (Instance
>= mFvbCount
) {
598 return EFI_INVALID_PARAMETER
;
601 if (EfiAtRuntime() && !mFvbEntry
[Instance
].IsRuntimeAccess
) {
602 return EFI_INVALID_PARAMETER
;
605 return mFvbEntry
[Instance
].Fvb
->GetPhysicalAddress (mFvbEntry
[Instance
].Fvb
, BaseAddress
);
610 Retrieve the block size of the specified fv.
612 The EfiFvbGetBlockSize() function retrieves the size of the requested block.
613 It also returns the number of additional blocks with the identical size.
614 If Instance is larger than the max FVB number, or Lba index is larger than
615 the last block of the firmware volume, this function return the status code
616 EFI_INVALID_PARAMETER.
618 If BlockSize is NULL, then ASSERT().
620 If NumOfBlocks is NULL, then ASSERT().
622 @param[in] Instance The FV instance to be operated.
623 @param[in] Lba Indicates which block to return the size for.
624 @param[out] BlockSize Pointer to a caller-allocated UINTN in which the
625 size of the block is returned.
626 @param[out] NumOfBlocks Pointer to a caller-allocated UINTN in which the
627 number of consecutive blocks, starting with Lba,
628 is returned. All blocks in this range have a size of BlockSize.
630 @retval EFI_EFI_SUCCESS The firmware volume base address is returned.
631 @retval EFI_INVALID_PARAMETER Invalid parameter. Instance is larger than the max FVB number.
632 Lba index is larger than the last block of the firmware volume.
640 OUT UINTN
*BlockSize
,
641 OUT UINTN
*NumOfBlocks
644 ASSERT (BlockSize
!= NULL
);
645 ASSERT (NumOfBlocks
!= NULL
);
647 if (Instance
>= mFvbCount
) {
648 return EFI_INVALID_PARAMETER
;
651 if (EfiAtRuntime() && !mFvbEntry
[Instance
].IsRuntimeAccess
) {
652 return EFI_INVALID_PARAMETER
;
655 return mFvbEntry
[Instance
].Fvb
->GetBlockSize (mFvbEntry
[Instance
].Fvb
, Lba
, BlockSize
, NumOfBlocks
);