ホスト コントローラー ドライバーが使用する UCX オブジェクトとハンドル

  • [アーティクル]

UCX は、WDF オブジェクト機能を拡張して、USB 固有の UCX オブジェクトを独自に定義します。 UCX は、基になるホスト コントローラー ドライバーへの要求をキューに入れるために、これらのオブジェクトを使用します。

まとめ

  • UCX オブジェクトは、コントローラー、そのルート ハブ、すべてのエンドポイントに関連する操作を処理するため、ホスト コントローラー ドライバーによって使用されます。
  • UCX オブジェクトはホスト コントローラー ドライバーによって作成され、各オブジェクトの有効期間は UCX によって管理されます。

重要な API

UCX は、WDF オブジェクト機能を拡張して、USB 固有の UCX オブジェクトを独自に定義します。 UCX は、基になるホスト コントローラー ドライバーへの要求をキューに入れるために、これらのオブジェクトを使用します。

WDF オブジェクトの詳細については、「フレームワーク オブジェクトの概要」を参照してください。

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: エンドポイント オブジェクト

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: ストリーム オブジェクト

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 によって管理され、ドライバーはオブジェクトを削除できません。