/** @file
Copyright (c) 2007 - 2008, Intel Corporation. All rights reserved.<BR>
This program and the accompanying materials
are licensed and made available under the terms and conditions of the BSD License
which accompanies this distribution. The full text of the license may be found at
http://opensource.org/licenses/bsd-license.php
THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
Module Name:
Dpc.c
Abstract:
**/
#include "Dpc.h"
//
// Handle for the EFI_DPC_PROTOCOL instance
//
EFI_HANDLE mDpcHandle = NULL;
//
// The EFI_DPC_PROTOCOL instances that is installed onto mDpcHandle
//
EFI_DPC_PROTOCOL mDpc = {
DpcQueueDpc,
DpcDispatchDpc
};
//
// Global variables used to meaasure the DPC Queue Depths
//
UINTN mDpcQueueDepth = 0;
UINTN mMaxDpcQueueDepth = 0;
//
// Free list of DPC entries. As DPCs are queued, entries are removed from this
// free list. As DPC entries are dispatched, DPC entries are added to the free list.
// If the free list is empty and a DPC is queued, the free list is grown by allocating
// an additional set of DPC entries.
//
LIST_ENTRY mDpcEntryFreeList = INITIALIZE_LIST_HEAD_VARIABLE(mDpcEntryFreeList);
//
// An array of DPC queues. A DPC queue is allocated for every leval EFI_TPL value.
// As DPCs are queued, they are added to the end of the linked list.
// As DPCs are dispatched, they are removed from the beginning of the linked list.
//
LIST_ENTRY mDpcQueue[TPL_HIGH_LEVEL + 1];
/**
Add a Deferred Procedure Call to the end of the DPC queue.
@param This Protocol instance pointer.
@param DpcTpl The EFI_TPL that the DPC should be invoked.
@param DpcProcedure Pointer to the DPC's function.
@param DpcContext Pointer to the DPC's context. Passed to DpcProcedure
when DpcProcedure is invoked.
@retval EFI_SUCCESS The DPC was queued.
@retval EFI_INVALID_PARAMETER DpcTpl is not a valid EFI_TPL.
@retval EFI_INVALID_PARAMETER DpcProcedure is NULL.
@retval EFI_OUT_OF_RESOURCES There are not enough resources available to
add the DPC to the queue.
**/
EFI_STATUS
EFIAPI
DpcQueueDpc (
IN EFI_DPC_PROTOCOL *This,
IN EFI_TPL DpcTpl,
IN EFI_DPC_PROCEDURE DpcProcedure,
IN VOID *DpcContext OPTIONAL
)
{
EFI_STATUS ReturnStatus;
EFI_TPL OriginalTpl;
DPC_ENTRY *DpcEntry;
UINTN Index;
//
// Make sure DpcTpl is valid
//
if (DpcTpl < TPL_APPLICATION || DpcTpl > TPL_HIGH_LEVEL) {
return EFI_INVALID_PARAMETER;
}
//
// Make sure DpcProcedure is valid
//
if (DpcProcedure == NULL) {
return EFI_INVALID_PARAMETER;
}
//
// Assume this function will succeed
//
ReturnStatus = EFI_SUCCESS;
//
// Raise the TPL level to TPL_HIGH_LEVEL for DPC list operation and save the
// current TPL value so it can be restored when this function returns.
//
OriginalTpl = gBS->RaiseTPL (TPL_HIGH_LEVEL);
//
// Check to see if there are any entries in the DPC free list
//
if (IsListEmpty (&mDpcEntryFreeList)) {
//
// If the current TPL is greater than TPL_NOTIFY, then memory allocations
// can not be performed, so the free list can not be expanded. In this case
// return EFI_OUT_OF_RESOURCES.
//
if (OriginalTpl > TPL_NOTIFY) {
ReturnStatus = EFI_OUT_OF_RESOURCES;
goto Done;
}
//
// Add 64 DPC entries to the free list
//
for (Index = 0; Index < 64; Index++) {
//
// Lower the TPL level to perform a memory allocation
//
gBS->RestoreTPL (OriginalTpl);
//
// Allocate a new DPC entry
//
DpcEntry = AllocatePool (sizeof (DPC_ENTRY));
//
// Raise the TPL level back to TPL_HIGH_LEVEL for DPC list operations
//
gBS->RaiseTPL (TPL_HIGH_LEVEL);
//
// If the allocation of a DPC entry fails, and the free list is empty,
// then return EFI_OUT_OF_RESOURCES.
//
if (DpcEntry == NULL) {
if (IsListEmpty (&mDpcEntryFreeList)) {
ReturnStatus = EFI_OUT_OF_RESOURCES;
goto Done;
}
}
//
// Add the newly allocated DPC entry to the DPC free list
//
InsertTailList (&mDpcEntryFreeList, &DpcEntry->ListEntry);
}
}
//
// Retrieve the first node from the free list of DPCs
//
DpcEntry = (DPC_ENTRY *)(GetFirstNode (&mDpcEntryFreeList));
//
// Remove the first node from the free list of DPCs
//
RemoveEntryList (&DpcEntry->ListEntry);
//
// Fill in the DPC entry with the DpcProcedure and DpcContext
//
DpcEntry->DpcProcedure = DpcProcedure;
DpcEntry->DpcContext = DpcContext;
//
// Add the DPC entry to the end of the list for the specified DplTpl.
//
InsertTailList (&mDpcQueue[DpcTpl], &DpcEntry->ListEntry);
//
// Increment the measured DPC queue depth across all TPLs
//
mDpcQueueDepth++;
//
// Measure the maximum DPC queue depth across all TPLs
//
if (mDpcQueueDepth > mMaxDpcQueueDepth) {
mMaxDpcQueueDepth = mDpcQueueDepth;
}
Done:
//
// Restore the original TPL level when this function was called
//
gBS->RestoreTPL (OriginalTpl);
return ReturnStatus;
}
/**
Dispatch the queue of DPCs. ALL DPCs that have been queued with a DpcTpl
value greater than or equal to the current TPL are invoked in the order that
they were queued. DPCs with higher DpcTpl values are invoked before DPCs with
lower DpcTpl values.
@param This Protocol instance pointer.
@retval EFI_SUCCESS One or more DPCs were invoked.
@retval EFI_NOT_FOUND No DPCs were invoked.
**/
EFI_STATUS
EFIAPI
DpcDispatchDpc (
IN EFI_DPC_PROTOCOL *This
)
{
EFI_STATUS ReturnStatus;
EFI_TPL OriginalTpl;
EFI_TPL Tpl;
DPC_ENTRY *DpcEntry;
//
// Assume that no DPCs will be invoked
//
ReturnStatus = EFI_NOT_FOUND;
//
// Raise the TPL level to TPL_HIGH_LEVEL for DPC list operation and save the
// current TPL value so it can be restored when this function returns.
//
OriginalTpl = gBS->RaiseTPL (TPL_HIGH_LEVEL);
//
// Check to see if there are 1 or more DPCs currently queued
//
if (mDpcQueueDepth > 0) {
//
// Loop from TPL_HIGH_LEVEL down to the current TPL value
//
for (Tpl = TPL_HIGH_LEVEL; Tpl >= OriginalTpl; Tpl--) {
//
// Check to see if the DPC queue is empty
//
while (!IsListEmpty (&mDpcQueue[Tpl])) {
//
// Retrieve the first DPC entry from the DPC queue specified by Tpl
//
DpcEntry = (DPC_ENTRY *)(GetFirstNode (&mDpcQueue[Tpl]));
//
// Remove the first DPC entry from the DPC queue specified by Tpl
//
RemoveEntryList (&DpcEntry->ListEntry);
//
// Decrement the measured DPC Queue Depth across all TPLs
//
mDpcQueueDepth--;
//
// Lower the TPL to TPL value of the current DPC queue
//
gBS->RestoreTPL (Tpl);
//
// Invoke the DPC passing in its context
//
(DpcEntry->DpcProcedure) (DpcEntry->DpcContext);
//
// At least one DPC has been invoked, so set the return status to EFI_SUCCESS
//
ReturnStatus = EFI_SUCCESS;
//
// Raise the TPL level back to TPL_HIGH_LEVEL for DPC list operations
//
gBS->RaiseTPL (TPL_HIGH_LEVEL);
//
// Add the invoked DPC entry to the DPC free list
//
InsertTailList (&mDpcEntryFreeList, &DpcEntry->ListEntry);
}
}
}
//
// Restore the original TPL level when this function was called
//
gBS->RestoreTPL (OriginalTpl);
return ReturnStatus;
}
/**
The entry point for DPC driver which installs the EFI_DPC_PROTOCOL onto a new handle.
@param ImageHandle The image handle of the driver.
@param SystemTable The system table.
@retval EFI_SUCCES The DPC queues were initialized and the EFI_DPC_PROTOCOL was
installed onto a new handle.
@retval Others Failed to install EFI_DPC_PROTOCOL.
**/
EFI_STATUS
EFIAPI
DpcDriverEntryPoint (
IN EFI_HANDLE ImageHandle,
IN EFI_SYSTEM_TABLE *SystemTable
)
{
EFI_STATUS Status;
UINTN Index;
//
// ASSERT() if the EFI_DPC_PROTOCOL is already present in the handle database
//
ASSERT_PROTOCOL_ALREADY_INSTALLED (NULL, &gEfiDpcProtocolGuid);
//
// Initialize the DPC queue for all possible TPL values
//
for (Index = 0; Index <= TPL_HIGH_LEVEL; Index++) {
InitializeListHead (&mDpcQueue[Index]);
}
//
// Install the EFI_DPC_PROTOCOL instance onto a new handle
//
Status = gBS->InstallMultipleProtocolInterfaces (
&mDpcHandle,
&gEfiDpcProtocolGuid,
&mDpc,
NULL
);
ASSERT_EFI_ERROR (Status);
return Status;
}