#include <fxeventqueue.hpp>

Inheritance diagram for FxEventQueue:

[legend]

Collaboration diagram for FxEventQueue:

[legend]

Public Member Functions
	FxEventQueue (__in UCHAR QueueDepth)

_Must_inspect_result_ NTSTATUS	Initialize (__in PFX_DRIVER_GLOBALS DriverGlobals)

	_Acquires_lock_ (this->m_QueueLock) __drv_maxIRQL(DISPATCH_LEVEL) __drv_setsIRQL(DISPATCH_LEVEL) VOID Lock(__out __drv_deref(__drv_savesIRQL) PKIRQL Irql)

	_Releases_lock_ (this->m_QueueLock) __drv_requiresIRQL(DISPATCH_LEVEL) VOID Unlock(__in __drv_restoresIRQL KIRQL Irql)

BOOLEAN	IsFull (VOID)

BOOLEAN	IsEmpty (VOID)

VOID	IncrementHead (VOID)

UCHAR	GetHead (VOID)

UCHAR	InsertAtHead (VOID)

UCHAR	InsertAtTail (VOID)

UCHAR	IncrementHistoryIndex (VOID)

BOOLEAN	IsClosedLocked (VOID)

VOID	GetFinishedState (__inout FxPostProcessInfo *Info)

BOOLEAN	SetFinished (__in FxCREvent *Event)

VOID	SetDelayedDeletion (VOID)

Public Member Functions inherited from FxStump
PVOID	operator new (__in size_t Size, __in PFX_DRIVER_GLOBALS FxDriverGlobals)

PVOID	operator new (__in size_t Size, __in PFX_DRIVER_GLOBALS FxDriverGlobals, __in POOL_TYPE PoolType)

VOID	operator delete (__in PVOID pointer)

PVOID	operator new[] (__in size_t Size, __in PFX_DRIVER_GLOBALS FxDriverGlobals)

VOID	operator delete[] (__in PVOID pointer)

Public Attributes
FxWaitLockInternal	m_StateMachineLock

Protected Member Functions
VOID	Configure (__in FxPkgPnp *Pnp, __in PFN_PNP_EVENT_WORKER WorkerRoutine, __in PVOID Context)

BOOLEAN	QueueToThreadWorker (VOID)

VOID	EventQueueWorker (VOID)

BOOLEAN	IsIdleLocked (VOID)

Protected Member Functions inherited from FxStump
	FxStump (VOID)

Protected Attributes
UCHAR	m_QueueHead

UCHAR	m_QueueTail

UCHAR	m_QueueDepth

UCHAR	m_HistoryIndex

FxPkgPnp *	m_PkgPnp

PVOID	m_EventWorkerContext

MxLock	m_QueueLock

PFN_PNP_EVENT_WORKER	m_EventWorker

FxCREvent *	m_WorkItemFinished

union {
UCHAR m_QueueFlags

struct {
UCHAR WorkItemQueued: 1

UCHAR Closed: 1

UCHAR DelayDeletion: 1

} m_QueueFlagsByName

};

UCHAR	m_WorkItemRunningCount

Detailed Description

Definition at line 51 of file fxeventqueue.hpp.

Constructor & Destructor Documentation

◆ FxEventQueue()

FxEventQueue::FxEventQueue ( __in UCHAR QueueDepth )

Definition at line 36 of file eventqueue.cpp.

{
    m_PkgPnp = NULL;
    m_EventWorker = NULL;
 
    m_HistoryIndex = 0;
    m_QueueHead = 0;
    m_QueueTail = 0;
    m_QueueDepth = QueueDepth;
 
    m_WorkItemFinished = NULL;
    m_QueueFlags = 0x0;
    m_WorkItemRunningCount = 0x0;
}

Member Function Documentation

◆ _Acquires_lock_()

FxEventQueue::_Acquires_lock_ ( this-> m_QueueLock )

inline

Definition at line 62 of file fxeventqueue.hpp.

    {
        m_QueueLock.Acquire(Irql);
    }

