fxlibrarycommon.h File Reference

Go to the source code of this file.

Macros
#define	_LIT_(a)   # a
#define	LITERAL(a)   _LIT_(a)
#define	__PrintUnfiltered(...)    DbgPrintEx(DPFLTR_DEFAULT_ID, DPFLTR_ERROR_LEVEL, __VA_ARGS__);
#define	__Print(_x_)
#define	WDF_ENHANCED_VERIFIER_OPTIONS_VALUE_NAME   L"EnhancedVerifierOptions"

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

Functions
_Must_inspect_result_ NTSTATUS	FxLibraryCommonCommission (VOID)
_Must_inspect_result_ NTSTATUS	FxLibraryCommonDecommission (VOID)
_Must_inspect_result_ NTSTATUS	FxLibraryCommonRegisterClient (__inout PWDF_BIND_INFO Info, __deref_out PWDF_DRIVER_GLOBALS *WdfDriverGlobals, __in_opt PCLIENT_INFO ClientInfo)
_Must_inspect_result_ NTSTATUS	FxLibraryCommonUnregisterClient (__in PWDF_BIND_INFO Info, __in PWDF_DRIVER_GLOBALS WdfDriverGlobals)
VOID	GetEnhancedVerifierOptions (__in PCLIENT_INFO ClientInfo, __out PULONG Options)
VOID	LibraryLogEvent (__in PDRIVER_OBJECT DriverObject, __in NTSTATUS ErrorCode, __in NTSTATUS FinalStatus, __in PWSTR ErrorInsertionString, __in_bcount(RawDataLen) PVOID RawDataBuf, __in USHORT RawDataLen)

Variables
ULONG	WdfLdrDbgPrintOn
PCHAR	WdfLdrType
WDFVERSION	WdfVersion
RTL_OSVERSIONINFOW	gOsVersion

Macro Definition Documentation

__Print

#define __Print

(

_x_

)

Value:

{                                                                              \
    if (WdfLdrDbgPrintOn) {                                                    \
        DbgPrintEx(DPFLTR_DEFAULT_ID, DPFLTR_ERROR_LEVEL, "%s: ", WdfLdrType); \
        __PrintUnfiltered _x_                                                  \
    }                                                                          \
}

Definition at line 24 of file fxlibrarycommon.h.

__PrintUnfiltered

#define __PrintUnfiltered

(

...

)

DbgPrintEx(DPFLTR_DEFAULT_ID, DPFLTR_ERROR_LEVEL, __VA_ARGS__);

Definition at line 21 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 32 of file fxlibrarycommon.h.

Typedef Documentation

PFN_RTL_GET_VERSION

typedef NTSTATUS(* PFN_RTL_GET_VERSION) (__out PRTL_OSVERSIONINFOW VersionInformation)

Definition at line 35 of file fxlibrarycommon.h.

Function Documentation

FxLibraryCommonCommission()

_Must_inspect_result_ 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;
}

Referenced by WDF_LIBRARY_COMMISSION().

FxLibraryCommonDecommission()

_Must_inspect_result_ 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;
}

Referenced by WDF_LIBRARY_DECOMMISSION().

FxLibraryCommonRegisterClient()

_Must_inspect_result_ NTSTATUS FxLibraryCommonRegisterClient	(	__inout PWDF_BIND_INFO	Info,
		__deref_out PWDF_DRIVER_GLOBALS *	WdfDriverGlobals,
		__in_opt PCLIENT_INFO	ClientInfo
	)

Definition at line 330 of file fxlibrarycommon.cpp.

{
    NTSTATUS           status;
    UNICODE_STRING serviceName = { 0 };
 
    status = STATUS_INVALID_PARAMETER;
 
    __Print((LITERAL(WDF_LIBRARY_REGISTER_CLIENT) ": enter\n"));
 
    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;
    }
 
    ASSERT(Info->FuncCount);
 
 
    *WdfDriverGlobals = NULL;
 
    //
    // 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_V1_15) {
        //
        // Make sure table count matches exactly with previously
        // released framework version table sizes.
        //
        switch (Info->FuncCount) {
 
        case WdfFunctionTableNumEntries_V1_15:
        case WdfFunctionTableNumEntries_V1_13:
        case WdfFunctionTableNumEntries_V1_11:
        case WdfFunctionTableNumEntries_V1_9:
     // case WdfFunctionTableNumEntries_V1_7:  // both 1.7 and 1.5 have 387 functions
        case WdfFunctionTableNumEntries_V1_5:
        case WdfFunctionTableNumEntries_V1_1:
        case WdfFunctionTableNumEntries_V1_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.
        if (Info->FuncCount != WdfFunctionTableNumEntries) {
            RtlZeroMemory(&serviceName, sizeof(UNICODE_STRING));
 
            if (IsClientInfoValid(ClientInfo)) {
                GetNameFromPath(ClientInfo->RegistryPath, &serviceName);
            }
            else {
                RtlInitUnicodeString(&serviceName, L"Unknown");
            }
 
            //
            // Report a DbgPrint message, telemetry event and an ETW event that
            // will serve as diagnostic aid.
            //
            ReportDdiFunctionCountMismatch((PCUNICODE_STRING)&serviceName,
                                        Info->FuncCount,
                                        WdfFunctionTableNumEntries);
 
            //
            // If loader diagnostics are enabled and KD is connected, break-in
            //
            if (WdfLdrDbgPrintOn && KD_DEBUGGER_ENABLED &&
                !KD_DEBUGGER_NOT_PRESENT) {
                DbgBreakPoint();
            }
            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) {
 
            //
            // 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_V1_13) {
                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"));
 
            LockVerifierSection(fxDriverGlobals, ClientInfo->RegistryPath);
 
            if (Microsoft_Windows_DriverFrameworks_KernelMode_PerformanceHandle == NULL) {
                EventRegisterMicrosoft_Windows_DriverFrameworks_KernelMode_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_V1_13) {
                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));
 
    return status;
}

