PALLOCATE_COMMON_BUFFER_EX回呼函式 (wdm.h)

發行項
02/27/2024

AllocateCommonBufferEx 例程會配置一般緩衝區的記憶體，並對應此記憶體，讓處理器和執行 DMA 作業的裝置可以存取它。

語法

PALLOCATE_COMMON_BUFFER_EX PallocateCommonBufferEx;

PVOID PallocateCommonBufferEx(
  [in]           PDMA_ADAPTER DmaAdapter,
  [in, optional] PPHYSICAL_ADDRESS MaximumAddress,
  [in]           ULONG Length,
  [out]          PPHYSICAL_ADDRESS LogicalAddress,
  [in]           BOOLEAN CacheEnabled,
  [in]           NODE_REQUIREMENT PreferredNode
)
{...}

參數

[in] DmaAdapter

DMA_ADAPTER 結構的指標。這個結構是代表驅動程式總線主機 DMA 裝置或系統 DMA 通道的配接器物件。呼叫端從先前呼叫 IoGetDmaAdapter 例程取得此指標。

[in, optional] MaximumAddress

變數的指標，其中包含通用緩衝區的最大邏輯位址。此參數表示緩衝區應該從此位址下方的記憶體配置。此參數是選擇性的，而且可以指定為 NULL，表示沒有最大位址。

[in] Length

要配置給 DMA 作業之通用緩衝區的大小，以位元組為單位。

[out] LogicalAddress

變數的指標，此例程會寫入裝置可用來存取通用緩衝區的邏輯位址。 DMA 裝置應該使用此邏輯位址，而不是由 MmGetPhysicalAddress 等例程傳回的實體位址。

[in] CacheEnabled

例程是否必須在要配置的通用緩衝區中啟用或停用快取的記憶體。如果為 TRUE，則會啟用快取。如果為 FALSE，則會停用它。如果硬體平臺不會強制執行 DMA 作業的快取共通，則傳遞 FALSE。如需 ARM 或 ARM 64 處理器目標電腦上此參數的相關信息，請參閱。

[in] PreferredNode

要從中配置記憶體的慣用NUMA節點。如果 N 是多處理器系統中的 NUMA 節點數目， PreferredNode 是範圍 0 到 N–1 的數位。如果是一個處理器系統或非 NUMA 多處理器系統，請將 PreferredNode 設定為零。

傳回值

AllocateCommonBufferEx 會傳回為通用緩衝區配置的記憶體虛擬位址。如果無法配置緩衝區，則會傳回NULL。

備註

AllocateCommonBufferEx 不是可直接依名稱呼叫的系統例程。此例程只能由 DMA_OPERATIONS 結構中 傳回之位址的指標呼叫。驅動程式會呼叫 IoGetDmaAdapter ，並將 DeviceDescription 參數的Version成員設定為DEVICE_DESCRIPTION_VERSION3，以取得此例程的位址。如果 IoGetDmaAdapter 傳回 NULL，您的平台上無法使用例程。

AllocateCommonBufferEx 是 AllocateCommonBuffer 例程的擴充版本。下列清單摘要說明僅適用於擴充版本的功能：

呼叫端可以為要配置的通用緩衝區指定最大邏輯位址。
呼叫端可以指定要配置通用緩衝區的慣用NUMA節點。

在具有 ARM 或 ARM 64 處理器的電腦上，系統 ACPI 中的快取設定優先順序高於驅動程式所傳遞的 CacheEnabled 參數值。如果 ACPI _CCA 方法指出裝置未快取一致，即使驅動程式將快取記憶體配置為 TRUE，操作系統仍會停用快取。

在具有 ARM 或 ARM 64 處理器的電腦上，作業系統會將未快取的通用緩衝區配置為裝置記憶體。如需緩衝區的詳細資訊，請參閱 ARMv7架構參考手冊中的A3.5.1和A3.5.6小節。

處理器不允許未對齊裝置記憶體的存取。您的驅動程式一律必須使用自然對齊的作業，從一般緩衝區存取數據。大部分的核心例程不接受裝置記憶體作為輸入參數。例如，網路驅動程式無法將裝置記憶體傳遞至 NdisMIndicateReceiveNetBufferLists。如果您的驅動程式需要將數據從 DMA 通用緩衝區傳遞至核心例程，請將 CacheEnabled 設定為 TRUE 的緩衝區配置，或將數據從未快取的通用緩衝區複製到暫存集區配置。

如需使用通用緩衝區之 DMA 作業的詳細資訊，請參閱下列主題：

使用一般緩衝區

使用 Common-Buffer Bus-Master DMA

使用 Common-Buffer System DMA