FxDpc Class Reference

#include <fxdpc.hpp>

Inheritance diagram for FxDpc:

Collaboration diagram for FxDpc:

Public Member Functions
	FxDpc (__in PFX_DRIVER_GLOBALS FxDriverGlobals)
virtual	~FxDpc (VOID)
KDPC *	GetDpcPtr (VOID)
WDFOBJECT	GetObject (VOID)
_Must_inspect_result_ NTSTATUS	Initialize (__in PWDF_OBJECT_ATTRIBUTES Attributes, __in PWDF_DPC_CONFIG Config, __in FxObject *ParentObject, __out WDFDPC *Dpc)
virtual BOOLEAN	Dispose (VOID)
BOOLEAN	Cancel (__in BOOLEAN Wait)
VOID	DpcHandler (__in PKDPC Dpc, __in PVOID SystemArgument1, __in PVOID SystemArgument2)
Public Member Functions inherited from FxNonPagedObject
	FxNonPagedObject (__in WDFTYPE Type, __in USHORT Size, __in PFX_DRIVER_GLOBALS FxDriverGlobals)
	FxNonPagedObject (__in WDFTYPE Type, __in USHORT Size, __in PFX_DRIVER_GLOBALS FxDriverGlobals, __in FxObjectType ObjectType)
virtual	~FxNonPagedObject (VOID)
	_Acquires_lock_ (this->m_NPLock.m_Lock) __drv_maxIRQL(DISPATCH_LEVEL) __drv_setsIRQL(DISPATCH_LEVEL) VOID Lock(__out __drv_deref(__drv_savesIRQL) PKIRQL PreviousIrql)
	_Releases_lock_ (this->m_NPLock.m_Lock) __drv_requiresIRQL(DISPATCH_LEVEL) __inline VOID Unlock(__in __drv_restoresIRQL KIRQL PreviousIrql)
	_Acquires_lock_ (this->m_NPLock.m_Lock) __drv_requiresIRQL(DISPATCH_LEVEL) VOID LockAtDispatch(VOID)
	_Requires_lock_held_ (this->m_NPLock.m_Lock) _Releases_lock_(this -> m_NPLock.m_Lock) __drv_requiresIRQL(DISPATCH_LEVEL) __inline VOID UnlockFromDispatch(VOID)
Public Member Functions inherited from FxObject
PVOID	GetCOMWrapper ()
void	SetCOMWrapper (__drv_aliasesMem PVOID Wrapper)
	FxObject (__in WDFTYPE Type, __in USHORT Size, __in PFX_DRIVER_GLOBALS FxDriverGlobals)
