pnpnotify.c File Reference

#include <ntoskrnl.h>
#include <debug.h>

Include dependency graph for pnpnotify.c:

Go to the source code of this file.

Macros
#define	NDEBUG

Functions
	_Guarded_by_ (PiNotifyHwProfileLock)
VOID	PiInitializeNotifications (VOID)
static VOID	PiDereferencePnpNotifyEntry (_In_ PPNP_NOTIFY_ENTRY Entry)
static VOID	PiReferencePnpNotifyEntry (_In_ PPNP_NOTIFY_ENTRY Entry)
static VOID	PiCallNotifyProc (_In_ PDRIVER_NOTIFICATION_CALLBACK_ROUTINE Proc, _In_ PVOID NotificationStructure, _In_ PVOID Context)
	Calls PnP notification routine and makes some checks to detect faulty drivers.
static	_Requires_lock_held_ (Lock)
VOID	PiNotifyDeviceInterfaceChange (_In_ LPCGUID Event, _In_ LPCGUID InterfaceClassGuid, _In_ PUNICODE_STRING SymbolicLinkName)
	Delivers the event to all drivers subscribed to EventCategoryDeviceInterfaceChange.
VOID	PiNotifyHardwareProfileChange (_In_ LPCGUID Event)
	Delivers the event to all drivers subscribed to EventCategoryHardwareProfileChange PnP event.
VOID	PiNotifyTargetDeviceChange (_In_ LPCGUID Event, _In_ PDEVICE_OBJECT DeviceObject, _In_opt_ PTARGET_DEVICE_CUSTOM_NOTIFICATION CustomNotification)
	Delivers the event to all drivers subscribed to EventCategoryTargetDeviceChange PnP event.
ULONG NTAPI	IoPnPDeliverServicePowerNotification (_In_ ULONG VetoedPowerOperation, _In_ ULONG PowerNotificationCode, _In_ ULONG PowerNotificationData, _In_ BOOLEAN Synchronous)
NTSTATUS NTAPI	IoRegisterPlugPlayNotification (_In_ IO_NOTIFICATION_EVENT_CATEGORY EventCategory, _In_ ULONG EventCategoryFlags, _In_opt_ PVOID EventCategoryData, _In_ PDRIVER_OBJECT DriverObject, _In_ PDRIVER_NOTIFICATION_CALLBACK_ROUTINE CallbackRoutine, _Inout_opt_ PVOID Context, _Out_ PVOID *NotificationEntry)
NTSTATUS NTAPI	IoUnregisterPlugPlayNotification (_In_ PVOID NotificationEntry)

Variables
KGUARDED_MUTEX	PiNotifyTargetDeviceLock
KGUARDED_MUTEX	PiNotifyHwProfileLock
KGUARDED_MUTEX	PiNotifyDeviceInterfaceLock
	PNP_NOTIFY_ENTRY
*	PPNP_NOTIFY_ENTRY

Macro Definition Documentation

NDEBUG

#define NDEBUG

Definition at line 14 of file pnpnotify.c.

Function Documentation

_Guarded_by_()

_Guarded_by_

(

PiNotifyHwProfileLock

)

Definition at line 23 of file pnpnotify.c.

{
    LIST_ENTRY PnpNotifyList;
    PVOID Context;
    PDRIVER_OBJECT DriverObject;
    PDRIVER_NOTIFICATION_CALLBACK_ROUTINE PnpNotificationProc;
    union
    {
        GUID Guid; // for EventCategoryDeviceInterfaceChange
        struct
        {
            PFILE_OBJECT FileObject; // for EventCategoryTargetDeviceChange
            PDEVICE_OBJECT DeviceObject;
        };
    };
    IO_NOTIFICATION_EVENT_CATEGORY EventCategory;
    UINT8 RefCount;
    BOOLEAN Deleted;
} PNP_NOTIFY_ENTRY, *PPNP_NOTIFY_ENTRY;

_Requires_lock_held_()

static _Requires_lock_held_ ( Lock  )

static

Definition at line 125 of file pnpnotify.c.

