호스트 컨트롤러 드라이버에서 사용하는 UCX 개체 및 핸들

  • 아티클

UCX는 WDF 개체 기능을 확장하여 자체 USB 관련 UCX 개체를 정의합니다. UCX는 이러한 개체를 사용하여 기본 호스트 컨트롤러 드라이버에 대한 요청을 큐에 대기합니다.

요약

  • UCX 개체는 호스트 컨트롤러 드라이버에서 컨트롤러, 루트 허브 및 모든 엔드포인트와 관련된 작업을 처리하는 데 사용됩니다.
  • UCX 개체는 호스트 컨트롤러 드라이버에 의해 생성되며 각 개체의 수명은 UCX에서 관리됩니다.

중요 API

UCX는 WDF 개체 기능을 확장하여 자체 USB 관련 UCX 개체를 정의합니다. UCX는 이러한 개체를 사용하여 기본 호스트 컨트롤러 드라이버에 대한 요청을 큐에 대기합니다.

WDF 개체에 대한 자세한 내용은 프레임워크 개체 소개를 참조하세요.

UCXCONTROLLER: 호스트 컨트롤러 개체

호스트 컨트롤러 드라이버에서 만든 호스트 컨트롤러를 나타냅니다. 드라이버는 instance 호스트 컨트롤러당 하나의 호스트 컨트롤러 개체만 만들어야 합니다. 일반적으로 UcxControllerCreate 메서드를 호출하여 EvtDriverDeviceAdd 콜백 내에서 생성됩니다.

호스트 컨트롤러 드라이버가 개체를 만들 때 드라이버는 UCX에서 호출하는 콜백 함수의 구현을 등록합니다. 드라이버는 호스트 컨트롤러가 연결된 버스 유형(예: ACPI 또는 PCI)을 추가로 식별해야 합니다. 또한 드라이버는 UcxControllerCreate 호출에 전달되는 UCX_CONTROLLER_CONFIG 구조를 사용하여 호스트 컨트롤러 디바이스 정보를 제공합니다.

I/O 요청을 처리하려면 호스트 컨트롤러 드라이버가 GUID_DEVINTERFACE_USB_HOST_CONTROLLER 디바이스 인터페이스를 등록해야 합니다. 드라이버는 이 인터페이스에 정의된 IOCTL을 구현할 필요가 없습니다. 대신 UCX 클라이언트는 UcxIoDeviceControl을 호출하여 이 인터페이스에서 받은 IOCTL 요청을 UCX에 전달합니다.

다음은 UCX에서 호출하는 호스트 컨트롤러 개체와 연결된 콜백 함수입니다. 이러한 함수는 호스트 컨트롤러 드라이버에 의해 구현되어야 합니다.

*
EVT_UCX_CONTROLLER_USBDEVICE_ADD 허브 드라이버가 루트 허브 및/또는 외부 허브와의 상호 작용을 통해 버스에 새 디바이스가 있다고 판단할 때 호출됩니다.

*
EVT_UCX_CONTROLLER_QUERY_USB_CAPABILITY USB 호스트 컨트롤러에서 지원하는 다양한 기능에 대한 정보를 수집하기 위해 UCX에서 호출합니다.

*
EVT_UCX_CONTROLLER_RESET 감지된 오류에 대한 응답으로 컨트롤러 하드웨어를 다시 설정하기 위해 UCX에서 호출됩니다.

*
EVT_UCX_CONTROLLER_GET_CURRENT_FRAMENUMBER 호스트 컨트롤러에서 현재 프레임 번호를 검색하는 데 사용되며, 이는 허브 드라이버가 등시 전송을 예약하는 데 사용됩니다.

UCXROOTHUB: 루트 허브 개체

호스트 컨트롤러의 루트 포트 상태 가져오고 제어합니다. 호스트 컨트롤러 드라이버가 일반적으로 호스트 컨트롤러 개체를 만든 후 UcxRootHubCreate 메서드를 호출하여 EvtDriverDeviceAdd 콜백 내에서 만듭니다. instance 호스트 컨트롤러당 루트 허브 개체가 하나만 있어야 합니다. UcxRootHubCreate 호출에서 드라이버는 콜백 구현을 등록합니다.


EVT_UCX_ROOTHUB_GET_INFO 루트 허브의 USB 2.0 및 USB 3.0 포트 수를 반환합니다.


EVT_UCX_ROOTHUB_GET_20PORT_INFO 루트 허브의 USB 2.0 또는 USB 3.0 포트(*EVT_UCX_ROOTHUB_GET_30PORT_INFO)에 대한 정보를 반환합니다.

루트 허브 개체를 만들고 초기화한 후 허브 드라이버는 인터럽트 및 제어 전송을 전송하여 루트 허브 포트와 상호 작용합니다. UCX는 호스트 컨트롤러 드라이버에서 구현한 이러한 콜백 함수를 호출하여 이러한 전송을 지원합니다.


EVT_UCX_ROOTHUB_CONTROL_URB USB 허브의 기능 제어 요청을 처리합니다.


EVT_UCX_ROOTHUB_INTERRUPT_TX 변경된 포트에 대한 정보 요청을 처리합니다.

자세한 내용은 호스트 컨트롤러 드라이버의 루트 허브 콜백 함수를 참조하세요.

UCXUSBDEVICE: USB 디바이스 개체

버스에 연결된 실제 USB 디바이스를 나타냅니다. 일반적으로 호스트 컨트롤러 드라이버가 UcxUsbDeviceCreate 메서드를 호출하여 EVT_UCX_CONTROLLER_USBDEVICE_ADD 콜백 내에서 만듭니다.

개체가 만들어지면 호스트 컨트롤러 드라이버가 콜백 함수의 구현을 UcxUsbDeviceCreate 호출에 등록합니다.

이러한 콜백 함수는 컨트롤러와 드라이버에 USB 디바이스의 현재 상태 대한 정보를 유지합니다.


EVT_UCX_USBDEVICE_ENABLE 디바이스의 기본 엔드포인트로 전송을 수행하기 위해 컨트롤러를 준비합니다.


EVT_UCX_USBDEVICE_DISABLE 디바이스 및 기본 엔드포인트와 연결된 컨트롤러 리소스를 해제합니다.


EVT_UCX_USBDEVICE_ADDRESS 컨트롤러에 주소를 프로그래밍하고 디바이스로 SET_ADDRESS 전송하여 주소가 지정된 상태로 전환합니다.


EVT_UCX_USBDEVICE_ENDPOINTS_CONFIGURE 비 기본 엔드포인트를 컨트롤러에 프로그래밍하고/또는 다른 기본이 아닌 엔드포인트를 해제합니다.


EVT_UCX_USBDEVICE_RESET 디바이스가 다시 설정되었다는 컨트롤러 알림입니다. 이 경우 드라이버는 컨트롤러를 USB 디바이스와 동기화하는 데 필요한 작업을 수행합니다.


EVT_UCX_USBDEVICE_UPDATE 컨트롤러에 디바이스와 관련된 다양한 정보 비트를 알 수 있습니다.


EVT_UCX_USBDEVICE_HUB_INFO 허브 디바이스에 대한 UCXUSBDEVICE 핸들인 경우 허브 속성에 대한 알림입니다.


EVT_UCX_USBDEVICE_ENDPOINT_ADD 드라이버에 디바이스에 대한 엔드포인트를 만들도록 알 수 있습니다. 기본 엔드포인트에 대한 EVT_UCX_USBDEVICE_DEFAULT_ENDPOINT_ADD.

일시 중단된 USB 3.0 디바이스의 인터페이스가 절전 모드 해제 신호를 받으면 드라이버는 UcxUsbDeviceRemoteWakeNotification 을 호출하여 UCX에 알릴 것으로 예상됩니다.

개체를 만든 후 개체의 수명은 UCX에서 관리되며 드라이버는 개체를 삭제하면 안됩니다.

UCXENDPOINT: 엔드포인트 개체