virtual	~FxObject (VOID)
PVOID __inline	operator new (__in size_t Size, __in PFX_DRIVER_GLOBALS FxDriverGlobals, __in FxObjectType Type)
PVOID __inline	operator new (__in size_t Size, __in PFX_DRIVER_GLOBALS FxDriverGlobals, __in_opt PWDF_OBJECT_ATTRIBUTES Attributes, __in USHORT ExtraSize=0)
VOID	operator delete (__in PVOID Memory)
VOID	SetNoContextHeader (VOID)
PVOID __inline	GetObjectHandle (VOID)
__inline FxContextHeader *	GetContextHeader (VOID)
__inline PFX_DRIVER_GLOBALS	GetDriverGlobals (VOID)
WDFTYPE	GetType (VOID)
USHORT	GetObjectSize (VOID)
LONG	GetRefCnt (VOID)
FxTagTracker *	GetTagTracker (VOID)
CfxDevice *	GetDevice (VOID)
CfxDeviceBase *	GetDeviceBase (VOID)
VOID	SetDeviceBase (__in CfxDeviceBase *DeviceBase)
__inline VOID	CallCleanup (VOID)
ULONG __inline	AddRef (__in_opt PVOID Tag=NULL, __in LONG Line=0, __in_opt PSTR File=NULL)
virtual ULONG	Release (__in_opt PVOID Tag=NULL, __in LONG Line=0, __in_opt PSTR File=NULL)
virtual ULONG	AddRefOverride (__in WDFOBJECT_OFFSET Offset, __in_opt PVOID Tag=NULL, __in LONG Line=0, __in_opt PSTR File=NULL)
virtual ULONG	ReleaseOverride (__in WDFOBJECT_OFFSET Offset, __in_opt PVOID Tag=NULL, __in LONG Line=0, __in_opt PSTR File=NULL)
virtual _Must_inspect_result_ NTSTATUS	QueryInterface (__in FxQueryInterfaceParams *Params)
VOID	MarkTraceState (VOID)
BOOLEAN __inline	IsTraceState (VOID)
VOID __inline	TraceDroppedEvent (__in FxObjectDroppedEvent Event)
VOID	MarkPassiveDispose (__in FxObjectLockState State=ObjectLock)
VOID	MarkPassiveCallbacks (__in FxObjectLockState State=ObjectLock)
VOID	MarkForceDisposeThread (__in FxObjectLockState State=ObjectLock)
BOOLEAN	IsPassiveCallbacks (__in BOOLEAN AcquireLock=TRUE)
BOOLEAN	IsPassiveDispose (__in BOOLEAN AcquireLock=TRUE)
BOOLEAN	IsForceDisposeThread (__in BOOLEAN AcquireLock=TRUE)
VOID	MarkCommitted (VOID)
BOOLEAN	IsCommitted (VOID)
VOID	MarkDisposeOverride (__in FxObjectLockState State=ObjectLock)
VOID	MarkNoDeleteDDI (__in FxObjectLockState State=ObjectLock)
BOOLEAN	IsNoDeleteDDI (VOID)
_Must_inspect_result_ NTSTATUS	Commit (__in_opt PWDF_OBJECT_ATTRIBUTES Attributes, __out_opt WDFOBJECT *ObjectHandle, __in_opt FxObject *Parent=NULL, __in BOOLEAN AssignDriverAsDefaultParent=TRUE)
VOID	DeleteFromFailedCreate (VOID)
VOID	ClearEvtCallbacks (VOID)
BOOLEAN	EarlyDispose (VOID)
virtual VOID	DeleteObject (VOID)
virtual BOOLEAN	Dispose (VOID)
_Must_inspect_result_ NTSTATUS	AssignParentObject (__in FxObject *ParentObject)
_Must_inspect_result_ NTSTATUS	AddContext (__in FxContextHeader *Header, __in PVOID *Context, __in PWDF_OBJECT_ATTRIBUTES Attributes)
_Must_inspect_result_ NTSTATUS	RemoveParentAssignment (VOID)
_Must_inspect_result_ FxObject *	GetParentObjectReferenced (__in PVOID Tag)
BOOLEAN	IsDisposed (VOID)

Static Public Member Functions
static _Must_inspect_result_ NTSTATUS	_Create (__in PFX_DRIVER_GLOBALS FxDriverGlobals, __in PWDF_DPC_CONFIG Config, __in PWDF_OBJECT_ATTRIBUTES Attributes, __in FxObject *ParentObject, __out WDFDPC *Dpc)
Static Public Member Functions inherited from FxObject
static FxObject *	_FromDisposeEntry (__in PSINGLE_LIST_ENTRY Entry)
static FxObject *	_GetObjectFromHandle (__in WDFOBJECT Handle, __inout PWDFOBJECT_OFFSET ObjectOffset)
static PVOID __inline	_ToHandle (__in FxObject *Object)
static VOID __inline	_ReferenceActual (__in WDFOBJECT Object, __in_opt PVOID Tag, __in LONG Line, __in PSTR File)
static VOID __inline	_DereferenceActual (__in WDFOBJECT Object, __in_opt PVOID Tag, __in LONG Line, __in PSTR File)
static PVOID	_GetDebugBase (__in FxObject *Object)
static PFX_POOL_HEADER	_CleanupPointer (__in PFX_DRIVER_GLOBALS FxDriverGlobals, __in FxObject *Object)
static _Must_inspect_result_ NTSTATUS	_GetEffectiveLock (__in FxObject *Object, __in_opt IFxHasCallbacks *Callbacks, __in BOOLEAN AutomaticLocking, __in BOOLEAN PassiveCallbacks, __out FxCallbackLock **CallbackLock, __out_opt FxObject **CallbackLockObject)
static _Must_inspect_result_ NTSTATUS	_ObjectQuery (_In_ FxObject *Object, _In_ CONST GUID *Guid, _In_ ULONG QueryBufferLength, _Out_writes_bytes_(QueryBufferLength) PVOID QueryBuffer)

Private Member Functions
VOID	FlushAndRundown ()

Static Private Member Functions
static VOID	WorkItemThunk (PDEVICE_OBJECT DeviceObject, PVOID Context)

