UCX は、WDF オブジェクト機能を拡張して、独自の USB 固有の UCX オブジェクトを定義します。 UCX では、これらのオブジェクトを使用して、基になるホスト コントローラー ドライバーへの要求をキューに格納します。
概要
- UCX オブジェクトは、コントローラー、そのルート ハブ、およびすべてのエンドポイントに関連する操作を処理するために、ホスト コントローラー ドライバーによって使用されます。
- UCX オブジェクトはホスト コントローラー ドライバーによって作成され、各オブジェクトの有効期間は UCX によって管理されます。
重要な API
- UcxControllerCreate
- UcxRootHubCreateの
- UcxUsbDeviceCreate
UCX は、WDF オブジェクト機能を拡張して、独自の USB 固有の UCX オブジェクトを定義します。 UCX では、これらのオブジェクトを使用して、基になるホスト コントローラー ドライバーへの要求をキューに格納します。
WDF オブジェクトの詳細については、「 Framework オブジェクトの概要」を参照してください。
UCXCONTROLLER: ホスト コントローラー オブジェクト
ホスト コントローラー ドライバーによって作成されるホスト コントローラーを表します。 ドライバーは、ホスト コントローラー インスタンスごとに 1 つのホスト コントローラー オブジェクトのみを作成する必要があります。 通常、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 コールバック内でホスト コントローラー ドライバーによって作成されます。 ホスト コントローラー インスタンスごとにルート ハブ オブジェクトは 1 つだけ必要です。 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: Endpoint オブジェクト
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 No Ping 応答エラーを受信した場合、ドライバーは UcxEndpointNoPingResponseError を呼び出す必要があります。 その呼び出しにより、USB デバイス オブジェクトが EVT_UCX_USBDEVICE_UPDATEを受信します。 詳細については、「 ホスト コントローラー ドライバーでの USB エンドポイントの構成」を参照してください。
UCXSTREAMS: Stream オブジェクト
1 つのエンドポイントにまたがるデバイスへのパイプの数を表します。 ホスト コントローラー ドライバーは、UcxStaticStreamsCreate を呼び出して、EVT_UCX_ENDPOINT_STATIC_STREAMS_ADD コールバックにストリーム オブジェクトを作成します。
UcxStaticStreamsCreate 呼び出し中に、ホスト コントローラー ドライバーはコールバック関数を登録します。 特定のエンドポイント オブジェクトの場合、ドライバーはストリーム オブジェクトを作成したかどうかを判断し、 UcxEndpointGetStaticStreamsReferenced を呼び出して UCXSTREAMS ハンドルを返すことができます。
オブジェクトが作成されると、ドライバーは、各ストリームのフレームワーク キュー オブジェクトを作成し、 UcxStaticStreamsSetStreamInfo を呼び出すことによって UCX に WDFQUEUE ハンドルを送信します。
ストリーム オブジェクトは、UCX による静的ストリームの管理を支援するために、ホスト コントローラーに対していくつかのコールバック関数を提供します。
EVT_UCX_ENDPOINT_STATIC_STREAMS_DISABLE
エンドポイントのすべてのストリームのコントローラー リソースを解放します。
EVT_UCX_ENDPOINT_STATIC_STREAMS_ENABLE
このエンドポイントのすべてのストリームのコントローラー ハードウェアを有効にします。
オブジェクトおよび関連するキューの有効期間は UCX によって管理され、ドライバーはオブジェクトを削除できません。