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

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

• Driver installation
• DriverEntry
• MiniportSetOptions
• MiniportInitializeEx
• MiniportHaltEx
• MiniportDriverUnload
• MiniportPause
• MiniportRestart
• MiniportResetEx
• MiniportDevicePnPEventNotify
• MiniportShutdownEx
• MiniportOidRequest
• MiniportCancelOidRequest
• NdisMIndicateStatusEx
• MiniportDirectOidRequest
• MiniportCancelDirectOidRequest
• MiniportSendNetBufferLists
• MiniportCancelSend
• MiniportReturnNetBufferLists
• WDI ハンドラー: ミニポートWdiOpenAdapter
• WDI ハンドラー: ミニポートWDIクローズアダプター

Driver installation

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 プロセスの一般的なフローを次に示します。

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

MiniportSetOptions

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

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

MiniportInitializeEx

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

1. Call MiniportWdiAllocateAdapter.

   オペレーティング システムが IHV ハードウェアのインスタンスを見つけると、これは WDI IHV ミニポート ドライバーへの最初の呼び出しです。 この呼び出しでは、WDI ミニポートは、デバイスのソフトウェア表現 (ミニポートAdapterContext) を作成するために必要なアクションを実行します。 また、デバイスに関する情報を決定し、それを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 ドライバーは 、ミニポートAdapterContext と InterfaceType フィールドを設定する必要があります。

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

2. Call MiniportWdiOpenAdapter.

   ミニポートWdiAllocateAdapter の後、Microsoft コンポーネントは、ファームウェアを読み込み、ハードウェアを初期化するミニポートWdiOpenAdapter を呼び出します。

3. ミニポートOidRequest を使用する複数の WDI コマンド。

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

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

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

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

4. Call MiniportWdiStartOperation.

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

   次の図は、ミニポートInitializeEx のフローを示しています。

   

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

MiniportHaltEx

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

1. Call MiniportWdiStopOperation.

   これは、IHV ドライバーがミニポートWdiStartOperation で実行した操作を元に戻すために使用できるNDIS_MINIPORT_DRIVER_WDI_CHARACTERISTICS内のオプションの WDI ミニポート ハンドラーです。

2. ミニポートOidRequest を使用する複数の WDI コマンド。

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

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

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

次の図は、ミニポートHaltEx のフローを示しています。

デバイスが突然削除された場合、またはシステムの電源がオフになっている場合、ミニポートHaltEx 処理は実行されません。 突然の削除については、 ミニポートDevicePnPEventNotify ハンドラーの動作を参照してください。 システムのシャットダウンについては、 ミニポートShutdownEx ハンドラーの動作を参照してください。

MiniportDriverUnload

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

次の図は、ミニポートDriverUnload のフローを示しています。

MiniportPause

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

次の図は、ミニポートPause のフローを示しています。

MiniportRestart

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

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

MiniportResetEx

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

MiniportDevicePnPEventNotify

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

次の図は、ミニポートDevicePnPEventNotify のフローを示しています。

MiniportShutdownEx

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

次の図は、ミニポートShutdownEx のフローを示しています。

MiniportOidRequest

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

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

WDI コマンドごとに、操作に対して NDIS_STATUS コードを返すことができる可能性のあるフィールドが 2 つあります。1つは ミニポートOidRequest 呼び出し (または NdisMOidRequestComplete) のステータスコード、もう1つは WDI_MESSAGE_HEADER フィールドにおけるステータスコードです。これは、OID の完了時または NdisMIndicateStatusEx で示されることになります。 Microsoft コンポーネントは、WDI_MESSAGE_HEADERStatus フィールドを見る前に、常に OID 完了から NDIS_STATUS を検査します。 WDI OID 処理に対する IHV コンポーネントの期待値は次のとおりです。

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

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

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

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

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

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 コンポーネントは、それを既存の表示に変換し、オペレーティング システムに転送します。

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

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

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

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 ハンドラー: ミニポートWdiOpenAdapter

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

WDI ハンドラー: MiniportWdiCloseAdapter

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