◆ _Releases_lock_()

FxEventQueue::_Releases_lock_ ( this-> m_QueueLock )

inline

Definition at line 74 of file fxeventqueue.hpp.

    {
        m_QueueLock.Release(Irql);
    }

◆ Configure()

VOID FxEventQueue::Configure	(	__in FxPkgPnp *	Pnp,
		__in PFN_PNP_EVENT_WORKER	WorkerRoutine,
		__in PVOID	Context
	)

protected

Definition at line 77 of file eventqueue.cpp.

{
    m_PkgPnp = Pnp;
    m_EventWorker = WorkerRoutine;
    m_EventWorkerContext = Context;
 
    return;
}

Referenced by FxWorkItemEventQueue::Init(), and FxThreadedEventQueue::Init().

◆ EventQueueWorker()

VOID FxEventQueue::EventQueueWorker ( VOID )

protected

Definition at line 229 of file eventqueue.cpp.

{
    FxPostProcessInfo info;
    KIRQL irql;
    FxPkgPnp* pPkgPnp;
 
#if (FX_CORE_MODE==FX_CORE_KERNEL_MODE)
    FX_TRACK_DRIVER(m_PkgPnp->GetDriverGlobals());
#endif
 
    //
    // Cache away m_PkgPnp while we know we still have a valid object.  Once
    // we Unlock() after the worker routine, the object could be gone until
    // the worker routine set a flag postponing deletion.
    //
    pPkgPnp = m_PkgPnp;
 
    Lock(&irql);
 
    ASSERT(m_QueueFlags & FxEventQueueFlagWorkItemQueued);
 
    //
    // Clear the queued flag, so that it's clear that the work item can
    // be safely re-enqueued.
    //
    m_QueueFlags &= ~FxEventQueueFlagWorkItemQueued;
 
    //
    // We should only see this count rise to a small number (like 10 or so).
    //
    ASSERT(m_WorkItemRunningCount < 0xFF);
    m_WorkItemRunningCount++;
 
    Unlock(irql);
 
    //
    // Call the function that will actually run the state machine.
    //
    m_EventWorker(m_PkgPnp, &info, m_EventWorkerContext);
 
    Lock(&irql);
    m_WorkItemRunningCount--;
    GetFinishedState(&info);
    Unlock(irql);
 
    //
    // NOTE:  There is no need to use a reference count to keep this event queue
    //        (and the containing state machine) alive.  Instead, the thread
    //        which wants to delete the state machine must wait for this work
    //        item to exit.  If there was a reference to release, we would have
    //        a race between Unlock()ing and releasing the reference if the state
    //        machine moved into the finished state and deletes the device after
    //        we dropped the lock, but before we released the reference.
    //
    //        This is important in that the device deletion can trigger
    //        DriverUnload to run before the release executes.  DriverUnload
    //        frees the IFR buffer.  If this potential release logs something to
    //        the IFR, you would bugcheck.  Since it is impossible to defensively
    //        prevent all destructors from logging to the IFR, we can't use a
    //        ref count here to keep the queue alive.
    //
 
    //
    // If Evaluate needs to use pPkgPnp, then the call to the worker routine
    // above made sure that pPkgPnp has not yet been freed.
    //
    info.Evaluate(pPkgPnp);
}

◆ GetFinishedState()

VOID FxEventQueue::GetFinishedState ( __inout FxPostProcessInfo * Info )

inline

Definition at line 165 of file fxeventqueue.hpp.

    {
        if (IsIdleLocked()) {
            if (m_QueueFlags & FxEventQueueFlagDelayDeletion) {
                m_QueueFlags &= ~FxEventQueueFlagDelayDeletion;
                Info->m_DeleteObject = TRUE;
            }
 
            if (IsClosedLocked()) {
                Info->m_Event = m_WorkItemFinished;
                m_WorkItemFinished = NULL;
            }
        }
    }

