MINIPORT_INITIALIZE コールバック関数 (ndis.h)

[アーティクル]
03/08/2023

NDIS は、ミニポートドライバーの MiniportInitializeEx 関数を呼び出して、ネットワーク I/O 操作用のミニポートアダプターを初期化します。

メモMINIPORT_INITIALIZE型を使用して関数を宣言する必要があります。詳細については、次の例に関するセクションを参照してください。

構文

MINIPORT_INITIALIZE MiniportInitialize;

NDIS_STATUS MiniportInitialize(
  [in] NDIS_HANDLE NdisMiniportHandle,
  [in] NDIS_HANDLE MiniportDriverContext,
  [in] PNDIS_MINIPORT_INIT_PARAMETERS MiniportInitParameters
)
{...}

パラメーター

[in] NdisMiniportHandle

ミニポートドライバーが初期化する必要があるミニポートアダプターを識別する NDIS 提供のハンドル。

[in] MiniportDriverContext

ドライバーが状態と構成情報を保持するドライバー割り当てコンテキスト領域へのハンドル。ミニポートドライバーは、このコンテキスト領域をに渡しました。 NdisMRegisterMiniportDriver 関数。

[in] MiniportInitParameters

へのポインターミニポートアダプターの初期化パラメーターを定義する構造体をNDIS_MINIPORT_INIT_PARAMETERSします。

戻り値

MiniportInitializeEx は、次のいずれかの状態値を返すことができます。

リターンコード	説明
NDIS_STATUS_SUCCESS	MiniportInitializeEx は、ミニポートアダプターを構成して設定し、ドライバーがネットワーク I/O 操作を実行するために必要なすべてのリソースを割り当てた。
NDIS_STATUS_NOT_ACCEPTED	MiniportInitializeEx は、レジストリから取得された MiniportInitializeEx の構成パラメーターを受け入れるためのミニポートアダプターを取得できませんでした。
NDIS_STATUS_RESOURCES	MiniportInitializeEx は、ネットワーク I/O 操作を実行するリソースを割り当てませんでした。 MiniportInitializeEx は NdisWriteErrorLogEntry 関数を呼び出して、リソースの競合 (I/O ポート範囲、割り込みベクトル、デバイスメモリ範囲など) を識別する必要があります。エラーログレコードを指定すると、このようなハードウェアリソースの競合を回避するためにコンピューターを再構成するために使用できるユーザーまたはシステム管理者の情報が提供されます。
NDIS_STATUS_FAILURE	MiniportInitializeEx は、上記の一覧以外の理由で失敗しました。ドライバーは、エラーの理由を指定するパラメーターを使用して NdisWriteErrorLogEntry を呼び出す必要があります。

注釈

NDIS は、システム PnP 操作の一部として MiniportInitializeEx を呼び出します。ドライバーは、を呼び出すことによって 、MiniportInitializeEx エントリポイントを指定します。DriverEntry ルーチンからの NdisMRegisterMiniportDriver 関数。 NDIS は、DriverEntry が返された後に MiniportInitializeEx を呼び出すことができます。詳細については、「 NDIS ミニポートドライバーの DriverEntry」を参照してください。

NDIS 中間ドライバーの場合、NDIS はのコンテキストで MiniportInitializeEx を呼び出すことができます NdisIMInitializeDeviceInstanceEx 関数、またはが返された後。このようなドライバーの ProtocolBindAdapterEx 関数は、通常 、NdisIMInitializeDeviceInstanceEx を呼び出します。

ドライバーは、ミニポートドライバーと中間ドライバーを組み合わせて登録できます ( 「NdisMRegisterMiniportDriver」を参照してください)。このようなミニポート中間ドライバーは、物理ミニポートドライバー上に階層化された中間ドライバーと同様に機能します。ミニポート中間ドライバーの仮想または物理デバイスインスタンスごとに、 IMMiniport レジストリキーが DWORD:0x0000001 に設定されている場合、NDIS は、ドライバーが仮想デバイスに登録されている MiniportInitializeEx 関数を呼び出します。それ以外の場合、NDIS は、ドライバーが物理デバイスに登録されているドライバーの MiniportInitializeEx 関数を呼び出します。

