FxDevicePwrRequirementMachine Class Reference

#include <fxdevicepwrreqstatemachine.hpp>

Inheritance diagram for FxDevicePwrRequirementMachine:

Collaboration diagram for FxDevicePwrRequirementMachine:

Public Member Functions
	FxDevicePwrRequirementMachine (__in FxPoxInterface *PoxInterface)
VOID	ProcessEvent (__in FxDevicePwrRequirementEvents Event)
Public Member Functions inherited from FxThreadedEventQueue
	FxThreadedEventQueue (__in UCHAR QueueDepth)
	~FxThreadedEventQueue (VOID)
_Must_inspect_result_ NTSTATUS	Init (__inout FxPkgPnp *Pnp, __in PFN_PNP_EVENT_WORKER WorkerRoutine, __in PVOID WorkerContext=NULL)
VOID	QueueToThread (VOID)
Public Member Functions inherited from FxEventQueue
	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)

Static Public Member Functions
static VOID	_ProcessEventInner (__inout FxPkgPnp *PkgPnp, __inout FxPostProcessInfo *Info, __in PVOID WorkerContext)

Protected Attributes
FxPoxInterface *	m_PoxInterface
BYTE	m_CurrentState
FxDevicePwrRequirementEvents	m_Queue [FxDevicePwrRequirementEventQueueDepth]
FxDevicePwrRequirementMachineStateHistory	m_States
Protected Attributes inherited from FxThreadedEventQueue
MxWorkItem	m_WorkItem
WORK_QUEUE_ITEM	m_EventWorkQueueItem
Protected Attributes inherited from FxEventQueue
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

Static Protected Attributes
static const FxDevicePwrRequirementStateTable	m_StateTable []
static const FxDevicePwrRequirementTargetState	m_UnregisteredStates []
static const FxDevicePwrRequirementTargetState	m_DevicePowerRequiredD0States []
static const FxDevicePwrRequirementTargetState	m_DevicePowerNotRequiredD0States []
static const FxDevicePwrRequirementTargetState	m_DevicePowerNotRequiredDxStates []
static const FxDevicePwrRequirementTargetState	m_DevicePowerRequiredDxStates []
static const FxDevicePwrRequirementTargetState	m_WaitingForDevicePowerRequiredD0States []
Static Protected Attributes inherited from FxThreadedEventQueue
static WORKER_THREAD_ROUTINE	_WorkerThreadRoutine
static MX_WORKITEM_ROUTINE	_WorkItemCallback

Private Member Functions
VOID	ProcessEventInner (__inout FxPostProcessInfo *Info)

Static Private Member Functions
static FxDevicePwrRequirementStates	PowerNotRequiredD0 (__in FxDevicePwrRequirementMachine *This)
static FxDevicePwrRequirementStates	PowerRequiredDx (__in FxDevicePwrRequirementMachine *This)
static FxDevicePwrRequirementStates	ReportingDevicePowerAvailable (__in FxDevicePwrRequirementMachine *This)

Additional Inherited Members
Public Attributes inherited from FxEventQueue
FxWaitLockInternal	m_StateMachineLock
Protected Member Functions inherited from FxThreadedEventQueue
VOID	QueueWorkItem (VOID)
Protected Member Functions inherited from FxEventQueue
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)

Detailed Description

Definition at line 88 of file fxdevicepwrreqstatemachine.hpp.

Constructor & Destructor Documentation

FxDevicePwrRequirementMachine()

FxDevicePwrRequirementMachine::FxDevicePwrRequirementMachine

(

__in FxPoxInterface *

PoxInterface

)

Definition at line 111 of file devicepwrreqstatemachine.cpp.

      : FxThreadedEventQueue(FxDevicePwrRequirementEventQueueDepth)
{
    //
    // Make sure we can fit the state into a byte
    //
    C_ASSERT(DprMax <= 0xFF);

    m_CurrentState = DprUnregistered;

    RtlZeroMemory(&m_Queue, sizeof(m_Queue));
    RtlZeroMemory(&m_States, sizeof(m_States));

    //
    // Store the initial state in the state history array
    //
    m_States.History[IncrementHistoryIndex()] = m_CurrentState;
    m_PoxInterface = PoxInterface;
}

Member Function Documentation

_ProcessEventInner()

VOID FxDevicePwrRequirementMachine::_ProcessEventInner ( __inout FxPkgPnp *  PkgPnp, __inout FxPostProcessInfo *  Info, __in PVOID  WorkerContext  )

static

Definition at line 238 of file devicepwrreqstatemachine.cpp.