{
    PAGED_CODE();
 
    // the notification may be unregistered inside the procedure
    // thus reference the entry so we may proceed
    PiReferencePnpNotifyEntry(Entry);
 
    // release the lock because the notification routine has to be called without any
    // limitations regarding APCs
    KeReleaseGuardedMutex(Lock);
    PiCallNotifyProc(Entry->PnpNotificationProc, NotificationStructure, Entry->Context);
    KeAcquireGuardedMutex(Lock);
 
    // take the next entry link only after the callback finishes
    // the lock is not held there, so Entry may have changed at this point
    *NextEntry = Entry->PnpNotifyList.Flink;
    PiDereferencePnpNotifyEntry(Entry);
}

IoPnPDeliverServicePowerNotification()

ULONG NTAPI IoPnPDeliverServicePowerNotification	(	_In_ ULONG	VetoedPowerOperation,
		_In_ ULONG	PowerNotificationCode,
		_In_ ULONG	PowerNotificationData,
		_In_ BOOLEAN	Synchronous
	)

Definition at line 330 of file pnpnotify.c.

{
    UNIMPLEMENTED;
    return 0;
}

IoRegisterPlugPlayNotification()

NTSTATUS NTAPI IoRegisterPlugPlayNotification	(	_In_ IO_NOTIFICATION_EVENT_CATEGORY	EventCategory,
		_In_ ULONG	EventCategoryFlags,
		_In_opt_ PVOID	EventCategoryData,
		_In_ PDRIVER_OBJECT	DriverObject,
		_In_ PDRIVER_NOTIFICATION_CALLBACK_ROUTINE	CallbackRoutine,
		_Inout_opt_ PVOID	Context,
		_Out_ PVOID *	NotificationEntry
	)

Definition at line 346 of file pnpnotify.c.

{
    PPNP_NOTIFY_ENTRY Entry;
    PWSTR SymbolicLinkList;
    NTSTATUS Status;
    PAGED_CODE();
 
    DPRINT("%s(EventCategory 0x%x, EventCategoryFlags 0x%lx, DriverObject %p) called.\n",
           __FUNCTION__, EventCategory, EventCategoryFlags, DriverObject);
 
    ObReferenceObject(DriverObject);
 
    /* Try to allocate entry for notification before sending any notification */
    Entry = ExAllocatePoolWithTag(PagedPool, sizeof(PNP_NOTIFY_ENTRY), TAG_PNP_NOTIFY);
    if (!Entry)
    {
        DPRINT("ExAllocatePool() failed\n");
        ObDereferenceObject(DriverObject);
        return STATUS_INSUFFICIENT_RESOURCES;
    }
 
    *Entry = (PNP_NOTIFY_ENTRY) {
        .PnpNotificationProc = CallbackRoutine,
        .Context = Context,
        .DriverObject = DriverObject,
        .EventCategory = EventCategory,
        .RefCount = 1
    };
 
    switch (EventCategory)
    {
        case EventCategoryDeviceInterfaceChange:
        {
            Entry->Guid = *(LPGUID)EventCategoryData;
 
            // first register the notification
            KeAcquireGuardedMutex(&PiNotifyDeviceInterfaceLock);
            InsertTailList(&PiNotifyDeviceInterfaceListHead, &Entry->PnpNotifyList);
            KeReleaseGuardedMutex(&PiNotifyDeviceInterfaceLock);
 
            // then process existing interfaces if asked
            if (EventCategoryFlags & PNPNOTIFY_DEVICE_INTERFACE_INCLUDE_EXISTING_INTERFACES)
            {
                DEVICE_INTERFACE_CHANGE_NOTIFICATION NotificationInfos;
                UNICODE_STRING SymbolicLinkU;
                PWSTR SymbolicLink;
 
                Status = IoGetDeviceInterfaces((LPGUID)EventCategoryData,
                                               NULL, /* PhysicalDeviceObject OPTIONAL */
                                               0, /* Flags */
                                               &SymbolicLinkList);
                if (NT_SUCCESS(Status))
                {
                    /* Enumerate SymbolicLinkList */
                    NotificationInfos.Version = 1;
                    NotificationInfos.Size = sizeof(DEVICE_INTERFACE_CHANGE_NOTIFICATION);
                    NotificationInfos.Event = GUID_DEVICE_INTERFACE_ARRIVAL;
                    NotificationInfos.InterfaceClassGuid = *(LPGUID)EventCategoryData;
                    NotificationInfos.SymbolicLinkName = &SymbolicLinkU;
 
                    for (SymbolicLink = SymbolicLinkList;
                         *SymbolicLink;
                         SymbolicLink += (SymbolicLinkU.Length / sizeof(WCHAR)) + 1)
                    {
                        RtlInitUnicodeString(&SymbolicLinkU, SymbolicLink);
                        DPRINT("Calling callback routine for %S\n", SymbolicLink);
                        PiCallNotifyProc(CallbackRoutine, &NotificationInfos, Context);
                    }
 
                    ExFreePool(SymbolicLinkList);
                }
            }
            break;
        }
        case EventCategoryHardwareProfileChange:
        {
            KeAcquireGuardedMutex(&PiNotifyHwProfileLock);
            InsertTailList(&PiNotifyHwProfileListHead, &Entry->PnpNotifyList);
            KeReleaseGuardedMutex(&PiNotifyHwProfileLock);
            break;
        }
        case EventCategoryTargetDeviceChange:
        {
            PDEVICE_NODE deviceNode;
            Entry->FileObject = (PFILE_OBJECT)EventCategoryData;
 
            // NOTE: the device node's PDO is referenced here
            Status = IopGetRelatedTargetDevice(Entry->FileObject, &deviceNode);
            if (!NT_SUCCESS(Status))
            {
                ObDereferenceObject(DriverObject);
                ExFreePoolWithTag(Entry, TAG_PNP_NOTIFY);
                return Status;
            }
            // save it so we can dereference it later
            Entry->DeviceObject = deviceNode->PhysicalDeviceObject;
 
            // each DEVICE_NODE has its own registered notifications list
            KeAcquireGuardedMutex(&PiNotifyTargetDeviceLock);
            InsertTailList(&deviceNode->TargetDeviceNotify, &Entry->PnpNotifyList);
            KeReleaseGuardedMutex(&PiNotifyTargetDeviceLock);
            break;
        }
        default:
        {
            DPRINT1("%s: unknown EventCategory 0x%x UNIMPLEMENTED\n",
                    __FUNCTION__, EventCategory);
 
            ObDereferenceObject(DriverObject);
            ExFreePoolWithTag(Entry, TAG_PNP_NOTIFY);
            return STATUS_NOT_SUPPORTED;
        }
    }
 
    DPRINT("%s returns NotificationEntry %p\n", __FUNCTION__, Entry);
 
    *NotificationEntry = Entry;
 
    return STATUS_SUCCESS;
}

