fxrequestbase.hpp

Go to the documentation of this file.

/*++
 
Copyright (c) Microsoft Corporation
 
Module Name:
 
    FxRequestBase.hpp
 
Abstract:
 
    This is the base class which request objects derive from for the driver
    frameworks.
 
    The request base object wraps the IRP, containing persistent
    information required by the driver frameworks.
 
Author:
 
 
 
 
Environment:
 
    Both kernel and user mode
 
Revision History:
 
--*/
 
#ifndef _FXREQUESTBASE_H_
#define _FXREQUESTBASE_H_
 
#include "fxrequestcallbacks.hpp"
 
#define WDF_REQUEST_REUSE_MUST_COMPLETE 2
 
 
//
// COMPLETED - set when the request's i/o completion routine has executed
//
// PENDED - set when the request has been put onto the target's CSQ
//
// TIMER_SET - set when a timer has been queued along with sending the request
//             down to the target
//
// CANCELLED_FROM_TIME - set by the timer to indicate that the request was
//                       cancelled by the timer DPC
//
// IGNORE_STATE - set when the request is going to be sent ignoring the
//                state of the target.
//
enum FxRequestTargetFlags {
    FX_REQUEST_COMPLETED                = 0x01,
    FX_REQUEST_PENDED                   = 0x02,
    FX_REQUEST_TIMER_SET                = 0x04,
    FX_REQUEST_CANCELLED_FROM_TIMER     = 0x08,
    FX_REQUEST_IGNORE_STATE             = 0x10,
};
 
//
// internal private constraints
//
#define WDF_REQUEST_SEND_INTERNAL_OPTION_FAIL_ON_PEND (0x80000000)
 
#define WDF_REQUEST_INTERNAL_CONSTRAINTS_VALID_FLAGS \
    (WDF_REQUEST_SEND_INTERNAL_OPTION_FAIL_ON_PEND)
 
 
//
// Completion event callback prototype
//
typedef
VOID
(*PFN_COMPLETE_COPY_ROUTINE)(
    __in FxIoTarget* This,
    __in FxRequest* Request,
    __in_opt FxRequestContext* Context
    );
 
 
struct FxRequestTimer : public FxStump {
    MxTimer Timer;
};
 
enum FxRequestAllocationSource {
    REQUEST_ALLOCATED_FROM_IO = 0,  // Irp came from the I/O package
    REQUEST_ALLOCATED_INTERNAL = 1, // Irp was allocated internally and should be freed by the request
    REQUEST_ALLOCATED_DRIVER = 2,   // Irp was given to the request by the driver writer
};
 
enum FxRequestIrpOwnership {
    FxRequestOwnsIrp = 1,
    FxRequestDoesNotOwnIrp,
};
 
// begin_wpp config
// CUSTOM_TYPE(FxRequestIrpOwnership, ItemEnum(FxRequestIrpOwnership));
// end_wpp
 
enum FxRequestConstructorCaller {
    FxRequestConstructorCallerIsFx = 1,
    FxRequestConstructorCallerIsDriver,
};
 
//
// These defines are for VerifierFlags
//
enum FxRequestVerifierFlags {
    // Request has been passed to the Driver
    FXREQUEST_FLAG_DRIVER_OWNED             = 0x0001,
 
    // Request was returned as a "Tag" request to WdfIoQueuePeekNextRequest.
    FXREQUEST_FLAG_TAG_REQUEST              = 0x0002,
 
    // Request has been forwarded from one queue to another
    FXREQUEST_FLAG_FORWARDED                = 0x0004,
 
    // Request is being EvtIoDefault to the driver
    FXREQUEST_FLAG_DRIVER_DISPATCH          = 0x0008,
 
    // The driver has specified the request as cancelable
    FXREQUEST_FLAG_DRIVER_CANCELABLE        = 0x0010,
 
    FXREQUEST_FLAG_DRIVER_INPROCESS_CONTEXT = 0x0020,
 