MiniportInitializeEx が返されるまで、NDIS は初期化中のミニポートアダプターに対する要求を送信しません。ミニポートアダプターが 初期化 中の状態です。

ミニポートアダプターの構成情報を取得するには、ドライバーは NdisOpenConfigurationEx および NdisReadConfiguration 関数を呼び出します。ドライバーは、バス固有の情報を取得する NdisMGetBusData 関数を呼び出すことができます。

ミニポートドライバーは、を呼び出す必要があります。 NdisMSetMiniportAttributes 関数とを指定します。次の属性を含む構造体NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTESします。

ドライバーによって割り当てられたコンテキスト領域へのハンドル。
適切な属性フラグ。
を呼び出すためのタイムアウト間隔 MiniportCheckForHangEx 関数。
インターフェイスの型。

ミニポートドライバーは、 NdisMSetMiniportAttributes NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTESの MiniportAdapterContext メンバーでハンドルを渡します。ドライバーは、このコンテキスト領域で指定されたミニポートアダプターの状態情報を保持します。 NDIS は、このハンドルを入力パラメーターとして他 の MiniportXxx 関数に渡します。

ミニポートドライバーは、の属性を設定する必要があります。 NDIS_MINIPORT_ADAPTER_GENERAL_ATTRIBUTES 構造体は、NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES構造体で登録属性を設定した後、追加の属性を設定する前に行います。

MiniportInitializeEx では、次のようなリソースを割り当てることもできます。

ページプール以外のメモリ
NET_BUFFER および NET_BUFFER_LIST 構造体プール
スピンロック
タイマー
IO ポート
DMA
共有メモリ
割り込み

ドライバーがと共に受信を示す場合は、 NdisMIndicateReceiveNetBufferLists 関数、 MiniportInitializeEx 関数はを呼び出す必要があります。 NdisAllocateNetBufferListPool と NdisAllocateNetBufferPool 関数と、これらの NDIS 関数によって返されるハンドルを保存します。通常、ドライバーが NdisMIndicateReceiveNetBufferLists で後で示すネットワークデータは、で割り当てられた構造体を参照します。 NdisAllocateNetBufferAndNetBufferList 関数。ドライバーは、 NdisAllocateNetBuffer で割り当てられた構造体を使用することもできます。 NdisAllocateNetBufferList 関数。

MiniportInterrupt 関数以外のドライバー関数がリソースを共有する場合、MiniportInitializeEx は NdisAllocateSpinLock 関数を呼び出して、このような共有リソースへのアクセスを同期するために必要なスピンロックを設定する必要があります。 NIC レジスタなど、他のドライバー関数が MiniportInterrupt と共有するリソースは、ドライバーがで設定した割り込みオブジェクトによって保護されます。 NdisMRegisterInterruptEx 関数。ドライバー関数は、を呼び出してこれらのリソースにアクセスします。 NdisMSynchronizeWithInterruptEx 関数。

MiniportInitializeEx は、ドライバーが提供する NetTimerCallback 関数と、タイマーオブジェクトのドライバー割り当てメモリへのポインターを使用して、NdisAllocateTimerObject 関数を呼び出すことができます。ドライバーは、それぞれ独自のタイマーオブジェクトを持つ複数の NetTimerCallback 関数を設定できます。ドライバーは NdisSetTimerObject 関数を呼び出して、定期的な NetTimerCallback 関数を有効にすることができます。ドライバーは、 NdisSetTimerObject 関数を呼び出して、1 回限りの NetTimerCallback 関数を 有効にすることもできます。

MiniportInitializeEx は を呼び出す必要があります。 NdisMSetMiniportAttributes 関数は、NdisMXxx 関数 (NdisMRegisterIoPortRange 関数や NdisMMapIoSpace 関数など) を呼び出す前に、ミニポートアダプターのハードウェアリソースを要求します。 MiniportInitializeEx は 、DMA 操作用のリソースの割り当てを試みる前に 、NdisMSetMiniportAttributes を呼び出す必要があります。

