fxtelemetry.hpp File Reference

#include <strsafe.h>
#include "fxtelemetrycommon.hpp"
#include "fxtelemetrykm.hpp"

Include dependency graph for fxtelemetry.hpp:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	FX_TELEMETRY_ENABLED(TraceHandle, Globals)    (TraceHandle && IsDriverTelemetryContextInitialized(Globals)) \
#define	WDF_CENSUS_EVT_DATA_COMMON(FxGlobals)
#define	WDF_CENSUS_EVT_WRITE_DRIVER_LOAD(TraceHandle, Globals, DrvImage, WdfVersion)
#define	MIN_HOURS_BEFORE_NEXT_LOG   24
#define	BASE_10   (10)
#define	WDF_LAST_TELEMETRY_LOG_TIME_VALUE   L"TimeOfLastTelemetryLog"
#define	WDF_DRIVER_IMAGE_NAME_VALUE   L"ImagePath"
#define	WDF_VERSION_STRING_SIZE_INCLUDING_SEPARATOR_CCH   10

Typedefs
typedef enum _FX_TELEMETRY_DO_ONCE_BITS	FX_TELEMETRY_DO_ONCE_BITS

Enumerations
enum	_FX_TELEMETRY_DO_ONCE_BITS { DeviceStartEventBit = 0 }
enum	FxDeviceInfoFlags : USHORT {   DeviceInfoLineBasedLevelTriggeredInterrupt = 0x1 , DeviceInfoLineBasedEdgeTriggeredInterrupt = 0x2 , DeviceInfoMsiXOrSingleMsi22Interrupt = 0x4 , DeviceInfoMsi22MultiMessageInterrupt = 0x8 ,   DeviceInfoPassiveLevelInterrupt = 0x10 , DeviceInfoDmaBusMaster = 0x20 , DeviceInfoDmaSystem = 0x40 , DeviceInfoDmaSystemDuplex = 0x80 ,   DeviceInfoHasStaticChildren = 0x100 , DeviceInfoHasDynamicChildren = 0x200 , DeviceInfoIsUsingDriverWppRecorder = 0x400 }

Functions
BOOLEAN __inline	IsDeviceInfoFlagSet (_In_ USHORT DeviceInfo, _In_ FxDeviceInfoFlags Flag)
VOID	AllocAndInitializeTelemetryContext (_In_ PFX_TELEMETRY_CONTEXT *TelemetryContext)
__inline BOOLEAN	IsDriverTelemetryContextInitialized (_In_ PFX_DRIVER_GLOBALS FxDrvGlobals)
VOID	RegisterTelemetryProvider (VOID)
VOID	UnregisterTelemetryProvider (VOID)
VOID	LogDeviceStartTelemetryEvent (_In_ PFX_DRIVER_GLOBALS Globals, _In_opt_ FxDevice *Fdo)
VOID	LogDriverInfoStream (_In_ PFX_DRIVER_GLOBALS Globals, _In_opt_ FxDevice *Fdo)
_Must_inspect_result_ NTSTATUS	GetImageName (_In_ PFX_DRIVER_GLOBALS DriverGlobals, _Out_ PUNICODE_STRING ImageName)
VOID __inline	BuildStringFromPartialInfo (_In_ PKEY_VALUE_PARTIAL_INFORMATION Info, _Out_ PUNICODE_STRING String)
VOID	GetNameFromPath (_In_ PCUNICODE_STRING Path, _Out_ PUNICODE_STRING Name)

Macro Definition Documentation

BASE_10

#define BASE_10   (10)

Definition at line 90 of file fxtelemetry.hpp.

FX_TELEMETRY_ENABLED

#define FX_TELEMETRY_ENABLED	(		TraceHandle,
			Globals
	)		(TraceHandle && IsDriverTelemetryContextInitialized(Globals)) \

Definition at line 45 of file fxtelemetry.hpp.

MIN_HOURS_BEFORE_NEXT_LOG

#define MIN_HOURS_BEFORE_NEXT_LOG   24

Definition at line 89 of file fxtelemetry.hpp.

WDF_CENSUS_EVT_DATA_COMMON

#define WDF_CENSUS_EVT_DATA_COMMON

