fxlibrarycommon.h File Reference

Go to the source code of this file.

Macros
#define	_LIT_(a)   # a
#define	LITERAL(a)   _LIT_(a)
#define	__Print(_x_)
#define	WDF_ENHANCED_VERIFIER_OPTIONS_VALUE_NAME   L"EnhancedVerifierOptions"

Typedefs
typedef NTSTATUS(*	PFN_RTL_GET_VERSION) (OUT PRTL_OSVERSIONINFOW VersionInformation)

Functions
NTSTATUS	FxLibraryCommonCommission (VOID)
NTSTATUS	FxLibraryCommonDecommission (VOID)
NTSTATUS	FxLibraryCommonRegisterClient (PWDF_BIND_INFO Info, PWDF_DRIVER_GLOBALS *WdfDriverGlobals, PCLIENT_INFO ClientInfo)
NTSTATUS	FxLibraryCommonUnregisterClient (PWDF_BIND_INFO Info, PWDF_DRIVER_GLOBALS WdfDriverGlobals)
VOID	GetEnhancedVerifierOptions (PCLIENT_INFO ClientInfo, PULONG Options)

Variables
ULONG	WdfLdrDbgPrintOn
PCHAR	WdfLdrType
WDFVERSION	WdfVersion
RTL_OSVERSIONINFOW	gOsVersion

Macro Definition Documentation

__Print

#define __Print

(

_x_

)

Value:

{                                       \
    if (WdfLdrDbgPrintOn) {             \
    }                                   \
}

Definition at line 24 of file fxlibrarycommon.h.

_LIT_

#define _LIT_

(

a

)

# a

Definition at line 18 of file fxlibrarycommon.h.

LITERAL

#define LITERAL

(

a

)

_LIT_(a)

Definition at line 19 of file fxlibrarycommon.h.

WDF_ENHANCED_VERIFIER_OPTIONS_VALUE_NAME

#define WDF_ENHANCED_VERIFIER_OPTIONS_VALUE_NAME   L"EnhancedVerifierOptions"

Definition at line 30 of file fxlibrarycommon.h.

Typedef Documentation

PFN_RTL_GET_VERSION

typedef NTSTATUS(* PFN_RTL_GET_VERSION) (OUT PRTL_OSVERSIONINFOW VersionInformation)

Definition at line 33 of file fxlibrarycommon.h.

Function Documentation

FxLibraryCommonCommission()

NTSTATUS FxLibraryCommonCommission

(

VOID

)

Definition at line 224 of file fxlibrarycommon.cpp.

{
    DECLARE_CONST_UNICODE_STRING(usName, L"RtlGetVersion");
    PFN_RTL_GET_VERSION pRtlGetVersion = NULL;
    NTSTATUS   status;
 
    __Print((LITERAL(WDF_LIBRARY_COMMISSION) "\n"));
 
    //
    // Commission this version's DLL globals.
    //
    status = FxLibraryGlobalsCommission();
 
    if (!NT_SUCCESS(status)) {
        __Print(("FxLibraryGlobalsCommission failed %X\n", status));
        return status;
    }
 
    //
    // register telemetry provider.
    //
    RegisterTelemetryProvider();
 
    //
    // Initialize internal WPP tracing.
    //
    status = FxTraceInitialize();
    if (NT_SUCCESS(status)) {
        FxLibraryGlobals.InternalTracingInitialized = TRUE;
    }
    else {
        __Print(("Failed to initialize tracing for WDF\n"));
 
        //
        // Failure to initialize is not critical enough to fail driver load.
        //
        status = STATUS_SUCCESS;
    }
 
    //
    // Attempt to load RtlGetVersion (works for > w2k).
    //
    pRtlGetVersion = (PFN_RTL_GET_VERSION) MmGetSystemRoutineAddress(
        (PUNICODE_STRING) &usName
        );
 
    //
    // Now attempt to get this OS's version.
    //
    if (pRtlGetVersion != NULL) {
        pRtlGetVersion(&gOsVersion);
    }
 
    __Print(("OsVersion(%d.%d)\n",
             gOsVersion.dwMajorVersion,
             gOsVersion.dwMinorVersion ));
 
    //
    // Init triage info for 9f bugcheck analysis.
    //
    GetTriageInfo();
 
    return STATUS_SUCCESS;
}

