EVT_WDF_IO_QUEUE_IO_STOP função de retorno de chamada (wdfio.h)

Artigo
08/08/2023

[Aplica-se a KMDF e UMDF]

A função de retorno de chamada de evento EvtIoStop de um driver é concluída, requeuida ou suspende o processamento de uma solicitação especificada porque a fila de E/S da solicitação está sendo interrompida.

Sintaxe

EVT_WDF_IO_QUEUE_IO_STOP EvtWdfIoQueueIoStop;

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

Parâmetros

[in] Queue

Um identificador para o objeto de fila de estrutura associado à solicitação de E/S.

[in] Request

Um identificador para um objeto de solicitação de estrutura.

[in] ActionFlags

Um OR bit a bit de um ou mais sinalizadores do tipo WDF_REQUEST_STOP_ACTION_FLAGS que identificam o motivo pelo qual a função de retorno de chamada está sendo chamada e se a solicitação é cancelável.

Retornar valor

Nenhum

Comentários

Um driver registra uma função de retorno de chamada EvtIoStop quando chama WdfIoQueueCreate. Para obter mais informações sobre como chamar WdfIoQueueCreate, consulte Criando filas de E/S.

Se um driver registrar uma função de retorno de chamada EvtIoStop para uma fila de E/S, a estrutura a chamará quando o dispositivo subjacente da fila estiver deixando seu estado de trabalho (D0). A estrutura chama a função de retorno de chamada EvtIoStop para cada solicitação de E/S que o driver não concluiu, incluindo solicitações que o driver possui e aquelas que ele encaminhou para um destino de E/S.

Na maioria dos casos, a função de retorno de chamada EvtIoStopconclui, cancela ou adia o processamento adicional da solicitação de E/S.

Normalmente, o driver faz um dos seguintes procedimentos:

Se o driver possuir a solicitação de E/S, ele chamará WdfRequestUnmarkCancelable (se a solicitação for cancelável) e chamará WdfRequestStopAcknowledge com um valor Requeue de TRUE ou chamará WdfRequestComplete com uma conclusão status valor de STATUS_SUCCESS ou STATUS_CANCELLED.
Antes de poder chamar os métodos WdfRequestXxx com segurança, o driver deve garantir que sua implementação do EvtIoStop tenha acesso exclusivo à solicitação.

Para fazer isso, o driver deve sincronizar o acesso à solicitação para impedir que outros threads manipulem a solicitação simultaneamente. O método de sincronização escolhido dependerá do design do driver.

Por exemplo, se a solicitação for mantida em uma área de contexto compartilhado, o retorno de chamada EvtIoStop poderá adquirir um bloqueio de driver interno, remover a solicitação do contexto compartilhado e liberar o bloqueio. Neste ponto, o retorno de chamada EvtIoStop é proprietário da solicitação e pode concluir ou reencontrar a solicitação com segurança.

Como alternativa, o driver adia o processamento adicional da solicitação e chama WdfRequestStopAcknowledge com um valor Requeue de FALSE.
Se o driver encaminhou a solicitação de E/S para um destino de E/S, ele pode chamar WdfRequestCancelSentRequest para tentar cancelar a solicitação.
Ou, se o driver encaminhou a solicitação de E/S para um driver de nível inferior em sua própria pilha de driver e a estrutura chama o retorno de chamada EvtIoStop do driver com um valor ActionFlags de WdfRequestStopActionSuspend, o driver pode chamar WdfRequestStopAcknowledge com um valor requeue de FALSE. Antes de fazer isso, o driver deve verificar se as seguintes condições foram atendidas:
- O driver inferior para de processar todas as solicitações de E/S pendentes em resposta ao recebimento de um Dx (IRP) de set-power do dispositivo.
- A função de retorno de chamada CompletionRoutine do driver pode concluir solicitações enquanto o dispositivo está em um estado de baixa potência.

Um driver pode optar por não executar nenhuma ação no EvtIoStop para solicitações que têm a garantia de serem concluídas em um pequeno período de tempo.

Nesse caso, a estrutura aguarda até que a solicitação especificada seja concluída antes de mover o dispositivo (ou sistema) para um estado de energia inferior ou remover o dispositivo. Potencialmente, essa inação pode impedir que um sistema insira seu estado de hibernação ou outro estado de baixa energia do sistema. Em casos extremos, isso pode fazer com que o sistema falhe com o código de verificação de bugs 9F.

Se o sinalizador WdfRequestStopRequestCancelable estiver definido no parâmetro ActionFlags , o driver deverá chamar WdfRequestUnmarkCancelable antes de chamar WdfRequestComplete para concluir (ou cancelar) a solicitação ou WdfRequestStopAcknowledge para redirecionar a solicitação.

Se o driver encaminhar uma solicitação de E/S de um de seus manipuladores de solicitação e especificar o sinalizador WDF_REQUEST_SEND_OPTION_SEND_AND_FORGET na estrutura de WDF_REQUEST_SEND_OPTIONS da solicitação, a estrutura não chamará a função de retorno de chamada EvtIoStop do driver para essa solicitação. No entanto, se o driver encaminhar a mesma solicitação de E/S de outro thread, a estrutura poderá chamar EvtIoStop para essa solicitação.

Para obter mais informações sobre a função de retorno de chamada EvtIoStop , consulte Usando filas de E/S de Power-Managed.

Essa função de retorno de chamada pode ser chamada em IRQL <= DISPATCH_LEVEL, a menos que o membro ExecutionLevel da estrutura de WDF_OBJECT_ATTRIBUTES do dispositivo ou do driver seja definido como WdfExecutionLevelPassive.

Requisitos

Requisito	Valor
Plataforma de Destino	Universal
Versão mínima do KMDF	1.0
Versão mínima do UMDF	2,0
Cabeçalho	wdfio.h (inclua Wdf.h)
IRQL	<= DISPATCH_LEVEL (consulte a seção Comentários)