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的迷你埠驅動程式，例如接收作業期間煙囪卸載能夠卸除的 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 一次。
當迷你埠驅動程式呼叫 NdisMAllocateNetBufferSGList時，NDIS 會呼叫 HAL 來建置散佈/收集清單。 在 HAL 建置散佈/收集清單之後，它會呼叫 MiniportProcessSGList 函式，此函式是由呼叫 miniport 驅動程式所註冊 NdisMRegisterScatterGatherDma。
HAL 可以在 NDIS 從 NdisMAllocateNetBufferSGList傳回之前或之後呼叫 MiniportProcessSGList。 在 HAL 呼叫 MiniportProcessSGList之後，迷你埠驅動程式不得嘗試存取散佈/收集清單。
為了改善系統效能，迷你埠驅動程序應該預先配置緩衝區，以便用於 NdisMAllocateNetBufferSGList的 ScatterGatherListBuffer 參數。 當迷你埠驅動程式呼叫 NdisMRegisterScatterGatherGatherDma時，NDI S 會為 DmaDescription 參數中的緩衝區提供建議的大小。 Miniport 驅動程式會在呼叫 NdisMAllocateNetBufferSGList時，指定 ScatterGatherListBufferSize 參數中的緩衝區大小。
即使迷你埠驅動程式在 ScatterGatherListBuffer 參數中指定緩衝區，NDIS 還是可能會配置緩衝區。 如果指定的緩衝區太小，無法保存散佈/收集清單，就會發生這種情況。 因此，驅動程式寫入器不得假設 ScatterGatherListBuffer 參數中指定的緩衝區包含散佈/收集清單。 HAL 會將正確的散佈/收集清單指標傳遞給迷你埠驅動程式的 MiniportProcessSGList 函式。
為了改善系統效能，散佈/收集清單是從在相關聯 NET_BUFFER_DATA 結構之 CurrentMdl 成員指定的 MDL 開頭開始產生的網路數據。 SG 清單中的網路數據開頭會由 CurrentMdlOffset 中指定的值從 SG 清單的開頭位移， 關聯NET_BUFFER_DATA結構的成員。
迷你埠驅動程序必須呼叫 NdisMFreeNetBufferSGList 函式，以釋放散佈/收集清單。
要求
| 要求 | 價值 |
|---|---|
| 最低支援的用戶端 | NDIS 6.0 和更新版本支援。 |
| 目標平臺 | 普遍 |
| 標頭 | ndis.h （包括 Ndis.h） |
| 連結庫 | Ndis.lib |
| IRQL | DISPATCH_LEVEL |
| DDI 合規性規則 | Irql_Gather_DMA_Function（ndis） |