Referenced by EventQueueWorker(), FxPkgPnp::PnpProcessEventInner(), FxPkgPnp::PowerPolicyProcessEventInner(), FxPkgPnp::PowerProcessEventInner(), FxDevicePwrRequirementMachine::ProcessEventInner(), and FxWakeInterruptMachine::ProcessEventInner().

◆ GetHead()

UCHAR FxEventQueue::GetHead ( VOID )

inline

Definition at line 110 of file fxeventqueue.hpp.

    {
        return m_QueueHead;
    }

Referenced by FxPkgPnp::PnpProcessEventInner(), FxPkgPnp::PowerPolicyProcessEventInner(), FxPkgPnp::PowerProcessEventInner(), FxDevicePwrRequirementMachine::ProcessEventInner(), and FxWakeInterruptMachine::ProcessEventInner().

◆ IncrementHead()

VOID FxEventQueue::IncrementHead ( VOID )

inline

Definition at line 102 of file fxeventqueue.hpp.

    {
        m_QueueHead = (m_QueueHead + 1) % m_QueueDepth;
    }

Referenced by FxPkgPnp::PnpProcessEventInner(), FxPkgPnp::PowerPolicyProcessEventInner(), FxPkgPnp::PowerProcessEventInner(), FxDevicePwrRequirementMachine::ProcessEventInner(), and FxWakeInterruptMachine::ProcessEventInner().

◆ IncrementHistoryIndex()

UCHAR FxEventQueue::IncrementHistoryIndex ( VOID )

inline

Definition at line 144 of file fxeventqueue.hpp.

    {
        UCHAR cur;
 
        cur = m_HistoryIndex;
        m_HistoryIndex = (m_HistoryIndex + 1) % m_QueueDepth;
 
        return cur;
    }

Referenced by FxDevicePwrRequirementMachine::FxDevicePwrRequirementMachine(), FxPnpMachine::FxPnpMachine(), FxPowerMachine::FxPowerMachine(), FxPowerPolicyMachine::FxPowerPolicyMachine(), FxWakeInterruptMachine::FxWakeInterruptMachine(), FxPkgPnp::NotPowerPolicyOwnerEnterNewState(), FxPkgPnp::PnpEnterNewState(), FxPkgPnp::PowerEnterNewState(), FxPkgPnp::PowerPolicyEnterNewState(), FxDevicePwrRequirementMachine::ProcessEventInner(), and FxWakeInterruptMachine::ProcessEventInner().

◆ Initialize()

_Must_inspect_result_ NTSTATUS FxEventQueue::Initialize ( __in PFX_DRIVER_GLOBALS DriverGlobals )

Definition at line 55 of file eventqueue.cpp.

{
    NTSTATUS status;
 
    //
    // For KM, lock initialize always succeeds. For UM, it might fail.
    //
    status = m_StateMachineLock.Initialize();
    if (!NT_SUCCESS(status)) {
        DoTraceLevelMessage(DriverGlobals,
            TRACE_LEVEL_ERROR, TRACINGPNP,
            "Initializing state machine lock failed for EventQueue 0x%p, "
            "status %!STATUS!",
            this, status);
    }
 
    return status;
}

Referenced by FxPkgFdo::_Create(), and FxInterrupt::CreateWakeInterruptMachine().

◆ InsertAtHead()

UCHAR FxEventQueue::InsertAtHead ( VOID )

inline

Definition at line 118 of file fxeventqueue.hpp.

    {
        m_QueueHead = (m_QueueHead + m_QueueDepth - 1) % m_QueueDepth;
        return m_QueueHead;
    }

Referenced by FxPkgPnp::PnpProcessEvent(), FxPkgPnp::PowerPolicyProcessEvent(), and FxPkgPnp::PowerProcessEvent().

◆ InsertAtTail()

UCHAR FxEventQueue::InsertAtTail ( VOID )

inline