{
    FxDevicePwrRequirementMachine * pThis = NULL;

    UNREFERENCED_PARAMETER(WorkerContext);

    pThis = PkgPnp->m_PowerPolicyMachine.m_Owner->
                m_PoxInterface.m_DevicePowerRequirementMachine;

    //
    // Take the state machine lock.
    //
    pThis->m_StateMachineLock.AcquireLock(
                pThis->m_PoxInterface->m_PkgPnp->GetDriverGlobals()
                );

    //
    // Call the function that will actually run the state machine.
    //
    pThis->ProcessEventInner(Info);

    //
    // We are being called from the work item and m_WorkItemRunning is > 0, so
    // we cannot be deleted yet.
    //
    ASSERT(Info->SomethingToDo() == FALSE);

    //
    // Now release the state machine lock
    //
    pThis->m_StateMachineLock.ReleaseLock(
                pThis->m_PoxInterface->m_PkgPnp->GetDriverGlobals()
                );

    return;
}

PowerNotRequiredD0()

FxDevicePwrRequirementStates FxDevicePwrRequirementMachine::PowerNotRequiredD0 ( __in FxDevicePwrRequirementMachine *  This )

staticprivate

Definition at line 402 of file devicepwrreqstatemachine.cpp.

{
    This->m_PoxInterface->PkgPnp()->PowerPolicyProcessEvent(
                                        PwrPolDevicePowerNotRequired
                                        );
    return DprMax;
}

PowerRequiredDx()

FxDevicePwrRequirementStates FxDevicePwrRequirementMachine::PowerRequiredDx ( __in FxDevicePwrRequirementMachine *  This )

staticprivate

Definition at line 413 of file devicepwrreqstatemachine.cpp.

{
    This->m_PoxInterface->PkgPnp()->PowerPolicyProcessEvent(
                                        PwrPolDevicePowerRequired
                                        );
    return DprMax;
}

ProcessEvent()

VOID FxDevicePwrRequirementMachine::ProcessEvent

(

__in FxDevicePwrRequirementEvents

Event

)

Definition at line 133 of file devicepwrreqstatemachine.cpp.

{
    NTSTATUS status;
    KIRQL irql;
    LONGLONG timeout = 0;

    //
    // Acquire state machine *queue* lock, raising to DISPATCH_LEVEL
    //
    Lock(&irql);

    if (IsFull()) {
        //
        // The queue is full. This should never happen.
        //
        Unlock(irql);

        ASSERTMSG("The device power requirement state machine queue is full\n",
                  FALSE);
        return;
    }

    if (IsClosedLocked()) {
        //
        // The queue is closed. This should never happen.
        //
        DoTraceLevelMessage(
          m_PkgPnp->GetDriverGlobals(), TRACE_LEVEL_INFORMATION, TRACINGPNP,
          "WDFDEVICE 0x%p !devobj 0x%p current device power requirement state"
          " %!FxDevicePwrRequirementStates! dropping event "
          "%!FxDevicePwrRequirementEvents! because of a closed queue",
          m_PoxInterface->m_PkgPnp->GetDevice()->GetHandle(),
          m_PoxInterface->m_PkgPnp->GetDevice()->GetDeviceObject(),
          m_CurrentState,
          Event);

        Unlock(irql);

        ASSERTMSG(
            "The device power requirement state machine queue is closed\n",
            FALSE
            );
        return;
    }

    //
    // Enqueue the event
    //
    m_Queue[InsertAtTail()] = Event;

    //
    // Drop the state machine *queue* lock
    //
    Unlock(irql);

    //
    // Now, if we are running at PASSIVE_LEVEL, attempt to run the state machine
    // on this thread. If we can't do that, then queue a work item.
    //
    if (irql == PASSIVE_LEVEL) {
        //
        // Try to acquire the state machine lock
        //
        status = m_StateMachineLock.AcquireLock(
                    m_PoxInterface->m_PkgPnp->GetDriverGlobals(),
                    &timeout
                    );
        if (FxWaitLockInternal::IsLockAcquired(status)) {
            FxPostProcessInfo info;

            //
            // We now hold the state machine lock.  So call the function that
            // dispatches the next state.
            //
            ProcessEventInner(&info);

            //
            // The pnp state machine should be the only one deleting the object
            //
            ASSERT(info.m_DeleteObject == FALSE);

            //
            // Release the state machine lock
            //
            m_StateMachineLock.ReleaseLock(
                m_PoxInterface->m_PkgPnp->GetDriverGlobals()
                );

            info.Evaluate(m_PkgPnp);

            return;
        }
    }

    //
    // For one reason or another, we couldn't run the state machine on this
    // thread.  So queue a work item to do it.
    //
    QueueToThread();
    return;
}

