NdisMRegisterScatterGatherDma 関数 (ndis.h)

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

注意事項

ARM および ARM64 プロセッサの場合、NDIS ドライバーライターでは、NDIS 散布/収集 DMA の代わりに WDF DMA または WDM DMA を使用することを強くお勧めします。

WDF DMA の詳細については、「 KMDF ドライバーでの DMA 操作の処理」を参照してください。

WDM DMA の詳細については、「ドライバーの入出力の管理」の DMA 関連の子トピックを参照してください。

バスマスターミニポートドライバーは、 NdisMRegisterScatterGatherDma 関数を MiniportInitializeEx から呼び出して、分散/収集 DMA チャネルを初期化します。

構文

NDIS_STATUS NdisMRegisterScatterGatherDma(
  [in]      NDIS_HANDLE              MiniportAdapterHandle,
  [in, out] PNDIS_SG_DMA_DESCRIPTION DmaDescription,
  [out]     PNDIS_HANDLE             NdisMiniportDmaHandle
);

パラメーター

[in] MiniportAdapterHandle

NDIS が MiniportInitializeEx に渡したミニポートハンドル。

[in, out] DmaDescription

NDIS_SG_DMA_DESCRIPTION構造体へのポインター。この構造体では、ミニポートドライバーの分散/収集 DMA プロパティについて説明します。構造体は次のように定義されます。

typedef struct _NDIS_SG_DMA_DESCRIPTION {
  NDIS_OBJECT_HEADER  Header;
  ULONG  Flags;
  ULONG  MaximumPhysicalMapping;
  MINIPORT_PROCESS_SG_LIST_HANDLER  ProcessSGListHandler;
  MINIPORT_ALLOCATE_SHARED_MEM_COMPLETE_HANDLER  SharedMemAllocateCompleteHandler;
  ULONG  ScatterGatherListSize;
} NDIS_SG_DMA_DESCRIPTION, *PNDIS_SG_DMA_DESCRIPTION;

この構造体には、次のメンバーが含まれます。

NDIS_SG_DMA_DESCRIPTION構造体のNDIS_OBJECT_HEADER構造体。 Header が指定する構造体の Type メンバーをNDIS_OBJECT_TYPE_SG_DMA_DESCRIPTIONに設定し、Revision メンバーを NDIS_SG_DMA_DESCRIPTION_REVISION_1に、Size メンバーを NDIS_SIZEOF_SG_DMA_DESCRIPTION_REVISION_1に設定します。

Flags

散布/収集特性を定義するビットフラグのセット。このメンバーを、必要なすべてのフラグのビットごとの OR に設定します。

NDIS_SG_DMA_64_BIT_ADDRESS フラグは、NIC が DMA 操作に 64 ビットアドレス指定を使用できることを指定します。それ以外の場合、NIC は 32 ビットアドレス指定を使用します。

64 ビットアドレス指定が不要な場合は、このメンバーを 0 に設定します。

MaximumPhysicalMapping

1 つの DMA 操作で NIC が転送できる最大バイト数。 NDIS は、DMA チャネルを割り当てるときにハードウェア抽象化レイヤー (HAL) にこの値を提供し、HAL はこの値を使用して、NIC 用に予約するマップレジスタの最大数を決定します。

ProcessSGListHandler

HAL が散布/収集リストの作成を完了したときに NDIS が呼び出す MiniportProcessSGList 関数。

SharedMemAllocateCompleteHandler

次に、を呼び出すミニポートドライバーの MiniportSharedMemoryAllocateComplete 関数 NdisMAllocateSharedMemoryAsyncEx。このフィールドは省略可能であり、ミニポートドライバーが NdisMAllocateSharedMemoryAsyncEx を呼び出さない場合は NULL にする必要があります。

ScatterGatherListSize

散布図/収集リストを保持するために必要なメモリのサイズ (バイト単位)。 NDIS は、 NdisMRegisterScatterGatherDma から返される前に、この値を設定します。ミニポートドライバーは、各散布図/収集リストのメモリを事前に割り当てるには、このサイズを使用する必要があります。

[out] NdisMiniportDmaHandle

