4 Step #1 - When a FV protocol is added to the system every driver in the FV
5 is added to the mDiscoveredList. The SOR, Before, and After Depex are
6 pre-processed as drivers are added to the mDiscoveredList. If an Apriori
7 file exists in the FV those drivers are addeded to the
8 mScheduledQueue. The mFvHandleList is used to make sure a
9 FV is only processed once.
11 Step #2 - Dispatch. Remove driver from the mScheduledQueue and load and
12 start it. After mScheduledQueue is drained check the
13 mDiscoveredList to see if any item has a Depex that is ready to
14 be placed on the mScheduledQueue.
16 Step #3 - Adding to the mScheduledQueue requires that you process Before
17 and After dependencies. This is done recursively as the call to add
18 to the mScheduledQueue checks for Before and recursively adds
19 all Befores. It then addes the item that was passed in and then
20 processess the After dependecies by recursively calling the routine.
23 The rules for the dispatcher are in chapter 10 of the DXE CIS. Figure 10-3
24 is the state diagram for the DXE dispatcher
26 Depex - Dependency Expresion.
27 SOR - Schedule On Request - Don't schedule if this bit is set.
29 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
30 SPDX-License-Identifier: BSD-2-Clause-Patent
37 // The Driver List contains one copy of every driver that has been discovered.
38 // Items are never removed from the driver list. List of EFI_CORE_DRIVER_ENTRY
40 LIST_ENTRY mDiscoveredList
= INITIALIZE_LIST_HEAD_VARIABLE (mDiscoveredList
);
43 // Queue of drivers that are ready to dispatch. This queue is a subset of the
44 // mDiscoveredList.list of EFI_CORE_DRIVER_ENTRY.
46 LIST_ENTRY mScheduledQueue
= INITIALIZE_LIST_HEAD_VARIABLE (mScheduledQueue
);
49 // List of handles who's Fv's have been parsed and added to the mFwDriverList.
51 LIST_ENTRY mFvHandleList
= INITIALIZE_LIST_HEAD_VARIABLE (mFvHandleList
); // list of KNOWN_HANDLE
54 // Lock for mDiscoveredList, mScheduledQueue, gDispatcherRunning.
56 EFI_LOCK mDispatcherLock
= EFI_INITIALIZE_LOCK_VARIABLE (TPL_HIGH_LEVEL
);
59 // Flag for the DXE Dispacher. TRUE if dispatcher is execuing.
61 BOOLEAN gDispatcherRunning
= FALSE
;
64 // Module globals to manage the FwVol registration notification event
66 EFI_EVENT mFwVolEvent
;
67 VOID
*mFwVolEventRegistration
;
70 // List of file types supported by dispatcher
72 EFI_FV_FILETYPE mDxeFileTypes
[] = {
73 EFI_FV_FILETYPE_DRIVER
,
74 EFI_FV_FILETYPE_COMBINED_SMM_DXE
,
75 EFI_FV_FILETYPE_COMBINED_PEIM_DRIVER
,
76 EFI_FV_FILETYPE_DXE_CORE
,
77 EFI_FV_FILETYPE_FIRMWARE_VOLUME_IMAGE
81 MEDIA_FW_VOL_FILEPATH_DEVICE_PATH File
;
82 EFI_DEVICE_PATH_PROTOCOL End
;
83 } FV_FILEPATH_DEVICE_PATH
;
85 FV_FILEPATH_DEVICE_PATH mFvDevicePath
;
88 // Function Prototypes
92 Insert InsertedDriverEntry onto the mScheduledQueue. To do this you
93 must add any driver with a before dependency on InsertedDriverEntry first.
94 You do this by recursively calling this routine. After all the Befores are
95 processed you can add InsertedDriverEntry to the mScheduledQueue.
96 Then you can add any driver with an After dependency on InsertedDriverEntry
97 by recursively calling this routine.
99 @param InsertedDriverEntry The driver to insert on the ScheduledLink Queue
103 CoreInsertOnScheduledQueueWhileProcessingBeforeAndAfter (
104 IN EFI_CORE_DRIVER_ENTRY
*InsertedDriverEntry
108 Event notification that is fired every time a FV dispatch protocol is added.
109 More than one protocol may have been added when this event is fired, so you
110 must loop on CoreLocateHandle () to see how many protocols were added and
111 do the following to each FV:
112 If the Fv has already been processed, skip it. If the Fv has not been
113 processed then mark it as being processed, as we are about to process it.
114 Read the Fv and add any driver in the Fv to the mDiscoveredList.The
115 mDiscoveredList is never free'ed and contains variables that define
116 the other states the DXE driver transitions to..
117 While you are at it read the A Priori file into memory.
118 Place drivers in the A Priori list onto the mScheduledQueue.
120 @param Event The Event that is being processed, not used.
121 @param Context Event Context, not used.
126 CoreFwVolEventProtocolNotify (
132 Convert FvHandle and DriverName into an EFI device path
134 @param Fv Fv protocol, needed to read Depex info out of
136 @param FvHandle Handle for Fv, needed in the
137 EFI_CORE_DRIVER_ENTRY so that the PE image can be
138 read out of the FV at a later time.
139 @param DriverName Name of driver to add to mDiscoveredList.
141 @return Pointer to device path constructed from FvHandle and DriverName
144 EFI_DEVICE_PATH_PROTOCOL
*
146 IN EFI_FIRMWARE_VOLUME2_PROTOCOL
*Fv
,
147 IN EFI_HANDLE FvHandle
,
148 IN EFI_GUID
*DriverName
152 Add an entry to the mDiscoveredList. Allocate memory to store the DriverEntry,
153 and initilize any state variables. Read the Depex from the FV and store it
154 in DriverEntry. Pre-process the Depex to set the SOR, Before and After state.
155 The Discovered list is never free'ed and contains booleans that represent the
156 other possible DXE driver states.
158 @param Fv Fv protocol, needed to read Depex info out of
160 @param FvHandle Handle for Fv, needed in the
161 EFI_CORE_DRIVER_ENTRY so that the PE image can be
162 read out of the FV at a later time.
163 @param DriverName Name of driver to add to mDiscoveredList.
164 @param Type Fv File Type of file to add to mDiscoveredList.
166 @retval EFI_SUCCESS If driver was added to the mDiscoveredList.
167 @retval EFI_ALREADY_STARTED The driver has already been started. Only one
168 DriverName may be active in the system at any one
173 CoreAddToDriverList (
174 IN EFI_FIRMWARE_VOLUME2_PROTOCOL
*Fv
,
175 IN EFI_HANDLE FvHandle
,
176 IN EFI_GUID
*DriverName
,
177 IN EFI_FV_FILETYPE Type
181 Get Fv image(s) from the FV through file name, and produce FVB protocol for every Fv image(s).
183 @param Fv The FIRMWARE_VOLUME protocol installed on the FV.
184 @param FvHandle The handle which FVB protocol installed on.
185 @param FileName The file name guid specified.
187 @retval EFI_OUT_OF_RESOURCES No enough memory or other resource.
188 @retval EFI_SUCCESS Function successfully returned.
192 CoreProcessFvImageFile (
193 IN EFI_FIRMWARE_VOLUME2_PROTOCOL
*Fv
,
194 IN EFI_HANDLE FvHandle
,
195 IN EFI_GUID
*FileName
199 Enter critical section by gaining lock on mDispatcherLock.
203 CoreAcquireDispatcherLock (
207 CoreAcquireLock (&mDispatcherLock
);
211 Exit critical section by releasing lock on mDispatcherLock.
215 CoreReleaseDispatcherLock (
219 CoreReleaseLock (&mDispatcherLock
);
223 Read Depex and pre-process the Depex for Before and After. If Section Extraction
224 protocol returns an error via ReadSection defer the reading of the Depex.
226 @param DriverEntry Driver to work on.
228 @retval EFI_SUCCESS Depex read and preprossesed
229 @retval EFI_PROTOCOL_ERROR The section extraction protocol returned an error
230 and Depex reading needs to be retried.
231 @retval Error DEPEX not found.
235 CoreGetDepexSectionAndPreProccess (
236 IN EFI_CORE_DRIVER_ENTRY
*DriverEntry
240 EFI_SECTION_TYPE SectionType
;
241 UINT32 AuthenticationStatus
;
242 EFI_FIRMWARE_VOLUME2_PROTOCOL
*Fv
;
244 Fv
= DriverEntry
->Fv
;
247 // Grab Depex info, it will never be free'ed.
249 SectionType
= EFI_SECTION_DXE_DEPEX
;
250 Status
= Fv
->ReadSection (
252 &DriverEntry
->FileName
,
256 (UINTN
*)&DriverEntry
->DepexSize
,
257 &AuthenticationStatus
259 if (EFI_ERROR (Status
)) {
260 if (Status
== EFI_PROTOCOL_ERROR
) {
262 // The section extraction protocol failed so set protocol error flag
264 DriverEntry
->DepexProtocolError
= TRUE
;
267 // If no Depex assume UEFI 2.0 driver model
269 DriverEntry
->Depex
= NULL
;
270 DriverEntry
->Dependent
= TRUE
;
271 DriverEntry
->DepexProtocolError
= FALSE
;
275 // Set Before, After, and Unrequested state information based on Depex
276 // Driver will be put in Dependent or Unrequested state
278 CorePreProcessDepex (DriverEntry
);
279 DriverEntry
->DepexProtocolError
= FALSE
;
286 Check every driver and locate a matching one. If the driver is found, the Unrequested
287 state flag is cleared.
289 @param FirmwareVolumeHandle The handle of the Firmware Volume that contains
290 the firmware file specified by DriverName.
291 @param DriverName The Driver name to put in the Dependent state.
293 @retval EFI_SUCCESS The DriverName was found and it's SOR bit was
295 @retval EFI_NOT_FOUND The DriverName does not exist or it's SOR bit was
302 IN EFI_HANDLE FirmwareVolumeHandle
,
303 IN EFI_GUID
*DriverName
307 EFI_CORE_DRIVER_ENTRY
*DriverEntry
;
310 // Check every driver
312 for (Link
= mDiscoveredList
.ForwardLink
; Link
!= &mDiscoveredList
; Link
= Link
->ForwardLink
) {
313 DriverEntry
= CR (Link
, EFI_CORE_DRIVER_ENTRY
, Link
, EFI_CORE_DRIVER_ENTRY_SIGNATURE
);
314 if ((DriverEntry
->FvHandle
== FirmwareVolumeHandle
) &&
315 DriverEntry
->Unrequested
&&
316 CompareGuid (DriverName
, &DriverEntry
->FileName
))
319 // Move the driver from the Unrequested to the Dependent state
321 CoreAcquireDispatcherLock ();
322 DriverEntry
->Unrequested
= FALSE
;
323 DriverEntry
->Dependent
= TRUE
;
324 CoreReleaseDispatcherLock ();
326 DEBUG ((DEBUG_DISPATCH
, "Schedule FFS(%g) - EFI_SUCCESS\n", DriverName
));
332 DEBUG ((DEBUG_DISPATCH
, "Schedule FFS(%g) - EFI_NOT_FOUND\n", DriverName
));
334 return EFI_NOT_FOUND
;
338 Convert a driver from the Untrused back to the Scheduled state.
340 @param FirmwareVolumeHandle The handle of the Firmware Volume that contains
341 the firmware file specified by DriverName.
342 @param DriverName The Driver name to put in the Scheduled state
344 @retval EFI_SUCCESS The file was found in the untrusted state, and it
345 was promoted to the trusted state.
346 @retval EFI_NOT_FOUND The file was not found in the untrusted state.
352 IN EFI_HANDLE FirmwareVolumeHandle
,
353 IN EFI_GUID
*DriverName
357 EFI_CORE_DRIVER_ENTRY
*DriverEntry
;
360 // Check every driver
362 for (Link
= mDiscoveredList
.ForwardLink
; Link
!= &mDiscoveredList
; Link
= Link
->ForwardLink
) {
363 DriverEntry
= CR (Link
, EFI_CORE_DRIVER_ENTRY
, Link
, EFI_CORE_DRIVER_ENTRY_SIGNATURE
);
364 if ((DriverEntry
->FvHandle
== FirmwareVolumeHandle
) &&
365 DriverEntry
->Untrusted
&&
366 CompareGuid (DriverName
, &DriverEntry
->FileName
))
369 // Transition driver from Untrusted to Scheduled state.
371 CoreAcquireDispatcherLock ();
372 DriverEntry
->Untrusted
= FALSE
;
373 DriverEntry
->Scheduled
= TRUE
;
374 InsertTailList (&mScheduledQueue
, &DriverEntry
->ScheduledLink
);
375 CoreReleaseDispatcherLock ();
381 return EFI_NOT_FOUND
;
385 This is the main Dispatcher for DXE and it exits when there are no more
386 drivers to run. Drain the mScheduledQueue and load and start a PE
387 image for each driver. Search the mDiscoveredList to see if any driver can
388 be placed on the mScheduledQueue. If no drivers are placed on the
389 mScheduledQueue exit the function. On exit it is assumed the Bds()
390 will be called, and when the Bds() exits the Dispatcher will be called
393 @retval EFI_ALREADY_STARTED The DXE Dispatcher is already running
394 @retval EFI_NOT_FOUND No DXE Drivers were dispatched
395 @retval EFI_SUCCESS One or more DXE Drivers were dispatched
405 EFI_STATUS ReturnStatus
;
407 EFI_CORE_DRIVER_ENTRY
*DriverEntry
;
409 EFI_EVENT DxeDispatchEvent
;
411 PERF_FUNCTION_BEGIN ();
413 if (gDispatcherRunning
) {
415 // If the dispatcher is running don't let it be restarted.
417 return EFI_ALREADY_STARTED
;
420 gDispatcherRunning
= TRUE
;
422 Status
= CoreCreateEventEx (
425 EfiEventEmptyFunction
,
427 &gEfiEventDxeDispatchGuid
,
430 if (EFI_ERROR (Status
)) {
434 ReturnStatus
= EFI_NOT_FOUND
;
437 // Drain the Scheduled Queue
439 while (!IsListEmpty (&mScheduledQueue
)) {
441 mScheduledQueue
.ForwardLink
,
442 EFI_CORE_DRIVER_ENTRY
,
444 EFI_CORE_DRIVER_ENTRY_SIGNATURE
448 // Load the DXE Driver image into memory. If the Driver was transitioned from
449 // Untrused to Scheduled it would have already been loaded so we may need to
450 // skip the LoadImage
452 if ((DriverEntry
->ImageHandle
== NULL
) && !DriverEntry
->IsFvImage
) {
453 DEBUG ((DEBUG_INFO
, "Loading driver %g\n", &DriverEntry
->FileName
));
454 Status
= CoreLoadImage (
457 DriverEntry
->FvFileDevicePath
,
460 &DriverEntry
->ImageHandle
464 // Update the driver state to reflect that it's been loaded
466 if (EFI_ERROR (Status
)) {
467 CoreAcquireDispatcherLock ();
469 if (Status
== EFI_SECURITY_VIOLATION
) {
471 // Take driver from Scheduled to Untrused state
473 DriverEntry
->Untrusted
= TRUE
;
476 // The DXE Driver could not be loaded, and do not attempt to load or start it again.
477 // Take driver from Scheduled to Initialized.
479 // This case include the Never Trusted state if EFI_ACCESS_DENIED is returned
481 DriverEntry
->Initialized
= TRUE
;
484 DriverEntry
->Scheduled
= FALSE
;
485 RemoveEntryList (&DriverEntry
->ScheduledLink
);
487 CoreReleaseDispatcherLock ();
490 // If it's an error don't try the StartImage
496 CoreAcquireDispatcherLock ();
498 DriverEntry
->Scheduled
= FALSE
;
499 DriverEntry
->Initialized
= TRUE
;
500 RemoveEntryList (&DriverEntry
->ScheduledLink
);
502 CoreReleaseDispatcherLock ();
504 if (DriverEntry
->IsFvImage
) {
506 // Produce a firmware volume block protocol for FvImage so it gets dispatched from.
508 Status
= CoreProcessFvImageFile (DriverEntry
->Fv
, DriverEntry
->FvHandle
, &DriverEntry
->FileName
);
510 REPORT_STATUS_CODE_WITH_EXTENDED_DATA (
512 (EFI_SOFTWARE_DXE_CORE
| EFI_SW_PC_INIT_BEGIN
),
513 &DriverEntry
->ImageHandle
,
514 sizeof (DriverEntry
->ImageHandle
)
516 ASSERT (DriverEntry
->ImageHandle
!= NULL
);
518 Status
= CoreStartImage (DriverEntry
->ImageHandle
, NULL
, NULL
);
520 REPORT_STATUS_CODE_WITH_EXTENDED_DATA (
522 (EFI_SOFTWARE_DXE_CORE
| EFI_SW_PC_INIT_END
),
523 &DriverEntry
->ImageHandle
,
524 sizeof (DriverEntry
->ImageHandle
)
528 ReturnStatus
= EFI_SUCCESS
;
532 // Now DXE Dispatcher finished one round of dispatch, signal an event group
533 // so that SMM Dispatcher get chance to dispatch SMM Drivers which depend
536 if (!EFI_ERROR (ReturnStatus
)) {
537 CoreSignalEvent (DxeDispatchEvent
);
541 // Search DriverList for items to place on Scheduled Queue
544 for (Link
= mDiscoveredList
.ForwardLink
; Link
!= &mDiscoveredList
; Link
= Link
->ForwardLink
) {
545 DriverEntry
= CR (Link
, EFI_CORE_DRIVER_ENTRY
, Link
, EFI_CORE_DRIVER_ENTRY_SIGNATURE
);
547 if (DriverEntry
->DepexProtocolError
) {
549 // If Section Extraction Protocol did not let the Depex be read before retry the read
551 Status
= CoreGetDepexSectionAndPreProccess (DriverEntry
);
554 if (DriverEntry
->Dependent
) {
555 if (CoreIsSchedulable (DriverEntry
)) {
556 CoreInsertOnScheduledQueueWhileProcessingBeforeAndAfter (DriverEntry
);
560 if (DriverEntry
->Unrequested
) {
561 DEBUG ((DEBUG_DISPATCH
, "Evaluate DXE DEPEX for FFS(%g)\n", &DriverEntry
->FileName
));
562 DEBUG ((DEBUG_DISPATCH
, " SOR = Not Requested\n"));
563 DEBUG ((DEBUG_DISPATCH
, " RESULT = FALSE\n"));
567 } while (ReadyToRun
);
570 // Close DXE dispatch Event
572 CoreCloseEvent (DxeDispatchEvent
);
574 gDispatcherRunning
= FALSE
;
576 PERF_FUNCTION_END ();
582 Insert InsertedDriverEntry onto the mScheduledQueue. To do this you
583 must add any driver with a before dependency on InsertedDriverEntry first.
584 You do this by recursively calling this routine. After all the Befores are
585 processed you can add InsertedDriverEntry to the mScheduledQueue.
586 Then you can add any driver with an After dependency on InsertedDriverEntry
587 by recursively calling this routine.
589 @param InsertedDriverEntry The driver to insert on the ScheduledLink Queue
593 CoreInsertOnScheduledQueueWhileProcessingBeforeAndAfter (
594 IN EFI_CORE_DRIVER_ENTRY
*InsertedDriverEntry
598 EFI_CORE_DRIVER_ENTRY
*DriverEntry
;
601 // Process Before Dependency
603 for (Link
= mDiscoveredList
.ForwardLink
; Link
!= &mDiscoveredList
; Link
= Link
->ForwardLink
) {
604 DriverEntry
= CR (Link
, EFI_CORE_DRIVER_ENTRY
, Link
, EFI_CORE_DRIVER_ENTRY_SIGNATURE
);
605 if (DriverEntry
->Before
&& DriverEntry
->Dependent
&& (DriverEntry
!= InsertedDriverEntry
)) {
606 DEBUG ((DEBUG_DISPATCH
, "Evaluate DXE DEPEX for FFS(%g)\n", &DriverEntry
->FileName
));
607 DEBUG ((DEBUG_DISPATCH
, " BEFORE FFS(%g) = ", &DriverEntry
->BeforeAfterGuid
));
608 if (CompareGuid (&InsertedDriverEntry
->FileName
, &DriverEntry
->BeforeAfterGuid
)) {
610 // Recursively process BEFORE
612 DEBUG ((DEBUG_DISPATCH
, "TRUE\n END\n RESULT = TRUE\n"));
613 CoreInsertOnScheduledQueueWhileProcessingBeforeAndAfter (DriverEntry
);
615 DEBUG ((DEBUG_DISPATCH
, "FALSE\n END\n RESULT = FALSE\n"));
621 // Convert driver from Dependent to Scheduled state
623 CoreAcquireDispatcherLock ();
625 InsertedDriverEntry
->Dependent
= FALSE
;
626 InsertedDriverEntry
->Scheduled
= TRUE
;
627 InsertTailList (&mScheduledQueue
, &InsertedDriverEntry
->ScheduledLink
);
629 CoreReleaseDispatcherLock ();
632 // Process After Dependency
634 for (Link
= mDiscoveredList
.ForwardLink
; Link
!= &mDiscoveredList
; Link
= Link
->ForwardLink
) {
635 DriverEntry
= CR (Link
, EFI_CORE_DRIVER_ENTRY
, Link
, EFI_CORE_DRIVER_ENTRY_SIGNATURE
);
636 if (DriverEntry
->After
&& DriverEntry
->Dependent
&& (DriverEntry
!= InsertedDriverEntry
)) {
637 DEBUG ((DEBUG_DISPATCH
, "Evaluate DXE DEPEX for FFS(%g)\n", &DriverEntry
->FileName
));
638 DEBUG ((DEBUG_DISPATCH
, " AFTER FFS(%g) = ", &DriverEntry
->BeforeAfterGuid
));
639 if (CompareGuid (&InsertedDriverEntry
->FileName
, &DriverEntry
->BeforeAfterGuid
)) {
641 // Recursively process AFTER
643 DEBUG ((DEBUG_DISPATCH
, "TRUE\n END\n RESULT = TRUE\n"));
644 CoreInsertOnScheduledQueueWhileProcessingBeforeAndAfter (DriverEntry
);
646 DEBUG ((DEBUG_DISPATCH
, "FALSE\n END\n RESULT = FALSE\n"));
653 Return TRUE if the Fv has been processed, FALSE if not.
655 @param FvHandle The handle of a FV that's being tested
657 @retval TRUE Fv protocol on FvHandle has been processed
658 @retval FALSE Fv protocol on FvHandle has not yet been processed
663 IN EFI_HANDLE FvHandle
667 KNOWN_HANDLE
*KnownHandle
;
669 for (Link
= mFvHandleList
.ForwardLink
; Link
!= &mFvHandleList
; Link
= Link
->ForwardLink
) {
670 KnownHandle
= CR (Link
, KNOWN_HANDLE
, Link
, KNOWN_HANDLE_SIGNATURE
);
671 if (KnownHandle
->Handle
== FvHandle
) {
680 Remember that Fv protocol on FvHandle has had it's drivers placed on the
681 mDiscoveredList. This fucntion adds entries on the mFvHandleList if new
682 entry is different from one in mFvHandleList by checking FvImage Guid.
683 Items are never removed/freed from the mFvHandleList.
685 @param FvHandle The handle of a FV that has been processed
687 @return A point to new added FvHandle entry. If FvHandle with the same FvImage guid
688 has been added, NULL will return.
693 IN EFI_HANDLE FvHandle
698 BOOLEAN FvNameGuidIsFound
;
699 UINT32 ExtHeaderOffset
;
700 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*Fvb
;
701 EFI_FIRMWARE_VOLUME_HEADER
*FwVolHeader
;
702 EFI_FV_BLOCK_MAP_ENTRY
*BlockMap
;
707 KNOWN_HANDLE
*KnownHandle
;
712 // Get the FirmwareVolumeBlock protocol on that handle
714 FvNameGuidIsFound
= FALSE
;
715 Status
= CoreHandleProtocol (FvHandle
, &gEfiFirmwareVolumeBlockProtocolGuid
, (VOID
**)&Fvb
);
716 if (!EFI_ERROR (Status
)) {
718 // Get the full FV header based on FVB protocol.
720 ASSERT (Fvb
!= NULL
);
721 Status
= GetFwVolHeader (Fvb
, &FwVolHeader
);
722 if (!EFI_ERROR (Status
)) {
723 ASSERT (FwVolHeader
!= NULL
);
724 if (VerifyFvHeaderChecksum (FwVolHeader
) && (FwVolHeader
->ExtHeaderOffset
!= 0)) {
725 ExtHeaderOffset
= (UINT32
)FwVolHeader
->ExtHeaderOffset
;
726 BlockMap
= FwVolHeader
->BlockMap
;
730 // Find LbaIndex and LbaOffset for FV extension header based on BlockMap.
732 while ((BlockMap
->NumBlocks
!= 0) || (BlockMap
->Length
!= 0)) {
733 for (Index
= 0; Index
< BlockMap
->NumBlocks
&& ExtHeaderOffset
>= BlockMap
->Length
; Index
++) {
734 ExtHeaderOffset
-= BlockMap
->Length
;
739 // Check whether FvExtHeader is crossing the multi block range.
741 if (Index
< BlockMap
->NumBlocks
) {
742 LbaOffset
= ExtHeaderOffset
;
750 // Read FvNameGuid from FV extension header.
752 Status
= ReadFvbData (Fvb
, &LbaIndex
, &LbaOffset
, sizeof (FvNameGuid
), (UINT8
*)&FvNameGuid
);
753 if (!EFI_ERROR (Status
)) {
754 FvNameGuidIsFound
= TRUE
;
758 CoreFreePool (FwVolHeader
);
762 if (FvNameGuidIsFound
) {
764 // Check whether the FV image with the found FvNameGuid has been processed.
766 for (Link
= mFvHandleList
.ForwardLink
; Link
!= &mFvHandleList
; Link
= Link
->ForwardLink
) {
767 KnownHandle
= CR (Link
, KNOWN_HANDLE
, Link
, KNOWN_HANDLE_SIGNATURE
);
768 if (CompareGuid (&FvNameGuid
, &KnownHandle
->FvNameGuid
)) {
769 DEBUG ((DEBUG_ERROR
, "FvImage on FvHandle %p and %p has the same FvNameGuid %g.\n", FvHandle
, KnownHandle
->Handle
, &FvNameGuid
));
775 KnownHandle
= AllocateZeroPool (sizeof (KNOWN_HANDLE
));
776 ASSERT (KnownHandle
!= NULL
);
778 KnownHandle
->Signature
= KNOWN_HANDLE_SIGNATURE
;
779 KnownHandle
->Handle
= FvHandle
;
780 if (FvNameGuidIsFound
) {
781 CopyGuid (&KnownHandle
->FvNameGuid
, &FvNameGuid
);
784 InsertTailList (&mFvHandleList
, &KnownHandle
->Link
);
789 Convert FvHandle and DriverName into an EFI device path
791 @param Fv Fv protocol, needed to read Depex info out of
793 @param FvHandle Handle for Fv, needed in the
794 EFI_CORE_DRIVER_ENTRY so that the PE image can be
795 read out of the FV at a later time.
796 @param DriverName Name of driver to add to mDiscoveredList.
798 @return Pointer to device path constructed from FvHandle and DriverName
801 EFI_DEVICE_PATH_PROTOCOL
*
803 IN EFI_FIRMWARE_VOLUME2_PROTOCOL
*Fv
,
804 IN EFI_HANDLE FvHandle
,
805 IN EFI_GUID
*DriverName
809 EFI_DEVICE_PATH_PROTOCOL
*FvDevicePath
;
810 EFI_DEVICE_PATH_PROTOCOL
*FileNameDevicePath
;
813 // Remember the device path of the FV
815 Status
= CoreHandleProtocol (FvHandle
, &gEfiDevicePathProtocolGuid
, (VOID
**)&FvDevicePath
);
816 if (EFI_ERROR (Status
)) {
817 FileNameDevicePath
= NULL
;
820 // Build a device path to the file in the FV to pass into gBS->LoadImage
822 EfiInitializeFwVolDevicepathNode (&mFvDevicePath
.File
, DriverName
);
823 SetDevicePathEndNode (&mFvDevicePath
.End
);
825 FileNameDevicePath
= AppendDevicePath (
827 (EFI_DEVICE_PATH_PROTOCOL
*)&mFvDevicePath
831 return FileNameDevicePath
;
835 Add an entry to the mDiscoveredList. Allocate memory to store the DriverEntry,
836 and initilize any state variables. Read the Depex from the FV and store it
837 in DriverEntry. Pre-process the Depex to set the SOR, Before and After state.
838 The Discovered list is never free'ed and contains booleans that represent the
839 other possible DXE driver states.
841 @param Fv Fv protocol, needed to read Depex info out of
843 @param FvHandle Handle for Fv, needed in the
844 EFI_CORE_DRIVER_ENTRY so that the PE image can be
845 read out of the FV at a later time.
846 @param DriverName Name of driver to add to mDiscoveredList.
847 @param Type Fv File Type of file to add to mDiscoveredList.
849 @retval EFI_SUCCESS If driver was added to the mDiscoveredList.
850 @retval EFI_ALREADY_STARTED The driver has already been started. Only one
851 DriverName may be active in the system at any one
856 CoreAddToDriverList (
857 IN EFI_FIRMWARE_VOLUME2_PROTOCOL
*Fv
,
858 IN EFI_HANDLE FvHandle
,
859 IN EFI_GUID
*DriverName
,
860 IN EFI_FV_FILETYPE Type
863 EFI_CORE_DRIVER_ENTRY
*DriverEntry
;
866 // Create the Driver Entry for the list. ZeroPool initializes lots of variables to
869 DriverEntry
= AllocateZeroPool (sizeof (EFI_CORE_DRIVER_ENTRY
));
870 ASSERT (DriverEntry
!= NULL
);
871 if (Type
== EFI_FV_FILETYPE_FIRMWARE_VOLUME_IMAGE
) {
872 DriverEntry
->IsFvImage
= TRUE
;
875 DriverEntry
->Signature
= EFI_CORE_DRIVER_ENTRY_SIGNATURE
;
876 CopyGuid (&DriverEntry
->FileName
, DriverName
);
877 DriverEntry
->FvHandle
= FvHandle
;
878 DriverEntry
->Fv
= Fv
;
879 DriverEntry
->FvFileDevicePath
= CoreFvToDevicePath (Fv
, FvHandle
, DriverName
);
881 CoreGetDepexSectionAndPreProccess (DriverEntry
);
883 CoreAcquireDispatcherLock ();
885 InsertTailList (&mDiscoveredList
, &DriverEntry
->Link
);
887 CoreReleaseDispatcherLock ();
893 Check if a FV Image type file (EFI_FV_FILETYPE_FIRMWARE_VOLUME_IMAGE) is
894 described by a EFI_HOB_FIRMWARE_VOLUME2 Hob.
896 @param FvNameGuid The FV image guid specified.
897 @param DriverName The driver guid specified.
899 @retval TRUE This file is found in a EFI_HOB_FIRMWARE_VOLUME2
901 @retval FALSE Not found.
906 IN CONST EFI_GUID
*FvNameGuid
,
907 IN CONST EFI_GUID
*DriverName
910 EFI_PEI_HOB_POINTERS HobFv2
;
912 HobFv2
.Raw
= GetHobList ();
914 while ((HobFv2
.Raw
= GetNextHob (EFI_HOB_TYPE_FV2
, HobFv2
.Raw
)) != NULL
) {
916 // Compare parent FvNameGuid and FileGuid both.
918 if (CompareGuid (DriverName
, &HobFv2
.FirmwareVolume2
->FileName
) &&
919 CompareGuid (FvNameGuid
, &HobFv2
.FirmwareVolume2
->FvName
))
924 HobFv2
.Raw
= GET_NEXT_HOB (HobFv2
);
931 Find USED_SIZE FV_EXT_TYPE entry in FV extension header and get the FV used size.
933 @param[in] FvHeader Pointer to FV header.
934 @param[out] FvUsedSize Pointer to FV used size returned,
935 only valid if USED_SIZE FV_EXT_TYPE entry is found.
936 @param[out] EraseByte Pointer to erase byte returned,
937 only valid if USED_SIZE FV_EXT_TYPE entry is found.
939 @retval TRUE USED_SIZE FV_EXT_TYPE entry is found,
940 FV used size and erase byte are returned.
941 @retval FALSE No USED_SIZE FV_EXT_TYPE entry found.
946 IN EFI_FIRMWARE_VOLUME_HEADER
*FvHeader
,
947 OUT UINT32
*FvUsedSize
,
951 UINT16 ExtHeaderOffset
;
952 EFI_FIRMWARE_VOLUME_EXT_HEADER
*ExtHeader
;
953 EFI_FIRMWARE_VOLUME_EXT_ENTRY
*ExtEntryList
;
954 EFI_FIRMWARE_VOLUME_EXT_ENTRY_USED_SIZE_TYPE
*ExtEntryUsedSize
;
956 ExtHeaderOffset
= ReadUnaligned16 (&FvHeader
->ExtHeaderOffset
);
957 if (ExtHeaderOffset
!= 0) {
958 ExtHeader
= (EFI_FIRMWARE_VOLUME_EXT_HEADER
*)((UINT8
*)FvHeader
+ ExtHeaderOffset
);
959 ExtEntryList
= (EFI_FIRMWARE_VOLUME_EXT_ENTRY
*)(ExtHeader
+ 1);
960 while ((UINTN
)ExtEntryList
< ((UINTN
)ExtHeader
+ ReadUnaligned32 (&ExtHeader
->ExtHeaderSize
))) {
961 if (ReadUnaligned16 (&ExtEntryList
->ExtEntryType
) == EFI_FV_EXT_TYPE_USED_SIZE_TYPE
) {
963 // USED_SIZE FV_EXT_TYPE entry is found.
965 ExtEntryUsedSize
= (EFI_FIRMWARE_VOLUME_EXT_ENTRY_USED_SIZE_TYPE
*)ExtEntryList
;
966 *FvUsedSize
= ReadUnaligned32 (&ExtEntryUsedSize
->UsedSize
);
967 if ((ReadUnaligned32 (&FvHeader
->Attributes
) & EFI_FVB2_ERASE_POLARITY
) != 0) {
975 "FV at 0x%x has 0x%x used size, and erase byte is 0x%02x\n",
983 ExtEntryList
= (EFI_FIRMWARE_VOLUME_EXT_ENTRY
*)
984 ((UINT8
*)ExtEntryList
+ ReadUnaligned16 (&ExtEntryList
->ExtEntrySize
));
989 // No USED_SIZE FV_EXT_TYPE entry found.
995 Get Fv image(s) from the FV through file name, and produce FVB protocol for every Fv image(s).
997 @param Fv The FIRMWARE_VOLUME protocol installed on the FV.
998 @param FvHandle The handle which FVB protocol installed on.
999 @param FileName The file name guid specified.
1001 @retval EFI_OUT_OF_RESOURCES No enough memory or other resource.
1002 @retval EFI_SUCCESS Function successfully returned.
1006 CoreProcessFvImageFile (
1007 IN EFI_FIRMWARE_VOLUME2_PROTOCOL
*Fv
,
1008 IN EFI_HANDLE FvHandle
,
1009 IN EFI_GUID
*FileName
1013 EFI_SECTION_TYPE SectionType
;
1014 UINT32 AuthenticationStatus
;
1016 VOID
*AlignedBuffer
;
1018 EFI_FIRMWARE_VOLUME_HEADER
*FvHeader
;
1020 EFI_DEVICE_PATH_PROTOCOL
*FvFileDevicePath
;
1026 // Read firmware volume section(s)
1028 SectionType
= EFI_SECTION_FIRMWARE_VOLUME_IMAGE
;
1036 AlignedBuffer
= NULL
;
1037 Status
= Fv
->ReadSection (
1044 &AuthenticationStatus
1046 if (!EFI_ERROR (Status
)) {
1048 // Evaluate the authentication status of the Firmware Volume through
1049 // Security Architectural Protocol
1051 if (gSecurity
!= NULL
) {
1052 FvFileDevicePath
= CoreFvToDevicePath (Fv
, FvHandle
, FileName
);
1053 Status
= gSecurity
->FileAuthenticationState (
1055 AuthenticationStatus
,
1058 if (FvFileDevicePath
!= NULL
) {
1059 FreePool (FvFileDevicePath
);
1062 if (Status
!= EFI_SUCCESS
) {
1064 // Security check failed. The firmware volume should not be used for any purpose.
1066 if (Buffer
!= NULL
) {
1075 // FvImage should be at its required alignment.
1077 FvHeader
= (EFI_FIRMWARE_VOLUME_HEADER
*)Buffer
;
1079 // If EFI_FVB2_WEAK_ALIGNMENT is set in the volume header then the first byte of the volume
1080 // can be aligned on any power-of-two boundary. A weakly aligned volume can not be moved from
1081 // its initial linked location and maintain its alignment.
1083 if ((ReadUnaligned32 (&FvHeader
->Attributes
) & EFI_FVB2_WEAK_ALIGNMENT
) != EFI_FVB2_WEAK_ALIGNMENT
) {
1085 // Get FvHeader alignment
1087 FvAlignment
= 1 << ((ReadUnaligned32 (&FvHeader
->Attributes
) & EFI_FVB2_ALIGNMENT
) >> 16);
1089 // FvAlignment must be greater than or equal to 8 bytes of the minimum FFS alignment value.
1091 if (FvAlignment
< 8) {
1097 "%a() FV at 0x%x, FvAlignment required is 0x%x\n",
1104 // Check FvImage alignment.
1106 if ((UINTN
)FvHeader
% FvAlignment
!= 0) {
1108 // Allocate the aligned buffer for the FvImage.
1110 AlignedBuffer
= AllocateAlignedPages (EFI_SIZE_TO_PAGES (BufferSize
), (UINTN
)FvAlignment
);
1111 if (AlignedBuffer
== NULL
) {
1113 Status
= EFI_OUT_OF_RESOURCES
;
1117 // Move FvImage into the aligned buffer and release the original buffer.
1119 if (GetFvUsedSize (FvHeader
, &FvUsedSize
, &EraseByte
)) {
1121 // Copy the used bytes and fill the rest with the erase value.
1123 CopyMem (AlignedBuffer
, FvHeader
, (UINTN
)FvUsedSize
);
1125 (UINT8
*)AlignedBuffer
+ FvUsedSize
,
1126 (UINTN
)(BufferSize
- FvUsedSize
),
1130 CopyMem (AlignedBuffer
, Buffer
, BufferSize
);
1133 FvHeader
= (EFI_FIRMWARE_VOLUME_HEADER
*)AlignedBuffer
;
1141 // Produce a FVB protocol for the file
1143 Status
= ProduceFVBProtocolOnBuffer (
1144 (EFI_PHYSICAL_ADDRESS
)(UINTN
)FvHeader
,
1147 AuthenticationStatus
,
1152 if (EFI_ERROR (Status
)) {
1154 // ReadSection or Produce FVB failed, Free data buffer
1156 if (Buffer
!= NULL
) {
1160 if (AlignedBuffer
!= NULL
) {
1161 FreeAlignedPages (AlignedBuffer
, EFI_SIZE_TO_PAGES (BufferSize
));
1172 // At least one FvImage has been processed successfully.
1181 Event notification that is fired every time a FV dispatch protocol is added.
1182 More than one protocol may have been added when this event is fired, so you
1183 must loop on CoreLocateHandle () to see how many protocols were added and
1184 do the following to each FV:
1185 If the Fv has already been processed, skip it. If the Fv has not been
1186 processed then mark it as being processed, as we are about to process it.
1187 Read the Fv and add any driver in the Fv to the mDiscoveredList.The
1188 mDiscoveredList is never free'ed and contains variables that define
1189 the other states the DXE driver transitions to..
1190 While you are at it read the A Priori file into memory.
1191 Place drivers in the A Priori list onto the mScheduledQueue.
1193 @param Event The Event that is being processed, not used.
1194 @param Context Event Context, not used.
1199 CoreFwVolEventProtocolNotify (
1205 EFI_STATUS GetNextFileStatus
;
1206 EFI_FIRMWARE_VOLUME2_PROTOCOL
*Fv
;
1207 EFI_DEVICE_PATH_PROTOCOL
*FvDevicePath
;
1208 EFI_HANDLE FvHandle
;
1212 EFI_FV_FILETYPE Type
;
1213 EFI_FV_FILE_ATTRIBUTES Attributes
;
1215 EFI_CORE_DRIVER_ENTRY
*DriverEntry
;
1216 EFI_GUID
*AprioriFile
;
1217 UINTN AprioriEntryCount
;
1220 UINT32 AuthenticationStatus
;
1223 KNOWN_HANDLE
*KnownHandle
;
1228 BufferSize
= sizeof (EFI_HANDLE
);
1229 Status
= CoreLocateHandle (
1232 mFwVolEventRegistration
,
1236 if (EFI_ERROR (Status
)) {
1238 // If no more notification events exit
1243 if (FvHasBeenProcessed (FvHandle
)) {
1245 // This Fv has already been processed so lets skip it!
1251 // Since we are about to process this Fv mark it as processed.
1253 KnownHandle
= FvIsBeingProcessed (FvHandle
);
1254 if (KnownHandle
== NULL
) {
1256 // The FV with the same FV name guid has already been processed.
1262 Status
= CoreHandleProtocol (FvHandle
, &gEfiFirmwareVolume2ProtocolGuid
, (VOID
**)&Fv
);
1263 if (EFI_ERROR (Status
) || (Fv
== NULL
)) {
1265 // FvHandle must have Firmware Volume2 protocol thus we should never get here.
1271 Status
= CoreHandleProtocol (FvHandle
, &gEfiDevicePathProtocolGuid
, (VOID
**)&FvDevicePath
);
1272 if (EFI_ERROR (Status
)) {
1274 // The Firmware volume doesn't have device path, can't be dispatched.
1280 // Discover Drivers in FV and add them to the Discovered Driver List.
1281 // Process EFI_FV_FILETYPE_DRIVER type and then EFI_FV_FILETYPE_COMBINED_PEIM_DRIVER
1282 // EFI_FV_FILETYPE_DXE_CORE is processed to produce a Loaded Image protocol for the core
1283 // EFI_FV_FILETYPE_FIRMWARE_VOLUME_IMAGE is processed to create a Fvb
1285 for (Index
= 0; Index
< sizeof (mDxeFileTypes
) / sizeof (EFI_FV_FILETYPE
); Index
++) {
1287 // Initialize the search key
1291 Type
= mDxeFileTypes
[Index
];
1292 GetNextFileStatus
= Fv
->GetNextFile (
1300 if (!EFI_ERROR (GetNextFileStatus
)) {
1301 if (Type
== EFI_FV_FILETYPE_DXE_CORE
) {
1303 // If this is the DXE core fill in it's DevicePath & DeviceHandle
1305 if (gDxeCoreLoadedImage
->FilePath
== NULL
) {
1306 if (CompareGuid (&NameGuid
, gDxeCoreFileName
)) {
1308 // Maybe One specail Fv cantains only one DXE_CORE module, so its device path must
1309 // be initialized completely.
1311 EfiInitializeFwVolDevicepathNode (&mFvDevicePath
.File
, &NameGuid
);
1312 SetDevicePathEndNode (&mFvDevicePath
.End
);
1314 gDxeCoreLoadedImage
->FilePath
= DuplicateDevicePath (
1315 (EFI_DEVICE_PATH_PROTOCOL
*)&mFvDevicePath
1317 gDxeCoreLoadedImage
->DeviceHandle
= FvHandle
;
1320 } else if (Type
== EFI_FV_FILETYPE_FIRMWARE_VOLUME_IMAGE
) {
1322 // Check if this EFI_FV_FILETYPE_FIRMWARE_VOLUME_IMAGE file has already
1325 if (FvFoundInHobFv2 (&KnownHandle
->FvNameGuid
, &NameGuid
)) {
1330 // Check if this EFI_FV_FILETYPE_FIRMWARE_VOLUME_IMAGE file has SMM depex section.
1334 Status
= Fv
->ReadSection (
1337 EFI_SECTION_SMM_DEPEX
,
1341 &AuthenticationStatus
1343 if (!EFI_ERROR (Status
)) {
1345 // If SMM depex section is found, this FV image is invalid to be supported.
1346 // ASSERT FALSE to report this FV image.
1348 FreePool (DepexBuffer
);
1353 // Check if this EFI_FV_FILETYPE_FIRMWARE_VOLUME_IMAGE file has DXE depex section.
1357 Status
= Fv
->ReadSection (
1360 EFI_SECTION_DXE_DEPEX
,
1364 &AuthenticationStatus
1366 if (EFI_ERROR (Status
)) {
1368 // If no depex section, produce a firmware volume block protocol for it so it gets dispatched from.
1370 CoreProcessFvImageFile (Fv
, FvHandle
, &NameGuid
);
1373 // If depex section is found, this FV image will be dispatched until its depex is evaluated to TRUE.
1375 FreePool (DepexBuffer
);
1376 CoreAddToDriverList (Fv
, FvHandle
, &NameGuid
, Type
);
1380 // Transition driver from Undiscovered to Discovered state
1382 CoreAddToDriverList (Fv
, FvHandle
, &NameGuid
, Type
);
1385 } while (!EFI_ERROR (GetNextFileStatus
));
1389 // Read the array of GUIDs from the Apriori file if it is present in the firmware volume
1392 Status
= Fv
->ReadSection (
1397 (VOID
**)&AprioriFile
,
1399 &AuthenticationStatus
1401 if (!EFI_ERROR (Status
)) {
1402 AprioriEntryCount
= SizeOfBuffer
/ sizeof (EFI_GUID
);
1404 AprioriEntryCount
= 0;
1408 // Put drivers on Apriori List on the Scheduled queue. The Discovered List includes
1409 // drivers not in the current FV and these must be skipped since the a priori list
1410 // is only valid for the FV that it resided in.
1413 for (Index
= 0; Index
< AprioriEntryCount
; Index
++) {
1414 for (Link
= mDiscoveredList
.ForwardLink
; Link
!= &mDiscoveredList
; Link
= Link
->ForwardLink
) {
1415 DriverEntry
= CR (Link
, EFI_CORE_DRIVER_ENTRY
, Link
, EFI_CORE_DRIVER_ENTRY_SIGNATURE
);
1416 if (CompareGuid (&DriverEntry
->FileName
, &AprioriFile
[Index
]) &&
1417 (FvHandle
== DriverEntry
->FvHandle
))
1419 CoreAcquireDispatcherLock ();
1420 DriverEntry
->Dependent
= FALSE
;
1421 DriverEntry
->Scheduled
= TRUE
;
1422 InsertTailList (&mScheduledQueue
, &DriverEntry
->ScheduledLink
);
1423 CoreReleaseDispatcherLock ();
1424 DEBUG ((DEBUG_DISPATCH
, "Evaluate DXE DEPEX for FFS(%g)\n", &DriverEntry
->FileName
));
1425 DEBUG ((DEBUG_DISPATCH
, " RESULT = TRUE (Apriori)\n"));
1432 // Free data allocated by Fv->ReadSection ()
1434 CoreFreePool (AprioriFile
);
1439 Initialize the dispatcher. Initialize the notification function that runs when
1440 an FV2 protocol is added to the system.
1444 CoreInitializeDispatcher (
1448 PERF_FUNCTION_BEGIN ();
1450 mFwVolEvent
= EfiCreateProtocolNotifyEvent (
1451 &gEfiFirmwareVolume2ProtocolGuid
,
1453 CoreFwVolEventProtocolNotify
,
1455 &mFwVolEventRegistration
1458 PERF_FUNCTION_END ();
1462 // Function only used in debug builds
1466 Traverse the discovered list for any drivers that were discovered but not loaded
1467 because the dependency experessions evaluated to false.
1471 CoreDisplayDiscoveredNotDispatched (
1476 EFI_CORE_DRIVER_ENTRY
*DriverEntry
;
1478 for (Link
= mDiscoveredList
.ForwardLink
; Link
!= &mDiscoveredList
; Link
= Link
->ForwardLink
) {
1479 DriverEntry
= CR (Link
, EFI_CORE_DRIVER_ENTRY
, Link
, EFI_CORE_DRIVER_ENTRY_SIGNATURE
);
1480 if (DriverEntry
->Dependent
) {
1481 DEBUG ((DEBUG_LOAD
, "Driver %g was discovered but not loaded!!\n", &DriverEntry
->FileName
));