Referenced by _Function_class_(), add_device(), add_volume_device(), CompBattPnpDispatch(), DriverEntry(), PciVerifierInit(), PoInitSystem(), register_fve_callback(), FxIoTargetRemote::RegisterForPnpNotification(), RegisterForTargetDeviceNotification(), SysAudioRegisterNotifications(), Test_IoRegisterPlugPlayNotification(), and WdmAudOpenSysAudioDevices().

IoUnregisterPlugPlayNotification()

NTSTATUS NTAPI IoUnregisterPlugPlayNotification

(

_In_ PVOID

NotificationEntry

)

Definition at line 480 of file pnpnotify.c.

{
    PPNP_NOTIFY_ENTRY Entry = NotificationEntry;
    PKGUARDED_MUTEX Lock;
 
    PAGED_CODE();
 
    DPRINT("%s(NotificationEntry %p) called\n", __FUNCTION__, Entry);
 
    switch (Entry->EventCategory)
    {
        case EventCategoryDeviceInterfaceChange:
            Lock = &PiNotifyDeviceInterfaceLock;
            break;
        case EventCategoryHardwareProfileChange:
            Lock = &PiNotifyHwProfileLock;
            break;
        case EventCategoryTargetDeviceChange:
            Lock = &PiNotifyTargetDeviceLock;
            break;
        default:
            UNREACHABLE;
            return STATUS_NOT_SUPPORTED;
    }
 
    KeAcquireGuardedMutex(Lock);
    if (!Entry->Deleted)
    {
        Entry->Deleted = TRUE; // so it can't be unregistered two times
        PiDereferencePnpNotifyEntry(Entry);
    }
    else
    {
        DPRINT1("IoUnregisterPlugPlayNotification called two times for 0x%p\n", NotificationEntry);
    }
    KeReleaseGuardedMutex(Lock);
 
    return STATUS_SUCCESS;
}