ProcessEventInner()

VOID FxDevicePwrRequirementMachine::ProcessEventInner ( __inout FxPostProcessInfo *  Info )

private

Definition at line 280 of file devicepwrreqstatemachine.cpp.

{
    KIRQL irql;
    FxDevicePwrRequirementEvents event;
    const FxDevicePwrRequirementStateTable* entry;
    FxDevicePwrRequirementStates newState;

    //
    // Process as many events as we can
    //
    for ( ; ; ) {
        //
        // Acquire state machine *queue* lock
        //
        Lock(&irql);

        if (IsEmpty()) {
            //
            // The queue is empty.
            //
            GetFinishedState(Info);
            Unlock(irql);
            return;
        }

        //
        // Get the event from the queue
        //
        event = m_Queue[GetHead()];
        IncrementHead();

        //
        // Drop the state machine *queue* lock
        //
        Unlock(irql);

        //
        // Get the state table entry for the current state
        //
        // NOTE: Prefast complains about buffer overflow if (m_CurrentState ==
        // DprMax), but that should never happen because DprMax is not a real
        // state. We just use it to represent the maximum value in the enum that
        // defines the states.
        //
        __analysis_assume(m_CurrentState < DprMax);
        entry = &m_StateTable[m_CurrentState - DprUnregistered];

        //
        // Based on the event received, figure out the next state
        //
        newState = DprMax;
        for (ULONG i = 0; i < entry->TargetStatesCount; i++) {
            if (entry->TargetStates[i].DprEvent == event) {
                DO_EVENT_TRAP(&entry->TargetStates[i]);
                newState = entry->TargetStates[i].DprState;
                break;
            }
        }

        if (newState == DprMax) {
            //
            // Unexpected event for this state
            //
            DoTraceLevelMessage(
                m_PoxInterface->PkgPnp()->GetDriverGlobals(),
                TRACE_LEVEL_INFORMATION,
                TRACINGPNP,
                "WDFDEVICE 0x%p !devobj 0x%p device power requirement state "
                "%!FxDevicePwrRequirementStates! dropping event "
                "%!FxDevicePwrRequirementEvents!",
                m_PoxInterface->PkgPnp()->GetDevice()->GetHandle(),
                m_PoxInterface->PkgPnp()->GetDevice()->GetDeviceObject(),
                m_CurrentState,
                event
                );

            COVERAGE_TRAP();
        }

        while (newState != DprMax) {
            DoTraceLevelMessage(
                m_PoxInterface->PkgPnp()->GetDriverGlobals(),
                TRACE_LEVEL_INFORMATION,
                TRACINGPNPPOWERSTATES,
                "WDFDEVICE 0x%p !devobj 0x%p entering device power requirement "
                "state %!FxDevicePwrRequirementStates! from "
                "%!FxDevicePwrRequirementStates!",
                m_PoxInterface->PkgPnp()->GetDevice()->GetHandle(),
                m_PoxInterface->PkgPnp()->GetDevice()->GetDeviceObject(),
                newState,
                m_CurrentState
                );

            //
            // Update the state history array
            //
            m_States.History[IncrementHistoryIndex()] = (UCHAR) newState;

            //
            // Move to the new state
            //
            m_CurrentState = (BYTE) newState;
            entry = &m_StateTable[m_CurrentState-DprUnregistered];

            //
            // Invoke the state entry function (if present) for the new state
            //
            if (entry->StateFunc != NULL) {
                newState = entry->StateFunc(this);
            }
            else {
                newState = DprMax;
            }
        }
    }

    return;
}

Referenced by _ProcessEventInner(), and ProcessEvent().

ReportingDevicePowerAvailable()

FxDevicePwrRequirementStates FxDevicePwrRequirementMachine::ReportingDevicePowerAvailable ( __in FxDevicePwrRequirementMachine *  This )

staticprivate

Definition at line 424 of file devicepwrreqstatemachine.cpp.

{
    This->m_PoxInterface->PoxReportDevicePoweredOn();
    return DprDevicePowerRequiredD0;
}

Member Data Documentation

m_CurrentState

BYTE FxDevicePwrRequirementMachine::m_CurrentState

protected

Definition at line 136 of file fxdevicepwrreqstatemachine.hpp.

Referenced by FxDevicePwrRequirementMachine(), ProcessEvent(), and ProcessEventInner().

m_DevicePowerNotRequiredD0States