FxLibraryCommonDecommission()

NTSTATUS FxLibraryCommonDecommission

(

VOID

)

Definition at line 293 of file fxlibrarycommon.cpp.

{
    __Print((LITERAL(WDF_LIBRARY_DECOMMISSION) ": enter\n"));
 
    //
    // Uninitialize WPP tracing.
    //
    if (FxLibraryGlobals.InternalTracingInitialized) {
        TraceUninitialize();
        FxLibraryGlobals.InternalTracingInitialized = FALSE;
    }
 
    //
    // Unregister telemetry provider.
    //
    UnregisterTelemetryProvider();
 
    EventUnregisterMicrosoft_Windows_DriverFrameworks_KernelMode_Performance();
 
    //
    // Decommission this version's DLL globals.
    //
    FxLibraryGlobalsDecommission();
 
    //
    // Note: This is the absolute last action from WDF library (dynamic or static).
    //       The image is likely to be deleted after returning.
    //
    __Print((LITERAL(WDF_LIBRARY_DECOMMISSION) ": exit\n"));
 
    return STATUS_SUCCESS;
}

FxLibraryCommonRegisterClient()

NTSTATUS FxLibraryCommonRegisterClient	(	PWDF_BIND_INFO	Info,
		PWDF_DRIVER_GLOBALS *	WdfDriverGlobals,
		PCLIENT_INFO	ClientInfo
	)

Definition at line 240 of file fxlibrarycommon.cpp.

