EVT_WDF_IO_QUEUE_IO_STOP 콜백 함수(wdfio.h)

아티클
02/27/2024

[KMDF 및 UMDF에 적용]

요청의 I/O 큐가 중지되므로 드라이버의 EvtIoStop 이벤트 콜백 함수는 지정된 요청의 처리를 완료, 다시 큐에 추가 또는 일시 중단합니다.

구문

EVT_WDF_IO_QUEUE_IO_STOP EvtWdfIoQueueIoStop;

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

매개 변수

[in] Queue

I/O 요청과 연결된 프레임워크 큐 개체에 대한 핸들입니다.

[in] Request

프레임워크 요청 개체에 대한 핸들입니다.

[in] ActionFlags

콜백 함수가 호출되는 이유와 요청을 취소할 수 있는지 여부를 식별하는 하나 이상의 WDF_REQUEST_STOP_ACTION_FLAGS 형식 플래그의 비트 OR입니다.

반환 값

없음

설명

드라이버는 WdfIoQueueCreate를 호출할 때 EvtIoStop 콜백 함수를 등록합니다. WdfIoQueueCreate 호출에 대한 자세한 내용은 I/O 큐 만들기를 참조하세요.

드라이버가 I/O 큐에 대한 EvtIoStop 콜백 함수를 등록하는 경우 프레임워크는 큐의 기본 디바이스가 작동 중(D0) 상태를 떠날 때 호출합니다. 프레임워크는 드라이버가 소유한 요청과 I/O 대상으로 전달한 요청을 포함하여 드라이버가 완료되지 않은 모든 I/O 요청에 대해 EvtIoStop 콜백 함수를 호출합니다.

대부분의 경우 EvtIoStop 콜백 함수는 I/O 요청의 추가 처리를 완료, 취소 또는 연기합니다.

일반적으로 드라이버는 다음 중 하나를 수행합니다.

드라이버가 I/O 요청을 소유하는 경우 WdfRequestUnmarkCancelable을 호출하고(요청을 취소할 수 있는 경우) Requeue 값이 TRUE인 WdfRequestStopAcknowledge를 호출하거나 완료 상태 값이 STATUS_SUCCESS 또는 STATUS_CANCELLED WdfRequestComplete를 호출합니다.
WdfRequestXxx 메서드를 안전하게 호출하려면 먼저 드라이버가 EvtIoStop의 구현에 요청에 대한 단독 액세스 권한이 있는지 확인해야 합니다.

이렇게 하려면 드라이버가 요청에 대한 액세스를 동기화하여 다른 스레드가 요청을 동시에 조작하지 못하도록 해야 합니다. 선택하는 동기화 방법은 드라이버의 디자인에 따라 달라집니다.

예를 들어 요청이 공유 컨텍스트 영역에서 유지되는 경우 EvtIoStop 콜백은 내부 드라이버 잠금을 획득하고 공유 컨텍스트에서 요청을 제거한 다음 잠금을 해제할 수 있습니다. 이 시점에서 EvtIoStop 콜백은 요청을 소유하며 요청을 안전하게 완료하거나 다시 큐에 추가할 수 있습니다.

또는 드라이버가 요청의 추가 처리를 연기하고 Requeue 값이 FALSE인 WdfRequestStopAcknowledge를 호출합니다.
드라이버가 I/O 요청을 I/O 대상으로 전달한 경우 WdfRequestCancelSentRequest 를 호출하여 요청을 취소할 수 있습니다.
또는 드라이버가 자체 드라이버 스택의 하위 수준 드라이버에 I/O 요청을 전달하고 프레임워크가 WdfRequestStopActionSuspend의 ActionFlags 값을 사용하여 드라이버의 EvtIoStop 콜백을 호출하는 경우 드라이버는 REqueue 값이 FALSE인 WdfRequestStopAcknowledge를 호출할 수 있습니다. 이렇게 하기 전에 드라이버는 다음 조건이 충족되는지 확인해야 합니다.
- 낮은 드라이버는 디바이스 Dx(set-power IRP)를 수신하는 데 대한 응답으로 모든 미해결 I/O 요청 처리를 중지합니다.
- 드라이버의 CompletionRoutine 콜백 함수는 디바이스가 저전력 상태인 동안 요청을 완료할 수 있습니다.

드라이버는 적은 시간 안에 완료되도록 보장되는 요청에 대해 EvtIoStop 에서 아무 작업도 수행하지 않을 수 있습니다.

이 경우 프레임워크는 디바이스(또는 시스템)를 더 낮은 전원 상태로 이동하거나 디바이스를 제거하기 전에 지정된 요청이 완료될 때까지 기다립니다. 잠재적으로 이 동작은 시스템이 최대 절전 모드 상태 또는 다른 낮은 시스템 전원 상태로 진입하는 것을 방지할 수 있습니다. 극단적인 경우 시스템이 버그 검사 코드 9F와 충돌할 수 있습니다.

WdfRequestStopRequestCancelable 플래그가 ActionFlags 매개 변수에 설정된 경우 드라이버는 WdfRequestComplete를 호출하기 전에 WdfRequestUnmarkCancelable을 호출하여 요청을 완료(또는 취소)하거나 WdfRequestStopAcknowledge를 호출하여 요청을 다시 큐에 추가해야 합니다.

드라이버가 요청 처리기 중 하나에서 I/O 요청을 전달하고 요청 의 WDF_REQUEST_SEND_OPTIONS 구조에서 WDF_REQUEST_SEND_OPTION_SEND_AND_FORGET 플래그를 지정하는 경우 프레임워크는 이 요청에 대해 드라이버의 EvtIoStop 콜백 함수를 호출하지 않습니다. 그러나 드라이버가 다른 스레드에서 동일한 I/O 요청을 전달하는 경우 프레임워크는 이 요청에 대해 EvtIoStop 을 호출할 수 있습니다.

EvtIoStop 콜백 함수에 대한 자세한 내용은 Power-Managed I/O 큐 사용을 참조하세요.

디바이스 또는 드라이버의 WDF_OBJECT_ATTRIBUTES 구조체의 ExecutionLevel 멤버가 WdfExecutionLevelPassive로 설정되지 않는 한 IRQL <= DISPATCH_LEVEL 이 콜백 함수를 호출할 수 있습니다.

요구 사항

요구 사항	값
대상 플랫폼	유니버설
최소 KMDF 버전	1.0
최소 UMDF 버전	2.0
머리글	wdfio.h(Wdf.h 포함)
IRQL	<= DISPATCH_LEVEL(주의 섹션 참조)