共用方式為

PALLOCATE_COMMON_BUFFER回呼函式 (wdm.h)

  • 發行項

AllocateCommonBuffer 例程會配置記憶體並加以對應，以便同時從處理器和裝置存取 DMA 作業。

語法

PALLOCATE_COMMON_BUFFER PallocateCommonBuffer;

PVOID PallocateCommonBuffer(
  [in]  PDMA_ADAPTER DmaAdapter,
  [in]  ULONG Length,
  [out] PPHYSICAL_ADDRESS LogicalAddress,
  [in]  BOOLEAN CacheEnabled
)
{...}

參數

[in] DmaAdapter

IoGetDmaAdapter 所傳回之DMA_ADAPTER結構的指標，代表總線主要適配卡或 DMA 控制器。

[in] Length

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

[out] LogicalAddress

接收裝置可用來存取配置緩衝區之邏輯位址的變數指標。 使用此位址，而不是呼叫 MmGetPhysicalAddress ，因為系統可以將任何平臺特定的記憶體限制納入考慮。

[in] CacheEnabled

指定是否可以快取配置的記憶體。

這個參數已忽略。 操作系統會決定是否要在要配置的一般緩衝區中啟用快取記憶體。 該決策是以處理器架構和裝置總線為基礎。

在 x86 型、x64 型和 Itanium 型處理器的電腦上，會啟用快取的記憶體。 假設裝置執行的所有 DMA 作業都與相關的 CPU 快取一致，這可能會快取該記憶體。 如果您的驅動程式需要停用快取，請改為呼叫 AllocateCommonBufferEx 。

在 ARM 或 ARM 64 型處理器的電腦上，操作系統不會為所有裝置自動啟用快取的記憶體。 系統會依賴每個裝置 的 ACPI_CCA 方法，判斷裝置是否為快取一致。

傳回值

AllocateCommonBuffer 會傳回配置範圍的基底虛擬位址。 如果無法配置緩衝區，則會傳回 NULL。

備註

AllocateCommonBuffer 不是可直接依名稱呼叫的系統例程。 這個例程只能由 DMA_OPERATIONS結構中 傳回之位址的指標呼叫。 驅動程式會藉由呼叫 IoGetDmaAdapter來取得此例程的位址。

AllocateCommonBuffer 支援 DMA，其中裝置和處理器會持續透過系統記憶體進行通訊，如同總線主機 DMA 裝置的控制結構一樣。

AllocateCommonBuffer 也支持輔助裝置，其驅動程式使用系統 DMA 控制器的自動初始化模式。

AllocateCommonBuffer 會執行下列動作：

  • 配置可從處理器和裝置觸達的記憶體。 此記憶體會與裝置連續顯示。
  • 如有系統需要，配置對應緩存器來對應緩衝區。
  • 設定裝置的翻譯，包括視需要載入地圖快取器。
若要以經濟方式使用駐留系統記憶體，驅動程式應該盡可能為每個裝置配置其中幾個緩衝區。 AllocateCommonBuffer 至少會配置一頁記憶體，而不論要求的 Length 為何。 在要求少於PAGE_SIZE個字節的成功配置之後，呼叫端只能存取要求的 Length。 在要求大於整數倍數PAGE_SIZE位元組的配置之後，最後一個配置頁面上的任何剩餘位元組都無法存取呼叫端。

如果驅動程式需要數個常見的緩衝區空間頁面，但頁面不需要連續，驅動程序應該對 AllocateCommonBuffer 提出數個單頁要求，而不是一個大型要求。 此方法可節省連續記憶體。

驅動程式通常會在回應 PnP IRP_MN_START_DEVICE要求期間，將 AllocateCommonBuffer 呼叫為裝置啟動的一部分。 啟動之後，如果有任何要求，則只有一頁要求會成功。

規格需求

需求 值
最低支援的用戶端 從 Windows 2000 開始提供。
目標平台 桌面
標頭 wdm.h (包括 Wdm.h、Ntddk.h、Ntifs.h)
IRQL PASSIVE_LEVEL
DDI 合規性規則 IrqlDispatch (wdm)

另請參閱

DMA_ADAPTER

DMA_OPERATIONS

FreeCommonBuffer

IoGetDmaAdapter