NdisMAllocateSharedMemory 函式（ndis.h）

發行項
02/07/2025

謹慎

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

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

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

NdisMAllocateSharedMemory 配置和對應主機記憶體範圍，讓記憶體範圍可從主機系統和 DMA NIC 同時存取。

語法

void NdisMAllocateSharedMemory(
  [in]  NDIS_HANDLE            MiniportAdapterHandle,
  [in]  ULONG                  Length,
  [in]  BOOLEAN                Cached,
  [out] PVOID                  *VirtualAddress,
  [out] PNDIS_PHYSICAL_ADDRESS PhysicalAddress
);

參數

[in] MiniportAdapterHandle

指定 MiniportInitializeEx的句柄輸入。

[in] Length

指定要配置的位元組數目。

[in] Cached

忽略此參數（快取記憶體一律用於 x86 和 x64 系統上）。

[out] VirtualAddress

呼叫端提供的變數指標，在此變數中，此函式會傳回配置基底虛擬位址以供迷你埠驅動程式使用。如果 NdisMAllocateSharedMemory 無法滿足其呼叫者，則會傳回 NULL，表示未配置記憶體。

[out] PhysicalAddress

呼叫端提供的變數指標，此變數會傳回實體位址，適合 NIC 使用，該位址對應至 virtualAddress 傳回的實體位址，或傳回 NULL。

傳回值

沒有

言論

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

Microsoft Windows Server 2003、Windows XP Service Pack 1 和更新版本的 Windows 允許總線主要 DMA DMA NIC 和次級 DMA NIC 呼叫 NdisMAllocateSharedMemory。先前的版本只允許總線主機 DMA NIC 呼叫 NdisMAllocateSharedMemory。在這些舊版中，如果 MiniportInitializeEx 未指定 NIC 是總線主機時呼叫 NdisMSetMiniportAttributes，NdisMAllocateSharedMemory 只會傳回控件而不嘗試進行配置。

NdisMAllocateSharedMemory 提供驅動程式用來存取共用記憶體區塊的對應虛擬位址範圍，以及 NIC 所使用的 NDIS_PHYSICAL_ADDRESS類型範圍。 PhysicalAddress 傳回的值可由系統進行雙重對應。也就是說，PhysicalAddress 和 Length 的值所描述的「實體」位址範圍可以是不符合每個可能平臺中配置主機實體位址的對應邏輯位址範圍。

NdisMAllocateSharedMemory 只能從 MiniportInitializeEx呼叫。要要求的配置大小取決於驅動程式寫入器如何瞭解 NIC 的功能和功能，決定在下列效能與大小兩難境地之間進行取捨：

在高網路流量的期間，如果小型埠驅動程式在裝置可存取數據緩衝區的共用記憶體空間上執行不足，則無法維持高 I/O 輸送量。
例如，迷你埠驅動程式可能表示共用記憶體中的接收緩衝區比這類緩衝區在接收大量傳入 NIC 時從系結通訊協定驅動程式傳回的快。如果未處理的接收緩衝區會取用其所有共用記憶體空間，迷你埠驅動程式可能必須停用 NIC 上的接收中斷，直到它有一些可供接收緩衝區使用的共用記憶體空間為止。
另一方面，呼叫 NdisMAllocateSharedMemory，並選擇 Length 來預測一些最大的傳輸需求，使得驅動程式的映像更大，其資源使用量相當不必要，但罕見的 I/O 需求期間除外。此外，如果系統記憶體不足，NdisMAllocateSharedMemory 可能無法為驅動程式提供如此大的區塊，迫使驅動程式無法初始化。

提供的迷你埠驅動程式 MiniportSharedMemoryAllocateComplete 函式在解決上述效能與大小兩難境地方面具有更大的彈性。如果驅動程式具有 MiniportSharedMemoryAllocateComplete 函式，MiniportInitializeEx 應該只配置足夠的共用記憶體與 NdisMAllocateSharedMemory，以適中要求透過 NIC 進行網路傳輸作業。這類迷你埠驅動程式可以呼叫 NdisMAllocateSharedMemoryAsyncEx 動態配置更多共用記憶體，以在 NIC 上較重的傳輸需求期間配置更多共用記憶體。當傳輸的高需求消退時，這類驅動程式會呼叫 NdisMFreeSharedMemory 釋放配置的額外記憶體。請注意，只有總線主機 DMA NIC 可以呼叫 NdisMAllocateSharedMemoryAsyncEx 並匯出 MiniportSharedMemoryAllocateComplete。次級 DMA NIC 不支援此功能。

NdisMAllocateSharedMemory 和 NdisMAllocateSharedMemoryAsyncEx 是唯一 NdisXxx 函式，可用來配置驅動程式之間共用的主機記憶體，該驅動程式會使用虛擬位址，以及使用對應邏輯位址的 NIC。

迷你埠驅動程序應該將它從共用快取記憶體配置的緩衝區對齊主機數據快取行界限的整數，以防止在 DMA 期間發生快取行撕裂。快取行撕裂可能會導致驅動程式中的數據完整性問題，或藉由要求過度的數據快取排清來維護數據完整性，使驅動程式的 I/O 效能降低。 MiniportInitializeEx 可以呼叫 NdisMGetDmaAlignment，以判斷目前平臺中驅動程式將在共用記憶體配置範圍內設定的可存取緩衝區的對齊界限。

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

MiniportInitializeEx 也可能在呼叫 NdisMAllocateSharedMemory 之前呼叫 NdisMAllocateSharedMemory 如果驅動程式寫入器決定在多處理器機器中配置較大的共用記憶體區塊，則假設任何 SMP 計算機可能是 NIC 上具有高於工作站網路傳輸需求的網路伺服器。

如果呼叫 NdisMAllocateSharedMemory 失敗，MiniportInitializeEx 可以再次呼叫要求較小的配置。不過，如果 MiniportInitializeEx 無法為 NIC 配置足夠的共用記憶體，則必須釋放它已配置的所有資源，且初始化失敗。

如果迷你埠驅動程序後續表示接收 NdisMIndicateReceiveNetBufferLists，它必須從緩衝池配置一些緩衝區描述元，以對應共用記憶體區塊中的 NIC 接收緩衝區。

如果快取已配置的記憶體，因此必須在傳輸時排清，迷你埠驅動程序必須呼叫 NdisAllocateMdl 來配置共用記憶體範圍的NDIS_BUFFER類型描述元。迷你埠驅動程序必須使用此緩衝區描述元呼叫 KeFlushIoBuffers，才能執行這類排清。

如果迷你埠驅動程式呼叫 NdisMAllocateSharedMemoryAsyncEx 或 NdisMAllocateSharedMemory，它必須釋放所有未完成的配置，並呼叫 NdisMFreeSharedMemory 時，也就是呼叫其 MiniportHaltEx 函式時。

要求

要求	價值
最低支援的用戶端	NDIS 6.0 和更新版本支援。
目標平臺	普遍
標頭	ndis.h （包括 Ndis.h）
連結庫	Ndis.lib
IRQL	PASSIVE_LEVEL