NdisMAllocateSharedMemoryAsyncEx 函式 (ndis.h)

發行項
02/26/2024

警告

針對 ARM 和 ARM64 處理器，我們強烈建議 NDIS 驅動程式寫入器使用 WDF DMA 或 WDM DMA，而不是 NDIS 散佈圖/收集 DMA。

如需 WDF DMA 的詳細資訊，請參閱處理 KMDF 驅動程式中的 DMA 作業。

如需 WDM DMA 的詳細資訊，請參閱管理驅動程式輸入/輸出的 DMA 相關子主題。

迷你埠驅動程式會呼叫 NdisMAllocateSharedMemoryAsyncEx 函式，以配置驅動程式與其總線主機 DMA NIC 之間共用的額外記憶體，通常是在可用的 NIC 接收緩衝區不足時。

語法

NDIS_STATUS NdisMAllocateSharedMemoryAsyncEx(
  [in] NDIS_HANDLE MiniportDmaHandle,
  [in] ULONG       Length,
  [in] BOOLEAN     Cached,
  [in] PVOID       Context
);

參數

[in] MiniportDmaHandle

NDIS 用來管理 DMA 資源的內容區域的句柄。呼叫端藉由呼叫來取得此句柄 NdisMRegisterScatterGatherDma 函式。

[in] Length

要配置的位元組數目。

[in] Cached

(快取記憶體一律用於 x86 和 x64 系統上) ，則會忽略此參數。

[in] Context

呼叫 MiniportSharedMemoryAllocateComplete 函式時，要傳遞至驅動程式決定內容的指標。

傳回值

NdisMAllocateSharedMemoryAsyncEx 可以傳回下列其中一項：

傳回碼	Description
NDIS_STATUS_PENDING	NDIS 會呼叫 MiniportSharedMemoryAllocateComplete 函式，並提供描述已配置共用記憶體的資訊。如果嘗試配置共用記憶體失敗，NDIS 會呼叫 MiniportSharedMemoryAllocateComplete 並傳遞 NULL 指標。
NDIS_STATUS_FAILURE	目前無法配置要求的記憶體。如果 NdisMAllocateSharedMemoryAsyncEx 傳回此狀態，則後續具有相同參數的呼叫可能會成功，視系統資源是否可用而定。

備註

注意迷你埠驅動程式必須已經呼叫 NdisMRegisterScatterGatherDma 或 NdisMRegisterDmaChannel ，才能在呼叫 NdisMAllocateSharedMemoryAsyncEx 之前初始化散佈/收集 DMA 信道。

總線主機 DMA DMA NIC 的驅動程式會呼叫 NdisMAllocateSharedMemoryAsyncEx ，以動態配置共用記憶體。這類驅動程式也會在初始化期間配置共用記憶體空間。當高網路流量對現有共用記憶體空間造成過多需求時，這些驅動程式會使用動態配置的共用記憶體來進行傳輸作業。

這類迷你埠驅動程式通常會維護一或多個狀態變數，以追蹤可用於傳入傳輸的共用記憶體緩衝區數目。當可用的緩衝區數目達到驅動程式決定的低時，迷你埠驅動程式會呼叫 NdisMAllocateSharedMemoryAsyncEx ，以在共用記憶體中配置更多緩衝區空間。當可用的緩衝區數目提升至驅動程序決定的高時，迷你埠驅動程式會呼叫 NdisMFreeSharedMemory 一或多次，以釋放其先前的動態配置。

通常，這類迷你埠驅動程式會保留其 MiniportInitializeEx 函式配置給 NdisMAllocateSharedMemory 的共用記憶體區塊，直到移除NIC為止。拿掉 NIC 時，NDIS 會呼叫迷你埠驅動程式的 MiniportHaltEx 函式。此配置足以處理透過 NIC 傳輸的平均需求。

迷你埠驅動程序應該設定可配置多少共用記憶體的限制。此限制是驅動程式特定的，而且應該夠高，因此驅動程式不會用盡緩衝區。請勿使用過多的限制，因為這可能會浪費耗用可能會降低系統效能的共用記憶體。

任何呼叫 NdisMAllocateSharedMemoryAsyncEx 或 NdisMAllocateSharedMemory 的迷你埠驅動程式，都必須在移除 NIC 時釋放所有未完成的配置，且呼叫 NdisMFreeSharedMemory 。

規格需求

需求	值
最低支援的用戶端	NDIS 6.0 和更新版本支援。
目標平台	Universal
標頭	ndis.h (包括 Ndis.h)
IRQL	<= DISPATCH_LEVEL
DDI 合規性規則	Irql_Gather_DMA_Function (ndis)