UMDF 1.x 드라이버에서 USB 파이프 작업

아티클
03/08/2023

경고

UMDF 2는 UMDF의 최신 버전이며 UMDF 1을 대체합니다. 모든 새 UMDF 드라이버는 UMDF 2를 사용하여 작성해야 합니다. UMDF 1에 새 기능이 추가되지 않으며 최신 버전의 Windows 10 UMDF 1에 대한 지원이 제한됩니다. 유니버설 Windows 드라이버는 UMDF 2를 사용해야 합니다.

보관된 UMDF 1 샘플은 Windows 11 버전 22H2 - 2022년 5월 드라이버 샘플 업데이트에서 찾을 수 있습니다.

자세한 내용은 UMDF를 사용하여 시작 참조하세요.

프레임워크는 USB 인터페이스의 각 파이프를 프레임워크 USB 파이프 개체로 나타냅니다. 드라이버가 USB 디바이스를 구성하는 경우 프레임워크는 선택한 각 인터페이스에서 각 파이프에 대한 프레임워크 USB 파이프 개체를 만듭니다. 파이프 개체 메서드를 사용하면 드라이버가 다음을 수행할 수 있습니다.

파이프 정보를 가져옵니다.
파이프에서 읽습니다.
파이프에 씁니다.
파이프를 중지, 플러시 또는 다시 설정합니다.
파이프 정책을 설정합니다.
파이프 오류를 처리합니다.

UMDF-USB 파이프 정보 가져오기

UMDF 드라이버가 IWDFUsbInterface::RetrieveUsbPipeObject 메서드를 호출하여 USB 파이프 개체에 대한 IWDFUsbTargetPipe 인터페이스에 대한 포인터를 가져온 후 드라이버는 USB 파이프 개체가 USB 파이프에 대한 정보를 얻기 위해 정의하는 다음 메서드를 호출할 수 있습니다.

IWDFUsbTargetPipe::GetInformation
USB 파이프 및 해당 엔드포인트에 대한 정보를 검색합니다.

IWDFUsbTargetPipe::GetType
USB 파이프의 형식을 반환합니다.

IWDFUsbTargetPipe::IsInEndPoint
USB 파이프가 입력 엔드포인트에 연결되어 있는지 여부를 확인합니다.

IWDFUsbTargetPipe::IsOutEndPoint
USB 파이프가 출력 엔드포인트에 연결되어 있는지 여부를 확인합니다.

IWDFUsbTargetPipe::RetrievePipePolicy
WinUsb 파이프 정책을 검색합니다.

UMDF-USB 파이프에서 읽기

USB 입력 파이프에서 데이터를 읽기 위해 드라이버는 다음 기술 중 하나(또는 둘 다)를 사용할 수 있습니다.

데이터를 동기적으로 읽습니다.

USB 입력 파이프에서 동기적으로 데이터를 읽으려면 UMDF 드라이버가 먼저 IWDFIoTarget::FormatRequestForRead 메서드를 호출하여 읽기 요청을 작성합니다. 그런 다음 드라이버는 IWDFIoRequest::Send 메서드를 호출하여 WDF_REQUEST_SEND_OPTION_SYNCHRONOUS 플래그를 지정하여 요청을 동기적으로 보냅니다.
데이터를 비동기적으로 읽습니다.

USB 입력 파이프에서 비동기적으로 데이터를 읽으려면 UMDF 드라이버가 먼저 IWDFIoTarget::FormatRequestForRead 메서드를 호출하여 읽기 요청을 작성합니다. 그런 다음 드라이버는 WDF_REQUEST_SEND_OPTION_SYNCHRONOUS 플래그를 지정하지 않고 IWDFIoRequest::Send 메서드를 호출합니다.
동기 및 지속적으로 데이터를 읽습니다.

연속 판독기는 USB 파이프에서 읽기 요청을 항상 사용할 수 있도록 하는 프레임워크 제공 메커니즘입니다. 이 메커니즘은 드라이버가 항상 비동기, 원치 않는 입력 스트림을 제공하는 디바이스에서 데이터를 수신할 준비가 되도록 보장합니다. 예를 들어 NIC(네트워크 인터페이스 카드)의 드라이버는 연속 판독기를 사용하여 입력 데이터를 수신할 수 있습니다.

