WDI IHV ドライバー インターフェイス

  • [アーティクル]

WDI IHV ミニポートは、他の NDIS ミニポート ドライバーと同様であり、任意の NDIS ミニポートの開発プラクティスとドキュメントに従います。 NDIS ハンドラーに対するネイティブ WLAN ミニポート ドライバーの役割は、MS コンポーネントと WDI IHV ドライバーの間で分割されます。 Microsoft WLAN コンポーネントは、すべての IHV がすべての作業をやり直す必要がないように、すべての Wi-Fi ミニポートに適用される NDIS 要件を処理します。 WDI IHV ミニポートに適用される場合のネイティブ WLAN IHV ミニポートの NDIS ハンドラーのマッピングと動作の変更については、以下で説明します。

ドライバーのインストール

WDI IHV ミニポート ドライバーが読み込まれ、システムにインストールされる仕組みに変更はありません。 INF およびインストール プロセスは、IHV ネイティブ WLAN ミニポート ドライバーのプロセスに似ています。 既存の NDIS ドライバーと同様に、IHV ドライバーを読み込んで IHV の WLAN アダプターを操作する必要がある場合、オペレーティング システムは IHV ミニポート ドライバーの DriverEntry ルーチンを呼び出します。

DriverEntry

オペレーティング システムは、WDI IHV ミニポート ドライバーの DriverEntry ルーチンを直接呼び出します。 IHV ミニポートは、通常の NDIS ミニポートの DriverEntry ルーチンのほとんどのガイドラインに従います。 1 つの例外は、NdisMRegisterMiniportDriver を呼び出す代わりに、IHV ミニポートが NdisMRegisterWdiMiniportDriver を呼び出して、Microsoft WLAN コンポーネントを有効にするようにオペレーティング システムに指示することです。

以下は、NdisMRegisterWdiMiniportDriver の主要なパラメーターです。

  • NDIS_MINIPORT_DRIVER_CHARACTERISTICS: これは、ネイティブ Wi-Fi ミニポートが NDIS に登録するために使用する元の NDIS 構造体です。 WDI モデルの場合、ほとんどのハンドラー パラメーターはオプションです。 必須のハンドラーは、 MINIPORT_OID_REQUEST_HANDLER と MINIPORT_DRIVER_UNLOADのみです。 MINIPORT_OID_REQUEST_HANDLER は、WDI メッセージを IHV ドライバーに渡すために使用されます。 他のハンドラーが指定されている場合、通常、Microsoft WLAN コンポーネントはハンドラーに対して独自の処理を実行した後にハンドラーを呼び出します。
  • NDIS_MINIPORT_DRIVER_WDI_CHARACTERISTICS: これは、WDI ミニポート ドライバーが実装する必要があるハンドラーの新しいセットです。 これは、コントロール パスの追加ハンドラーと、データ パスのハンドラーの完全なセットを登録するために IHV ドライバーによって使用されます。

IHV ミニポートが NdisMRegisterWdiMiniportDriver を呼び出すと、Microsoft WLAN コンポーネントは、NDIS_MINIPORT_DRIVER_CHARACTERISTICS のハンドラーを更新し、NDISの NdisMRegisterMiniportDriver を呼び出します。 更新は、Microsoft WLAN コンポーネントが WDI IHV ミニポート ドライバーに支援/簡略化を提供できるハンドラーをインターセプトできるように実行されます。

以下は WDI IHV ミニポート ドライバーの DriverEntry プロセスの一般的なフローです。

wdi driverentry flow.

DriverEntry の詳細については、「NDIS ミニポート ドライバーの DriverEntry」を参照してください。

MiniportSetOptions

上記の DriverEntry の図に示すように、WDI IHV ミニポートが MiniportSetOptions ハンドラーを登録している場合、オペレーティング システムは NdisMRegisterWdiMiniportDriver を呼び出すミニポート ドライバーのコンテキストでその関数を呼び出します。

IHV ミニポート ドライバーが NdisSetOptionalHandlers を使用してオプション ハンドラーを登録する場合、これらのハンドラーは、Microsoft コンポーネントによって WDI レイヤーを介してシリアル化されない可能性があります。 したがって、IHV コンポーネントは、これらのハンドラーの同期要件を処理する役割を担います。

MiniportInitializeEx

