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 - 2012, Intel Corporation. All rights reserved.<BR>
30 This program and the accompanying materials
31 are licensed and made available under the terms and conditions of the BSD License
32 which accompanies this distribution. The full text of the license may be found at
33 http://opensource.org/licenses/bsd-license.php
35 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
36 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
43 // The Driver List contains one copy of every driver that has been discovered.
44 // Items are never removed from the driver list. List of EFI_CORE_DRIVER_ENTRY
46 LIST_ENTRY mDiscoveredList
= INITIALIZE_LIST_HEAD_VARIABLE (mDiscoveredList
);
49 // Queue of drivers that are ready to dispatch. This queue is a subset of the
50 // mDiscoveredList.list of EFI_CORE_DRIVER_ENTRY.
52 LIST_ENTRY mScheduledQueue
= INITIALIZE_LIST_HEAD_VARIABLE (mScheduledQueue
);
55 // List of handles who's Fv's have been parsed and added to the mFwDriverList.
57 LIST_ENTRY mFvHandleList
= INITIALIZE_LIST_HEAD_VARIABLE (mFvHandleList
); // list of KNOWN_HANDLE
60 // Lock for mDiscoveredList, mScheduledQueue, gDispatcherRunning.
62 EFI_LOCK mDispatcherLock
= EFI_INITIALIZE_LOCK_VARIABLE (TPL_HIGH_LEVEL
);
66 // Flag for the DXE Dispacher. TRUE if dispatcher is execuing.
68 BOOLEAN gDispatcherRunning
= FALSE
;
71 // Module globals to manage the FwVol registration notification event
73 EFI_EVENT mFwVolEvent
;
74 VOID
*mFwVolEventRegistration
;
77 // List of file types supported by dispatcher
79 EFI_FV_FILETYPE mDxeFileTypes
[] = {
80 EFI_FV_FILETYPE_DRIVER
,
81 EFI_FV_FILETYPE_COMBINED_SMM_DXE
,
82 EFI_FV_FILETYPE_COMBINED_PEIM_DRIVER
,
83 EFI_FV_FILETYPE_DXE_CORE
,
84 EFI_FV_FILETYPE_FIRMWARE_VOLUME_IMAGE
88 MEDIA_FW_VOL_FILEPATH_DEVICE_PATH File
;
89 EFI_DEVICE_PATH_PROTOCOL End
;
90 } FV_FILEPATH_DEVICE_PATH
;
92 FV_FILEPATH_DEVICE_PATH mFvDevicePath
;
96 // Function Prototypes
99 Insert InsertedDriverEntry onto the mScheduledQueue. To do this you
100 must add any driver with a before dependency on InsertedDriverEntry first.
101 You do this by recursively calling this routine. After all the Befores are
102 processed you can add InsertedDriverEntry to the mScheduledQueue.
103 Then you can add any driver with an After dependency on InsertedDriverEntry
104 by recursively calling this routine.
106 @param InsertedDriverEntry The driver to insert on the ScheduledLink Queue
110 CoreInsertOnScheduledQueueWhileProcessingBeforeAndAfter (
111 IN EFI_CORE_DRIVER_ENTRY
*InsertedDriverEntry
115 Event notification that is fired every time a FV dispatch protocol is added.
116 More than one protocol may have been added when this event is fired, so you
117 must loop on CoreLocateHandle () to see how many protocols were added and
118 do the following to each FV:
119 If the Fv has already been processed, skip it. If the Fv has not been
120 processed then mark it as being processed, as we are about to process it.
121 Read the Fv and add any driver in the Fv to the mDiscoveredList.The
122 mDiscoveredList is never free'ed and contains variables that define
123 the other states the DXE driver transitions to..
124 While you are at it read the A Priori file into memory.
125 Place drivers in the A Priori list onto the mScheduledQueue.
127 @param Event The Event that is being processed, not used.
128 @param Context Event Context, not used.
133 CoreFwVolEventProtocolNotify (
139 Convert FvHandle and DriverName into an EFI device path
141 @param Fv Fv protocol, needed to read Depex info out of
143 @param FvHandle Handle for Fv, needed in the
144 EFI_CORE_DRIVER_ENTRY so that the PE image can be
145 read out of the FV at a later time.
146 @param DriverName Name of driver to add to mDiscoveredList.
148 @return Pointer to device path constructed from FvHandle and DriverName
151 EFI_DEVICE_PATH_PROTOCOL
*
153 IN EFI_FIRMWARE_VOLUME2_PROTOCOL
*Fv
,
154 IN EFI_HANDLE FvHandle
,
155 IN EFI_GUID
*DriverName
159 Add an entry to the mDiscoveredList. Allocate memory to store the DriverEntry,
160 and initilize any state variables. Read the Depex from the FV and store it
161 in DriverEntry. Pre-process the Depex to set the SOR, Before and After state.
162 The Discovered list is never free'ed and contains booleans that represent the
163 other possible DXE driver states.
165 @param Fv Fv protocol, needed to read Depex info out of
167 @param FvHandle Handle for Fv, needed in the
168 EFI_CORE_DRIVER_ENTRY so that the PE image can be
169 read out of the FV at a later time.
170 @param DriverName Name of driver to add to mDiscoveredList.
171 @param Type Fv File Type of file to add to mDiscoveredList.
173 @retval EFI_SUCCESS If driver was added to the mDiscoveredList.
174 @retval EFI_ALREADY_STARTED The driver has already been started. Only one
175 DriverName may be active in the system at any one
180 CoreAddToDriverList (
181 IN EFI_FIRMWARE_VOLUME2_PROTOCOL
*Fv
,
182 IN EFI_HANDLE FvHandle
,
183 IN EFI_GUID
*DriverName
,
184 IN EFI_FV_FILETYPE Type
188 Get the driver from the FV through driver name, and produce a FVB protocol on FvHandle.
190 @param Fv The FIRMWARE_VOLUME protocol installed on the FV.
191 @param FvHandle The handle which FVB protocol installed on.
192 @param DriverName The driver guid specified.
194 @retval EFI_OUT_OF_RESOURCES No enough memory or other resource.
195 @retval EFI_VOLUME_CORRUPTED Corrupted volume.
196 @retval EFI_SUCCESS Function successfully returned.
200 CoreProcessFvImageFile (
201 IN EFI_FIRMWARE_VOLUME2_PROTOCOL
*Fv
,
202 IN EFI_HANDLE FvHandle
,
203 IN EFI_GUID
*DriverName
208 Enter critical section by gaining lock on mDispatcherLock.
212 CoreAcquireDispatcherLock (
216 CoreAcquireLock (&mDispatcherLock
);
221 Exit critical section by releasing lock on mDispatcherLock.
225 CoreReleaseDispatcherLock (
229 CoreReleaseLock (&mDispatcherLock
);
234 Read Depex and pre-process the Depex for Before and After. If Section Extraction
235 protocol returns an error via ReadSection defer the reading of the Depex.
237 @param DriverEntry Driver to work on.
239 @retval EFI_SUCCESS Depex read and preprossesed
240 @retval EFI_PROTOCOL_ERROR The section extraction protocol returned an error
241 and Depex reading needs to be retried.
242 @retval Error DEPEX not found.
246 CoreGetDepexSectionAndPreProccess (
247 IN EFI_CORE_DRIVER_ENTRY
*DriverEntry
251 EFI_SECTION_TYPE SectionType
;
252 UINT32 AuthenticationStatus
;
253 EFI_FIRMWARE_VOLUME2_PROTOCOL
*Fv
;
256 Fv
= DriverEntry
->Fv
;
259 // Grab Depex info, it will never be free'ed.
261 SectionType
= EFI_SECTION_DXE_DEPEX
;
262 Status
= Fv
->ReadSection (
264 &DriverEntry
->FileName
,
268 (UINTN
*)&DriverEntry
->DepexSize
,
269 &AuthenticationStatus
271 if (EFI_ERROR (Status
)) {
272 if (Status
== EFI_PROTOCOL_ERROR
) {
274 // The section extraction protocol failed so set protocol error flag
276 DriverEntry
->DepexProtocolError
= TRUE
;
279 // If no Depex assume UEFI 2.0 driver model
281 DriverEntry
->Depex
= NULL
;
282 DriverEntry
->Dependent
= TRUE
;
283 DriverEntry
->DepexProtocolError
= FALSE
;
287 // Set Before, After, and Unrequested state information based on Depex
288 // Driver will be put in Dependent or Unrequested state
290 CorePreProcessDepex (DriverEntry
);
291 DriverEntry
->DepexProtocolError
= FALSE
;
299 Check every driver and locate a matching one. If the driver is found, the Unrequested
300 state flag is cleared.
302 @param FirmwareVolumeHandle The handle of the Firmware Volume that contains
303 the firmware file specified by DriverName.
304 @param DriverName The Driver name to put in the Dependent state.
306 @retval EFI_SUCCESS The DriverName was found and it's SOR bit was
308 @retval EFI_NOT_FOUND The DriverName does not exist or it's SOR bit was
315 IN EFI_HANDLE FirmwareVolumeHandle
,
316 IN EFI_GUID
*DriverName
320 EFI_CORE_DRIVER_ENTRY
*DriverEntry
;
323 // Check every driver
325 for (Link
= mDiscoveredList
.ForwardLink
; Link
!= &mDiscoveredList
; Link
= Link
->ForwardLink
) {
326 DriverEntry
= CR(Link
, EFI_CORE_DRIVER_ENTRY
, Link
, EFI_CORE_DRIVER_ENTRY_SIGNATURE
);
327 if (DriverEntry
->FvHandle
== FirmwareVolumeHandle
&&
328 DriverEntry
->Unrequested
&&
329 CompareGuid (DriverName
, &DriverEntry
->FileName
)) {
331 // Move the driver from the Unrequested to the Dependent state
333 CoreAcquireDispatcherLock ();
334 DriverEntry
->Unrequested
= FALSE
;
335 DriverEntry
->Dependent
= TRUE
;
336 CoreReleaseDispatcherLock ();
338 DEBUG ((DEBUG_DISPATCH
, "Schedule FFS(%g) - EFI_SUCCESS\n", DriverName
));
344 DEBUG ((DEBUG_DISPATCH
, "Schedule FFS(%g) - EFI_NOT_FOUND\n", DriverName
));
346 return EFI_NOT_FOUND
;
352 Convert a driver from the Untrused back to the Scheduled state.
354 @param FirmwareVolumeHandle The handle of the Firmware Volume that contains
355 the firmware file specified by DriverName.
356 @param DriverName The Driver name to put in the Scheduled state
358 @retval EFI_SUCCESS The file was found in the untrusted state, and it
359 was promoted to the trusted state.
360 @retval EFI_NOT_FOUND The file was not found in the untrusted state.
366 IN EFI_HANDLE FirmwareVolumeHandle
,
367 IN EFI_GUID
*DriverName
371 EFI_CORE_DRIVER_ENTRY
*DriverEntry
;
374 // Check every driver
376 for (Link
= mDiscoveredList
.ForwardLink
; Link
!= &mDiscoveredList
; Link
= Link
->ForwardLink
) {
377 DriverEntry
= CR(Link
, EFI_CORE_DRIVER_ENTRY
, Link
, EFI_CORE_DRIVER_ENTRY_SIGNATURE
);
378 if (DriverEntry
->FvHandle
== FirmwareVolumeHandle
&&
379 DriverEntry
->Untrusted
&&
380 CompareGuid (DriverName
, &DriverEntry
->FileName
)) {
382 // Transition driver from Untrusted to Scheduled state.
384 CoreAcquireDispatcherLock ();
385 DriverEntry
->Untrusted
= FALSE
;
386 DriverEntry
->Scheduled
= TRUE
;
387 InsertTailList (&mScheduledQueue
, &DriverEntry
->ScheduledLink
);
388 CoreReleaseDispatcherLock ();
393 return EFI_NOT_FOUND
;
398 An empty function to pass error checking of CreateEventEx ().
400 @param Event Event whose notification function is being invoked.
401 @param Context Pointer to the notification function's context,
402 which is implementation-dependent.
407 CoreEmptyCallbackFunction (
416 This is the main Dispatcher for DXE and it exits when there are no more
417 drivers to run. Drain the mScheduledQueue and load and start a PE
418 image for each driver. Search the mDiscoveredList to see if any driver can
419 be placed on the mScheduledQueue. If no drivers are placed on the
420 mScheduledQueue exit the function. On exit it is assumed the Bds()
421 will be called, and when the Bds() exits the Dispatcher will be called
424 @retval EFI_ALREADY_STARTED The DXE Dispatcher is already running
425 @retval EFI_NOT_FOUND No DXE Drivers were dispatched
426 @retval EFI_SUCCESS One or more DXE Drivers were dispatched
436 EFI_STATUS ReturnStatus
;
438 EFI_CORE_DRIVER_ENTRY
*DriverEntry
;
440 EFI_EVENT DxeDispatchEvent
;
443 if (gDispatcherRunning
) {
445 // If the dispatcher is running don't let it be restarted.
447 return EFI_ALREADY_STARTED
;
450 gDispatcherRunning
= TRUE
;
452 Status
= CoreCreateEventEx (
455 CoreEmptyCallbackFunction
,
457 &gEfiEventDxeDispatchGuid
,
460 if (EFI_ERROR (Status
)) {
464 ReturnStatus
= EFI_NOT_FOUND
;
467 // Drain the Scheduled Queue
469 while (!IsListEmpty (&mScheduledQueue
)) {
471 mScheduledQueue
.ForwardLink
,
472 EFI_CORE_DRIVER_ENTRY
,
474 EFI_CORE_DRIVER_ENTRY_SIGNATURE
478 // Load the DXE Driver image into memory. If the Driver was transitioned from
479 // Untrused to Scheduled it would have already been loaded so we may need to
480 // skip the LoadImage
482 if (DriverEntry
->ImageHandle
== NULL
&& !DriverEntry
->IsFvImage
) {
483 DEBUG ((DEBUG_INFO
, "Loading driver %g\n", &DriverEntry
->FileName
));
484 Status
= CoreLoadImage (
487 DriverEntry
->FvFileDevicePath
,
490 &DriverEntry
->ImageHandle
494 // Update the driver state to reflect that it's been loaded
496 if (EFI_ERROR (Status
)) {
497 CoreAcquireDispatcherLock ();
499 if (Status
== EFI_SECURITY_VIOLATION
) {
501 // Take driver from Scheduled to Untrused state
503 DriverEntry
->Untrusted
= TRUE
;
506 // The DXE Driver could not be loaded, and do not attempt to load or start it again.
507 // Take driver from Scheduled to Initialized.
509 // This case include the Never Trusted state if EFI_ACCESS_DENIED is returned
511 DriverEntry
->Initialized
= TRUE
;
514 DriverEntry
->Scheduled
= FALSE
;
515 RemoveEntryList (&DriverEntry
->ScheduledLink
);
517 CoreReleaseDispatcherLock ();
520 // If it's an error don't try the StartImage
526 CoreAcquireDispatcherLock ();
528 DriverEntry
->Scheduled
= FALSE
;
529 DriverEntry
->Initialized
= TRUE
;
530 RemoveEntryList (&DriverEntry
->ScheduledLink
);
532 CoreReleaseDispatcherLock ();
535 if (DriverEntry
->IsFvImage
) {
537 // Produce a firmware volume block protocol for FvImage so it gets dispatched from.
539 Status
= CoreProcessFvImageFile (DriverEntry
->Fv
, DriverEntry
->FvHandle
, &DriverEntry
->FileName
);
541 REPORT_STATUS_CODE_WITH_EXTENDED_DATA (
543 (EFI_SOFTWARE_DXE_CORE
| EFI_SW_PC_INIT_BEGIN
),
544 &DriverEntry
->ImageHandle
,
545 sizeof (DriverEntry
->ImageHandle
)
547 ASSERT (DriverEntry
->ImageHandle
!= NULL
);
549 Status
= CoreStartImage (DriverEntry
->ImageHandle
, NULL
, NULL
);
551 REPORT_STATUS_CODE_WITH_EXTENDED_DATA (
553 (EFI_SOFTWARE_DXE_CORE
| EFI_SW_PC_INIT_END
),
554 &DriverEntry
->ImageHandle
,
555 sizeof (DriverEntry
->ImageHandle
)
559 ReturnStatus
= EFI_SUCCESS
;
563 // Now DXE Dispatcher finished one round of dispatch, signal an event group
564 // so that SMM Dispatcher get chance to dispatch SMM Drivers which depend
567 if (!EFI_ERROR (ReturnStatus
)) {
568 CoreSignalEvent (DxeDispatchEvent
);
572 // Search DriverList for items to place on Scheduled Queue
575 for (Link
= mDiscoveredList
.ForwardLink
; Link
!= &mDiscoveredList
; Link
= Link
->ForwardLink
) {
576 DriverEntry
= CR (Link
, EFI_CORE_DRIVER_ENTRY
, Link
, EFI_CORE_DRIVER_ENTRY_SIGNATURE
);
578 if (DriverEntry
->DepexProtocolError
){
580 // If Section Extraction Protocol did not let the Depex be read before retry the read
582 Status
= CoreGetDepexSectionAndPreProccess (DriverEntry
);
585 if (DriverEntry
->Dependent
) {
586 if (CoreIsSchedulable (DriverEntry
)) {
587 CoreInsertOnScheduledQueueWhileProcessingBeforeAndAfter (DriverEntry
);
591 if (DriverEntry
->Unrequested
) {
592 DEBUG ((DEBUG_DISPATCH
, "Evaluate DXE DEPEX for FFS(%g)\n", &DriverEntry
->FileName
));
593 DEBUG ((DEBUG_DISPATCH
, " SOR = Not Requested\n"));
594 DEBUG ((DEBUG_DISPATCH
, " RESULT = FALSE\n"));
598 } while (ReadyToRun
);
601 // Close DXE dispatch Event
603 CoreCloseEvent (DxeDispatchEvent
);
605 gDispatcherRunning
= FALSE
;
612 Insert InsertedDriverEntry onto the mScheduledQueue. To do this you
613 must add any driver with a before dependency on InsertedDriverEntry first.
614 You do this by recursively calling this routine. After all the Befores are
615 processed you can add InsertedDriverEntry to the mScheduledQueue.
616 Then you can add any driver with an After dependency on InsertedDriverEntry
617 by recursively calling this routine.
619 @param InsertedDriverEntry The driver to insert on the ScheduledLink Queue
623 CoreInsertOnScheduledQueueWhileProcessingBeforeAndAfter (
624 IN EFI_CORE_DRIVER_ENTRY
*InsertedDriverEntry
628 EFI_CORE_DRIVER_ENTRY
*DriverEntry
;
631 // Process Before Dependency
633 for (Link
= mDiscoveredList
.ForwardLink
; Link
!= &mDiscoveredList
; Link
= Link
->ForwardLink
) {
634 DriverEntry
= CR(Link
, EFI_CORE_DRIVER_ENTRY
, Link
, EFI_CORE_DRIVER_ENTRY_SIGNATURE
);
635 if (DriverEntry
->Before
&& DriverEntry
->Dependent
&& DriverEntry
!= InsertedDriverEntry
) {
636 DEBUG ((DEBUG_DISPATCH
, "Evaluate DXE DEPEX for FFS(%g)\n", &DriverEntry
->FileName
));
637 DEBUG ((DEBUG_DISPATCH
, " BEFORE FFS(%g) = ", &DriverEntry
->BeforeAfterGuid
));
638 if (CompareGuid (&InsertedDriverEntry
->FileName
, &DriverEntry
->BeforeAfterGuid
)) {
640 // Recursively process BEFORE
642 DEBUG ((DEBUG_DISPATCH
, "TRUE\n END\n RESULT = TRUE\n"));
643 CoreInsertOnScheduledQueueWhileProcessingBeforeAndAfter (DriverEntry
);
645 DEBUG ((DEBUG_DISPATCH
, "FALSE\n END\n RESULT = FALSE\n"));
651 // Convert driver from Dependent to Scheduled state
653 CoreAcquireDispatcherLock ();
655 InsertedDriverEntry
->Dependent
= FALSE
;
656 InsertedDriverEntry
->Scheduled
= TRUE
;
657 InsertTailList (&mScheduledQueue
, &InsertedDriverEntry
->ScheduledLink
);
659 CoreReleaseDispatcherLock ();
662 // Process After Dependency
664 for (Link
= mDiscoveredList
.ForwardLink
; Link
!= &mDiscoveredList
; Link
= Link
->ForwardLink
) {
665 DriverEntry
= CR(Link
, EFI_CORE_DRIVER_ENTRY
, Link
, EFI_CORE_DRIVER_ENTRY_SIGNATURE
);
666 if (DriverEntry
->After
&& DriverEntry
->Dependent
&& DriverEntry
!= InsertedDriverEntry
) {
667 DEBUG ((DEBUG_DISPATCH
, "Evaluate DXE DEPEX for FFS(%g)\n", &DriverEntry
->FileName
));
668 DEBUG ((DEBUG_DISPATCH
, " AFTER FFS(%g) = ", &DriverEntry
->BeforeAfterGuid
));
669 if (CompareGuid (&InsertedDriverEntry
->FileName
, &DriverEntry
->BeforeAfterGuid
)) {
671 // Recursively process AFTER
673 DEBUG ((DEBUG_DISPATCH
, "TRUE\n END\n RESULT = TRUE\n"));
674 CoreInsertOnScheduledQueueWhileProcessingBeforeAndAfter (DriverEntry
);
676 DEBUG ((DEBUG_DISPATCH
, "FALSE\n END\n RESULT = FALSE\n"));
684 Return TRUE if the Fv has been processed, FALSE if not.
686 @param FvHandle The handle of a FV that's being tested
688 @retval TRUE Fv protocol on FvHandle has been processed
689 @retval FALSE Fv protocol on FvHandle has not yet been processed
694 IN EFI_HANDLE FvHandle
698 KNOWN_HANDLE
*KnownHandle
;
700 for (Link
= mFvHandleList
.ForwardLink
; Link
!= &mFvHandleList
; Link
= Link
->ForwardLink
) {
701 KnownHandle
= CR(Link
, KNOWN_HANDLE
, Link
, KNOWN_HANDLE_SIGNATURE
);
702 if (KnownHandle
->Handle
== FvHandle
) {
711 Remember that Fv protocol on FvHandle has had it's drivers placed on the
712 mDiscoveredList. This fucntion adds entries on the mFvHandleList if new
713 entry is different from one in mFvHandleList by checking FvImage Guid.
714 Items are never removed/freed from the mFvHandleList.
716 @param FvHandle The handle of a FV that has been processed
718 @return A point to new added FvHandle entry. If FvHandle with the same FvImage guid
719 has been added, NULL will return.
723 FvIsBeingProcesssed (
724 IN EFI_HANDLE FvHandle
729 BOOLEAN FvNameGuidIsFound
;
730 UINT32 ExtHeaderOffset
;
731 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*Fvb
;
732 EFI_FIRMWARE_VOLUME_HEADER
*FwVolHeader
;
733 EFI_FV_BLOCK_MAP_ENTRY
*BlockMap
;
738 KNOWN_HANDLE
*KnownHandle
;
741 // Get the FirmwareVolumeBlock protocol on that handle
743 FvNameGuidIsFound
= FALSE
;
744 Status
= CoreHandleProtocol (FvHandle
, &gEfiFirmwareVolumeBlockProtocolGuid
, (VOID
**)&Fvb
);
745 if (!EFI_ERROR (Status
)) {
747 // Get the full FV header based on FVB protocol.
749 ASSERT (Fvb
!= NULL
);
750 Status
= GetFwVolHeader (Fvb
, &FwVolHeader
);
751 if (!EFI_ERROR (Status
)) {
752 ASSERT (FwVolHeader
!= NULL
);
753 if (VerifyFvHeaderChecksum (FwVolHeader
) && FwVolHeader
->ExtHeaderOffset
!= 0) {
754 ExtHeaderOffset
= (UINT32
) FwVolHeader
->ExtHeaderOffset
;
755 BlockMap
= FwVolHeader
->BlockMap
;
759 // Find LbaIndex and LbaOffset for FV extension header based on BlockMap.
761 while ((BlockMap
->NumBlocks
!= 0) || (BlockMap
->Length
!= 0)) {
762 for (Index
= 0; Index
< BlockMap
->NumBlocks
&& ExtHeaderOffset
>= BlockMap
->Length
; Index
++) {
763 ExtHeaderOffset
-= BlockMap
->Length
;
767 // Check whether FvExtHeader is crossing the multi block range.
769 if (Index
< BlockMap
->NumBlocks
) {
770 LbaOffset
= ExtHeaderOffset
;
776 // Read FvNameGuid from FV extension header.
778 Status
= ReadFvbData (Fvb
, &LbaIndex
, &LbaOffset
, sizeof (FvNameGuid
), (UINT8
*) &FvNameGuid
);
779 if (!EFI_ERROR (Status
)) {
780 FvNameGuidIsFound
= TRUE
;
783 CoreFreePool (FwVolHeader
);
787 if (FvNameGuidIsFound
) {
789 // Check whether the FV image with the found FvNameGuid has been processed.
791 for (Link
= mFvHandleList
.ForwardLink
; Link
!= &mFvHandleList
; Link
= Link
->ForwardLink
) {
792 KnownHandle
= CR(Link
, KNOWN_HANDLE
, Link
, KNOWN_HANDLE_SIGNATURE
);
793 if (CompareGuid (&FvNameGuid
, &KnownHandle
->FvNameGuid
)) {
794 DEBUG ((EFI_D_ERROR
, "FvImage on FvHandle %p and %p has the same FvNameGuid %g.\n", FvHandle
, KnownHandle
->Handle
, FvNameGuid
));
800 KnownHandle
= AllocateZeroPool (sizeof (KNOWN_HANDLE
));
801 ASSERT (KnownHandle
!= NULL
);
803 KnownHandle
->Signature
= KNOWN_HANDLE_SIGNATURE
;
804 KnownHandle
->Handle
= FvHandle
;
805 if (FvNameGuidIsFound
) {
806 CopyGuid (&KnownHandle
->FvNameGuid
, &FvNameGuid
);
808 InsertTailList (&mFvHandleList
, &KnownHandle
->Link
);
816 Convert FvHandle and DriverName into an EFI device path
818 @param Fv Fv protocol, needed to read Depex info out of
820 @param FvHandle Handle for Fv, needed in the
821 EFI_CORE_DRIVER_ENTRY so that the PE image can be
822 read out of the FV at a later time.
823 @param DriverName Name of driver to add to mDiscoveredList.
825 @return Pointer to device path constructed from FvHandle and DriverName
828 EFI_DEVICE_PATH_PROTOCOL
*
830 IN EFI_FIRMWARE_VOLUME2_PROTOCOL
*Fv
,
831 IN EFI_HANDLE FvHandle
,
832 IN EFI_GUID
*DriverName
836 EFI_DEVICE_PATH_PROTOCOL
*FvDevicePath
;
837 EFI_DEVICE_PATH_PROTOCOL
*FileNameDevicePath
;
840 // Remember the device path of the FV
842 Status
= CoreHandleProtocol (FvHandle
, &gEfiDevicePathProtocolGuid
, (VOID
**)&FvDevicePath
);
843 if (EFI_ERROR (Status
)) {
844 FileNameDevicePath
= NULL
;
847 // Build a device path to the file in the FV to pass into gBS->LoadImage
849 EfiInitializeFwVolDevicepathNode (&mFvDevicePath
.File
, DriverName
);
850 SetDevicePathEndNode (&mFvDevicePath
.End
);
852 FileNameDevicePath
= AppendDevicePath (
854 (EFI_DEVICE_PATH_PROTOCOL
*)&mFvDevicePath
858 return FileNameDevicePath
;
864 Add an entry to the mDiscoveredList. Allocate memory to store the DriverEntry,
865 and initilize any state variables. Read the Depex from the FV and store it
866 in DriverEntry. Pre-process the Depex to set the SOR, Before and After state.
867 The Discovered list is never free'ed and contains booleans that represent the
868 other possible DXE driver states.
870 @param Fv Fv protocol, needed to read Depex info out of
872 @param FvHandle Handle for Fv, needed in the
873 EFI_CORE_DRIVER_ENTRY so that the PE image can be
874 read out of the FV at a later time.
875 @param DriverName Name of driver to add to mDiscoveredList.
876 @param Type Fv File Type of file to add to mDiscoveredList.
878 @retval EFI_SUCCESS If driver was added to the mDiscoveredList.
879 @retval EFI_ALREADY_STARTED The driver has already been started. Only one
880 DriverName may be active in the system at any one
885 CoreAddToDriverList (
886 IN EFI_FIRMWARE_VOLUME2_PROTOCOL
*Fv
,
887 IN EFI_HANDLE FvHandle
,
888 IN EFI_GUID
*DriverName
,
889 IN EFI_FV_FILETYPE Type
892 EFI_CORE_DRIVER_ENTRY
*DriverEntry
;
896 // Create the Driver Entry for the list. ZeroPool initializes lots of variables to
899 DriverEntry
= AllocateZeroPool (sizeof (EFI_CORE_DRIVER_ENTRY
));
900 ASSERT (DriverEntry
!= NULL
);
901 if (Type
== EFI_FV_FILETYPE_FIRMWARE_VOLUME_IMAGE
) {
902 DriverEntry
->IsFvImage
= TRUE
;
905 DriverEntry
->Signature
= EFI_CORE_DRIVER_ENTRY_SIGNATURE
;
906 CopyGuid (&DriverEntry
->FileName
, DriverName
);
907 DriverEntry
->FvHandle
= FvHandle
;
908 DriverEntry
->Fv
= Fv
;
909 DriverEntry
->FvFileDevicePath
= CoreFvToDevicePath (Fv
, FvHandle
, DriverName
);
911 CoreGetDepexSectionAndPreProccess (DriverEntry
);
913 CoreAcquireDispatcherLock ();
915 InsertTailList (&mDiscoveredList
, &DriverEntry
->Link
);
917 CoreReleaseDispatcherLock ();
924 Check if a FV Image type file (EFI_FV_FILETYPE_FIRMWARE_VOLUME_IMAGE) is
925 described by a EFI_HOB_FIRMWARE_VOLUME2 Hob.
927 @param FvNameGuid The FV image guid specified.
928 @param DriverName The driver guid specified.
930 @retval TRUE This file is found in a EFI_HOB_FIRMWARE_VOLUME2
932 @retval FALSE Not found.
937 IN CONST EFI_GUID
*FvNameGuid
,
938 IN CONST EFI_GUID
*DriverName
941 EFI_PEI_HOB_POINTERS HobFv2
;
943 HobFv2
.Raw
= GetHobList ();
945 while ((HobFv2
.Raw
= GetNextHob (EFI_HOB_TYPE_FV2
, HobFv2
.Raw
)) != NULL
) {
947 // Compare parent FvNameGuid and FileGuid both.
949 if (CompareGuid (DriverName
, &HobFv2
.FirmwareVolume2
->FileName
) &&
950 CompareGuid (FvNameGuid
, &HobFv2
.FirmwareVolume2
->FvName
)) {
953 HobFv2
.Raw
= GET_NEXT_HOB (HobFv2
);
962 Get the driver from the FV through driver name, and produce a FVB protocol on FvHandle.
964 @param Fv The FIRMWARE_VOLUME protocol installed on the FV.
965 @param FvHandle The handle which FVB protocol installed on.
966 @param DriverName The driver guid specified.
968 @retval EFI_OUT_OF_RESOURCES No enough memory or other resource.
969 @retval EFI_VOLUME_CORRUPTED Corrupted volume.
970 @retval EFI_SUCCESS Function successfully returned.
974 CoreProcessFvImageFile (
975 IN EFI_FIRMWARE_VOLUME2_PROTOCOL
*Fv
,
976 IN EFI_HANDLE FvHandle
,
977 IN EFI_GUID
*DriverName
981 EFI_SECTION_TYPE SectionType
;
982 UINT32 AuthenticationStatus
;
986 EFI_FIRMWARE_VOLUME_HEADER
*FvHeader
;
990 // Read the first (and only the first) firmware volume section
992 SectionType
= EFI_SECTION_FIRMWARE_VOLUME_IMAGE
;
997 AlignedBuffer
= NULL
;
998 Status
= Fv
->ReadSection (
1005 &AuthenticationStatus
1007 if (!EFI_ERROR (Status
)) {
1009 // FvImage should be at its required alignment.
1011 FvHeader
= (EFI_FIRMWARE_VOLUME_HEADER
*) Buffer
;
1013 // Get FvHeader alignment
1015 FvAlignment
= 1 << ((FvHeader
->Attributes
& EFI_FVB2_ALIGNMENT
) >> 16);
1017 // FvAlignment must be greater than or equal to 8 bytes of the minimum FFS alignment value.
1019 if (FvAlignment
< 8) {
1023 // Allocate the aligned buffer for the FvImage.
1025 AlignedBuffer
= AllocateAlignedPages (EFI_SIZE_TO_PAGES (BufferSize
), (UINTN
) FvAlignment
);
1026 if (AlignedBuffer
== NULL
) {
1027 Status
= EFI_OUT_OF_RESOURCES
;
1030 // Move FvImage into the aligned buffer and release the original buffer.
1032 CopyMem (AlignedBuffer
, Buffer
, BufferSize
);
1033 CoreFreePool (Buffer
);
1036 // Produce a FVB protocol for the file
1038 Status
= ProduceFVBProtocolOnBuffer (
1039 (EFI_PHYSICAL_ADDRESS
) (UINTN
) AlignedBuffer
,
1042 AuthenticationStatus
,
1048 if (EFI_ERROR (Status
)) {
1050 // ReadSection or Produce FVB failed, Free data buffer
1052 if (Buffer
!= NULL
) {
1056 if (AlignedBuffer
!= NULL
) {
1057 FreeAlignedPages (AlignedBuffer
, EFI_SIZE_TO_PAGES (BufferSize
));
1066 Event notification that is fired every time a FV dispatch protocol is added.
1067 More than one protocol may have been added when this event is fired, so you
1068 must loop on CoreLocateHandle () to see how many protocols were added and
1069 do the following to each FV:
1070 If the Fv has already been processed, skip it. If the Fv has not been
1071 processed then mark it as being processed, as we are about to process it.
1072 Read the Fv and add any driver in the Fv to the mDiscoveredList.The
1073 mDiscoveredList is never free'ed and contains variables that define
1074 the other states the DXE driver transitions to..
1075 While you are at it read the A Priori file into memory.
1076 Place drivers in the A Priori list onto the mScheduledQueue.
1078 @param Event The Event that is being processed, not used.
1079 @param Context Event Context, not used.
1084 CoreFwVolEventProtocolNotify (
1090 EFI_STATUS GetNextFileStatus
;
1091 EFI_STATUS SecurityStatus
;
1092 EFI_FIRMWARE_VOLUME2_PROTOCOL
*Fv
;
1093 EFI_DEVICE_PATH_PROTOCOL
*FvDevicePath
;
1094 EFI_HANDLE FvHandle
;
1098 EFI_FV_FILETYPE Type
;
1099 EFI_FV_FILE_ATTRIBUTES Attributes
;
1101 EFI_CORE_DRIVER_ENTRY
*DriverEntry
;
1102 EFI_GUID
*AprioriFile
;
1103 UINTN AprioriEntryCount
;
1106 UINT32 AuthenticationStatus
;
1109 KNOWN_HANDLE
*KnownHandle
;
1112 BufferSize
= sizeof (EFI_HANDLE
);
1113 Status
= CoreLocateHandle (
1116 mFwVolEventRegistration
,
1120 if (EFI_ERROR (Status
)) {
1122 // If no more notification events exit
1127 if (FvHasBeenProcessed (FvHandle
)) {
1129 // This Fv has already been processed so lets skip it!
1135 // Since we are about to process this Fv mark it as processed.
1137 KnownHandle
= FvIsBeingProcesssed (FvHandle
);
1138 if (KnownHandle
== NULL
) {
1140 // The FV with the same FV name guid has already been processed.
1146 Status
= CoreHandleProtocol (FvHandle
, &gEfiFirmwareVolume2ProtocolGuid
, (VOID
**)&Fv
);
1147 if (EFI_ERROR (Status
) || Fv
== NULL
) {
1149 // FvHandle must have Firmware Volume2 protocol thus we should never get here.
1155 Status
= CoreHandleProtocol (FvHandle
, &gEfiDevicePathProtocolGuid
, (VOID
**)&FvDevicePath
);
1156 if (EFI_ERROR (Status
)) {
1158 // The Firmware volume doesn't have device path, can't be dispatched.
1164 // Evaluate the authentication status of the Firmware Volume through
1165 // Security Architectural Protocol
1167 if (gSecurity
!= NULL
) {
1168 SecurityStatus
= gSecurity
->FileAuthenticationState (
1173 if (SecurityStatus
!= EFI_SUCCESS
) {
1175 // Security check failed. The firmware volume should not be used for any purpose.
1182 // Discover Drivers in FV and add them to the Discovered Driver List.
1183 // Process EFI_FV_FILETYPE_DRIVER type and then EFI_FV_FILETYPE_COMBINED_PEIM_DRIVER
1184 // EFI_FV_FILETYPE_DXE_CORE is processed to produce a Loaded Image protocol for the core
1185 // EFI_FV_FILETYPE_FIRMWARE_VOLUME_IMAGE is processed to create a Fvb
1187 for (Index
= 0; Index
< sizeof (mDxeFileTypes
) / sizeof (EFI_FV_FILETYPE
); Index
++) {
1189 // Initialize the search key
1193 Type
= mDxeFileTypes
[Index
];
1194 GetNextFileStatus
= Fv
->GetNextFile (
1202 if (!EFI_ERROR (GetNextFileStatus
)) {
1203 if (Type
== EFI_FV_FILETYPE_DXE_CORE
) {
1205 // If this is the DXE core fill in it's DevicePath & DeviceHandle
1207 if (gDxeCoreLoadedImage
->FilePath
== NULL
) {
1208 if (CompareGuid (&NameGuid
, gDxeCoreFileName
)) {
1210 // Maybe One specail Fv cantains only one DXE_CORE module, so its device path must
1211 // be initialized completely.
1213 EfiInitializeFwVolDevicepathNode (&mFvDevicePath
.File
, &NameGuid
);
1214 SetDevicePathEndNode (&mFvDevicePath
.End
);
1216 gDxeCoreLoadedImage
->FilePath
= DuplicateDevicePath (
1217 (EFI_DEVICE_PATH_PROTOCOL
*)&mFvDevicePath
1219 gDxeCoreLoadedImage
->DeviceHandle
= FvHandle
;
1222 } else if (Type
== EFI_FV_FILETYPE_FIRMWARE_VOLUME_IMAGE
) {
1224 // Check if this EFI_FV_FILETYPE_FIRMWARE_VOLUME_IMAGE file has already
1227 if (FvFoundInHobFv2 (&KnownHandle
->FvNameGuid
, &NameGuid
)) {
1232 // Check if this EFI_FV_FILETYPE_FIRMWARE_VOLUME_IMAGE file has PEI depex section.
1236 Status
= Fv
->ReadSection (
1239 EFI_SECTION_PEI_DEPEX
,
1243 &AuthenticationStatus
1245 if (!EFI_ERROR (Status
)) {
1247 // If PEI depex section is found, this FV image will be ignored in DXE phase.
1248 // Now, DxeCore doesn't support FV image with more one type DEPEX section.
1250 FreePool (DepexBuffer
);
1255 // Check if this EFI_FV_FILETYPE_FIRMWARE_VOLUME_IMAGE file has SMM depex section.
1259 Status
= Fv
->ReadSection (
1262 EFI_SECTION_SMM_DEPEX
,
1266 &AuthenticationStatus
1268 if (!EFI_ERROR (Status
)) {
1270 // If SMM depex section is found, this FV image will be ignored in DXE phase.
1271 // Now, DxeCore doesn't support FV image with more one type DEPEX section.
1273 FreePool (DepexBuffer
);
1278 // Check if this EFI_FV_FILETYPE_FIRMWARE_VOLUME_IMAGE file has DXE depex section.
1282 Status
= Fv
->ReadSection (
1285 EFI_SECTION_DXE_DEPEX
,
1289 &AuthenticationStatus
1291 if (EFI_ERROR (Status
)) {
1293 // If no depex section, produce a firmware volume block protocol for it so it gets dispatched from.
1295 CoreProcessFvImageFile (Fv
, FvHandle
, &NameGuid
);
1298 // If depex section is found, this FV image will be dispatched until its depex is evaluated to TRUE.
1300 FreePool (DepexBuffer
);
1301 CoreAddToDriverList (Fv
, FvHandle
, &NameGuid
, Type
);
1305 // Transition driver from Undiscovered to Discovered state
1307 CoreAddToDriverList (Fv
, FvHandle
, &NameGuid
, Type
);
1310 } while (!EFI_ERROR (GetNextFileStatus
));
1314 // Read the array of GUIDs from the Apriori file if it is present in the firmware volume
1317 Status
= Fv
->ReadSection (
1322 (VOID
**)&AprioriFile
,
1324 &AuthenticationStatus
1326 if (!EFI_ERROR (Status
)) {
1327 AprioriEntryCount
= SizeOfBuffer
/ sizeof (EFI_GUID
);
1329 AprioriEntryCount
= 0;
1333 // Put drivers on Apriori List on the Scheduled queue. The Discovered List includes
1334 // drivers not in the current FV and these must be skipped since the a priori list
1335 // is only valid for the FV that it resided in.
1338 for (Index
= 0; Index
< AprioriEntryCount
; Index
++) {
1339 for (Link
= mDiscoveredList
.ForwardLink
; Link
!= &mDiscoveredList
; Link
= Link
->ForwardLink
) {
1340 DriverEntry
= CR(Link
, EFI_CORE_DRIVER_ENTRY
, Link
, EFI_CORE_DRIVER_ENTRY_SIGNATURE
);
1341 if (CompareGuid (&DriverEntry
->FileName
, &AprioriFile
[Index
]) &&
1342 (FvHandle
== DriverEntry
->FvHandle
)) {
1343 CoreAcquireDispatcherLock ();
1344 DriverEntry
->Dependent
= FALSE
;
1345 DriverEntry
->Scheduled
= TRUE
;
1346 InsertTailList (&mScheduledQueue
, &DriverEntry
->ScheduledLink
);
1347 CoreReleaseDispatcherLock ();
1348 DEBUG ((DEBUG_DISPATCH
, "Evaluate DXE DEPEX for FFS(%g)\n", &DriverEntry
->FileName
));
1349 DEBUG ((DEBUG_DISPATCH
, " RESULT = TRUE (Apriori)\n"));
1356 // Free data allocated by Fv->ReadSection ()
1358 CoreFreePool (AprioriFile
);
1365 Initialize the dispatcher. Initialize the notification function that runs when
1366 an FV2 protocol is added to the system.
1370 CoreInitializeDispatcher (
1374 mFwVolEvent
= EfiCreateProtocolNotifyEvent (
1375 &gEfiFirmwareVolume2ProtocolGuid
,
1377 CoreFwVolEventProtocolNotify
,
1379 &mFwVolEventRegistration
1384 // Function only used in debug builds
1388 Traverse the discovered list for any drivers that were discovered but not loaded
1389 because the dependency experessions evaluated to false.
1393 CoreDisplayDiscoveredNotDispatched (
1398 EFI_CORE_DRIVER_ENTRY
*DriverEntry
;
1400 for (Link
= mDiscoveredList
.ForwardLink
;Link
!=&mDiscoveredList
; Link
= Link
->ForwardLink
) {
1401 DriverEntry
= CR(Link
, EFI_CORE_DRIVER_ENTRY
, Link
, EFI_CORE_DRIVER_ENTRY_SIGNATURE
);
1402 if (DriverEntry
->Dependent
) {
1403 DEBUG ((DEBUG_LOAD
, "Driver %g was discovered but not loaded!!\n", &DriverEntry
->FileName
));