NdisMAllocateNetBufferSGList 関数 (ndis.h)
注意事項
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 は、次のいずれかを返します。
| リターン コード | 説明 |
|---|---|
|
NdisMAllocateNetBufferSGList は、指定したNET_BUFFER構造体の散布/収集リストを正常に作成しました。 |
|
リソースが不足しているため、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) |