NdisMAllocateNetBufferSGList 函式 (ndis.h)
警告
針對 ARM 和 ARM64 處理器，我們強烈建議 NDIS 驅動程式寫入器使用 WDF DMA 或 WDM DMA，而不是 NDIS 散佈圖/收集 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 旗標。 若要清除所有旗標，請將此成員設定為零。 此函式支援NDIS_SG_LIST_WRITE_TO_DEVICE旗標;如果設定，則表示 DMA 傳輸的方向是從NET_BUFFER到裝置。 如果NDIS_SG_LIST_WRITE_TO_DEVICE清楚，則傳輸會來自裝置。 當 DMA 作業將資料從NET_BUFFER傳輸到裝置時，迷你埠驅動程式應該會在傳送路徑上設定此旗標。 從裝置執行 DMA 作業到預先配置的NET_BUFFER的迷你埠驅動程式，例如接收作業期間具有 chimney 卸除功能的 NIC，應該清除此旗標。
[in, optional] ScatterGatherListBuffer
如果不是 NULL，ScatterGatherListBuffer 會指定呼叫端配置來保存散佈/收集清單的記憶體指標。 如果 為 NULL，NDIS 會為散佈/收集清單配置記憶體。
[in] ScatterGatherListBufferSize
如果 ScatterGatherListBuffer 參數不是 NULL，ScatterGatherListBufferSize 會指定包含散佈/收集清單的緩衝區大小。 如果此大小太小，NDIS 會為散佈/收集清單配置記憶體。 如果 ScatterGatherListBuffer 參數為 NULL，則不會使用此參數。
傳回值
NdisMAllocateNetBufferSGList 會傳回下列其中一項：
| 傳回碼 | Description |
|---|---|
|
NdisMAllocateNetBufferSGList 已成功為指定的NET_BUFFER結構建置散佈/收集清單。 |
|
NdisMAllocateNetBufferSGList 因為資源不足而失敗。 |
備註
NDIS 總線主要迷你埠驅動程式會從其呼叫 NdisMAllocateNetBufferSGList MiniportSendNetBufferLists 函式 。 迷你埠驅動程式會針對每個必須取得散佈/收集清單的NET_BUFFER結構，呼叫 NdisMAllocateNetBufferSGList 一次。
當迷你埠驅動程式呼叫 NdisMAllocateNetBufferSGList 時，NDIS 會呼叫 HAL 來建置散佈/收集清單。 HAL 建置散佈/收集清單之後，它會呼叫 MiniportProcessSGList 函式，此函式是透過呼叫所註冊的miniport驅動程式 NdisMRegisterScatterGatherDma.
HAL 可以在 NDIS 傳回 NdisMAllocateNetBufferSGList 之前或之後呼叫 MiniportProcessSGList。 在 HAL 呼叫 MiniportProcessSGList 之前，迷你埠驅動程式不得嘗試存取散佈/收集清單。
為了改善系統效能，迷你埠驅動程序應該預先配置緩衝區，以用於 NdisMAllocateNetBufferSGList 的 ScatterGatherListBuffer 參數。 當迷你埠驅動程式呼叫 NdisMRegisterScatterGatherDma 時，NDIS 為 DmaDescription 參數的 ScatterGatherListSize 成員中的緩衝區提供建議的大小。 迷你埠驅動程式會在呼叫 NdisMAllocateNetBufferSGList 時，在 ScatterGatherListBufferSize 參數中指定緩衝區的大小。
即使迷你埠驅動程式在 ScatterGatherListBuffer 參數中指定緩衝區，NDIS 還是可能會配置緩衝區。 如果指定的緩衝區太小而無法保存散佈/收集清單，就會發生這種情況。 因此，驅動程式寫入器不得假設 ScatterGatherListBuffer 參數中指定的緩衝區包含散佈/收集清單。 HAL 會將正確的散佈/收集清單指標傳遞至迷你埠驅動程式的 MiniportProcessSGList 函式。
為了改善系統效能，從在相關聯NET_BUFFER_DATA結構之 CurrentMdl 成員指定的 MDL 開頭開始，從網路數據產生散佈/收集清單。 SG 清單中的網路數據的開頭會依相關聯NET_BUFFER_DATA結構 之 CurrentMdlOffset 成員中指定的值，從 SG 清單的開頭位移。
迷你埠驅動程序必須呼叫 NdisMFreeNetBufferSGList 函式以釋放散佈/收集清單。
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 | NDIS 6.0 和更新版本支援。 |
| 目標平台 | Universal |
| 標頭 | ndis.h (包括 Ndis.h) |
| 程式庫 | Ndis.lib |
| IRQL | DISPATCH_LEVEL |
| DDI 合規性規則 | Irql_Gather_DMA_Function (ndis) |