Definition at line 127 of file fxeventqueue.hpp.

    {
        UCHAR index;
 
        // Save the index which is the current tail
        index = m_QueueTail;
 
        // goto next slot
        m_QueueTail = (m_QueueTail + 1) % m_QueueDepth;
 
        // return the old tail as the slot to insert at
        return index;
    }

Referenced by FxPkgPnp::PnpProcessEvent(), FxPkgPnp::PowerPolicyProcessEvent(), FxPkgPnp::PowerProcessEvent(), FxDevicePwrRequirementMachine::ProcessEvent(), and FxWakeInterruptMachine::ProcessEvent().

◆ IsClosedLocked()

BOOLEAN FxEventQueue::IsClosedLocked ( VOID )

inline

Definition at line 157 of file fxeventqueue.hpp.

    {
        return (m_QueueFlags & FxEventQueueFlagClosed) ? TRUE : FALSE;
    }

Referenced by GetFinishedState(), FxPkgPnp::PnpProcessEvent(), FxPkgPnp::PowerPolicyProcessEvent(), FxPkgPnp::PowerProcessEvent(), FxDevicePwrRequirementMachine::ProcessEvent(), and FxWakeInterruptMachine::ProcessEvent().

◆ IsEmpty()

BOOLEAN FxEventQueue::IsEmpty ( VOID )

inline

Definition at line 94 of file fxeventqueue.hpp.

    {
        return m_QueueHead == m_QueueTail;
    }

Referenced by FxPkgPnp::PnpProcessEventInner(), FxPkgPnp::PowerPolicyProcessEventInner(), and FxPkgPnp::PowerProcessEventInner().

◆ IsFull()

BOOLEAN FxEventQueue::IsFull ( VOID )

inline

Definition at line 86 of file fxeventqueue.hpp.

    {
        return ((m_QueueHead + m_QueueDepth - 1) % m_QueueDepth) == (m_QueueTail % m_QueueDepth);
    }

Referenced by FxPkgPnp::PnpProcessEvent(), FxPkgPnp::PowerPolicyProcessEvent(), FxPkgPnp::PowerProcessEvent(), FxDevicePwrRequirementMachine::ProcessEvent(), and FxWakeInterruptMachine::ProcessEvent().

◆ IsIdleLocked()

BOOLEAN FxEventQueue::IsIdleLocked ( VOID )

inlineprotected

Definition at line 211 of file fxeventqueue.hpp.

    {
        //
        // We are idle if there is no work item queued, no work item running,
        // and there are no events in the queue.  Since m_WorkItemQueued is
        // cleared before we enter the state machine, we must also track the
        // number of work items running.
        //
        if ((m_QueueFlags & FxEventQueueFlagWorkItemQueued) == 0x00 &&
            m_WorkItemRunningCount == 0x0 &&
            IsEmpty()) {
            return TRUE;
        }
        else {
            return FALSE;
        }
    }

Referenced by GetFinishedState(), and SetFinished().

◆ QueueToThreadWorker()

BOOLEAN FxEventQueue::QueueToThreadWorker ( VOID )

protected

Definition at line 154 of file eventqueue.cpp.

{
    KIRQL irql;
    BOOLEAN result;
 
    Lock(&irql);
 
    //
    // For one reason or another, we couldn't run the state machine on this
    // thread.  So queue a work item to do it.
    //
    if (IsEmpty()) {
        //
        // There is no work to do.  This means that the caller inserted the
        // event into the queue, dropped the lock, and then another thread came
        // in and processed the event.
        //
        // This check also helps in the rundown case when the queue is closing
        // and the following happens between 2 thread:
        // #1                       #2
        // insert event
        // drop lock
        //                          process event queue
        //                          queue goes to empty, so event is set
        // try to queue work item
        //
        result = FALSE;
 
        DoTraceLevelMessage(
            m_PkgPnp->GetDriverGlobals(), TRACE_LEVEL_INFORMATION, TRACINGPNP,
            "WDFDEVICE 0x%p !devobj 0x%p not queueing work item to process "
            "event queue", m_PkgPnp->GetDevice()->GetHandle(),
            m_PkgPnp->GetDevice()->GetDeviceObject());
    }
    else if ((m_QueueFlags & FxEventQueueFlagWorkItemQueued) == 0x00) {
        m_QueueFlags |= FxEventQueueFlagWorkItemQueued;
        result = TRUE;
    }
    else {
        //
        // Somebody is already in the process of enqueuing the work item.
        //
        result = FALSE;
    }
 
    Unlock(irql);
 
    return result;
}