    // The request has been cancelled
    FXREQUEST_FLAG_CANCELLED                = 0x0040,
 
    // the next stack location has been formatted
    FXREQUEST_FLAG_FORMATTED                = 0x0080,
 
    // the request has been sent on an I/O target and is in the target's sent list
    FXREQUEST_FLAG_SENT_TO_TARGET           = 0x0100,
 
    // used to make sure the driver stop acknowledges in the context of EvtIoStop
    FXREQUEST_FLAG_DRIVER_IN_EVTIOSTOP_CONTEXT = 0x0200,
 
    // used to indicate whether the Reserved Request is in use or on Free list
    FXREQUEST_FLAG_RESERVED_REQUEST_ASSOCIATED_WITH_IRP = 0x0400,
};
 
enum FxRequestBaseFlags {
    FxRequestBaseSystemMdlMapped  = 0x1,
    FxRequestBaseOutputMdlMapped  = 0x2,
    FxRequestBaseSyncCleanupContext = 0x10,
};
 
enum FxRequestBaseStaticFlags {
    FxRequestBaseStaticSystemBufferValid  = 0x1,
    FxRequestBaseStaticOutputBufferValid  = 0x2,
};
 
//
// Designed to fit into a byte.  FxRequestCompletionPkgFlag is a bit value
// used to distinguish between calling back into the io package or the current
// queue.  When calling back into the current queue, we assume m_IoQueue is valid
//
enum FxRequestCompletionState {
    FxRequestCompletionStateIoPkgFlag = 0x80,
 
    FxRequestCompletionStateNone  = 0x00,
    FxRequestCompletionStateQueue = 0x01,
    FxRequestCompletionStateIoPkg = 0x02 | FxRequestCompletionStateIoPkgFlag,
};
 
class FxRequestBase : public FxNonPagedObject {
 
    friend FxIoTarget;
    friend FxSyncRequest;
 
public:
 
    __inline
    VOID
    SetCompletionRoutine(
        __in_opt PFN_WDF_REQUEST_COMPLETION_ROUTINE CompletionRoutine = NULL,
        __in_opt WDFCONTEXT CompletionContext = NULL
        )
    {
        m_CompletionRoutine.m_Completion = CompletionRoutine;
        m_TargetCompletionContext = CompletionContext;
    }
 
    PFN_WDF_REQUEST_COMPLETION_ROUTINE
    ClearCompletionRoutine(
        VOID
        )
    {
        PFN_WDF_REQUEST_COMPLETION_ROUTINE pRoutine;
 
        pRoutine = m_CompletionRoutine.m_Completion;
        m_CompletionRoutine.m_Completion = NULL;
 
        return pRoutine;
    }
 
    WDFCONTEXT
    ClearCompletionContext(
        VOID
        )
    {
        WDFCONTEXT pContext;
 
        pContext = m_TargetCompletionContext;
        m_TargetCompletionContext = NULL;
 
        return pContext;
    }
 
    __inline
    BOOLEAN
    IsCompletionRoutineSet(
        VOID
        )
    {
        return (m_CompletionRoutine.m_Completion != NULL) ?
                    TRUE : FALSE;
    }
 
    __inline
    BOOLEAN
    IsCancelRoutineSet(
        VOID
        )
    {
        return (m_CancelRoutine.m_Cancel != NULL) ?
                    TRUE : FALSE;
    }
 
    __inline
    FxRequestContext*
    GetContext(
        VOID
        )
    {
        return m_RequestContext;
    }
 
    __inline
    VOID
    SetContext(
        __in FxRequestContext* RequestContext = NULL
        )
    {
        //
        // If we are setting to the same value, just return
        //
        if (m_RequestContext == RequestContext) {
            return;
        }
 
        //
        // If we are changing the context to another unique pointer, free the
        // old context.
        //
        if (m_RequestContext != NULL) {
            delete m_RequestContext;
        }
 
        m_RequestContext = RequestContext;
    }
 
    VOID
    ContextReleaseAndRestore(
        VOID
        )
    {
        //
        // This does not free the context, rather it tells the context to release
        // any references it is holding and restore fields back into the PIRP
        //
        if (m_RequestContext != NULL && m_Irp.GetIrp() != NULL) {
            m_RequestContext->ReleaseAndRestore(this);
            VerifierClearFormatted();
        }
    }
 
    __inline
    VOID
    EnableContextDisposeNotification(
        VOID
        )
    {
        MarkDisposeOverride();
    }
 
    __inline
    BOOLEAN
    HasContextType(
        __in FX_REQUEST_CONTEXT_TYPE Type
        )
    {
        return (m_RequestContext != NULL &&
                m_RequestContext->m_RequestType == Type) ? TRUE : FALSE;
    }
 
    __inline
    BOOLEAN
    HasContext(
        VOID
        )
    {
        return (m_RequestContext != NULL &&
                m_RequestContext->m_RequestType !=
                    FX_REQUEST_CONTEXT_TYPE_NONE) ? TRUE : FALSE;
    }
 
    __inline
    MdIrp
    GetSubmitIrp(
        VOID
        )
    {
        return m_Irp.GetIrp();
    }
 
    __inline
    FxIrp*
    GetSubmitFxIrp(
        VOID
        )
    {
        return &m_Irp;
    }
 
    MdIrp
    SetSubmitIrp(
        __in_opt MdIrp NewIrp,
        __in BOOLEAN FreeIrp = TRUE
        );
 
    __inline
    BOOLEAN
    CanComplete(
        VOID
        )
    {
        LONG count;
        count = InterlockedDecrement(&m_IrpCompletionReferenceCount);
        ASSERT(count >= 0);
        return count == 0 ? TRUE : FALSE;
    }
 
    VOID
    CompleteSubmitted(
        VOID
        );
 
    _Must_inspect_result_
    NTSTATUS
    ValidateTarget(
        __in FxIoTarget* Target
        );
 
    __inline
    FxIoTarget*
    GetTarget(
        VOID
        )
    {
        return m_Target;
    }
 
    VOID
    __inline
    SetTarget(
        __in FxIoTarget* Target
        )
    {
        m_Target = Target;
    }
 
    __inline
    UCHAR
    GetTargetFlags(
        VOID
        )
    {
        // Assumes caller is holding appropriate lock
        return m_TargetFlags;
    }
 
    __inline
    VOID
    SetTargetFlags(
        __in UCHAR Flags
        )
    {
        // Assumes caller is holding appropriate lock
        m_TargetFlags |= Flags;
    }
 
    __inline
    ULONG
    ClearTargetFlags(
        __in UCHAR Flags
        )
    {
        ULONG oldFlags;
 
        oldFlags = m_TargetFlags;
 
        // Assumes caller is holding appropriate lock
        m_TargetFlags &= ~Flags;
 
        return oldFlags;
    }
 
    __inline
    VOID
    SetRequestBaseFlags(
        __in UCHAR Flags
        )
    {
        // Assumes caller is holding appropriate lock
        m_RequestBaseFlags|= Flags;
    }
 
    SHORT
    GetVerifierFlagsLocked(
        VOID
        )
    {
        ASSERT(GetDriverGlobals()->FxVerifierOn);
        return m_VerifierFlags;
    }
 
    __inline
    SHORT
    GetVerifierFlags(
        VOID
        )
    {
        SHORT flags;
        KIRQL irql;
 
        Lock(&irql);
        flags =  GetVerifierFlagsLocked();
        Unlock(irql);
 
        return flags;
    }
 
    __inline
    VOID
    SetVerifierFlagsLocked(
        __in SHORT Flags
        )
    {
        m_VerifierFlags |= Flags;
    }
 
    __inline
    VOID
    SetVerifierFlags(
        __in SHORT Flags
        )
    {
        KIRQL irql;
 
        ASSERT(GetDriverGlobals()->FxVerifierOn);
 
        Lock(&irql);
        SetVerifierFlagsLocked(Flags);
        Unlock(irql);
    }
 
