|
|
|
System components send this IRP to ask the drivers for a device whether the device can support a special file. If all the drivers for the device succeed the IRP, the system creates the special file. The system also sends this IRP to inform drivers that a special file has been removed from the device. The special files can be a paging file, a crash dump file, or a hibernation file.
Function drivers must handle this IRP if their device can contain a paging file, dump file, or hibernation file. Filter drivers must handle this IRP if the function driver they are filtering handles the IRP. Bus drivers must handle this IRP for their adapter or controller (bus FDO) and for their child devices (child PDOs).
The system sends this IRP when it is creating or deleting a paging file, dump file, or hibernation file. A driver can send this IRP to propagate device usage information to another device stack.
System components and drivers send this IRP at IRQL PASSIVE_LEVEL in an arbitrary thread context.
The Parameters.UsageNotification.InPath member of the IO_STACK_LOCATION structure is a BOOLEAN. When this parameter is TRUE, the system is creating a paging, crash dump, or hibernation file on the device. When InPath is FALSE, such a file has been removed from the device.
Parameters.UsageNotification.Type is an enum indicating the kind of file. This parameter has one of the following values: DeviceUsageTypePaging, DeviceUsageTypeDumpFile, or DeviceUsageTypeHibernation.
None
Drivers set Irp->IoStatus.Status to STATUS_SUCCESS or to an appropriate error status.
Drivers do not modify the Irp->IoStatus.Information field; it remains at zero as set by the component sending the IRP.
A driver handles this IRP on the IRP's way down the device stack and on the IRP's way back up the stack.
A driver responds to this IRP with a procedure like the following:
A driver should test for the specific Parameters.UsageNotification.Type(s) that the driver can support. Additional notification types might be added in the future.
See further information below describing the actions required to support each notification type.
If Parameters.UsageNotification.InPath is TRUE and the driver cannot support the special file on the device, the driver must complete the IRP with a failure status.
A driver typically increments or decrements a counter. For example, if Parameters.UsageNotification.Type is DeviceUsageTypePaging and Parameters.UsageNotification.InPath is TRUE, increment a count of the number of paging files on the device. Certain driver dispatch routines must check the counter(s).
A device that contains a special file should not be disabled. A driver can call IoInvalidateDeviceState, requesting the PnP Manager to re-query for the device's PnP device state information. In response to the resulting IRP_MN_QUERY_PNP_DEVICE_STATE IRP, the driver should set the PNP_DEVICE_NOT_DISABLEABLE flag.
If InPath is FALSE, a driver sets the DO_POWER_PAGABLE bit in its device object for the device.
As part of its handling of an IRP_MN_DEVICE_USAGE_NOTIFICATION IRP, a driver might be required to pass the information to one or more other device stacks. Such a driver creates new IRP_MN_DEVICE_USAGE_NOTIFICATION IRP(s) and sends them to the appropriate device stack(s). The driver must wait for completion of any device-usage-notification IRP(s) it sends before the driver finishes processing the device-usage IRP it received.
How to identify the related devices is device- and driver-specific. Typically, a driver sends the IRP to other drivers to which it would send I/O requests for the file. When a bus driver handles this request for a child device, it must send a usage notification IRP to the device stack for the device's parent.
For example, when ftdisk is running a five-disk stripe set, it propagates paging, hibernate, and crash dump notifications to each of those five disks, since each of those devices can be required to handle paging, hibernate, or crash dump file operations.
In a bus driver that is handling the IRP for a child PDO: set Irp->IoStatus.Status and complete the IRP (IoCompleteRequest).
If an IoCompletion routine detects that a lower driver has failed the IRP, the function or filter driver must undo any operations it performed in response to the IRP and propagate the error. If the function or filter driver propagated the usage information to any other device stacks, the driver must send another usage IRP to those stacks to notify them of the failure.
If status is STATUS_SUCCESS and InPath is TRUE, clear the DO_POWER_PAGABLE bit.
See Plug and Play for the general rules for handling Plug and Play Minor IRPs.
When any of a driver's special file counts is nonzero, the driver must support the presence of the special file(s) on its device (or a descendant device).
For a DeviceUsageTypePaging file created on its device, a driver must do the following:
For a DeviceUsageTypeDumpFile file on its device, a driver must do the following:
Do not register the device for idle detection (PoRegisterDeviceForIdleDetection). If the device is already registered, cancel the registration. If the driver performs its own idle detection for the device, suspend such detection.
For a DeviceUsageTypeHibernation file on its device, a driver must do the following:
Upon receipt of such a D3 set-power IRP, perform all tasks required to put the device in the D3 state except for powering off the device and notifying the Power Manager (PoSetPowerState). The device must retain power until the hibernation file has been written.
See Power Management for more information about device power states, power IRPs, and supporting power management in drivers.
A driver can send an IRP_MN_DEVICE_USAGE_INFORMATION IRP, but only to propagate device usage information to another device stack. A driver is never the initial source of device usage information.
IoAdjustPagingPathCount, IRP_MN_QUERY_REMOVE_DEVICE, IRP_MN_QUERY_STOP_DEVICE