呼び出し元が提供し、NDIS がハンドルで埋める変数へのポインター。ハンドルは、NDIS がこの DMA リソースを管理するために使用するコンテキスト領域を識別します。ミニポートドライバーは、この DMA リソースを含む NDIS への後続の呼び出しで NDIS にこのハンドルを渡します。

戻り値

NdisMRegisterScatterGatherDma は、次のいずれかを返します。

リターンコード	説明
NDIS_STATUS_SUCCESS	NdisMRegisterScatterGatherDma によって、バスマスター DMA 操作用のリソースが正常に割り当てられます。
NDIS_STATUS_RESOURCES	リソースが不足しているため、NdisMRegisterScatterGatherDma が失敗しました。
NDIS_STATUS_NOT_SUPPORTED	NdisMRegisterScatterGatherDma は、ミニポートが NDIS 6.0 以降のバージョンをサポートすることを指定しなかったか、ミニポートドライバーが NIC がバスマスター DMA デバイスであることを指定していないために失敗しました。ミニポートドライバーは、を呼び出すときに NDIS バージョンを指定します。 NdisMRegisterMiniportDriver。ミニポートドライバーは、呼び出し時にバスマスター DMA デバイスをサポートすることを指定します NdisMSetMiniportAttributes。
NDIS_STATUS_BAD_VERSION	NDIS の現在のバージョンでは、DmaDescription の Header 構造体の Revision メンバーで指定されたバージョンはサポートされていません。

注釈

NDIS バスマスターミニポートドライバーは、その MiniportInitializeEx 関数内で NdisMRegisterScatterGatherDma を呼び出して、DMA 操作を分散または収集するためのリソースを初期化します。ミニポートドライバーが NdisMRegisterScatterGatherDma に渡す DmaDescription パラメーターには、NDIS が散布/収集 DMA リソースを初期化するために使用する情報が含まれています。 NdisMRegisterScatterGatherDma が返された後、DmaDescription の ScatterGatherListSize メンバーには、スキャッター/ギャザーリストを保持するのに十分なバッファーサイズが含まれます。ミニポートドライバーは、散布図/収集リストのメモリを事前に割り当てるには、このサイズを使用する必要があります。

DmaDescription パラメーターの ProcessSGListHandler メンバーは、MiniportProcessSGList 関数のミニポートドライバーのエントリポイントを定義します。ミニポートドライバーがを呼び出すとき NdisMAllocateNetBufferSGList では、NDIS は HAL を呼び出して、ミニポートドライバーに散布/収集リストを提供します。 HAL は、HAL が散布/収集リストの作成を完了した後に 、MiniportProcessSGList を呼び出します。 NDIS は、NdisMAllocateNetBufferSGList の呼び出しのコンテキスト外で MiniportProcessSGList を呼び出すことができます。

NdisMRegisterScatterGatherDma は、ミニポートドライバーに不透明なコンテキスト領域へのポインターを返します。ミニポートドライバーは、NDIS 散布図/DMA 関数を収集する後続の呼び出しでこのハンドルを使用する必要があります。

バスマスターミニポートドライバーの呼び出し NdisMAllocateSharedMemoryAsyncEx を使用して、データ転送操作用に共有メモリを動的に割り当てます。この呼び出しは、高いネットワークトラフィックが原因でミニポートドライバーが初期化中に割り当てられた共有メモリ領域で低く実行する場合に必要です。 NdisMAllocateSharedMemoryAsyncEx がNDIS_STATUS_PENDINGを返す場合、NDIS はを呼び出します。ミニポートSharedMemoryAllocateComplete 関数は、後で操作を完了します。ミニポートドライバーは、DmaDescription パラメーターの SharedMemAllocateCompleteHandler メンバーのミニポートSharedMemoryAllocateComplete 関数のエントリポイントを指定します。

ミニポートドライバーは、を呼び出します。 NdisMDeregisterScatterGatherDma が割り当てた DMA リソースの割り当てを解除する NdisMDeregisterScatterGatherDma 関数。

要件

要件	値
サポートされている最小のクライアント	NDIS 6.0 以降でサポートされています。
対象プラットフォーム	ユニバーサル
Header	ndis.h (Ndis.h を含む)
Library	Ndis.lib
IRQL	PASSIVE_LEVEL
DDI コンプライアンス規則	Init_RegisterSG(ndis)、 Irql_Gather_DMA_Function(ndis)