    __inline
    VOID
    ClearVerifierFlagsLocked(
        __in SHORT Flags
        )
    {
        m_VerifierFlags &= ~Flags;
    }
 
    __inline
    VOID
    ClearVerifierFlags(
        __in SHORT Flags
        )
    {
        KIRQL irql;
 
        ASSERT(GetDriverGlobals()->FxVerifierOn);
 
        Lock(&irql);
        ClearVerifierFlagsLocked(Flags);
        Unlock(irql);
    }
 
    __inline
    VOID
    VerifierSetFormatted(
        VOID
        )
    {
        if (GetDriverGlobals()->FxVerifierOn &&
            GetDriverGlobals()->FxVerifierIO) {
            SetVerifierFlags(FXREQUEST_FLAG_FORMATTED);
        }
    }
 
    __inline
    VOID
    VerifierClearFormatted(
        VOID
        )
    {
        if (GetDriverGlobals()->FxVerifierOn &&
            GetDriverGlobals()->FxVerifierIO) {
            ClearVerifierFlags(FXREQUEST_FLAG_FORMATTED);
        }
    }
 
    __inline
    BOOLEAN
    VerifierIsFormatted(
        VOID
        )
    {
        if (GetDriverGlobals()->FxVerifierOn &&
            GetDriverGlobals()->FxVerifierIO) {
            return (GetVerifierFlags() & FXREQUEST_FLAG_FORMATTED) ? TRUE : FALSE;
        }
        else {
            //
            // we are not tracking the state
            //
            return TRUE;
        }
    }
 
    __inline
    BOOLEAN
    ShouldClearContext(
        VOID
        )
    {
        return (m_RequestBaseFlags & FxRequestBaseSyncCleanupContext) ? TRUE
                                                                      : FALSE;
    }
 
    _Must_inspect_result_
    NTSTATUS
    CreateTimer(
        VOID
        );
 
    VOID
    StartTimer(
        __in LONGLONG Timeout
        );
 
    _Must_inspect_result_
    BOOLEAN
    CancelTimer(
        VOID
        );
 
    BOOLEAN
    Cancel(
        VOID
        );
 
    BOOLEAN
    __inline
    IsAllocatedFromIo(
        VOID
        )
    {
        return m_IrpAllocation == REQUEST_ALLOCATED_FROM_IO ? TRUE : FALSE;
    }
 
    BOOLEAN
    __inline
    IsAllocatedDriver(
        VOID
        )
    {
        return m_IrpAllocation == REQUEST_ALLOCATED_DRIVER ? TRUE : FALSE;
    }
 
    BOOLEAN
    __inline
    IsCanComplete(
        VOID
        )
    {
        return m_CanComplete;
    }
 
    __inline
    VOID
    SetCompleted(
        __in BOOLEAN Value
        )
    {
        m_Completed = Value;
    }
 
    VOID
    __inline
    SetPriorityBoost(
        CCHAR PriorityBoost
        )
    {
        m_PriorityBoost = PriorityBoost;
    }
 
    CCHAR
    __inline
    GetPriorityBoost(
        VOID
        )
    {
        return m_PriorityBoost;
    }
 
 
 
 
 
 
 
 
 
 
 
 
 
 
    __inline
    WDFREQUEST
    GetHandle(
        VOID
        )
    {
        return (WDFREQUEST) GetObjectHandle();
    }
 
    __inline
    static
    FxRequestBase*
    _FromListEntry(
        __in PLIST_ENTRY Entry
        )
    {
        return CONTAINING_RECORD(Entry, FxRequestBase, m_ListEntry);
    }
 
    __inline
    static
    FxRequestBase*
    _FromDrainEntry(
        __in PSINGLE_LIST_ENTRY Entry
        )
    {
        return CONTAINING_RECORD(Entry, FxRequestBase, m_DrainSingleEntry);
    }
 
 
    __inline
    static
    FxRequestBase*
    _FromCsqContext(
        __in PMdIoCsqIrpContext Context
        )
    {
        return CONTAINING_RECORD(Context, FxRequestBase, m_CsqContext);
    }
 