Referenced by WDF_LIBRARY_REGISTER_CLIENT().

FxLibraryCommonUnregisterClient()

_Must_inspect_result_ NTSTATUS FxLibraryCommonUnregisterClient	(	__in PWDF_BIND_INFO	Info,
		__in PWDF_DRIVER_GLOBALS	WdfDriverGlobals
	)

Definition at line 524 of file fxlibrarycommon.cpp.

{
    NTSTATUS status;
 
    __Print((LITERAL(WDF_LIBRARY_UNREGISTER_CLIENT) ": enter\n"));
 
    ASSERT(Info);
    ASSERT(WdfDriverGlobals);
 
    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);
 
        //
        // unlock enhanced-verifier image sections
        //
        if (IsFxVerifierFunctionTableHooking(pFxDriverGlobals)) {
            UnlockVerifierSection(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;
}

Referenced by WDF_LIBRARY_UNREGISTER_CLIENT().

GetEnhancedVerifierOptions()

VOID GetEnhancedVerifierOptions	(	__in PCLIENT_INFO	ClientInfo,
		__out PULONG	Options
	)

Definition at line 583 of file fxlibrarycommon.cpp.

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

Referenced by FxLibraryCommonRegisterClient().

LibraryLogEvent()

VOID LibraryLogEvent	(	__in PDRIVER_OBJECT	DriverObject,
		__in NTSTATUS	ErrorCode,
		__in NTSTATUS	FinalStatus,
		__in PWSTR	ErrorInsertionString,
		__in_bcount(RawDataLen) PVOID	RawDataBuf,
		__in USHORT	RawDataLen
	)

Definition at line 633 of file fxlibrarycommon.cpp.

{
    PIO_ERROR_LOG_PACKET errorLogEntry;
    size_t               errorLogEntrySize;                  // [including null]
    size_t               errorInsertionStringByteSize = 0;
 
    if (ErrorInsertionString) {
        errorInsertionStringByteSize = wcslen(ErrorInsertionString) * sizeof(WCHAR);
        errorInsertionStringByteSize += sizeof(UNICODE_NULL);
    }
 
    errorLogEntrySize = sizeof(IO_ERROR_LOG_PACKET) + RawDataLen + errorInsertionStringByteSize;
 
    //
    // Log an error.
    //
    //
    // prefast complains about comparison of constant with constant here
    //
#pragma prefast(suppress:__WARNING_CONST_CONST_COMP, "If ErrorInsertionString is not null then this is not a constant")
    if (errorLogEntrySize <= ERROR_LOG_MAXIMUM_SIZE) {
 
        errorLogEntry = (PIO_ERROR_LOG_PACKET)IoAllocateErrorLogEntry(DriverObject,
            (UCHAR)errorLogEntrySize);
 
        if (errorLogEntry != NULL) {
 
            RtlZeroMemory(errorLogEntry, errorLogEntrySize);
 
            errorLogEntry->ErrorCode = ErrorCode;
            errorLogEntry->FinalStatus = FinalStatus;
            errorLogEntry->NumberOfStrings = (ErrorInsertionString) ? 1 : 0;
            errorLogEntry->DumpDataSize = RawDataLen;
            errorLogEntry->StringOffset = (FIELD_OFFSET(IO_ERROR_LOG_PACKET, DumpData)) + errorLogEntry->DumpDataSize;
 
            //
            // Insertion strings follow dumpdata and since there is no dumpdata we place the
            // insertion string at the start offset of the dumpdata.
            //
            if (RawDataBuf) {
                RtlCopyMemory(errorLogEntry->DumpData,
                    RawDataBuf,
                    RawDataLen);
            }
 
            if (ErrorInsertionString) {
                RtlCopyMemory(((PCHAR)errorLogEntry->DumpData) + RawDataLen,
                    ErrorInsertionString,
                    errorInsertionStringByteSize);
            }
 
            IoWriteErrorLogEntry(errorLogEntry);
        }
    }
 
    return;
}

Referenced by ReportDdiFunctionCountMismatch(), and WDF_LIBRARY_REGISTER_CLIENT().

Variable Documentation

gOsVersion

RTL_OSVERSIONINFOW gOsVersion

extern

Definition at line 104 of file version.cpp.

Referenced by FxLibraryCommonCommission().

WdfLdrDbgPrintOn

ULONG WdfLdrDbgPrintOn

extern

Definition at line 106 of file version.cpp.

Referenced by FxLibraryCommonRegisterClient().

WdfLdrType

PCHAR WdfLdrType

extern

Definition at line 108 of file version.cpp.

Referenced by FxInitializeBugCheckDriverInfo().

WdfVersion

WDFVERSION WdfVersion

extern

Referenced by FxLibraryCommonRegisterClient(), and RosInitWdf().