{
    NTSTATUS           status;
 
    status = STATUS_INVALID_PARAMETER;
 
    __Print((LITERAL(WDF_LIBRARY_REGISTER_CLIENT) ": enter\n"));
 
    ASSERT(Info != NULL && Info->FuncCount != 0);
    ASSERT(WdfDriverGlobals != 0);
 
    if (Info == NULL || WdfDriverGlobals == NULL || Info->FuncTable == NULL) {
        __Print((LITERAL(WDF_LIBRARY_REGISTER_CLIENT)
                 ": NULL parameter -- %s\n",
                 (Info == NULL)             ? "PWDF_BIND_INFO" :
                 (WdfDriverGlobals == NULL) ? "PWDF_DRIVER_GLOBALS *" :
                 (Info->FuncTable == NULL)  ? "PWDF_BIND_INFO->FuncTable" :
                                              "unknown" ));
        goto Done;
    }
 
    *WdfDriverGlobals = NULL;
 
    ASSERT(Info->FuncCount <= WdfVersion.FuncCount);
 
    //
    // WdfVersion.Count is initialized in FxDynamics.h and is never changed.
    // Prefast is unable to make that determination.
    //
    __assume(WdfVersion.FuncCount == sizeof(WDFFUNCTIONS)/sizeof(PVOID));
 
    if (Info->FuncCount > WdfVersion.FuncCount) {
        __Print((LITERAL(WDF_LIBRARY_REGISTER_CLIENT)
                 ": version mismatch detected in function table count: client"
                 "has 0x%x,  library has 0x%x\n",
                 Info->FuncCount, WdfVersion.FuncCount));
        goto Done;
    }
 
    if (Info->FuncCount <= WdfFunctionTableNumEntries_V2_15) {
 
        switch (Info->FuncCount) {
 
        case WdfFunctionTableNumEntries_V2_15:
        case WdfFunctionTableNumEntries_V2_0:
            break;
 
        default:
            __Print((LITERAL(WDF_LIBRARY_REGISTER_CLIENT)
                     ": Function table count 0x%x doesn't match any previously "
                     "released framework version table size\n",
                     Info->FuncCount));
            goto Done;
        }
    }
    else {
        //
        // Client version is same as framework version. Make
        // sure table count is exact.
        //
        // Note that in order for build-to-build upgrade to work, the following
        // check should be commented out during active development.
        //
        // DO CHANGE it to a real failure towards the tail end of release to
        // prevent cases where a driver sneaks out into public after being built
        // with a non-RTM version of WDF and has a function count less than the
        // final count. An HCK test has been added to ensure such drivers are
        // caught early. This check is an additional prevention.
        //
        if (Info->FuncCount != WdfFunctionTableNumEntries) {
            __Print(("Framework function table size (%d) doesn't match "
                   "with client (%d). Rebuild the client driver.",
                   WdfFunctionTableNumEntries, Info->FuncCount));
 
            ASSERT(FALSE);
            goto Done;
        }
    }
 
    //
    // Allocate an new FxDriverGlobals area for this driver.
    //
    *WdfDriverGlobals = FxAllocateDriverGlobals();
 
    if (*WdfDriverGlobals) {
        BOOLEAN isFunctinTableHookingOn  = FALSE;
        BOOLEAN isPerformanceAnalysisOn  = FALSE;
        PFX_DRIVER_GLOBALS fxDriverGlobals = NULL;
        //
        // Check the registry to see if Enhanced verifier is on for this driver.
        // if registry read fails, options value remains unchanged.
        // store enhanced verifier options in driver globals
        //
        fxDriverGlobals = GetFxDriverGlobals(*WdfDriverGlobals);
        GetEnhancedVerifierOptions(ClientInfo, &fxDriverGlobals->FxEnhancedVerifierOptions);
        isFunctinTableHookingOn = IsFxVerifierFunctionTableHooking(fxDriverGlobals);
        isPerformanceAnalysisOn = IsFxPerformanceAnalysis(fxDriverGlobals);
 
        //
        // Set-up the function table. Enhanced verifier and Performance analysis is off by default.
        //
        if (isFunctinTableHookingOn == FALSE && isPerformanceAnalysisOn == FALSE) {
            //
            // Set-up the function table
            //
            // Starting in 2.15 we reference a copy of the DDI table in WDF01000,
            // prior to that we copy the entire table to local memory.
            //
            if (Info->FuncCount <= WdfFunctionTableNumEntries_V2_0) {
                RtlCopyMemory( Info->FuncTable,
                               &WdfVersion.Functions,
                               Info->FuncCount * sizeof(PVOID) );
            }
            else {
                //
                // FuncTable arrives with a ptr to &WdfFunctions, so we update
                // what WdfFunctions points to
                //
                *((WDFFUNC**) Info->FuncTable) = (WDFFUNC*) &WdfVersion.Functions;
            }
        }
        else {
            __Print((LITERAL(WDF_LIBRARY_REGISTER_CLIENT)
                     ": Enhanced Verification is ON \n"));
 
            if (Microsoft_Windows_DriverFrameworks_UserMode_PerformanceHandle == NULL)
            {
                EventRegisterMicrosoft_Windows_DriverFrameworks_UserMode_Performance();
            }
 
            //
            // Enhanced verification is on. Return verifier function table
            //
            // Starting in 1.15 we reference a copy of the DDI table in WDF01000,
            // prior to that we copy the entire table to local memory.
            //
            if (Info->FuncCount <= WdfFunctionTableNumEntries_V2_0) {
                RtlCopyMemory( Info->FuncTable,
                               &VfWdfVersion.Functions,
                               Info->FuncCount * sizeof(PVOID) );
            }
            else {
                //
                // FuncTable arrives with a ptr to &WdfFunctions, so we update
                // what WdfFunctions points to.
                //
                *((WDFFUNC**) Info->FuncTable) = (WDFFUNC*) &VfWdfVersion.Functions;
            }
        }
 
        status = STATUS_SUCCESS;
 
        __Print((LITERAL(WDF_LIBRARY_REGISTER_CLIENT)
                 ": WdfFunctions %p\n", Info->FuncTable));
    }
 
Done:
    __Print((LITERAL(WDF_LIBRARY_REGISTER_CLIENT)
             ": exit: status %X\n", status));
 
    if (!NT_SUCCESS(status)) {
        FX_VERIFY(DRIVER(BadArgument, TODO),
            TRAPMSG("Version mismatch detected in function table count. Recompile"
            " driver with correct headers"));
    }
 
    return status;
}

