EVT_WDF_IO_QUEUE_IO_STOP función de devolución de llamada (wdfio.h)

Artículo
08/08/2023

[Se aplica a KMDF y UMDF]

La función de devolución de llamada de eventos EvtIoStop de un controlador se completa, vuelve a poner en cola o suspende el procesamiento de una solicitud especificada porque la cola de E/S de la solicitud se detiene.

Sintaxis

EVT_WDF_IO_QUEUE_IO_STOP EvtWdfIoQueueIoStop;

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

Parámetros

[in] Queue

Identificador del objeto de cola de marco asociado a la solicitud de E/S.

[in] Request

Identificador de un objeto de solicitud de marco.

[in] ActionFlags

Or bit a bit de una o varias marcas de tipo WDF_REQUEST_STOP_ACTION_FLAGS que identifican el motivo por el que se llama a la función de devolución de llamada y si se puede cancelar la solicitud.

Valor devuelto

None

Observaciones

Un controlador registra una función de devolución de llamada EvtIoStop cuando llama a WdfIoQueueCreate. Para obtener más información sobre cómo llamar a WdfIoQueueCreate, vea Creating I/O Queues.

Si un controlador registra una función de devolución de llamada EvtIoStop para una cola de E/S, el marco lo llama cuando el dispositivo subyacente de la cola deja su estado de trabajo (D0). El marco llama a la función de devolución de llamada EvtIoStop para cada solicitud de E/S que el controlador no ha completado, incluidas las solicitudes que posee el controlador y las que ha reenviado a un destino de E/S.

En la mayoría de los casos, la función de devolución de llamada EvtIoStopcompleta, cancela o pospone el procesamiento posterior de la solicitud de E/S.

Normalmente, el controlador realiza una de las siguientes acciones:

Si el controlador posee la solicitud de E/S, llama a WdfRequestUnmarkCancelable (si la solicitud es cancelable) y llama a WdfRequestStopAcknowledge con un valor Requeue de TRUE o llama a WdfRequestComplete con un valor de estado de finalización de STATUS_SUCCESS o STATUS_CANCELLED.
Para poder llamar a métodos WdfRequestXxx de forma segura, el controlador debe asegurarse de que su implementación de EvtIoStop tiene acceso exclusivo a la solicitud.

Para ello, el controlador debe sincronizar el acceso a la solicitud para evitar que otros subprocesos manipulen la solicitud simultáneamente. El método de sincronización que elija dependerá del diseño del controlador.

Por ejemplo, si la solicitud se mantiene en un área de contexto compartido, la devolución de llamada EvtIoStop podría adquirir un bloqueo de controlador interno, quitar la solicitud del contexto compartido y, a continuación, liberar el bloqueo. En este momento, la devolución de llamada EvtIoStop posee la solicitud y puede completar o volver a poner en cola la solicitud de forma segura.

Como alternativa, el controlador pospone el procesamiento adicional de la solicitud y llama a WdfRequestStopAcknowledge con un valor Requeue de FALSE.
Si el controlador ha reenviado la solicitud de E/S a un destino de E/S, puede llamar a WdfRequestCancelSentRequest para intentar cancelar la solicitud.
O bien, si el controlador ha reenviado la solicitud de E/S a un controlador de nivel inferior en su propia pila de controladores, y el marco llama a la devolución de llamada EvtIoStop del controlador con un valor ActionFlags de WdfRequestStopActionSuspend, el controlador puede llamar a WdfRequestStopAcknowledge con un valor Requeue de FALSE. Antes de hacerlo, el controlador debe comprobar que se cumplen las condiciones siguientes:
- El controlador inferior deja de procesar todas las solicitudes de E/S pendientes en respuesta a la recepción de un IRP (Dx) de conjunto de dispositivos.
- La función de devolución de llamada CompletionRoutine del controlador puede completar las solicitudes mientras el dispositivo está en un estado de bajo consumo.

Un controlador puede optar por no realizar ninguna acción en EvtIoStop para las solicitudes que se garantiza que se completen en una pequeña cantidad de tiempo.

En este caso, el marco espera hasta que se complete la solicitud especificada antes de mover el dispositivo (o sistema) a un estado de energía inferior o quitar el dispositivo. Potencialmente, esta inacción puede impedir que un sistema entre en su estado de hibernación u otro estado de energía del sistema bajo. En casos extremos, puede hacer que el sistema se bloquee con el código de comprobación de errores 9F.

Si la marca WdfRequestStopRequestCancelable está establecida en el parámetro ActionFlags , el controlador debe llamar a WdfRequestUnmarkCancelable antes de llamar a WdfRequestComplete para completar (o cancelar) la solicitud o WdfRequestStopAcknowledge para volver a poner en cola la solicitud.

Si el controlador reenvía una solicitud de E/S de uno de sus controladores de solicitudes y especifica la marca WDF_REQUEST_SEND_OPTION_SEND_AND_FORGET en la estructura de WDF_REQUEST_SEND_OPTIONS de la solicitud, el marco no llama a la función de devolución de llamada EvtIoStop del controlador para esta solicitud. Sin embargo, si el controlador reenvía la misma solicitud de E/S desde otro subproceso, el marco podría llamar a EvtIoStop para esta solicitud.

Para obtener más información sobre la función de devolución de llamada EvtIoStop , consulte Uso de Power-Managed colas de E/S.

Se puede llamar a esta función de devolución de llamada en IRQL <= DISPATCH_LEVEL, a menos que el miembro ExecutionLevel de la estructura de WDF_OBJECT_ATTRIBUTES del dispositivo o controlador esté establecido en WdfExecutionLevelPassive.

Requisitos

Requisito	Value
Plataforma de destino	Universal
Versión mínima de KMDF	1.0
Versión mínima de UMDF	2.0
Encabezado	wdfio.h (incluir Wdf.h)
IRQL	<= DISPATCH_LEVEL (consulte la sección Comentarios)