fxsystemworkitem.cpp

Go to the documentation of this file.

/*++
 
Copyright (c) Microsoft Corporation
 
Module Name:
 
    FxSystemWorkItem.hpp
 
Abstract:
 
    This module implements a frameworks managed WORKITEM that
    can synchrononize with driver frameworks object locks.
 
Author:
 
 
 
Environment:
 
    Both kernel and user mode
 
Revision History:
 
 
--*/
 
#include "coreprivshared.hpp"
 
#include "fxsystemworkitem.hpp"
 
// Tracing support
extern "C" {
// #include "FxSystemWorkItem.tmh"
}
 
//
// Public constructors
//
_Must_inspect_result_
NTSTATUS
FxSystemWorkItem::_Create(
    __in PFX_DRIVER_GLOBALS FxDriverGlobals,
    __in PVOID              WdmObject,
    __out FxSystemWorkItem** pObject
    )
{
    NTSTATUS status;
    FxSystemWorkItem* wi;
 
    wi = new(FxDriverGlobals) FxSystemWorkItem(FxDriverGlobals);
    if (wi == NULL) {
        return STATUS_INSUFFICIENT_RESOURCES;
    }
 
    status = wi->Initialize(WdmObject);
    if (!NT_SUCCESS(status)) {
        wi->Release();
        return status;
    }
 
    *pObject = wi;
 
    return status;
}
 
FxSystemWorkItem::FxSystemWorkItem(
    __in PFX_DRIVER_GLOBALS FxDriverGlobals
    ) :
    FxNonPagedObject(FX_TYPE_SYSTEMWORKITEM, 0, FxDriverGlobals),
    m_WorkItemCompleted(NotificationEvent, TRUE),
    m_RemoveEvent(SynchronizationEvent, FALSE)
{
    m_RunningDown = FALSE;
    m_Enqueued = FALSE;
    m_Callback = NULL;
    m_CallbackArg = NULL;
    m_WorkItemRunningCount = 0;
    m_OutStandingWorkItem = 1;
}
 
FxSystemWorkItem::~FxSystemWorkItem()
{
    PFX_DRIVER_GLOBALS FxDriverGlobals = GetDriverGlobals();
 
    //
    // If this hits, it's because someone destroyed the WORKITEM by
    // removing too many references by mistake without calling WdfObjectDelete
    //
    if( !m_RunningDown && (m_WorkItem.GetWorkItem() != NULL)) {
        DoTraceLevelMessage(FxDriverGlobals, TRACE_LEVEL_ERROR, TRACINGDEVICE,
                            "WorkItem destroyed without calling "
                            "FxSystemWorkItem::Delete, or by Framework "
                            "processing DeviceRemove. "
                            "Possible reference count problem?");
        FxVerifierDbgBreakPoint(FxDriverGlobals);
    }
 
    // Free the workitem
    if( m_WorkItem.GetWorkItem() != NULL ) {
        m_WorkItem.Free();
    }
 
    ASSERT(m_Enqueued == FALSE);
    ASSERT(m_WorkItemRunningCount == 0L);
 
    return;
}
 
_Must_inspect_result_
NTSTATUS
FxSystemWorkItem::Initialize(
    __in PVOID WdmObject
    )
{
    PFX_DRIVER_GLOBALS FxDriverGlobals = GetDriverGlobals();
    NTSTATUS status;
 
    //
    // Mark this object as passive level to ensure that Dispose() is passive
    //
    MarkPassiveCallbacks(ObjectDoNotLock);
 
    MarkDisposeOverride(ObjectDoNotLock);
 
#if (FX_CORE_MODE == FX_CORE_USER_MODE)
    status = m_WorkItemCompleted.Initialize(NotificationEvent, TRUE);
    if (!NT_SUCCESS(status)) {
        DoTraceLevelMessage(FxDriverGlobals, TRACE_LEVEL_ERROR, TRACINGDEVICE,
                            "Could not initialize m_WorkItemCompleted event "
                            "status %!status!", status);
        return status;
    }
 
    status = m_RemoveEvent.Initialize(SynchronizationEvent, FALSE);
    if(!NT_SUCCESS(status)) {
        DoTraceLevelMessage(FxDriverGlobals, TRACE_LEVEL_ERROR, TRACINGDEVICE,
                            "Could not initialize m_RemoveEvent event "
                            "status %!status!", status);
        return status;
    }
#endif
 
    //
    // Allocate the PIO_WORKITEM we will re-use
    //
    status = m_WorkItem.Allocate((MdDeviceObject) WdmObject);
    if(!NT_SUCCESS(status)) {
        DoTraceLevelMessage(FxDriverGlobals, TRACE_LEVEL_ERROR, TRACINGDEVICE,
                            "Could not allocate IoWorkItem, insufficient resources");
        return status;
    }
 
    ASSERT(m_WorkItem.GetWorkItem() != NULL);
 
    return STATUS_SUCCESS;
}
 
BOOLEAN
FxSystemWorkItem::EnqueueWorker(
    __in PFN_WDF_SYSTEMWORKITEM Func,
    __in PVOID                  Parameter,
    __in BOOLEAN                AssertIfAlreadyQueued
    )