Referenced by _Function_class_(), do_shutdown(), free_vol(), MountMgrFreeMountedDeviceInfo(), MountMgrMountedDeviceRemoval(), MountMgrUnload(), Mx::MxUnRegisterPlugPlayNotification(), register_fve_callback(), remove_volume_child(), SysAudio_AddDevice(), SysAudio_Pnp(), Test_IoRegisterPlugPlayNotification(), FxIoTargetRemote::UnregisterForPnpNotification(), and WdmAudClose().

PiCallNotifyProc()

static VOID PiCallNotifyProc ( _In_ PDRIVER_NOTIFICATION_CALLBACK_ROUTINE  Proc, _In_ PVOID  NotificationStructure, _In_ PVOID  Context  )

static

Calls PnP notification routine and makes some checks to detect faulty drivers.

Definition at line 106 of file pnpnotify.c.

{
    PAGED_CODE();
#if DBG
    KIRQL oldIrql = KeGetCurrentIrql();
    ULONG oldApcDisable = KeGetCurrentThread()->CombinedApcDisable;
#endif
 
    Proc(NotificationStructure, Context);
 
    ASSERT(oldIrql == KeGetCurrentIrql() &&
           oldApcDisable == KeGetCurrentThread()->CombinedApcDisable);
}

Referenced by _Requires_lock_held_(), and IoRegisterPlugPlayNotification().

PiDereferencePnpNotifyEntry()

static VOID PiDereferencePnpNotifyEntry ( _In_ PPNP_NOTIFY_ENTRY  Entry )

static

Definition at line 67 of file pnpnotify.c.

{
    PAGED_CODE();
    ASSERT(Entry->RefCount > 0);
 
    ObDereferenceObject(Entry->DriverObject);
    Entry->RefCount--;
    if (Entry->RefCount == 0)
    {
        ASSERT(Entry->Deleted);
 
        RemoveEntryList(&Entry->PnpNotifyList);
        if (Entry->EventCategory == EventCategoryTargetDeviceChange)
        {
            // IopGetRelatedTargetDevice referenced the device upon the notification registration
            ObDereferenceObject(Entry->DeviceObject);
        }
        ExFreePoolWithTag(Entry, TAG_PNP_NOTIFY);
    }
}

Referenced by _Requires_lock_held_(), and IoUnregisterPlugPlayNotification().

PiInitializeNotifications()

VOID PiInitializeNotifications

(

VOID

)

Definition at line 55 of file pnpnotify.c.

{
    KeInitializeGuardedMutex(&PiNotifyTargetDeviceLock);
    KeInitializeGuardedMutex(&PiNotifyHwProfileLock);
    KeInitializeGuardedMutex(&PiNotifyDeviceInterfaceLock);
    InitializeListHead(&PiNotifyHwProfileListHead);
    InitializeListHead(&PiNotifyDeviceInterfaceListHead);
}

Referenced by IoInitSystem().

PiNotifyDeviceInterfaceChange()

VOID PiNotifyDeviceInterfaceChange	(	_In_ LPCGUID	Event,
		_In_ LPCGUID	InterfaceClassGuid,
		_In_ PUNICODE_STRING	SymbolicLinkName
	)

Delivers the event to all drivers subscribed to EventCategoryDeviceInterfaceChange.

Parameters

[in]	Event	The PnP event GUID
[in]	InterfaceClassGuid	The GUID of an interface class
[in]	SymbolicLinkName	Pointer to a string identifying the device interface name

Definition at line 161 of file pnpnotify.c.