    __inline
    PVOID
    GetTraceObjectHandle(
        VOID
        )
    {
        PVOID handle;
 
        handle = GetObjectHandle();
 
        if (handle != NULL) {
            return handle;
        }
        else {
            return (PVOID) this;
        }
    }
 
    VOID
    FreeMdls(
        VOID
    );
 
    DECLSPEC_NORETURN
    VOID
    FatalError(
        __in NTSTATUS Status
        );
 
    VOID
    ClearFieldsForReuse(
        VOID
        );
 
protected:
    FxRequestBase(
        __in PFX_DRIVER_GLOBALS FxDriverGlobals,
        __in USHORT ObjectSize,
        __in_opt MdIrp Irp,
        __in FxRequestIrpOwnership Ownership,
        __in FxRequestConstructorCaller Caller,
        __in FxObjectType ObjectType = FxObjectTypeExternal
        );
 
    virtual
    ~FxRequestBase(
        VOID
        );
 
    // Do not specify argument names
    FX_DECLARE_VF_FUNCTION(
    VOID,
    VerifyDispose
        );
 
    // FxObject overrides
    virtual
    BOOLEAN
    Dispose(
        VOID
        );
 
    static
    MdDeferredRoutineType _TimerDPC;
 
    VOID
    CompleteSubmittedNoContext(
        VOID
        );
 
    VOID
    ZeroOutDriverContext(
        VOID
        )
    {
#if (FX_CORE_MODE == FX_CORE_KERNEL_MODE)
    RtlZeroMemory(GetSubmitFxIrp()->GetDriverContext(),
                  GetSubmitFxIrp()->GetDriverContextSize());
#else
    //
    // UMDF host doesn't expose any easier way to zero out the contexts so
    // set context to NULL one by one.
    //
    GetSubmitFxIrp()->SetContext(0, NULL);
    GetSubmitFxIrp()->SetContext(1, NULL);
    GetSubmitFxIrp()->SetContext(2, NULL);
    GetSubmitFxIrp()->SetContext(3, NULL);
#endif
    }
 
public:
 
    union {
        //
        // The cancel safe queues use this context to identify
        // the request in a race free manner.
        //
        MdIoCsqIrpContext m_CsqContext;
 
        //
        // IoTargets uses this to track the request when it is sent to the target.
        // Since the request cannot be on an CSQ and sent to a target at the
        // same time, we can unionize this with the CSQ context.
        //
        LIST_ENTRY   m_ListEntry;
    };
 
    union {
        //
        // IoTargest uses this when it needs to create a list of requests to cancel
        // when making a state transition
        //
        SINGLE_LIST_ENTRY m_DrainSingleEntry;
 
        //
        // If TRUE, the driver formatted the request by copying the current stack
        // location to next or by manually passing in an IO_STACK_LOCATION.  This
        // is union'ed with m_DrainSingleEntry b/c it is only relevant during
        // send and forget and the request is never enqueued on the target in
        // this case and m_DrainSingleEntry is used when tracking requests sent
        // on a target for cancelation due to a target state change.
        //
        BOOLEAN m_NextStackLocationFormatted;
    };
 
protected:
    //
    // The NT IRP is wrapped by a frameworks FxIrp
    //
    // Note: If m_Irp is NULL after initialization, this means
    //       the IRP was cancelled by a FxIrpQueue cancellation
    //       callback, or completed.
    //
    FxIrp              m_Irp;
 
    //
    // Target of the request.  Access to this field is unguarded.  The following
    // have access to this field
    // o The owning target itself
    // o _TimerDPC()
    // o Cancel() IFF it has successfully incremented the irp completion ref count
    //
    FxIoTarget* m_Target;
 
    FxRequestContext* m_RequestContext;
 
 
 
 
    FxRequestTimer* m_Timer;
 