FxLibraryCommonUnregisterClient()

NTSTATUS FxLibraryCommonUnregisterClient	(	PWDF_BIND_INFO	Info,
		PWDF_DRIVER_GLOBALS	WdfDriverGlobals
	)

Definition at line 414 of file fxlibrarycommon.cpp.

{
    NTSTATUS status;
 
    __Print((LITERAL(WDF_LIBRARY_UNREGISTER_CLIENT) ": enter\n"));
 
    ASSERT(Info != NULL);
    ASSERT(WdfDriverGlobals != NULL);
 
    if (Info != NULL && WdfDriverGlobals != NULL) {
        PFX_DRIVER_GLOBALS pFxDriverGlobals;
 
        status = STATUS_SUCCESS;
 
        pFxDriverGlobals = GetFxDriverGlobals(WdfDriverGlobals);
 
        //
        // Destroy this FxDriver instance, if its still indicated.
        //
        if (pFxDriverGlobals->Driver != NULL) {
            //
            // Association support, we are a root with no parent
            //
            pFxDriverGlobals->Driver->DeleteObject();
 
            FxDestroy(pFxDriverGlobals);
        }
 
        //
        // Stop IFR logging
        //
        FxIFRStop(pFxDriverGlobals);
 
        //
        // This will free the client's FxDriverGlobals area
        //
        FxFreeDriverGlobals(WdfDriverGlobals);
    }
    else {
        status = STATUS_UNSUCCESSFUL;
    }
 
    __Print((LITERAL(WDF_LIBRARY_UNREGISTER_CLIENT)
             ": exit: status %X\n", status));
 
    return status;
}

GetEnhancedVerifierOptions()

VOID GetEnhancedVerifierOptions	(	PCLIENT_INFO	ClientInfo,
		PULONG	Options
	)

Definition at line 466 of file fxlibrarycommon.cpp.

{
    NTSTATUS status;
    ULONG value;
    FxAutoRegKey hWdf;
    DECLARE_CONST_UNICODE_STRING(valueName, WDF_ENHANCED_VERIFIER_OPTIONS_VALUE_NAME);
 
    *Options = 0;
    if (ClientInfo == NULL                       ||
        ClientInfo->Size != sizeof(CLIENT_INFO)  ||
        ClientInfo->RegistryPath == NULL         ||
        ClientInfo->RegistryPath->Length == 0    ||
        ClientInfo->RegistryPath->Buffer == NULL ||
        Options == NULL) {
 
        __Print((LITERAL(WDF_LIBRARY_REGISTER_CLIENT)
                 ": Invalid ClientInfo received from wudfldr \n"));
        return;
    }
 
    status = FxRegKey::_OpenKey(NULL,
                                ClientInfo->RegistryPath,
                                &hWdf.m_Key,
                                KEY_READ);
    if (!NT_SUCCESS(status)) {
        return;
    }
 
    status = FxRegKey::_QueryULong(
        hWdf.m_Key, &valueName, &value);
 
    //
    // Examine key values and set Options only on success.
    //
    if (NT_SUCCESS(status)) {
        if (value) {
            *Options = value;
        }
    }
}

Variable Documentation

gOsVersion

RTL_OSVERSIONINFOW gOsVersion

extern

Definition at line 104 of file version.cpp.

WdfLdrDbgPrintOn

ULONG WdfLdrDbgPrintOn

extern

Definition at line 106 of file version.cpp.

Referenced by DriverEntry().

WdfLdrType

PCHAR WdfLdrType

extern

Definition at line 108 of file version.cpp.

WdfVersion

WDFVERSION WdfVersion

extern