{
    PAGED_CODE();
 
    PDEVICE_INTERFACE_CHANGE_NOTIFICATION notifyStruct;
    notifyStruct = ExAllocatePoolWithTag(PagedPool, sizeof(*notifyStruct), TAG_PNP_NOTIFY);
    if (!notifyStruct)
    {
        return;
    }
 
    *notifyStruct = (DEVICE_INTERFACE_CHANGE_NOTIFICATION) {
        .Version = 1,
        .Size = sizeof(DEVICE_INTERFACE_CHANGE_NOTIFICATION),
        .Event = *Event,
        .InterfaceClassGuid = *InterfaceClassGuid,
        .SymbolicLinkName = SymbolicLinkName
    };
 
    DPRINT("Delivering a DeviceInterfaceChange PnP event\n");
 
    KeAcquireGuardedMutex(&PiNotifyDeviceInterfaceLock);
 
    PLIST_ENTRY entry = PiNotifyDeviceInterfaceListHead.Flink;
    while (entry != &PiNotifyDeviceInterfaceListHead)
    {
        PPNP_NOTIFY_ENTRY nEntry = CONTAINING_RECORD(entry, PNP_NOTIFY_ENTRY, PnpNotifyList);
 
        if (!IsEqualGUID(&notifyStruct->InterfaceClassGuid, &nEntry->Guid))
        {
            entry = entry->Flink;
            continue;
        }
 
        PiProcessSingleNotification(nEntry, notifyStruct, &PiNotifyDeviceInterfaceLock, &entry);
    }
 
    KeReleaseGuardedMutex(&PiNotifyDeviceInterfaceLock);
    ExFreePoolWithTag(notifyStruct, TAG_PNP_NOTIFY);
}

Referenced by IoSetDeviceInterfaceState().

PiNotifyHardwareProfileChange()

VOID PiNotifyHardwareProfileChange

(

_In_ LPCGUID

Event

)

Delivers the event to all drivers subscribed to EventCategoryHardwareProfileChange PnP event.

Parameters

[in]

Event

The PnP event GUID

Definition at line 214 of file pnpnotify.c.

{
    PAGED_CODE();
 
    PHWPROFILE_CHANGE_NOTIFICATION notifyStruct;
    notifyStruct = ExAllocatePoolWithTag(PagedPool, sizeof(*notifyStruct), TAG_PNP_NOTIFY);
    if (!notifyStruct)
    {
        return;
    }
 
    *notifyStruct = (HWPROFILE_CHANGE_NOTIFICATION) {
        .Version = 1,
        .Size = sizeof(HWPROFILE_CHANGE_NOTIFICATION),
        .Event = *Event
    };
 
    DPRINT("Delivering a HardwareProfileChange PnP event\n");
 
    KeAcquireGuardedMutex(&PiNotifyHwProfileLock);
 
    PLIST_ENTRY entry = PiNotifyHwProfileListHead.Flink;
    while (entry != &PiNotifyHwProfileListHead)
    {
        PPNP_NOTIFY_ENTRY nEntry = CONTAINING_RECORD(entry, PNP_NOTIFY_ENTRY, PnpNotifyList);
 
        PiProcessSingleNotification(nEntry, notifyStruct, &PiNotifyHwProfileLock, &entry);
    }
 
    KeReleaseGuardedMutex(&PiNotifyHwProfileLock);
    ExFreePoolWithTag(notifyStruct, TAG_PNP_NOTIFY);
}

PiNotifyTargetDeviceChange()

VOID PiNotifyTargetDeviceChange	(	_In_ LPCGUID	Event,
		_In_ PDEVICE_OBJECT	DeviceObject,
		_In_opt_ PTARGET_DEVICE_CUSTOM_NOTIFICATION	CustomNotification
	)

Delivers the event to all drivers subscribed to EventCategoryTargetDeviceChange PnP event.

Parameters

[in]	Event	The PnP event GUID
[in]	DeviceObject	The (target) device object
[in]	CustomNotification	Pointer to a custom notification for GUID_PNP_CUSTOM_NOTIFICATION

Definition at line 258 of file pnpnotify.c.