WDI モデルは、MiniportInitializeEx の 動作を複数の WDI インターフェイス呼び出しに分割します。

  1. MiniportWdiAllocateAdapter を呼び出します。

    オペレーティング システムが IHV ハードウェアのインスタンスを見つけると、これは WDI IHV ミニポート ドライバーへの最初の呼び出しです。 この呼び出しでは、WDI ミニポートは、デバイスのソフトウェア表現 (MiniportAdapterContext) を作成するために必要なアクションを実行します。 また、NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES 構造体に入力するデバイスに関する情報も決定します。 デバイスと Wi-Fi スタックの実際の初期化は、後で Microsoft コンポーネントが WDI コマンドを送信して特定の初期化を実行するときに行われます。

    WDI IHV ミニポート ドライバーから取得したデータを使用して、Microsoft コンポーネントは NdisMSetMiniportAttributes を呼び出し、NDIS の NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES を設定します。 NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES のほとんどのフィールドには、Microsoft コンポーネントによって既定値が入力されます。 IHV ドライバーは、MiniportAdapterContext と InterfaceType のフィールドに値を入力する必要があります。

    この呼び出しは、IHV ミニポート ドライバーから返されると、その MiniportOidRequest ハンドラーを介して WDI コマンドの受信を開始します。 この呼び出し中に、Microsoft コンポーネントはリセット/回復操作を実行できない可能性があるため、ここで実行されるアクティビティは迅速かつ信頼性が高いはずです。

  2. MiniportWdiOpenAdapter を呼び出します。

    MiniportWdiAllocateAdapter の後で、Microsoft コンポーネントは MiniportWdiOpenAdapter を呼び出してファームウェアします。をロードし、ハードウェアを初期化to load the firmware and initialize the hardware.

  3. MiniportOidRequest を使用する複数の WDI コマンド。

    MiniportWdiOpenAdapter の後、Microsoft コンポーネントは、IHV ミニポートに次のタスク/プロパティ/呼び出しを送信します。

    1. MiniportWdiTalTxRxInitialize を呼び出してして、データ パスと交換ハンドラーを初期化します。
    2. OID_WDI_GET_ADAPTER_CAPABILITIES を呼び出して、アダプターの機能を取得します。
    3. OID_WDI_SET_ADAPTER_CONFIGURATION を呼び出してしてアダプターを構成します。
    4. OID_WDI_TASK_SET_RADIO_STATE を呼び出して、初期無線状態がまだ想定された状態でない場合に設定します。
    5. MiniportWdiTalTxRxStart を呼び出してデータ パスを設定します。
    6. OID_WDI_TASK_CREATE_PORT を呼び出して初期ポートを作成します。

    その他のコマンドは、Microsoft コンポーネントのミニポートInitializeEx 処理の一部として IHV コンポーネントに送信することもできます。 ただし、MiniportWdiStartOperation が呼び出されるまで、Microsoft コンポーネントは、OTA (over-the-air) を必要とするタスクを送信しません。 常に最初に送信される OID_WDI_TASK_OPEN を除き、他のコマンド/呼び出しの順序は変わる可能性があります。

    WDI IHV ミニポート ドライバーから取得したデータを使用して、Microsoft コンポーネントは NdisMSetMiniportAttributes を呼び出し、NDIS の NDIS_MINIPORT_ADAPTER_GENERAL_ATTRIBUTES と NDIS_MINIPORT_ADAPTER_NATIVE_802_11_ATTRIBUTES を設定します。

  4. MiniportWdiStartOperation を呼び出します。

    これは、IHV ドライバーが追加のミニポート初期化Ex タスクを実行するために使用できる NDIS_MINIPORT_DRIVER_WDI_CHARACTERISTICS 内のオプションの WDI ミニポート ハンドラーです。 また、Microsoft コンポーネントがミニポートの初期化を完了し、ミニポートが必要なバックグラウンド アクティビティを開始できることを示すヒントとして、IHV ミニポートで使用することもできます。

    次の図は、MiniportInitializeEx のフローを示しています。

    wdi miniport initialization flow.

    中間操作が失敗した場合、Microsoft コンポーネントは前の操作を元に戻し、ミニポートの起動に失敗します。 たとえば、OID_WDI_TASK_CREATE_PORT が失敗した場合、データ パスがクリーンされ、OID_WDI_TASK_CLOSE が送信され、ミニポートが失敗します。

MiniportHaltEx