    //
    // Client driver completion routine to call when the request has come back
    // from the target device.
    //
    FxRequestCancelCallback m_CancelRoutine;
 
    FxRequestCompletionCallback m_CompletionRoutine;
 
    //
    // Context to pass to CompletionRoutine when called
    //
    WDFCONTEXT m_TargetCompletionContext;
 
    //
    // Synchronization for this field is through Interlocked operations
    //
    LONG m_IrpCompletionReferenceCount;
 
    //
    // Access to flags guarded by FxIoTarget::Lock
    //
    // Values defined in the enum FxRequestTargetFlags
    //
    union {
        UCHAR m_TargetFlags;
 
        //
        // These are used purely for debugging, not in live code anywhere!
        // NOTE:  if FxRequestTargetFlagschanges, so this this union
        //
        struct {
            UCHAR Completed : 1;
            UCHAR FlagsPended : 1;
            UCHAR TimerSet : 1;
            UCHAR CancelledFromTimer : 1;
            UCHAR IgnoreState : 1;
        } m_TargetFlagsByName;
    };
 
    //
    // Contains a value from the enum type FxRequestAllocationSource describing
    // how the irp was allocated
    //
    UCHAR m_IrpAllocation;
 
    BOOLEAN m_Completed;
 
    BOOLEAN m_Canceled;
 
    WDFOBJECT_OFFSET_ALIGNED m_SystemBufferOffset;
 
    union {
        //
        // These are flags used by verifier.  Set with values from the enum
        // FxRequestVerifierFlags
        //
        SHORT m_VerifierFlags;
 
        struct {
            SHORT DriverOwned : 1;
            SHORT TagRequest : 1;
            SHORT Forwarded : 1;
            SHORT DriverDispatch : 1;
            SHORT DriverCancelable : 1;
            SHORT DriverInprocessContext : 1;
            SHORT Cancelled : 1;
            SHORT Formatted : 1;
            SHORT SentToTarget : 1;
            SHORT DriverInEvtIoStopContext : 1;
        } m_VeriferFlagsByName;
    };
 
    //
    // If this is !=0, its an indication of outstanding references
    // on WDM IRP fields such as any system buffers.
    //
    LONG m_IrpReferenceCount;
 
    // This field !=NULL if the request is on an IrpQueue.
    FxIrpQueue*        m_IrpQueue;
 
    WDFOBJECT_OFFSET_ALIGNED m_OutputBufferOffset;
 
    union {
        //
        // Bit field.  Set with values from the enum FxRequestBaseFlags
        //
        UCHAR m_RequestBaseFlags;
 
        struct {
            UCHAR SystemMdlMapped : 1;
            UCHAR OutputMdlMapped : 1;
            UCHAR SyncCleanupContext : 1;
        } m_RequestBaseFlagsByName;
    };
 
    union {
        //
        // Bit field.  Set with values from the enum FxRequestBaseStaticFlags
        //
 
        //
        UCHAR m_RequestBaseStaticFlags;
 
        struct {
            UCHAR SystemBufferValid  : 1;
            UCHAR OutputBufferValid  : 1;
        } m_RequestBaseStaticFlagsByName;
    };
 
    //
    // Priority boost.
    //
    CCHAR m_PriorityBoost;
 
    //
    // Contains values from FxRequestCompletionState
    //
    BYTE m_CompletionState;
 
    //
    // TRUE, request can be completed by the driver.
    //
    BOOLEAN m_CanComplete;
 
    //
    // If !=NULL, MDL allocated and assocated with the request
    //
    PMDL m_AllocatedMdl;
};
 
#if ((FX_CORE_MODE)==(FX_CORE_KERNEL_MODE))
#include "fxrequestbasekm.hpp"
#elif ((FX_CORE_MODE)==(FX_CORE_USER_MODE))
#include "fxrequestbaseum.hpp"
#endif
 
 
#endif // _FXREQUESTBASE_H_