fxdriver.hpp

Go to the documentation of this file.

/*++

Copyright (c) Microsoft Corporation

Module Name:

    FxDriver.hpp

Abstract:

    This is the definition of the FxDriver object.

Author:



Environment:

    Both kernel and user mode

Revision History:

--*/

#ifndef _FXDRIVER_H_
#define _FXDRIVER_H_

#include "fxdrivercallbacks.hpp"


//
// Unique value to retrieve the FxDriver* from the PDEVICE_OBJECT.
//
#define FX_TRACE_INFO_ID   (FxDriver::_GetTraceInfoExtension)

//
// Structure to hold WMI Callback info
//
struct FxTraceInfo {
    MdDriverObject           DriverObject;
    PFN_WDF_TRACE_CALLBACK   Callback;
    PVOID                    Context;
};

//
// Unique value to retrieve the FxDriver* from the MdDriverObject.  Use a value
// that is not exposed to the driver writer through the dispatch table or WDM.
//
#define FX_DRIVER_ID ((PVOID)FxDriver::GetFxDriver)

//
// The following are support classes for FxDriver
//
class FxDriver : public FxNonPagedObject, public IFxHasCallbacks
{
friend class FxDevice;
friend class FxPackage;
friend class FxWmiIrpHandler;

private:

    MxDriverObject m_DriverObject;
    UNICODE_STRING m_RegistryPath;

    BOOLEAN m_DebuggerConnected;

    //
    // Callbacks to device driver
    //
    FxDriverDeviceAdd m_DriverDeviceAdd;

    //
    // This represents any constraints on callbacks
    // to the device driver that may be inherited
    // by child devices and their objects
    //
    WDF_EXECUTION_LEVEL       m_ExecutionLevel;
    WDF_SYNCHRONIZATION_SCOPE m_SynchronizationScope;

    //
    // Frameworks objects that raise event callbacks into the device
    // driver provide spinlock and mutex based callback locks
    // to allow proper synchronization between the driver and
    // these callbacks.
    //
    // Some events must be passive level, while others at dispatch
    // level, thus the need for two locks.
    //
    // The objects internal state is protected by the FxNonPagedObject
    // lock inherited by the object, and is different from the callback
    // locks.
    //
    FxCallbackMutexLock m_CallbackMutexLock;

    //
    // These pointers allow the proper lock to be acquired
    // based on the configuration with a minimal of runtime
    // checks. This is configured by ConfigureConstraints()
    //
    FxCallbackLock* m_CallbackLockPtr;
    FxObject*       m_CallbackLockObjectPtr;

    //
    // This is the Driver-wide configuration
    //
    WDF_DRIVER_CONFIG m_Config;

    //
    // Deferred Disposal List
    //
    FxDisposeList*    m_DisposeList;

#if FX_IS_USER_MODE
    //
    // A handle to the driver service parameters key.
    // The framework does not have permission to open it with
    // write access from user mode, so we keep a pre-opened one.
    //
    HKEY m_DriverParametersKey;
#endif

private:

    static
    MdDriverAddDeviceType AddDevice;

public:

    // This is public to allow the C function FxCoreDriverUnload to call it
    FxDriverUnload              m_DriverUnload;

    FxDriver(
        __in MdDriverObject DriverObject,
        __in PWDF_DRIVER_CONFIG DriverConfig,
        __in PFX_DRIVER_GLOBALS FxDriverGlobals
        );

    ~FxDriver();

    static
    VOID
    _InitializeDriverName(
        __in PFX_DRIVER_GLOBALS Globals,
        __in PCUNICODE_STRING RegistryPath
        );

    static
    VOID
    _InitializeTag(
        __in PFX_DRIVER_GLOBALS Globals,
        __in PWDF_DRIVER_CONFIG Config
        );

    static
    FxDriver*
    GetFxDriver(
        __in MdDriverObject DriverObject
        );

    _Must_inspect_result_
    NTSTATUS
    AllocateDriverObjectExtensionAndStoreFxDriver(
        VOID
        );



































    __inline
    WDFDRIVER
    GetHandle(
        VOID
        )
    {
        return (WDFDRIVER) GetObjectHandle();
    }

#if (FX_CORE_MODE == FX_CORE_KERNEL_MODE)

    _Must_inspect_result_
    NTSTATUS
    AddDevice(
        __in MdDeviceObject PhysicalDeviceObject
        );

#else