Referenced by FxWorkItemEventQueue::QueueToThread(), and FxThreadedEventQueue::QueueToThread().

◆ SetDelayedDeletion()

VOID FxEventQueue::SetDelayedDeletion ( VOID )

Definition at line 135 of file eventqueue.cpp.

{
    KIRQL irql;
 
    DoTraceLevelMessage(
        m_PkgPnp->GetDriverGlobals(), TRACE_LEVEL_INFORMATION, TRACINGPNP,
        "WDFDEVICE 0x%p !devobj 0x%p delaying deletion to outside state machine",
        m_PkgPnp->GetDevice()->GetHandle(),
        m_PkgPnp->GetDevice()->GetDeviceObject());
 
    Lock(&irql);
    ASSERT((m_QueueFlags & FxEventQueueFlagDelayDeletion) == 0x0);
    m_QueueFlags |= FxEventQueueFlagDelayDeletion;
    Unlock(irql);
}

◆ SetFinished()

BOOLEAN FxEventQueue::SetFinished ( __in FxCREvent * Event )

Definition at line 91 of file eventqueue.cpp.

{
    KIRQL irql;
    BOOLEAN result;
 
    result = TRUE;
 
    Lock(&irql);
    ASSERT((m_QueueFlags & FxEventQueueFlagClosed) == 0x0);
    m_QueueFlags |= FxEventQueueFlagClosed;
 
    result = IsIdleLocked();
 
    if (result == FALSE) {
        m_WorkItemFinished = Event;
    }
 
    Unlock(irql);
 
    if (result) {
        Event->Set();
    }
 
    return result;
}

Referenced by FxPkgPnp::CleanupStateMachines().

Member Data Documentation

◆

union { ... } FxEventQueue::@4759

◆ Closed

UCHAR FxEventQueue::Closed

Definition at line 279 of file fxeventqueue.hpp.

◆ DelayDeletion

UCHAR FxEventQueue::DelayDeletion

Definition at line 280 of file fxeventqueue.hpp.

◆ m_EventWorker

PFN_PNP_EVENT_WORKER FxEventQueue::m_EventWorker

protected

Definition at line 260 of file fxeventqueue.hpp.

Referenced by Configure(), EventQueueWorker(), and FxEventQueue().

◆ m_EventWorkerContext

PVOID FxEventQueue::m_EventWorkerContext

protected

Definition at line 249 of file fxeventqueue.hpp.

Referenced by Configure(), and EventQueueWorker().

◆ m_HistoryIndex

UCHAR FxEventQueue::m_HistoryIndex

protected

Definition at line 241 of file fxeventqueue.hpp.

Referenced by FxEventQueue(), and IncrementHistoryIndex().

◆ m_PkgPnp

FxPkgPnp* FxEventQueue::m_PkgPnp

protected

Definition at line 243 of file fxeventqueue.hpp.

Referenced by FxWakeInterruptMachine::_ProcessEventInner(), Configure(), EventQueueWorker(), FxEventQueue(), FxPowerPolicyMachine::InitUsbSS(), FxDevicePwrRequirementMachine::ProcessEvent(), FxWakeInterruptMachine::ProcessEvent(), FxWakeInterruptMachine::ProcessEventInner(), QueueToThreadWorker(), FxWorkItemEventQueue::QueueWorkItem(), FxThreadedEventQueue::QueueWorkItem(), and SetDelayedDeletion().

◆ m_QueueDepth

UCHAR FxEventQueue::m_QueueDepth

protected