USB 디바이스 개체의 엔드포인트를 나타냅니다. 엔드포인트 개체는 EVT_UCX_USBDEVICE_DEFAULT_ENDPOINT_ADD 또는 EVT_UCX_USBDEVICE_ENDPOINT_ADD콜백 중에 호스트 컨트롤러에 의해 만들어집니다. 엔드포인트 개체를 만들 때 드라이버는 콜백 함수를 등록합니다.

또한 드라이버는 각 엔드포인트에 대한 프레임워크 큐 개체를 만들고 UcxEndpointSetWdfIoQueue를 호출하여 해당 큐에 대한 WDFQUEUE를 UCX에 전달합니다. 엔드포인트가 만들어지면 개체 및 관련 큐의 수명이 UCX에서 관리되며 드라이버는 이러한 개체 자체를 삭제해서는 안 됩니다.

엔드포인트 개체는 드라이버가 엔드포인트와 관련된 작업을 UCX에 지원할 수 있도록 하는 여러 콜백 함수를 구현합니다.


EVT_UCX_ENDPOINT_ABORT 엔드포인트와 연결된 큐를 중단합니다.


EVT_UCX_ENDPOINT_OK_TO_CANCEL_TRANSFERS 컨트롤러 드라이버에 엔드포인트에서 취소된 전송을 완료할 수 있음을 알립니다.


EVT_UCX_ENDPOINT_PURGE 엔드포인트에서 모든 미해결 I/O 요청을 완료합니다.


EVT_UCX_ENDPOINT_START 엔드포인트와 연결된 큐를 시작합니다.


EVT_UCX_ENDPOINT_STATIC_STREAMS_ADD 정적 스트림을 만듭니다.


EVT_UCX_ENDPOINT_RESET 엔드포인트의 컨트롤러 프로그래밍을 다시 설정하도록 드라이버에 알립니다.

호스트 컨트롤러 드라이버가 엔드포인트에서 USB 3.0 Ping 응답 없음 오류를 수신하면 드라이버는 UcxEndpointNoPingResponseError를 호출해야 합니다. 이 호출은 USB 디바이스 개체가 EVT_UCX_USBDEVICE_UPDATE 수신합니다. 자세한 내용은 호스트 컨트롤러 드라이버에서 USB 엔드포인트 구성을 참조하세요.

UCXSTREAMS: Stream 개체

단일 엔드포인트에서 디바이스에 대한 여러 파이프를 나타냅니다. 호스트 컨트롤러 드라이버는 UcxStaticStreamsCreate를 호출하여 EVT_UCX_ENDPOINT_STATIC_STREAMS_ADD 콜백에 스트림 개체를 만듭니다.

UcxStaticStreamsCreate 호출 중에 호스트 컨트롤러 드라이버가 콜백 함수를 등록합니다. 특정 엔드포인트 개체의 경우 드라이버는 스트림 개체를 만들었는지 여부를 확인하고 UcxEndpointGetStaticStreamsReferenced를 호출하여 UCXSTREAMS 핸들을 반환할 수 있습니다.

개체를 만든 후 드라이버는 각 스트림에 대한 프레임워크 큐 개체를 만들고 UcxStaticStreamsSetStreamInfo를 호출하여 WDFQUEUE 핸들을 UCX로 보냅니다.

스트림 개체는 UCX가 정적 스트림을 관리하는 데 도움이 되도록 호스트 컨트롤러에 대한 여러 콜백 함수를 제공합니다.


EVT_UCX_ENDPOINT_STATIC_STREAMS_DISABLE 엔드포인트에 대한 모든 스트림에 대한 컨트롤러 리소스를 해제합니다.


EVT_UCX_ENDPOINT_STATIC_STREAMS_ENABLE 이 엔드포인트에 대한 모든 스트림의 컨트롤러 하드웨어를 사용하도록 설정합니다.

개체 및 연결된 큐의 수명은 UCX에서 관리되며 드라이버는 개체를 삭제해서는 안 됩니다.