입력 파이프에 대한 연속 판독기를 구성하려면 드라이버의 IPnpCallbackHardware::OnPrepareHardware 콜백 함수가 IWDFUsbTargetPipe2::ConfigureContinuousReader 메서드를 호출해야 합니다. 이 메서드는 디바이스의 I/O 대상에 대한 읽기 요청 집합을 큐에 대기합니다.

또한 드라이버의 IPnpCallback::OnD0Entry 콜백 함수는 IWDFIoTargetStateManagement::Start 를 호출하여 연속 판독기를 시작해야 하며 드라이버의 IPnpCallback::OnD0Exit 콜백 함수는 IWDFIoTargetStateManagement::Stop 을 호출하여 연속 판독기를 중지해야 합니다.

디바이스에서 데이터를 사용할 때마다 I/O 대상은 읽기 요청을 완료하고 I/O 대상이 데이터를 성공적으로 읽는 경우 IUsbTargetPipeContinuousReaderCallbackReadComplete::OnReaderCompletion , IUsbTargetPipeContinuousReaderCallbackReadersFailed::OnReaderFailure 의 두 콜백 함수 중 하나를 호출합니다.

드라이버가 IWDFUsbTargetPipe2::ConfigureContinuousReader를 호출한 후 드라이버의 IUsbTargetPipeContinuousReaderCallbackReadersFailed::OnReaderFailure 콜백 함수가 호출되고 FALSE를 반환하지 않는 한 드라이버는 IWDFIoRequest::Send를 사용하여 I/O 요청을 파이프에 보낼 수 없습니다.

연속 판독기 는 UMDF 버전 1.9 이상에서 지원됩니다.

UMDF-USB 파이프에 쓰기

USB 출력 파이프에 데이터를 쓰기 위해 UMDF 드라이버는 먼저 IWDFIoTarget::FormatRequestForWrite 메서드를 호출하여 쓰기 요청을 작성할 수 있습니다. 그런 다음 드라이버는 IWDFIoRequest::Send 메서드를 호출하여 요청을 비동기적으로 보낼 수 있습니다.

UMDF-USB 파이프 중지, 플러시 및 초기화

UMDF 드라이버는 다음 메서드를 호출하여 USB 파이프를 중지, 플러시 또는 다시 설정할 수 있습니다.

IWDFUsbTargetPipe::Abort
USB 파이프에서 보류 중인 모든 전송을 중지하라는 요청을 동기적으로 보냅니다.

IWDFUsbTargetPipe::Flush
디바이스가 클라이언트가 요청한 것보다 더 많은 데이터를 반환할 때 WinUsb에서 저장한 모든 데이터를 삭제하도록 요청을 동기적으로 보냅니다.

IWDFUsbTargetPipe::Reset
USB 파이프를 다시 설정하라는 요청을 동기적으로 보냅니다.

UMDF-USB 파이프에 대한 정책 설정

UMDF 드라이버는 IWDFUsbTargetPipe::SetPipePolicy 메서드를 호출하여 USB 파이프에 대해 WinUsb에서 사용하는 동작(예: 시간 제한, 짧은 패킷 처리 및 기타 동작)을 제어할 수 있습니다.

파이프 오류 처리

드라이버의 USB 대상이 오류 상태 값으로 I/O 요청을 완료하는 경우 드라이버는 다음을 수행해야 합니다.

WdfIoTargetCancelSentIo 플래그 집합을 사용하여 IWDFIoTargetStateManagement::Stop을 호출합니다. 이 호출은 파이프를 중지하고 대상이 요청을 완료하지 않은 경우 드라이버가 USB 대상으로 보낸 추가 I/O 요청을 취소합니다.
IWDFUsbTargetPipe::Abort를 호출하여 파이프에 중단 요청을 보냅니다.
IWDFUsbTargetPipe::Reset을 호출하여 파이프에 다시 설정 요청을 보냅니다.
IWDFIoTargetStateManagement::Start를 호출하여 파이프를 다시 시작합니다.
실패한 I/O 요청과 실패한 요청 이후의 모든 I/O 요청을 다시 보냅니다.