Definition at line 239 of file fxeventqueue.hpp.

Referenced by FxEventQueue(), IncrementHead(), IncrementHistoryIndex(), InsertAtHead(), InsertAtTail(), and IsFull().

◆ m_QueueFlags

UCHAR FxEventQueue::m_QueueFlags

Definition at line 275 of file fxeventqueue.hpp.

Referenced by EventQueueWorker(), FxEventQueue(), GetFinishedState(), IsClosedLocked(), IsIdleLocked(), QueueToThreadWorker(), SetDelayedDeletion(), and SetFinished().

◆

struct { ... } FxEventQueue::m_QueueFlagsByName

◆ m_QueueHead

UCHAR FxEventQueue::m_QueueHead

protected

Definition at line 233 of file fxeventqueue.hpp.

Referenced by FxEventQueue(), GetHead(), IncrementHead(), InsertAtHead(), IsEmpty(), and IsFull().

◆ m_QueueLock

MxLock FxEventQueue::m_QueueLock

protected

Definition at line 254 of file fxeventqueue.hpp.

Referenced by _Acquires_lock_(), and _Releases_lock_().

◆ m_QueueTail

UCHAR FxEventQueue::m_QueueTail

protected

Definition at line 236 of file fxeventqueue.hpp.

Referenced by FxEventQueue(), InsertAtTail(), IsEmpty(), and IsFull().

◆ m_StateMachineLock

FxWaitLockInternal FxEventQueue::m_StateMachineLock

Definition at line 257 of file fxeventqueue.hpp.

Referenced by FxDevicePwrRequirementMachine::_ProcessEventInner(), FxWakeInterruptMachine::_ProcessEventInner(), Initialize(), FxPkgPnp::PnpProcessEvent(), FxPkgPnp::PowerPolicyProcessEvent(), FxPkgPnp::PowerPolicySetSxWakeState(), FxPkgPnp::PowerProcessEvent(), FxDevicePwrRequirementMachine::ProcessEvent(), and FxWakeInterruptMachine::ProcessEvent().

◆ m_WorkItemFinished

FxCREvent* FxEventQueue::m_WorkItemFinished

protected

Definition at line 267 of file fxeventqueue.hpp.

Referenced by FxEventQueue(), GetFinishedState(), and SetFinished().

◆ m_WorkItemRunningCount

UCHAR FxEventQueue::m_WorkItemRunningCount

protected

Definition at line 289 of file fxeventqueue.hpp.

Referenced by EventQueueWorker(), FxEventQueue(), and IsIdleLocked().

◆ WorkItemQueued

UCHAR FxEventQueue::WorkItemQueued

Definition at line 278 of file fxeventqueue.hpp.

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

sdk/lib/drivers/wdf/shared/inc/private/common/fxeventqueue.hpp
sdk/lib/drivers/wdf/shared/irphandlers/pnp/eventqueue.cpp

Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ FxEventQueue()

Member Function Documentation

◆ _Acquires_lock_()

◆ _Releases_lock_()

◆ Configure()

◆ EventQueueWorker()

◆ GetFinishedState()

◆ GetHead()

◆ IncrementHead()

◆ IncrementHistoryIndex()

◆ Initialize()

◆ InsertAtHead()

◆ InsertAtTail()

◆ IsClosedLocked()

◆ IsEmpty()

◆ IsFull()

◆ IsIdleLocked()

◆ QueueToThreadWorker()

◆ SetDelayedDeletion()

◆ SetFinished()

Member Data Documentation

◆

◆ Closed

◆ DelayDeletion

◆ m_EventWorker

◆ m_EventWorkerContext

◆ m_HistoryIndex

◆ m_PkgPnp

◆ m_QueueDepth

◆ m_QueueFlags

◆

◆ m_QueueHead

◆ m_QueueLock

◆ m_QueueTail

◆ m_StateMachineLock

◆ m_WorkItemFinished

◆ m_WorkItemRunningCount

◆ WorkItemQueued