EVT_WDF_IO_QUEUE_IO_STOP callback function (wdfio.h)

Article
10/21/2021

[Applies to KMDF and UMDF]

A driver's EvtIoStop event callback function completes, requeues, or suspends processing of a specified request because the request's I/O queue is being stopped.

Syntax

EVT_WDF_IO_QUEUE_IO_STOP EvtWdfIoQueueIoStop;

void EvtWdfIoQueueIoStop(
  [in] WDFQUEUE Queue,
  [in] WDFREQUEST Request,
  [in] ULONG ActionFlags
)
{...}

Parameters

[in] Queue

A handle to the framework queue object that is associated with the I/O request.

[in] Request

A handle to a framework request object.

[in] ActionFlags

A bitwise OR of one or more WDF_REQUEST_STOP_ACTION_FLAGS-typed flags that identify the reason that the callback function is being called and whether the request is cancelable.

Return value

None

Remarks

A driver registers an EvtIoStop callback function when it calls WdfIoQueueCreate. For more information about calling WdfIoQueueCreate, see Creating I/O Queues.

If a driver registers an EvtIoStop callback function for an I/O queue, the framework calls it when the queue's underlying device is leaving its working (D0) state. The framework calls the EvtIoStop callback function for every I/O request that the driver has not completed, including requests that the driver owns and those that it has forwarded to an I/O target.

In most cases, the EvtIoStop callback function completes, cancels, or postpones further processing of the I/O request.

Typically, the driver does one of the following:

If the driver owns the I/O request, it calls WdfRequestUnmarkCancelable (if the request is cancelable) and either calls WdfRequestStopAcknowledge with a Requeue value of TRUE, or it calls WdfRequestComplete with a completion status value of STATUS_SUCCESS or STATUS_CANCELLED.
Before it can call WdfRequestXxx methods safely, the driver must make sure that its implementation of EvtIoStop has exclusive access to the request.

In order to do that, the driver must synchronize access to the request to prevent other threads from manipulating the request concurrently. The synchronization method you choose will depend on your driver's design.

For example, if the request is held in a shared context area, the EvtIoStop callback might acquire an internal driver lock, remove the request from the shared context, and then release the lock. At this point, the EvtIoStop callback owns the request and can safely complete or requeue the request.

Alternatively, the driver postpones further processing of the request and calls WdfRequestStopAcknowledge with a Requeue value of FALSE.
If the driver has forwarded the I/O request to an I/O target, it can call WdfRequestCancelSentRequest to attempt to cancel the request.
Or, if the driver has forwarded the I/O request to a lower-level driver in its own driver stack, and the framework calls the driver's EvtIoStop callback with an ActionFlags value of WdfRequestStopActionSuspend, the driver can call WdfRequestStopAcknowledge with a Requeue value of FALSE. Before doing so, the driver should verify that the following conditions are met:
- The lower driver stops processing all outstanding I/O requests in response to receiving a device set-power IRP (Dx).
- The driver's CompletionRoutine callback function can complete requests while the device is in a low-power state.

A driver might choose to take no action in EvtIoStop for requests that are guaranteed to complete in a small amount of time.

In this case, the framework waits until the specified request is complete before moving the device (or system) to a lower power state or removing the device. Potentially, this inaction can prevent a system from entering its hibernation state or another low system power state. In extreme cases, it can cause the system to crash with bugcheck code 9F.

If the WdfRequestStopRequestCancelable flag is set in the ActionFlags parameter, the driver must call WdfRequestUnmarkCancelable before it calls WdfRequestComplete to complete (or cancel) the request or WdfRequestStopAcknowledge to requeue the request.

If the driver forwards an I/O request from one of its request handlers and specifies the WDF_REQUEST_SEND_OPTION_SEND_AND_FORGET flag in the request's WDF_REQUEST_SEND_OPTIONS structure, the framework does not call the driver's EvtIoStop callback function for this request. However, if the driver forwards the same I/O request from another thread, the framework might call EvtIoStop for this request.

For more information about the EvtIoStop callback function, see Using Power-Managed I/O Queues.

This callback function can be called at IRQL <= DISPATCH_LEVEL, unless the ExecutionLevel member of the device or driver's WDF_OBJECT_ATTRIBUTES structure is set to WdfExecutionLevelPassive.

Requirements

Requirement	Value
Target Platform	Universal
Minimum KMDF version	1.0
Minimum UMDF version	2.0
Header	wdfio.h (include Wdf.h)
IRQL	<= DISPATCH_LEVEL (see Remarks section)