IRP_MN_DEVICE_USAGE_NOTIFICATION
System components send this IRP to ask the drivers for a device whether the device can support a special file. Special files include paging files, dump files, and hibernation files. 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.
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).
Value
0x16
Major Code
When Sent
The system sends this IRP when it is creating or deleting a paging file, dump file, or hibernation file. If a device has a power management relationship that falls outside of the conventional parent-child relationship, the driver can send this IRP to propagate device usage information to another device stack. For more information, see the description of the PowerRelations request in IRP_MN_QUERY_DEVICE_RELATIONS.
System components and drivers send this IRP at IRQL PASSIVE_LEVEL in an arbitrary thread context.
Input Parameters
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.
Output Parameters
None
I/O Status Block
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.
Operation
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:
If Parameters.UsageNotification.InPath is TRUE, determine whether the device supports the special file.
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.
If the device supports the special file:
Take appropriate actions to reflect that the device now contains, or no longer contains, a special file.
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.
Propagate the device usage information to any related devices that require the information.
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 a new IRP_MN_DEVICE_USAGE_NOTIFICATION IRP (or IRPs) and sends them to the appropriate device stack (or stacks). The driver must wait for completion of any device-usage-notification IRP(s) that it sends before the driver finishes processing the device-usage IRP that 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 notifications to each of these five disks, since each of these devices can be required to handle paging file operations.
In a function or filter driver, set an IoCompletion routine.
In a function or filter driver, set Irp->IoStatus.Status to STATUS_SUCCESS, set up the next stack location, and pass the IRP to the next lower driver with IoCallDriver. Do not complete the IRP.
In a bus driver that is handling the IRP for a child PDO: set Irp->IoStatus.Status and complete the IRP (IoCompleteRequest).
During IRP completion processing:
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.
Supporting Paging, Crash Dump, and Hibernation Files on a Device
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:
Lock code in memory for its DispatchRead, DispatchWrite, DispatchDeviceControl, and DispatchPower routines.
Clear the DO_POWER_PAGABLE bit in its device object for the device (on the IRP's way up the device stack).
Fail IRP_MN_QUERY_STOP_DEVICE and IRP_MN_QUERY_REMOVE_DEVICE requests for the device.
For a DeviceUsageTypeDumpFile file on its device, a driver must do the following:
Lock code in memory for its DispatchRead, DispatchWrite, DispatchDeviceControl, and DispatchPower routines.
Do not take the device out of the D0 state.
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.
Clear the DO_POWER_PAGABLE bit in its device object for the device (on the IRP's way up the device stack).
Fail IRP_MN_QUERY_STOP_DEVICE and IRP_MN_QUERY_REMOVE_DEVICE requests for the device.
For a DeviceUsageTypeHibernation file on its device, a driver must do the following:
Lock code in memory for its DispatchRead, DispatchWrite, DispatchDeviceControl, and DispatchPower routines.
Ensure the device is in the D0 state when the driver receives an S4 system power IRP indicating that the system is about to hibernate.
Do not power down the device in response to a D3 set-power IRP that is part of an S4 hibernate action. See System Power Actions for more information.
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.
Clear the DO_POWER_PAGABLE bit in its device object for the device (on the IRP's way up the device stack).
Fail IRP_MN_QUERY_STOP_DEVICE and IRP_MN_QUERY_REMOVE_DEVICE requests for the device.
See Power Management for more information about device power states, power IRPs, and supporting power management in drivers.
Sending This IRP
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.
Requirements
Header |
Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h) |