(

FxGlobals

)

Value:

    TraceLoggingStruct(1, "CensusCommonV1"),                      \
        TraceLoggingGuid((FxGlobals)->TelemetryContext->DriverSessionGUID, "SessionGUID")

Definition at line 48 of file fxtelemetry.hpp.

WDF_CENSUS_EVT_WRITE_DRIVER_LOAD

#define WDF_CENSUS_EVT_WRITE_DRIVER_LOAD	(		TraceHandle,
			Globals,
			DrvImage,
			WdfVersion
	)

Value:

            TraceLoggingWrite(TraceHandle,                                             \
                "WdfCensusEvtDrvLoad",                                                 \
                WDF_TELEMETRY_EVT_KEYWORDS,                                            \
                WDF_CENSUS_EVT_DATA_COMMON(Globals),                                   \
                TraceLoggingStruct(9, "DriverInfo"                                                                                       ), \
                    TraceLoggingString((Globals)->Public.DriverName,                                         "DriverService"             ), \
                    TraceLoggingWideString(DrvImage,                                                         "DriverImage"               ), \
                    TraceLoggingWideString(WdfVersion,                                                       "WdfVersion"                ), \
                    TraceLoggingUInt32((Globals)->WdfBindInfo->Version.Major,                                "DriverVersionMajor"        ), \
                    TraceLoggingUInt32((Globals)->WdfBindInfo->Version.Minor,                                "DriverVersionMinor"        ), \
                    TraceLoggingBoolean((Globals)->FxVerifierOn,                                             "FxVerifierOn"              ), \
                    TraceLoggingBoolean(!!((Globals)->Public.DriverFlags & WdfDriverInitNonPnpDriver),       "DriverNonPnP"              ), \
                    TraceLoggingBoolean(!!((Globals)->Public.DriverFlags & WdfDriverInitNoDispatchOverride), "DriverNoDispatchOverride"  ), \
                    TraceLoggingUInt32((Globals)->FxEnhancedVerifierOptions,                                 "FxEnhancedVeriferOptions"  )  \
                );

Definition at line 72 of file fxtelemetry.hpp.

WDF_DRIVER_IMAGE_NAME_VALUE

#define WDF_DRIVER_IMAGE_NAME_VALUE   L"ImagePath"

Definition at line 93 of file fxtelemetry.hpp.

WDF_LAST_TELEMETRY_LOG_TIME_VALUE

#define WDF_LAST_TELEMETRY_LOG_TIME_VALUE   L"TimeOfLastTelemetryLog"

Definition at line 92 of file fxtelemetry.hpp.

WDF_VERSION_STRING_SIZE_INCLUDING_SEPARATOR_CCH

#define WDF_VERSION_STRING_SIZE_INCLUDING_SEPARATOR_CCH   10

Definition at line 115 of file fxtelemetry.hpp.

Typedef Documentation

FX_TELEMETRY_DO_ONCE_BITS

typedef enum _FX_TELEMETRY_DO_ONCE_BITS FX_TELEMETRY_DO_ONCE_BITS

Enumeration Type Documentation

_FX_TELEMETRY_DO_ONCE_BITS

enum _FX_TELEMETRY_DO_ONCE_BITS

Enumerator
DeviceStartEventBit

Definition at line 56 of file fxtelemetry.hpp.

                                        {
    DeviceStartEventBit = 0
} FX_TELEMETRY_DO_ONCE_BITS;

FxDeviceInfoFlags

enum FxDeviceInfoFlags : USHORT

Enumerator
DeviceInfoLineBasedLevelTriggeredInterrupt
DeviceInfoLineBasedEdgeTriggeredInterrupt
DeviceInfoMsiXOrSingleMsi22Interrupt
DeviceInfoMsi22MultiMessageInterrupt
DeviceInfoPassiveLevelInterrupt
DeviceInfoDmaBusMaster
DeviceInfoDmaSystem
DeviceInfoDmaSystemDuplex
DeviceInfoHasStaticChildren
DeviceInfoHasDynamicChildren
DeviceInfoIsUsingDriverWppRecorder