    _Must_inspect_result_
    NTSTATUS
    FxDriver::AddDevice(
        _In_  IWudfDeviceStack *        DevStack,
        _In_  LPCWSTR                   KernelDeviceName,
        _In_opt_ HKEY                   PdoKey,
        _In_  LPCWSTR                   ServiceName,
        _In_  LPCWSTR                   DevInstanceID,
        _In_  ULONG                     DriverID
        );
#endif

    VOID
    InitializeInternal(
        VOID
        );

    _Must_inspect_result_
    FxString *
    GetRegistryPath(
        VOID
        );

    PUNICODE_STRING
    GetRegistryPathUnicodeString(
        VOID
        )
    {
        return &m_RegistryPath;
    }

    __inline
    MdDriverObject
    GetDriverObject(
        VOID
        )
    {
        return m_DriverObject.GetObject();
    }

    _Must_inspect_result_
    NTSTATUS
    Initialize(
        __in PCUNICODE_STRING RegistryPath,
        __in PWDF_DRIVER_CONFIG Config,
        __in_opt PWDF_OBJECT_ATTRIBUTES DriverAttributes
        );

    //
    // The following methods support the callback constraints
    // and handle locking and deferral
    //
    VOID
    ConfigureConstraints(
        __in_opt PWDF_OBJECT_ATTRIBUTES DriverAttributes
        );

    //
    // IFxHasCallbacks Support
    //

    virtual
    VOID
    GetConstraints(
        __out WDF_EXECUTION_LEVEL*       ExecutionLevel,
        __out WDF_SYNCHRONIZATION_SCOPE* SynchronizationScope
        ) {

        if (ExecutionLevel != NULL) {
            *ExecutionLevel = m_ExecutionLevel;
        }

        if (SynchronizationScope != NULL) {
            *SynchronizationScope = m_SynchronizationScope;
        }
    }

    virtual
    FxCallbackLock*
    GetCallbackLockPtr(
        __deref_out FxObject** LockObject
        ) {

        if (LockObject != NULL) {
            *LockObject = m_CallbackLockObjectPtr;
        }

        return m_CallbackLockPtr;
    }

    //
    // IFxAssociation Support
    //
    virtual
    NTSTATUS
    QueryInterface(
        __inout FxQueryInterfaceParams* Params
        )
    {
        switch (Params->Type) {
        case FX_TYPE_DRIVER:
            *Params->Object = (FxDriver*) this;
            break;

        default:
            return FxNonPagedObject::QueryInterface(Params); // __super call
        }

        return STATUS_SUCCESS;
    }

    virtual
    VOID
    DeleteObject(
        VOID
        )
    {
        //
        // If diposed at > PASSIVE, we will cause a deadlock in FxDriver::Dispose
        // when we call into  the dispose list to wait for empty when we are in
        // the context of the dispose list's work item.
        //
        ASSERT(Mx::MxGetCurrentIrql() == PASSIVE_LEVEL);

        FxNonPagedObject::DeleteObject(); // __super call
    }

    virtual
    BOOLEAN
    Dispose(
        VOID
        );

    __inline
    FxDisposeList*
    GetDisposeList(
        )
    {
        return m_DisposeList;
    }

    __inline
    PFN_WDF_DRIVER_DEVICE_ADD
    GetDriverDeviceAddMethod(
        )
    {
        return m_DriverDeviceAdd.Method;
    }

    static
    MdDriverUnloadType Unload;

#if FX_IS_USER_MODE
private:

    //
    // Open the handle to the driver service parameters key
    // that we keep opened for use from user mode.
    //
    NTSTATUS
    OpenParametersKey(
        VOID
        );

    VOID
    ClearDriverObjectFxDriver(
        VOID
        );

public:

    __inline
    HKEY
    GetDriverParametersKey(
        VOID
        )
    {
        return m_DriverParametersKey;
    }
#endif

#if (FX_CORE_MODE == FX_CORE_USER_MODE)

    VOID
    SetDriverObjectFlag(
        _In_ FxDriverObjectUmFlags Flag
        )
    {
        m_DriverObject.SetDriverObjectFlag(Flag);
    }

    BOOLEAN
    IsDriverObjectFlagSet(
        _In_ FxDriverObjectUmFlags Flag
        )
    {
        return m_DriverObject.IsDriverObjectFlagSet(Flag);
    }

#endif

};

#endif // _FXDRIVER_H_