{
    PAGED_CODE();
 
    PVOID notificationStruct;
    // just in case our device is removed during the operation
    ObReferenceObject(DeviceObject);
 
    PDEVICE_NODE deviceNode = IopGetDeviceNode(DeviceObject);
    ASSERT(deviceNode);
 
    if (!IsEqualGUID(Event, &GUID_PNP_CUSTOM_NOTIFICATION))
    {
        PTARGET_DEVICE_REMOVAL_NOTIFICATION notifStruct;
        notifStruct = ExAllocatePoolWithTag(PagedPool, sizeof(*notifStruct), TAG_PNP_NOTIFY);
        if (!notifStruct)
        {
            return;
        }
 
        *notifStruct = (TARGET_DEVICE_REMOVAL_NOTIFICATION) {
            .Version = 1,
            .Size = sizeof(TARGET_DEVICE_REMOVAL_NOTIFICATION),
            .Event = *Event
        };
 
        notificationStruct = notifStruct;
 
        DPRINT("Delivering a (non-custom) TargetDeviceChange PnP event\n");
    }
    else
    {
        ASSERT(CustomNotification);
        // assuming everythng else is correct
 
        notificationStruct = CustomNotification;
 
        DPRINT("Delivering a (custom) TargetDeviceChange PnP event\n");
    }
 
    KeAcquireGuardedMutex(&PiNotifyTargetDeviceLock);
 
    PLIST_ENTRY entry = deviceNode->TargetDeviceNotify.Flink;
    while (entry != &deviceNode->TargetDeviceNotify)
    {
        PPNP_NOTIFY_ENTRY nEntry = CONTAINING_RECORD(entry, PNP_NOTIFY_ENTRY, PnpNotifyList);
 
        // put the file object from our saved entry to this particular notification's struct
        ((PTARGET_DEVICE_REMOVAL_NOTIFICATION)notificationStruct)->FileObject = nEntry->FileObject;
        // so you don't need to look at the definition ;)
        C_ASSERT(FIELD_OFFSET(TARGET_DEVICE_REMOVAL_NOTIFICATION, FileObject)
                 == FIELD_OFFSET(TARGET_DEVICE_CUSTOM_NOTIFICATION, FileObject));
 
        PiProcessSingleNotification(nEntry, notificationStruct, &PiNotifyTargetDeviceLock, &entry);
    }
 
    KeReleaseGuardedMutex(&PiNotifyTargetDeviceLock);
    if (notificationStruct != CustomNotification)
        ExFreePoolWithTag(notificationStruct, TAG_PNP_NOTIFY);
    ObDereferenceObject(DeviceObject);
}

Referenced by IopCancelRemoveDevice(), IopQueryRemoveDevice(), IopSendRemoveDevice(), and PpSetCustomTargetEvent().

PiReferencePnpNotifyEntry()

static VOID PiReferencePnpNotifyEntry ( _In_ PPNP_NOTIFY_ENTRY  Entry )

static

Definition at line 92 of file pnpnotify.c.

{
    PAGED_CODE();
    ObReferenceObject(Entry->DriverObject);
    Entry->RefCount++;
}

Referenced by _Requires_lock_held_().

Variable Documentation

PiNotifyDeviceInterfaceLock

KGUARDED_MUTEX PiNotifyDeviceInterfaceLock

Definition at line 21 of file pnpnotify.c.

Referenced by IoRegisterPlugPlayNotification(), IoUnregisterPlugPlayNotification(), PiInitializeNotifications(), and PiNotifyDeviceInterfaceChange().

PiNotifyHwProfileLock

KGUARDED_MUTEX PiNotifyHwProfileLock

Definition at line 20 of file pnpnotify.c.

Referenced by IoRegisterPlugPlayNotification(), IoUnregisterPlugPlayNotification(), PiInitializeNotifications(), and PiNotifyHardwareProfileChange().

PiNotifyTargetDeviceLock

KGUARDED_MUTEX PiNotifyTargetDeviceLock

Definition at line 19 of file pnpnotify.c.

Referenced by IoRegisterPlugPlayNotification(), IoUnregisterPlugPlayNotification(), PiInitializeNotifications(), and PiNotifyTargetDeviceChange().

PNP_NOTIFY_ENTRY

PNP_NOTIFY_ENTRY

Definition at line 49 of file pnpnotify.c.

Referenced by IoRegisterPlugPlayNotification(), PiNotifyDeviceInterfaceChange(), PiNotifyHardwareProfileChange(), and PiNotifyTargetDeviceChange().

PPNP_NOTIFY_ENTRY

* PPNP_NOTIFY_ENTRY

Definition at line 49 of file pnpnotify.c.

Referenced by IoRegisterPlugPlayNotification(), IoUnregisterPlugPlayNotification(), PiNotifyDeviceInterfaceChange(), PiNotifyHardwareProfileChange(), and PiNotifyTargetDeviceChange().