const FxDevicePwrRequirementTargetState FxDevicePwrRequirementMachine::m_DevicePowerNotRequiredD0States

staticprotected

Initial value:

=
{
    {DprEventDeviceGoingToDx, DprDevicePowerNotRequiredDx DEBUGGED_EVENT},
    {DprEventPoxRequiresPower, DprReportingDevicePowerAvailable DEBUGGED_EVENT},
    {DprEventUnregisteredWithPox, DprUnregistered TRAP_ON_EVENT}
}

Definition at line 147 of file fxdevicepwrreqstatemachine.hpp.

m_DevicePowerNotRequiredDxStates

const FxDevicePwrRequirementTargetState FxDevicePwrRequirementMachine::m_DevicePowerNotRequiredDxStates

staticprotected

Initial value:

=
{
    {DprEventDeviceReturnedToD0, DprWaitingForDevicePowerRequiredD0 DEBUGGED_EVENT},
    {DprEventPoxRequiresPower, DprDevicePowerRequiredDx DEBUGGED_EVENT}
}

Definition at line 148 of file fxdevicepwrreqstatemachine.hpp.

m_DevicePowerRequiredD0States

const FxDevicePwrRequirementTargetState FxDevicePwrRequirementMachine::m_DevicePowerRequiredD0States

staticprotected

Initial value:

=
{
    {DprEventPoxDoesNotRequirePower, DprDevicePowerNotRequiredD0 DEBUGGED_EVENT},
    {DprEventUnregisteredWithPox, DprUnregistered DEBUGGED_EVENT},
    {DprEventDeviceReturnedToD0, DprDevicePowerRequiredD0 DEBUGGED_EVENT}
}

Definition at line 146 of file fxdevicepwrreqstatemachine.hpp.

m_DevicePowerRequiredDxStates

const FxDevicePwrRequirementTargetState FxDevicePwrRequirementMachine::m_DevicePowerRequiredDxStates

staticprotected

Initial value:

=
{
    {DprEventDeviceReturnedToD0, DprReportingDevicePowerAvailable DEBUGGED_EVENT}
}

Definition at line 149 of file fxdevicepwrreqstatemachine.hpp.

m_PoxInterface

FxPoxInterface* FxDevicePwrRequirementMachine::m_PoxInterface

protected

Definition at line 133 of file fxdevicepwrreqstatemachine.hpp.

Referenced by _ProcessEventInner(), FxDevicePwrRequirementMachine(), ProcessEvent(), and ProcessEventInner().

m_Queue

FxDevicePwrRequirementEvents FxDevicePwrRequirementMachine::m_Queue[FxDevicePwrRequirementEventQueueDepth]

protected

Definition at line 140 of file fxdevicepwrreqstatemachine.hpp.

Referenced by FxDevicePwrRequirementMachine(), ProcessEvent(), and ProcessEventInner().

m_States

FxDevicePwrRequirementMachineStateHistory FxDevicePwrRequirementMachine::m_States

protected

Definition at line 141 of file fxdevicepwrreqstatemachine.hpp.

Referenced by FxDevicePwrRequirementMachine(), and ProcessEventInner().

m_StateTable

const FxDevicePwrRequirementStateTable FxDevicePwrRequirementMachine::m_StateTable

staticprotected

Definition at line 143 of file fxdevicepwrreqstatemachine.hpp.

Referenced by ProcessEventInner().

m_UnregisteredStates

const FxDevicePwrRequirementTargetState FxDevicePwrRequirementMachine::m_UnregisteredStates

staticprotected

Initial value:

=
{
    {DprEventRegisteredWithPox, DprDevicePowerRequiredD0 DEBUGGED_EVENT}
}

Definition at line 145 of file fxdevicepwrreqstatemachine.hpp.

m_WaitingForDevicePowerRequiredD0States

const FxDevicePwrRequirementTargetState FxDevicePwrRequirementMachine::m_WaitingForDevicePowerRequiredD0States

staticprotected

Initial value:

=
{
    {DprEventPoxRequiresPower, DprReportingDevicePowerAvailable DEBUGGED_EVENT},
    {DprEventDeviceReturnedToD0, DprWaitingForDevicePowerRequiredD0 TRAP_ON_EVENT},
    {DprEventUnregisteredWithPox, DprUnregistered DEBUGGED_EVENT},
}

Definition at line 150 of file fxdevicepwrreqstatemachine.hpp.

---

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

• sdk/lib/drivers/wdf/shared/inc/private/common/fxdevicepwrreqstatemachine.hpp
• sdk/lib/drivers/wdf/shared/irphandlers/pnp/devicepwrreqstatemachine.cpp