Private Attributes
KDPC	m_Dpc
FxObject *	m_Object
FxCallbackLock *	m_CallbackLock
FxObject *	m_CallbackLockObject
PFN_WDF_DPC	m_Callback
BOOLEAN	m_RunningDown

Static Private Attributes
static KDEFERRED_ROUTINE	FxDpcThunk

Additional Inherited Members
Protected Member Functions inherited from FxObject
	FxObject (__in WDFTYPE Type, __in USHORT Size, __in PFX_DRIVER_GLOBALS FxDriverGlobals, __in FxObjectType ObjectType)
FxObjectDebugExtension *	GetDebugExtension (VOID)
BOOLEAN	IsDebug (VOID)
VOID	AllocateTagTracker (__in WDFTYPE Type)
virtual VOID	SelfDestruct (VOID)
PVOID __inline	GetObjectHandleUnchecked (VOID)
VOID __inline	DestroyChildren (VOID)
VOID	DeleteEarlyDisposedObject (VOID)
Static Protected Member Functions inherited from FxObject
static PVOID	_GetBase (__in FxObject *Object)
Protected Attributes inherited from FxObject
union {
CfxDeviceBase *   m_DeviceBase
CfxDevice *   m_Device
};

Detailed Description

Definition at line 63 of file fxdpc.hpp.

Constructor & Destructor Documentation

FxDpc()

FxDpc::FxDpc

(

__in PFX_DRIVER_GLOBALS

FxDriverGlobals

)

Definition at line 40 of file fxdpc.cpp.

      :
    FxNonPagedObject(FX_TYPE_DPC, sizeof(FxDpc), FxDriverGlobals)
{
   m_Object = NULL;
   m_CallbackLock = NULL;
   m_CallbackLockObject = NULL;
   m_Callback = NULL;
   m_RunningDown = FALSE;
 
   //
   // Mark the object has having passive level dispose so that KeFlushQueuedDpcs
   // can be called in Dispose().
   //
   MarkPassiveDispose(ObjectDoNotLock);
 
   MarkDisposeOverride(ObjectDoNotLock);
}

~FxDpc()

FxDpc::~FxDpc ( VOID  )

virtual

Definition at line 61 of file fxdpc.cpp.

{
    //
    // If this hits, its because someone destroyed the DPC by
    // removing too many references by mistake without calling WdfObjectDelete
    //
    if (m_Object != NULL) {
        DoTraceLevelMessage(
            GetDriverGlobals(), TRACE_LEVEL_ERROR, TRACINGDEVICE,
            "Destroy WDFDPC %p destroyed without calling WdfObjectDelete, or by"
            " Framework processing DeviceRemove.  Possible reference count "
            "problem?", GetObjectHandleUnchecked());
        FxVerifierDbgBreakPoint(GetDriverGlobals());
    }
}

Member Function Documentation

_Create()

_Must_inspect_result_ NTSTATUS FxDpc::_Create ( __in PFX_DRIVER_GLOBALS  FxDriverGlobals, __in PWDF_DPC_CONFIG  Config, __in PWDF_OBJECT_ATTRIBUTES  Attributes, __in FxObject *  ParentObject, __out WDFDPC *  Dpc  )

static

Definition at line 79 of file fxdpc.cpp.

{
    FxDpc* pFxDpc;
    NTSTATUS status;
 
    pFxDpc = new(FxDriverGlobals, Attributes) FxDpc(FxDriverGlobals);
 
    if (pFxDpc == NULL) {
        return STATUS_INSUFFICIENT_RESOURCES;
    }
 
    status = pFxDpc->Initialize(
        Attributes,
        Config,
        ParentObject,
        Dpc
        );
 
    if (!NT_SUCCESS(status)) {
        pFxDpc->DeleteFromFailedCreate();
    }
 
    return status;
}

Cancel()

BOOLEAN FxDpc::Cancel

(

__in BOOLEAN

Wait

)

Definition at line 261 of file fxdpc.cpp.