ネイティブ Wi-Fi ミニポートでは、MiniportHaltEx を使用して、操作を停止し、アダプター インスタンスをクリーンするようにミニポートに指示します。 WDI モデルでは、Microsoft コンポーネントは元の MiniportHaltEx 呼び出しを処理し、複数の WDI インターフェイス呼び出しに分割します。

  1. MiniportWdiStopOperation を呼び出します。

    これは、NDIS_MINIPORT_DRIVER_WDI_CHARACTERISTICS 内部のオプションの WDI ミニポート ハンドラーであり、これを使用すると MiniportWdiStartOperation で実行した操作を元に戻すことができます。

  2. MiniportOidRequest を使用する複数の WDI コマンド。

    MiniportWdiStopOperation の後で、Microsoft コンポーネントは、IHV ドライバーの現在の状態をクリーンする IHV ミニポートにタスク/プロパティを送信します。 このクリーンアップには、以下が含まれる場合があります。

    1. OID_WDI_TASK_DISCONNECT/OID_WDI_TASK_STOP_AP を呼び出して、既存の接続をティアダウンします。
    2. OID_WDI_TASK_DELETE_PORT を呼びたして、作成されたすべてのポートを削除します。
    3. MiniportWdiTalTxRxStop を呼び出して、データ パスを停止します。
    4. MiniportWdiTalTxRxDeinitialize を呼び出して、データ パスの初期化を解除します。
    5. ハードウェアの状態をクリーンアップするために呼び出します。 これは、IHV ドライバーによって登録されている MiniportWdiCloseAdapter を使用して IHV に送信されます。

  3. 上記のすべてのコマンドが呼び出されると、Microsoft コンポーネントは、MiniportWdiFreeAdapter を呼び出して、IHV ドライバーが持っている可能性があるソフトウェアの状態を削除します。

次の図は、MiniportHaltEx のフローを示しています。

wdi miniport halt flow.

デバイスが突然取り外された場合、またはシステムの電源がオフになっている場合、MiniportHaltEx の処理は実行されません。 突然の取り外しについては、MiniportDevicePnPEventNotify ハンドラーの動作の説明を参照してください。 システムのシャットダウンについては、MiniportShutdownEx ハンドラーの動作の説明を参照してください。

MiniportDriverUnload

MiniportDriverUnload は、WDI IHV ミニポートがアンロードされる前に呼び出されるハンドラーです。 WDI IHV ミニポート ドライバーは、それ自体を登録解除する Microsoft コンポーネントを呼び出します。 Microsoft コンポーネントは NdisMDeregisterMiniportDriver を呼び出します。

次の図は、MiniportDriverUnload のフローを示しています。

wdi miniport driver unload flow.

MiniportPause

NDIS MiniportPause の要件は、Microsoft コンポーネントによって処理されます。 MiniportPause の一部として、Microsoft コンポーネントはデータ パスを停止し、クリーンアップするまで待機します。 WDI IHV ミニポートは、必要に応じて、データ パスのクリーンアップが完了した後、Microsoft コンポーネントによって呼び出される MiniportWdiPostAdapterPause コールバックを登録できます。

次の図は、MiniportPause のフローを示しています。

wdi miniport pause flow.

MiniportRestart

NDIS MiniportRestart の要件は、Microsoft コンポーネントによって処理されます。 MiniportRestart の一部として、Microsoft コンポーネントは、MiniportPause の一部として実行されたデータ パスの一時停止作業を元に戻します。 WDI IHV ミニポートは、必要に応じて、データ パスのクリーンアップが完了した後、Microsoft コンポーネントによって呼び出される MiniportWdiPostAdapterRestart コールバックを登録できます。

次の図は、MiniportRestart のフローを示しています。

wdi miniport restart flow.

MiniportResetEx

MiniportResetEx は、Microsoft コンポーネントによって処理されません。 WDI IHV ミニポートは、必要に応じて、Microsoft コンポーネントによって呼び出される MiniportResetEx コールバックを登録できます。

MiniportDevicePnPEventNotify

MiniportDevicePnPEventNotify は、デバイスの突然の取り外しなどの PNP イベントの NDIS ドライバーに通知するために使用されます。 NDIS がこの通知を送信すると、処理の対象として WDI IHV ミニポートに最初に転送されます。 IHV コンポーネントの処理が完了すると、Microsoft コンポーネントはこのイベントに対して適切な処理を実行します。 IHV コンポーネントに転送される呼び出しは、他のタスクとコールバックと共にシリアル化されません。

次の図は、MiniportDevicePnPEventNotify のフローを示しています。

wdi miniport drive pnp notification flow.

MiniportShutdownEx

MiniportShutdownEx は、システムのシャットダウン イベントについて NDIS ドライバーに通知するために使用されます。 NDIS がこの通知を送信すると、最初に Microsoft コンポーネントによって処理されます。 Microsoft コンポーネントは、処理が完了すると、イベントを処理の対象として WDI IHV ミニポートに渡します。

次の図は、MiniportShutdownEx のフローを示しています。

wdi miniport shutdown flow.

MiniportOidRequest

