EvtIoStop function

[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 EvtIoStop;

VOID EvtIoStop(
  _In_  WDFQUEUE Queue,
  _In_  WDFREQUEST Request,
  _In_  ULONG ActionFlags
)
{ ... }

Parameters

Queue [in]

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

Request [in]

A handle to a framework request object.

ActionFlags [in]

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 these 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.

Examples

To define an EvtIoStop callback function, you must first provide a function declaration that identifies the type of callback function you’re defining. Windows provides a set of callback function types for drivers. Declaring a function using the callback function types helps Code Analysis for Drivers, Static Driver Verifier (SDV), and other verification tools find errors, and it’s a requirement for writing drivers for the Windows operating system.

For example, to define an EvtIoStop callback function that is named MyIoStop, use the EVT_WDF_IO_QUEUE_IO_STOP type as shown in this code example:


EVT_WDF_IO_QUEUE_IO_STOP  MyIoStop;

Then, implement your callback function as follows:


_Use_decl_annotations_
VOID
 MyIoStop (
    WDFQUEUE  Queue,
    WDFREQUEST  Request,
    ULONG  ActionFlags
    )
..{...}

The EVT_WDF_IO_QUEUE_IO_STOP function type is defined in the Wdfio.h header file. To more accurately identify errors when you run the code analysis tools, be sure to add the _Use_decl_annotations_ annotation to your function definition. The _Use_decl_annotations_ annotation ensures that the annotations that are applied to the EVT_WDF_IO_QUEUE_IO_STOP function type in the header file are used. For more information about the requirements for function declarations, see Declaring Functions by Using Function Role Types for KMDF Drivers. For information about _Use_decl_annotations_, see Annotating Function Behavior.

Requirements

Minimum KMDF version

1.0

Minimum UMDF version

2.0

Header

Wdfio.h (include Wdf.h)

IRQL

<= DISPATCH_LEVEL (see Remarks section)

See also

WdfIoQueueCreate
WdfRequestComplete
WdfRequestStopAcknowledge
WDF_OBJECT_ATTRIBUTES
WDF_REQUEST_STOP_ACTION_FLAGS
EvtIoResume

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft