NdisMAllocateNetBufferSGList 関数 (ndis.h)

[アーティクル]
02/29/2024

注意事項

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

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

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

バスマスターミニポートドライバーは 、NdisMAllocateNetBufferSGList 関数を呼び出して、 NET_BUFFER 構造に関連付けられているネットワークデータの散布図/収集リストを取得します。

構文

NDIS_STATUS NdisMAllocateNetBufferSGList(
  [in]           NDIS_HANDLE NdisMiniportDmaHandle,
  [in]           PNET_BUFFER NetBuffer,
  [in]           PVOID       Context,
  [in]           ULONG       Flags,
  [in, optional] PVOID       ScatterGatherListBuffer,
  [in]           ULONG       ScatterGatherListBufferSize
);

パラメーター

[in] NdisMiniportDmaHandle

NDIS が DMA リソースの管理に使用するコンテキスト領域へのハンドル。呼び出し元は、を呼び出してこのハンドルを取得しました。 NdisMRegisterScatterGatherDma 関数。

[in] NetBuffer

NET_BUFFER構造体へのポインター。 NdisMAllocateNetBufferSGList は、このNET_BUFFER構造に関連付けられているネットワークデータの散布/収集リストを割り当てます。散布図/収集リストは、関連付けられたNET_BUFFER_DATA構造体の CurrentMdl メンバーで指定された MDL の先頭からデータから生成されます。

[in] Context

呼び出し元が作成したコンテキスト領域へのポインター。 HAL は、HAL が散布図/収集リストを作成した後に、このポインターを MiniportProcessSGList に渡します。呼び出し元は、独自の目的でこのコンテキスト領域を使用できます。

[in] Flags

OR 操作と組み合わせることができる NDIS フラグ。すべてのフラグをクリアするには、このメンバーを 0 に設定します。この関数は、NDIS_SG_LIST_WRITE_TO_DEVICE フラグをサポートします。が設定されている場合は、DMA 転送の方向がNET_BUFFERからデバイスに送信されていることを示します。 NDIS_SG_LIST_WRITE_TO_DEVICEが明確な場合、転送はデバイスから行われます。 DMA 操作がNET_BUFFERからデバイスにデータを転送する場合、ミニポートドライバーは送信パスにこのフラグを設定する必要があります。デバイスから事前に割り当てられたNET_BUFFERに DMA 操作を実行するミニポートドライバー (たとえば、受信操作中にチムニーオフロード対応 NIC) は、このフラグをクリアする必要があります。

[in, optional] ScatterGatherListBuffer

NULL でない場合、ScatterGatherListBuffer は、呼び出し元が散布/収集リストを保持するために割り当てるストレージへのポインターを指定します。 NULL の場合、NDIS は散布/収集リストの記憶域を割り当てます。

[in] ScatterGatherListBufferSize

ScatterGatherListBuffer パラメーターが NULL でない場合、ScatterGatherListBufferSize は、散布/収集リストを含むバッファーのサイズを指定します。このサイズが小さすぎる場合、NDIS は散布図/収集リストに記憶域を割り当てます。 ScatterGatherListBuffer パラメーターが NULL の場合、このパラメーターは使用されません。

戻り値

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

リターンコード	説明
NDIS_STATUS_SUCCESS	NdisMAllocateNetBufferSGList は、指定したNET_BUFFER構造体の散布/収集リストを正常に作成しました。
NDIS_STATUS_RESOURCES	リソースが不足しているため、NdisMAllocateNetBufferSGList が失敗しました。

注釈

NDIS バスマスターミニポートドライバーは、 そのから NdisMAllocateNetBufferSGList を呼び出します。 MiniportSendNetBufferLists 関数。ミニポートドライバーは、散布図/収集リストを取得する必要がある各NET_BUFFER構造体に対して NdisMAllocateNetBufferSGList を 1 回呼び出します。

ミニポートドライバーが NdisMAllocateNetBufferSGList を呼び出すと、NDIS は HAL を呼び出して散布/収集リストを構築します。 HAL は、散布図/収集リストをビルドした後、ミニポートドライバーを呼び出すことによって登録されている ミニポートProcessSGList 関数を呼び出します。 NdisMRegisterScatterGatherDma。

HAL は、NDIS が NdisMAllocateNetBufferSGList から返される前または後に、MiniportProcessSGList を呼び出すことができます。ミニポートドライバーは、HAL が MiniportProcessSGList を呼び出すまで、散布図/収集リストへのアクセスを試みてはいけません。

システムパフォーマンスを向上させるために、ミニポートドライバーは NdisMAllocateNetBufferSGList の ScatterGatherListBuffer パラメーターで使用するためにバッファーを事前割り当てする必要があります。 NDIS は、ミニポートドライバーが NdisMRegisterScatterGatherDma を呼び出すときに DmaDescription パラメーターの ScatterGatherListSize メンバーのバッファーに推奨されるサイズを提供します。ミニポートドライバーは、NdisMAllocateNetBufferSGList を呼び出すときに、ScatterGatherListBufferSize パラメーター内のバッファーのサイズを指定します。

ミニポートドライバーが ScatterGatherListBuffer パラメーターでバッファーを指定している場合でも、NDIS はバッファーを割り当てる可能性があります。これは、指定されたバッファーが小さすぎて散布/収集リストを保持できない場合に発生する可能性があります。したがって、ドライバーライターは、 ScatterGatherListBuffer パラメーターで指定されたバッファーに散布/収集リストが含まれていると想定しないでください。 HAL は、ミニポートドライバーの MiniportProcessSGList 関数に正しい散布図/収集リストポインターを渡します。

システムパフォーマンスを向上させるために、関連付けられたNET_BUFFER_DATA構造の CurrentMdl メンバーで指定された MDL の先頭から、ネットワークデータから散布図/収集リストが生成されます。 SG リスト内のネットワークデータの開始は、関連付けられたNET_BUFFER_DATA構造体の CurrentMdlOffset メンバーで指定された値によって、SG リストの先頭からオフセットされます。

ミニポートドライバーは、散布図/収集リストを解放するために NdisMFreeNetBufferSGList 関数を呼び出す必要があります。

要件

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