{
    BOOLEAN result;
 
    result = KeRemoveQueueDpc(GetDpcPtr());
 
    //
    // If result == FALSE, then the DPC could already be running.
    //
    // If the caller supplies Wait == TRUE, they want to wait and
    // ensure on return the DPC has finished running.
    //
    // The trick here is to implement this without adding execessive
    // overhead to the "normal" path, such as tracking reference counts,
    // locking, signaling events to waiting threads, etc.
    //
    // So we take the expensive approach for the Cancel call in the
    // case the caller wants to wait, and misses the DPC window. In
    // this case we will just do the system wide FlushQueuedDpc's to
    // ensure the DPC has finished running before return.
    //
    if( Wait && !result ) {
 
        ASSERT(KeGetCurrentIrql() == PASSIVE_LEVEL);
 
        KeFlushQueuedDpcs();
    }
 
    return result;
}

Dispose()

BOOLEAN FxDpc::Dispose ( VOID  )

virtual

Reimplemented from FxObject.

Definition at line 371 of file fxdpc.cpp.

{
    // MarkPassiveDispose() in Initialize ensures this
    ASSERT(KeGetCurrentIrql() == PASSIVE_LEVEL);
 
    m_RunningDown = TRUE;
 
    FlushAndRundown();
 
    return TRUE;
}

DpcHandler()

VOID FxDpc::DpcHandler	(	__in PKDPC	Dpc,
		__in PVOID	SystemArgument1,
		__in PVOID	SystemArgument2
	)

Definition at line 295 of file fxdpc.cpp.

{
    UNREFERENCED_PARAMETER(Dpc);
    UNREFERENCED_PARAMETER(SystemArgument1);
    UNREFERENCED_PARAMETER(SystemArgument2);
 
    FX_TRACK_DRIVER(GetDriverGlobals());
 
    if (m_Callback != NULL) {
 
        FxPerfTraceDpc(&m_Callback);
 
        if (m_CallbackLock != NULL) {
            KIRQL irql = 0;
 
            m_CallbackLock->Lock(&irql);
            m_Callback((WDFDPC)(this->GetObjectHandle()));
            m_CallbackLock->Unlock(irql);
        }
        else {
           m_Callback((WDFDPC)(this->GetObjectHandle()));
        }
    }
}

FlushAndRundown()

VOID FxDpc::FlushAndRundown ( )

private

Definition at line 387 of file fxdpc.cpp.

{
    FxObject* pObject;
 
    //
    // If we have the KeFlushQueuedDpcs function call it
    // to ensure the DPC routine is no longer running before
    // we release the final reference and memory to the framework objects
    //
    KeFlushQueuedDpcs();
 
    //
    // Release our reference count to the associated parent object if present
    //
    if (m_Object != NULL) {
        pObject = m_Object;
        m_Object = NULL;
 
        pObject->RELEASE(this);
    }
 
    //
    // Perform our final release to ourselves, destroying the FxDpc
    //
    RELEASE(this);
}

Referenced by Dispose().

GetDpcPtr()

KDPC * FxDpc::GetDpcPtr ( VOID  )

inline

Definition at line 117 of file fxdpc.hpp.

    {
         return &m_Dpc;
    }

GetObject()

WDFOBJECT FxDpc::GetObject ( VOID  )

inline

Definition at line 125 of file fxdpc.hpp.

    {
        if (m_Object != NULL) {
            return m_Object->GetObjectHandle();
        }
        else {
            return NULL;
        }
    }

Initialize()

_Must_inspect_result_ NTSTATUS FxDpc::Initialize	(	__in PWDF_OBJECT_ATTRIBUTES	Attributes,
		__in PWDF_DPC_CONFIG	Config,
		__in FxObject *	ParentObject,
		__out WDFDPC *	Dpc
	)

Definition at line 127 of file fxdpc.cpp.