デバイスがバスマスター DMA をサポートしている場合、 MiniportInitializeEx は を呼び出す必要があります。NdisMSetMiniportAttributes を呼び出した後、呼び出す前の NdisMRegisterScatterGatherDma 関数 NdisMAllocateSharedMemory 関数。デバイスが下位 DMA をサポートしている場合、 MiniportInitializeEx は を呼び出す前に NdisMSetMiniportAttributes を呼び出す必要があります。 NdisMRegisterDmaChannel 関数。

MiniportInitializeEx が呼び出された後、 NdisMRegisterInterruptEx 関数、NDIS はドライバーのミニポートInterrupt 関数を呼び出すことができます。 NIC が割り込みを生成する場合、または NIC が割り込みを共有する他のデバイスが割り込みを生成する場合、NDIS は MiniportInterrupt を呼び出します。ミニポートドライバーは、 NdisMRegisterInterruptEx を呼び出すとすぐに割り込みを取得でき、への呼び出しまで割り込みを取得し続ける可能性があることに注意してください。 NdisMDeregisterInterruptEx 関数はを返します。

MiniportInitializeEx は、NIC をテストして、ハードウェアが正しく構成されていることを確認する必要があります。ドライバーがハードウェアで状態の変更が発生するまで待機する必要がある場合、 MiniportInitializeEx は NdisWaitEvent 関数または NdisMSleep 関数を使用できます。

MiniportInitializeEx が正常に返されると、ミニポートアダプターは一時停止状態になります。 NDIS は、ミニポートアダプターを実行中の状態に移行するミニポートの再起動関数を呼び出すことができます。

MiniportInitializeEx がNDIS_STATUS_SUCCESSを返す場合、ドライバーは、ミニポートHaltEx 関数内のミニポートアダプターのすべてのリソースを解放する必要があります。

ドライバーは NdisMSetMiniportAttributes を呼び出し、NDIS_STATUS_SUCCESSを返す場合は、NDIS_MINIPORT_ADAPTER_ATTRIBUTES構造体に GeneralAttributes を設定する必要があります。

MiniportInitializeEx が失敗した場合、MiniportInitializeEx は、割り当てられたすべてのリソースを解放してから、ミニポートアダプターが Halted 状態に戻る必要があります。

NDIS は、IRQL = PASSIVE_LEVELで MiniportInitializeEx を呼び出します。

例

MiniportInitializeEx 関数を定義するには、まず、定義する関数の種類を識別する関数宣言を指定する必要があります。 Windows には、ドライバー用の一連の関数型が用意されています。関数の種類を使用して関数を宣言すると、ドライバー、静的ドライバー検証ツール (SDV)、およびその他の検証ツールのコード分析でエラーが検出され、Windows オペレーティングシステムのドライバーを記述するための要件になります。

たとえば、" MyInitializeEx" という名前の MiniportInitializeEx 関数を定義するには、次のコード例に示すように 、MINIPORT_INITIALIZE 型を使用します。

MINIPORT_INITIALIZE MyInitializeEx;

次に、次のように関数を実装します。

_Use_decl_annotations_
NDIS_STATUS
 MyInitializeEx(
    NDIS_HANDLE  NdisMiniportHandle,
    NDIS_HANDLE  MiniportDriverContext,
    PNDIS_MINIPORT_INIT_PARAMETERS  MiniportInitParameters
    )
  {...}

MINIPORT_INITIALIZE関数の種類は、Ndis.h ヘッダーファイルで定義されています。コード分析ツールの実行時にエラーをより正確に識別するには、 Use_decl_annotations 注釈を関数定義に追加してください。 Use_decl_annotations注釈を使用すると、ヘッダーファイルのMINIPORT_INITIALIZE関数型に適用される注釈が確実に使用されます。関数宣言の要件の詳細については、「NDIS ドライバーの関数ロール型を使用して関数を宣言する」を参照してください。

Use_decl_annotationsの詳細については、「関数の動作に注釈を付ける」を参照してください。

要件

要件	値
サポートされている最小のクライアント	NDIS 6.0 以降でサポートされています。
対象プラットフォーム	Windows
ヘッダー	ndis.h (Ndis.h を含む)
IRQL	PASSIVE_LEVEL