Definition at line 98 of file fxtelemetry.hpp.

                       : USHORT {
    DeviceInfoLineBasedLevelTriggeredInterrupt =   0x1,
    DeviceInfoLineBasedEdgeTriggeredInterrupt  =   0x2,
    DeviceInfoMsiXOrSingleMsi22Interrupt       =   0x4,
    DeviceInfoMsi22MultiMessageInterrupt       =   0x8,
    DeviceInfoPassiveLevelInterrupt            =  0x10,
    DeviceInfoDmaBusMaster                     =  0x20,
    DeviceInfoDmaSystem                        =  0x40,
    DeviceInfoDmaSystemDuplex                  =  0x80,
    DeviceInfoHasStaticChildren                = 0x100,
    DeviceInfoHasDynamicChildren               = 0x200,
    DeviceInfoIsUsingDriverWppRecorder         = 0x400
};

Function Documentation

AllocAndInitializeTelemetryContext()

VOID AllocAndInitializeTelemetryContext

(

_In_ PFX_TELEMETRY_CONTEXT *

TelemetryContext

)

Definition at line 46 of file fxtelemetrykm.cpp.

{
    PFX_TELEMETRY_CONTEXT context = NULL;
    NTSTATUS status;
 
    context = (PFX_TELEMETRY_CONTEXT)MxMemory::MxAllocatePoolWithTag(
                                                    NonPagedPool,
                                                    sizeof(FX_TELEMETRY_CONTEXT),
                                                    FX_TAG);
    if (NULL == context) {
        goto exit;
    }
 
    status = ExUuidCreate(&(context->DriverSessionGUID));
    if (!NT_SUCCESS(status)) {
        MxMemory::MxFreePool(context);
        context = NULL;
        goto exit;
    }
 
    context->DoOnceFlagsBitmap = 0;
 
exit:
    *TelemetryContext = context;
}

Referenced by FxAllocateDriverGlobals().

BuildStringFromPartialInfo()

VOID __inline BuildStringFromPartialInfo	(	_In_ PKEY_VALUE_PARTIAL_INFORMATION	Info,
		_Out_ PUNICODE_STRING	String
	)

Definition at line 173 of file fxtelemetry.hpp.

{
    String->Buffer = (PWCHAR) &Info->Data[0];
    String->MaximumLength = (USHORT) Info->DataLength;
    String->Length = String->MaximumLength - sizeof(UNICODE_NULL);
 
    //
    // ensure string is null terminated
    //
    String->Buffer[String->Length/sizeof(WCHAR)] = UNICODE_NULL;
}

Referenced by GetImageName().

GetImageName()

_Must_inspect_result_ NTSTATUS GetImageName	(	_In_ PFX_DRIVER_GLOBALS	DriverGlobals,
		_Out_ PUNICODE_STRING	ImageName
	)

Definition at line 521 of file fxtelemetrykm.cpp.