MiniportOidRequest ハンドラーは、WDI IHV ミニポートを実装する必要があります必要なハンドラーです。 これは、WDI コマンドを IHV ミニポートに送信するために Microsoft コンポーネントによって使用されます。 また、Microsoft コンポーネントが IHV ミニポートに処理しない OID を転送するためにも使用します。

WDI IHV ミニポートへの MiniportOidRequest 呼び出しは、WDI コマンドの M1 メッセージと見なす必要があります。 OID の完了 (NdisMOidRequestComplete 経由、または MiniportOidRequest から PENDING 以外の戻り値を使用) は、WDI タスク/コマンドの M3 メッセージと見なす必要があります。

WDI コマンドごとに、操作にNDIS_STATUS コードを返すことができる可能性のあるフィールドが 2 つあります。MiniportOidRequest 呼び出し (または NdisMOidRequestComplete) と WDI_MESSAGE_HEADER フィールド内の状態コード (OID 完了またはNdisMIndicateStatusEx 経由のいずれか) です。 Microsoft コンポーネントは、WDI_MESSAGE_HEADERStatus フィールドを見る前に、常に OID 完了から NDIS_STATUS を調べます。 WDI OID 処理に対する IHV コンポーネントの期待値は次のとおりです。

  1. WDI OID は NDIS_OID_REQUESTRequestType (NdisRequestMethod) を使用して IHV コンポーネントに送信され、対応するメッセージとメッセージ長が DATA.METHOD_INFORMATION.InformationBuffer と DATA.METHOD_INFORMATION.InputBufferLength のフィールド内にそれぞれあります。
  2. IHV コンポーネントは、コマンドの処理中にエラーが発生した場合に OID 入力候補のエラーを報告し、Wi-Fi レベルのエラーがある場合は、WDI_MESSAGE_HEADER の Status フィールドを成功以外に設定します。
  3. タスクとプロパティの場合、要求のポート番号は WDI_MESSAGE_HEADERPortId フィールドにあります。 PortNumber は NDIS_OID_REQUEST 内にあり、常に 0 に設定されます。
  4. OID の完了については、MiniportOidRequest が NDIS_STATUS_PENDING を返し、後で (同期的または非同期的に) NdisMOidRequestComplete で OID を完了することが許容されます。
  5. IHV コンポーネントが NDIS_STATUS_SUCCESSを使用して OID を完了する場合は、WDI_MESSAGE_HEADERの領域を含む、適切なバイト数を OID 要求の BytesWritten フィールドに適切なバイト数を (WDI_MESSAGE_HEADER のスペースを含めて) 設定する必要があります。
  6. IHV コンポーネントで DATA.METHOD_INFORMATION.OutputBufferLength フィールドにレスポンスを満たせる十分な領域がない場合、コンポーネントは NDIS_STATUS_BUFFER_TOO_SHORT で OID を完了し、DATA.METHOD_INFORMATION.BytesNeeded フィールドに値を入力します。 Microsoft コンポーネントは、要求されたサイズのバッファーを割り当て、新しい要求を IHV に送信しようとする場合があります。
  7. これがタスクの場合、タスクの M4 (NdisMIndicateStatusEx) は、タスクが正常に開始されたと報告された場合、つまり OID が正常に完了がして Status が (WDI_MESSAGE_HEADER で) 成功の場合にのみ示す必要があります。

次の図は、1 つの WDI コマンドにマップされる NDIS OID 要求の例を示しています。 オペレーティング システムによって OID 要求が送信されると、Microsoft コンポーネントはそれを WDI OID 要求に変換し、WDI OID 要求を IHV ミニポートに送信します。 IHV ミニポートが OID を完了すると、Microsoft コンポーネントは、元の OID 要求を適切に完了します。

wdi miniport oid request sequence for single wdi command.

OriginalOidRequest が複数の WDI OidRequest にマップされ、いずれかの WDI 要求が失敗した場合、OriginalOidRequest も失敗します。 中間操作のサブセットが既に完了している場合、Microsoft コンポーネントはクリーンアップをサポートする操作を元に戻そうとします。

次の図は、Microsoft コンポーネントによって完了した処理される NDIS OID 要求の例を示しています。 オペレーティング システムによって OID 要求が送信されると、Microsoft コンポーネントは OID を処理して完了します。 この OID は、WDI IHV ミニポートに渡されません。

wdi miniport oid request sequence for oids handled by microsoft component.

Microsoft コンポーネントで認識されない OID は、処理のために IHV コンポーネントに直接転送されます。

wdi miniport oid request sequence for oids not handled by microsoft component.