{
    PFX_DRIVER_GLOBALS pFxDriverGlobals;
    IFxHasCallbacks* pCallbacks;
    NTSTATUS status;
    KDPC* pDpc;
 
    pFxDriverGlobals = GetDriverGlobals();
    pDpc = NULL;
    pCallbacks = NULL;
 
    pDpc = &m_Dpc;
 
    //
    // Set user's callback function
    //
    m_Callback = Config->EvtDpcFunc;
 
    //
    // Initialize the DPC to point to our thunk
    //
    KeInitializeDpc(
        pDpc,         // Dpc
        FxDpcThunk,   // DeferredRoutine
        this          // DeferredContext
        );
 
    //
    // As long as we are associated, the parent object holds a reference
    // count on the DPC.
    //
    // We keep an extra reference count since on Dispose, we wait until
    // all outstanding DPC's complete before allowing finalization.
    //
    // This reference must be taken early before we return any failure,
    // since Dispose() expects this extra reference, and Dispose() will
    // be called even if we return a failure status right now.
    //
    ADDREF(this);
 
    //
    // DPC's can be parented by, and optionally serialize with an FxDevice or
    // an FxQueue.
    //
    m_DeviceBase = FxDeviceBase::_SearchForDevice(ParentObject, &pCallbacks);
 
    if (m_DeviceBase == NULL) {
        return STATUS_INVALID_DEVICE_REQUEST;
    }
 
    //
    // Configure Serialization for the DPC and callbacks on the supplied object
    //
    status = _GetEffectiveLock(
        ParentObject,
        pCallbacks,
        Config->AutomaticSerialization,
        FALSE,
        &m_CallbackLock,
        &m_CallbackLockObject
        );
 
    if (!NT_SUCCESS(status)) {
        if (status == STATUS_WDF_INCOMPATIBLE_EXECUTION_LEVEL) {
 
 
 
 
 
 
            DoTraceLevelMessage(
                pFxDriverGlobals, TRACE_LEVEL_ERROR, TRACINGDEVICE,
                "ParentObject %p can not automatically synchronize callbacks "
                "with a DPC since it is configured for passive level callback "
                "constraints. Set AutomaticSerialization to FALSE. %!STATUS!",
                Attributes->ParentObject, status);
        }
 
        return status;
    }
 
    //
    // We automatically synchronize with and reference count
    // the lifetime of the framework object to prevent any DPC races
    // that can access the object while it is going away.
    //
 
    //
    // The caller supplied object is the object the caller wants the
    // DPC to be associated with, and the framework must ensure this
    // object remains live until the DPC object is destroyed. Otherwise,
    // it could access either object context memory, or an object API
    // on a freed object.
    //
    // Due to the locking model of the framework, the lock may actually
    // be owned by a higher level object as well. This is the lockObject
    // returned. As long was we are a child of this object, the lockObject
    // does not need to be dereferenced since it will notify us of Cleanup
    // before it goes away.
    //
 
    //
    // Associate the FxDpc with the object. When this object gets deleted or
    // disposed, it will notify our Dispose function as well.
    //
 
    //
    // Add a reference to the parent object we are associated with.
    // We will be notified of Cleanup to release this reference.
    //
    ParentObject->ADDREF(this);
 
    // Save the ptr to the object the DPC is associated with
    m_Object = ParentObject;
 
    //
    // Attributes->ParentObject is the same as ParentObject.  Since we already
    // converted it to an object, use that.
    //
    status = Commit(Attributes, (WDFOBJECT*)Dpc, ParentObject);
 
    if (!NT_SUCCESS(status)) {
        return status;
    }
 
    return status;
}

Referenced by _Create().

WorkItemThunk()

static VOID FxDpc::WorkItemThunk ( PDEVICE_OBJECT  DeviceObject, PVOID  Context  )

staticprivate

Member Data Documentation

FxDpcThunk

VOID FxDpc::FxDpcThunk

staticprivate

Definition at line 190 of file fxdpc.hpp.

Referenced by Initialize().

m_Callback

PFN_WDF_DPC FxDpc::m_Callback

private

Definition at line 90 of file fxdpc.hpp.

Referenced by DpcHandler(), FxDpc(), and Initialize().

m_CallbackLock

FxCallbackLock* FxDpc::m_CallbackLock

private

Definition at line 79 of file fxdpc.hpp.

Referenced by DpcHandler(), FxDpc(), and Initialize().

m_CallbackLockObject

FxObject* FxDpc::m_CallbackLockObject

private

Definition at line 85 of file fxdpc.hpp.

Referenced by FxDpc(), and Initialize().

m_Dpc

KDPC FxDpc::m_Dpc

private

Definition at line 67 of file fxdpc.hpp.

Referenced by GetDpcPtr(), and Initialize().

m_Object

FxObject* FxDpc::m_Object

private

Definition at line 73 of file fxdpc.hpp.

Referenced by FlushAndRundown(), FxDpc(), GetObject(), Initialize(), and ~FxDpc().

m_RunningDown

BOOLEAN FxDpc::m_RunningDown

private

Definition at line 93 of file fxdpc.hpp.

Referenced by Dispose(), and FxDpc().

---

The documentation for this class was generated from the following files:

• sdk/lib/drivers/wdf/kmdf/inc/private/fxdpc.hpp
• sdk/lib/drivers/wdf/kmdf/src/core/fxdpc.cpp