{
    NTSTATUS status;
    FxAutoRegKey hKey;
    DECLARE_CONST_UNICODE_STRING(valueName, L"ImagePath");
    UNICODE_STRING imagePath = {0};
    UNICODE_STRING imageName = {0};
    PKEY_VALUE_PARTIAL_INFORMATION value = NULL;
    USHORT size;
 
    ASSERT(ImageName != NULL);
    RtlZeroMemory(ImageName, sizeof(UNICODE_STRING));
 
    //
    // Open driver's Service base key
    //
    status = FxRegKey::_OpenKey(NULL,
                                DriverGlobals->Driver->GetRegistryPathUnicodeString(),
                                &hKey.m_Key,
                                KEY_READ);
    if (!NT_SUCCESS(status)) {
        DoTraceLevelMessage(DriverGlobals, TRACE_LEVEL_ERROR, TRACINGDRIVER,
            "Unable to open driver's service key, status %!STATUS!", status);
        return status;
    }
 
    status = QueryAndAllocString(hKey.m_Key,
                                DriverGlobals,
                                &valueName,
                                &value);
    if (!NT_SUCCESS(status)) {
        DoTraceLevelMessage(DriverGlobals, TRACE_LEVEL_ERROR, TRACINGDRIVER,
            "Failed to get Image name from service key, status %!STATUS!",
            status);
        return status;
    }
 
    BuildStringFromPartialInfo(value, &imagePath);
 
    //
    // Now read the "ImagePath" and extract just the driver filename as a new
    // unicode string.
    //
    GetNameFromPath(&imagePath, &imageName);
 
    if (imageName.Length == 0x0) {
        status = STATUS_INVALID_PARAMETER;
        DoTraceLevelMessage(DriverGlobals, TRACE_LEVEL_ERROR, TRACINGDRIVER,
            "ERROR: GetNameFromPath could not find a name, status 0x%x\n",
                 status);
        goto cleanUp;
    }
 
    //
    // Check for interger overflow for length before we allocate memory
    // size = path->Length + sizeof(UNICODE_NULL);
    // len is used below to compute the string size including the NULL, so
    // compute len to include the terminating NULL.
    //
    status = RtlUShortAdd(imageName.Length, sizeof(UNICODE_NULL), &size);
    if (!NT_SUCCESS(status)) {
        DoTraceLevelMessage(DriverGlobals, TRACE_LEVEL_ERROR, TRACINGDRIVER,
            "ERROR: size computation failed with Status 0x%x\n", status);
        goto cleanUp;
    }
 
    //
    // allocate a buffer to hold Unicode string + null char.
    //
    ImageName->Buffer = (PWCH) FxPoolAllocate(DriverGlobals, PagedPool, size);
 
    if (ImageName->Buffer == NULL) {
        status = STATUS_INSUFFICIENT_RESOURCES;
        DoTraceLevelMessage(DriverGlobals, TRACE_LEVEL_ERROR, TRACINGDRIVER,
            "ERROR: ExAllocatePoolWithTag failed with Status 0x%x\n", status);
        goto cleanUp;
    }
 
    RtlZeroMemory(ImageName->Buffer, size);
    ImageName->Length = 0x0;
    ImageName->MaximumLength = size;
 
    status = RtlUnicodeStringCopy(ImageName, &imageName);
 
    //
    // The copy cannot fail since we setup the buffer to hold enough space for
    // the contents of the ImagePath value.
    //
    ASSERT(NT_SUCCESS(status));
 
cleanUp:
 
    if (value != NULL) {
        FxPoolFree(value);
    }
 
    return status;
}

Referenced by ClassCreate(), if(), and LibraryLinkInClient().

GetNameFromPath()

VOID GetNameFromPath	(	_In_ PCUNICODE_STRING	Path,
		_Out_ PUNICODE_STRING	Name
	)

Definition at line 54 of file fxtelemetry.cpp.

{
    BOOLEAN foundSlash;
 
    ASSERT(Path != NULL);
 
    //
    // Ideally a check of Path->Length == 0 would be sufficient except that
    // PreFAST thinks that Length can be odd, so it thinks Length == 1 is possible.
    // Comparing Length < sizeof(WCHAR) satisfies PreFAST and keeps the logic
    // at runtime correct.
    //
    if (Path->Length < sizeof(WCHAR)) {
        RtlZeroMemory(Name, sizeof(UNICODE_STRING));
        return;
    }
 
    //
    // Initialize Name to point to the last WCHAR of the buffer and we will work
    // our way backwards to the beginning of the string or a '\'
    //
 
    Name->Buffer = WDF_PTR_ADD_OFFSET_TYPE(Path->Buffer,
                                           Path->Length - sizeof(WCHAR),
                                           PWCH);
    Name->Length = sizeof(WCHAR);
    foundSlash = FALSE;
 
    while (Name->Buffer >= Path->Buffer) {
        if (*Name->Buffer == L'\\') {
            //
            // Skip the \ in the buffer moving forward a character and adjusting
            // the length
            //
            foundSlash = TRUE;
            Name->Buffer++;
            Name->Length -= sizeof(WCHAR);
            break;
        }
 
        //
        // Move backwards in the string
        //
        Name->Buffer--;
        Name->Length += sizeof(WCHAR);
    }
 
    if (foundSlash && Name->Length == 0) {
        //
        // Handle the case where a slash was found and it is the only character
        //
        Name->Buffer = NULL;
    }
    else if (foundSlash == FALSE) {
        //
        // Handle the case where no slash was found. In this case, Name->Buffer
        // points to one WCHAR before the beginning of the string.
        //
        Name->Length -= sizeof(WCHAR);
        Name->Buffer++;
    }
 
    //
    // Need to set MaximumLength to the same value as Length so that the struct
    // format is valid.
    //
    Name->MaximumLength = Name->Length;
}