WDI IHV ミニポート ドライバーの MiniportOidRequest の動作は (ネイティブ Wi-Fi ミニポートと比較して) 変更されません。 呼び出しはシリアル化され、IHV ミニポートは、NdisMOidRequestComplete の呼び出しを使用して同期的または非同期的に完了できます。

MiniportCancelOidRequest

これは、WDI メッセージにマップされていない OID を処理する必要がある WDI IHV ミニポートによって使用される省略可能なハンドラーです。 このハンドラーは、WDI OID には使用されません。 WDI OID はすぐに完了する必要があり、保留中の OID を取り消そうとする IHV ミニポート ドライバーの必要はありません。 WDI タスクの取り消しは、適切な取り消しタスク OID 要求を使用して処理されます。 マップされていない OID の場合、期待される動作は NDIS によって定義されます。

NdisMIndicateStatusEx

NdisMIndicateStatusEx は、Microsoft コンポーネントに表示を送信する WDI IHV ミニポートによって使用されます。 この表示は、TKIP MIC 障害などの未承諾の表示、またはタスクの完了 (M4) に対する要請された表示である可能性があります。

次の図は、対応する NDIS/ネイティブ Wi-Fi 表示がある WDI 表示の例を示しています。 IHV ミニポートによって Microsoft コンポーネントに表示が送信されると、Microsoft コンポーネントは、それを既存の表示に変換し、オペレーティング システムに転送します。

wdi miniport status indication flow.

次の図は、対応する NDIS/ネイティブ Wi-Fi 表示がない WDI 表示の例を示しています。 これは Microsoft コンポーネントによって処理されます。

wdi status indication without direct mapping to ndis.

次の図は、Microsoft コンポーネントによって認識されないことを示しています。 表示は、そのままオペレーティング システムに転送されます。

wdi status indication not recognized by microsoft component.

WDI IHV ミニポート ドライバーの NdisMIndicateStatusEx の動作は (ネイティブ Wi-Fi ミニポートと比較して) 変更されません。

MiniportDirectOidRequest

これは、WDI メッセージにマップされていない Direct OID を処理する必要がある場合、WDI IHV ミニポート ドライバーによって登録される省略可能なハンドラーです。 Wi-Fi Direct 用の既存の Direct OID はすべて WDI メッセージにマップされるため、このハンドラーはその機能をサポートする必要はありません。 サポートされていない Direct OID は、Microsoft コンポーネントによってシリアル化されません。

MiniportCancelDirectOidRequest

これは、WDI メッセージにマップされていない Direct OID を処理する必要がある WDI IHV ミニポートによって使用される省略可能なハンドラーです。 マップされていない OID の場合、期待される動作は NDIS によって定義されます。

MiniportSendNetBufferLists

このハンドラーは、WDI IHV ミニポート ドライバーでは使用されないため、指定しないでください。 Microsoft コンポーネントは、NDIS_MINIPORT_DRIVER_WDI_CHARACTERISTICS 経由で登録されたデータ パス ハンドラーを使用して、IHV ミニポートにパケットを送信します。

MiniportCancelSend

このハンドラーは、WDI IHV ミニポート ドライバーでは使用されないため、指定しないでください。

MiniportReturnNetBufferLists

このハンドラーは、WDI IHV ミニポート ドライバーでは使用されないため、指定しないでください。 Microsoft コンポーネントは、NDIS_MINIPORT_DRIVER_WDI_CHARACTERISTICS 経由で登録されたデータ パス ハンドラーを使用して、受信したパケットを IHV ミニポートに返します。

WDI ハンドラー: MiniportWdiOpenAdapter

MiniportWdiOpenAdapter ハンドラーは、IHV ドライバーでタスクを開く操作を開始する Microsoft コンポーネントによって使用されます。 この呼び出しはすぐに完了し、開く操作が正常に開始された場合、IHV はこの呼び出しで NDIS_STATUS_SUCCESS を返し、OpenAdapterComplete ハンドラーを呼び出す必要があり、ハンドラーは NDIS_WDI_INIT_PARAMETERS (MiniportWdiAllocateAdapter のパラメーター) に渡されます。.

WDI ハンドラー: MiniportWdiCloseAdapter

MiniportWdiCloseAdapter ハンドラーは、IHV ドライバーでタスクを閉じる操作を開始する Microsoft コンポーネントによって使用されます。 この呼び出しはすぐに完了し、閉じる操作が正常に開始された場合、IHV はこの呼び出しで NDIS_STATUS_SUCCESS を返し、OpenAdapterComplete ハンドラーを呼び出す必要があり、ハンドラーは NDIS_WDI_INIT_PARAMETERS (MiniportWdiAllocateAdapter のパラメーター) に渡されます。.