/*++
 
Routine Description:
 
    Called to queue the workitem. This function, under verifier, will
    throw an assert if AssertIfAlreadyQueued parameter is set.
 
Arguments:
    Func - Callback function.
 
    Parameter - Callback's context.
 
    AssertIfAlreadyQueued - is used to make sure that caller doesn't
        miss any workitem callback.
 
Return Value:
 
    FALSE
        - if the previously queued workitem hasn't run to completion.
        - if the object is running down.
 
    TRUE - workitem is queued.
--*/
{
    PFX_DRIVER_GLOBALS pFxDriverGlobals;
    KIRQL irql;
 
    pFxDriverGlobals = GetDriverGlobals();
 
    Lock(&irql);
 
    if( m_Enqueued ) {
        if (AssertIfAlreadyQueued) {
            DoTraceLevelMessage(pFxDriverGlobals, TRACE_LEVEL_ERROR, TRACINGDEVICE,
                                "WorkItem 0x%p already enqueued IoWorkItem 0x%p",
                                this, m_WorkItem.GetWorkItem());
            FxVerifierDbgBreakPoint(pFxDriverGlobals);
        }
 
        Unlock(irql);
        return FALSE;
    }
 
    //
    // If running down, fail
    //
    if( m_RunningDown ) {
        DoTraceLevelMessage(pFxDriverGlobals, TRACE_LEVEL_ERROR, TRACINGDEVICE,
                "WorkItem 0x%p is already deleted", this);
        FxVerifierDbgBreakPoint(pFxDriverGlobals);
        Unlock(irql);
        return FALSE;
    }
 
    m_WorkItemCompleted.Clear();
 
    m_Callback = Func;
    m_CallbackArg = Parameter;
 
    m_Enqueued = TRUE;
 
    // Add a reference while outstanding
    IncrementWorkItemQueued();
 
    Unlock(irql);
 
    m_WorkItem.Enqueue(_WorkItemThunk, this);
 
    return TRUE;
}
 
VOID
FxSystemWorkItem::WorkItemHandler()
{
    PFN_WDF_SYSTEMWORKITEM Callback;
    PVOID                  CallbackArg;
    KIRQL                  irql;
 
    FX_TRACK_DRIVER(GetDriverGlobals());
 
    Lock(&irql);
 
    m_Enqueued  = FALSE;
 
    Callback    = m_Callback;
    CallbackArg = m_CallbackArg;
 
    m_Callback = NULL;
 
    //
    // We should only see this count rise to a small number (like 10 or so).
    //
    ASSERT(m_WorkItemRunningCount < 0xFF);
 
    m_WorkItemRunningCount++;
 
    Unlock(irql);
 
    Callback(CallbackArg);
 
    Lock(&irql);
 
    m_WorkItemRunningCount--;
 
    //
    // The driver could re-enqueue a new callback from within the
    // callback handler, which could make m_Enqueued no longer false.
    //
    // We only set the event specifying the callback as completed when
    // we are ensured that no more workitems are enqueued.
    //
    if (m_WorkItemRunningCount == 0L && m_Enqueued == FALSE) {
        m_WorkItemCompleted.Set();
    }
 
    Unlock(irql);
 
    return;
}
 
VOID
FxSystemWorkItem::_WorkItemThunk(
    __in MdDeviceObject DeviceObject,
    __in_opt PVOID      Context
    )
 
/*++
 
Routine Description:
 
    This is the static routine called by the kernel's PIO_WORKITEM handler.
 
    A reference count was taken by Enqueue, which this routine releases
    on return.
 
Arguments:
 
Return Value:
 
    Nothing.
 
--*/
 
{
    FxSystemWorkItem* pWorkItem = (FxSystemWorkItem*)Context;
 
    UNREFERENCED_PARAMETER(DeviceObject);
 
    pWorkItem->WorkItemHandler();
 
    // Release the reference taken when enqueued
    pWorkItem->DecrementWorkItemQueued();
 
    return;
}
 
//
// Invoked when DeleteObject is called on the object, or its parent.
//
BOOLEAN
FxSystemWorkItem::Dispose(
    )
{
    KIRQL irql;
 
    ASSERT(Mx::MxGetCurrentIrql() == PASSIVE_LEVEL);
 
    Lock(&irql);
 
    ASSERT(!m_RunningDown);
 
    m_RunningDown = TRUE;
 
    Unlock(irql);
 
    ReleaseWorkItemQueuedCountAndWait();
 
    return TRUE;
}
 
//
// Wait until any outstanding WorkItem has completed safely
//
// Can only be called after Delete
//
// The caller must call AddRef() and Release() around this call
// to ensure the FxSystemWorkItem remains valid while it is doing the
// wait.
//
VOID
FxSystemWorkItem::WaitForExit(
    )
{
    NTSTATUS Status;
 
    //
    // Wait for current workitem to complete processing
    //
    Status = m_WorkItemCompleted.EnterCRAndWaitAndLeave();
 
    ASSERT(NT_SUCCESS(Status));
    UNREFERENCED_PARAMETER(Status);
 
    //
    // This assert is not under a lock, but the code in WorkItemHandler()
    // clears m_Enqueued under the lock, thus releasing it with a memory
    // barrier. Since we have ensured above that no one can re-queue a request
    // due to m_RunningDown, we should not hit this assert unless there
    // is a code problem with wakeup occuring while an outstanding
    // workitem is running.
    //
    ASSERT(m_Enqueued == FALSE);
 
    return;
}