Referenced by _Requires_lock_held_(), FindClassByServiceNameLocked(), FxLibraryCommonRegisterClient(), and GetImageName().

IsDeviceInfoFlagSet()

BOOLEAN __inline IsDeviceInfoFlagSet	(	_In_ USHORT	DeviceInfo,
		_In_ FxDeviceInfoFlags	Flag
	)

Definition at line 119 of file fxtelemetry.hpp.

{
    return FLAG_TO_BOOL(DeviceInfo, Flag);
}

Referenced by GetDriverInfo().

IsDriverTelemetryContextInitialized()

__inline BOOLEAN IsDriverTelemetryContextInitialized

(

_In_ PFX_DRIVER_GLOBALS

FxDrvGlobals

)

Definition at line 134 of file fxtelemetry.hpp.

{
    ASSERT(FxDrvGlobals);
    return (NULL != FxDrvGlobals->TelemetryContext);
}

LogDeviceStartTelemetryEvent()

VOID LogDeviceStartTelemetryEvent	(	_In_ PFX_DRIVER_GLOBALS	Globals,
		_In_opt_ FxDevice *	Fdo
	)

Definition at line 91 of file fxtelemetrykm.cpp.

{
    //
    // See if telemetry registered and all the criteria to log is met.
    if (IsLoggingEnabledAndNeeded(DriverGlobals) == FALSE) {
        return;
    }
 
    //
    // Log driver info stream
    //
    LogDriverInfoStream(DriverGlobals, Fdo);
}

LogDriverInfoStream()

VOID LogDriverInfoStream	(	_In_ PFX_DRIVER_GLOBALS	Globals,
		_In_opt_ FxDevice *	Fdo
	)

Definition at line 171 of file fxtelemetrykm.cpp.

{
    FxTelemetryDriverInfo driverInfo = {0};
    FxAutoString hardwareIDs, setupClass, busEnum, manufacturer;
 
    //
    // Log driver and device info
    //
    GetDriverInfo(DriverGlobals, Fdo, &driverInfo);
 
    if (Fdo != NULL) {
        //
        // Get Setup class
        //
        FxGetDevicePropertyString(Fdo,
                                  DevicePropertyClassName,
                                  &setupClass.m_UnicodeString);
        //
        // Get Bus enumerator
        //
        FxGetDevicePropertyString(Fdo,
                                  DevicePropertyEnumeratorName,
                                  &busEnum.m_UnicodeString);
        //
        // Get hardware id multi-string
        //
        FxGetDevicePropertyString(Fdo,
                                  DevicePropertyHardwareID,
                                  &hardwareIDs.m_UnicodeString);
 
        GetFirstHardwareId(&hardwareIDs.m_UnicodeString);
 
        //
        // Get manufacturer
        //
        FxGetDevicePropertyString(Fdo,
                                  DevicePropertyManufacturer,
                                  &manufacturer.m_UnicodeString);
    }
 
    KMDF_CENSUS_EVT_WRITE_DEVICE_START(g_TelemetryProvider,
        DriverGlobals,
        driverInfo,
        setupClass,
        busEnum,
        hardwareIDs,
        manufacturer);
 
    //
    // write current time to registry
    //
    RegistryWriteCurrentTime(DriverGlobals);
}

Referenced by LogDeviceStartTelemetryEvent().

RegisterTelemetryProvider()

VOID RegisterTelemetryProvider

(

VOID

)

Definition at line 75 of file fxtelemetrykm.cpp.

{
    TraceLoggingRegister(g_TelemetryProvider);
}

Referenced by FxLibraryCommonCommission().

UnregisterTelemetryProvider()

VOID UnregisterTelemetryProvider

(

VOID

)

Definition at line 83 of file fxtelemetrykm.cpp.

{
    TraceLoggingUnregister(g_TelemetryProvider);
}

Referenced by FxLibraryCommonDecommission().