PCREATE_COMMON_BUFFER_FROM_MDL回呼函式 (wdm.h)

發行項
02/27/2024

CreateCommonBufferFromMdl 例程會藉由測試裝置存取相容性，並可能根據轉譯類型，嘗試從 MDL 建立通用緩衝區，並將記憶體對應至連續邏輯範圍。如同所有其他常見的緩衝區配置函式，此函式不會提供向前進度保證。

語法

PCREATE_COMMON_BUFFER_FROM_MDL PcreateCommonBufferFromMdl;

NTSTATUS PcreateCommonBufferFromMdl(
  [in]  PDMA_ADAPTER DmaAdapter,
  [in]  PMDL Mdl,
  [in]  PDMA_COMMON_BUFFER_EXTENDED_CONFIGURATION ExtendedConfigs,
  [in]  ULONG ExtendedConfigsCount,
  [out] PPHYSICAL_ADDRESS LogicalAddress
)
{...}

參數

[in] DmaAdapter

提供執行作業之 DMA 配接器的指標。

[in] Mdl

提供將對應至一般緩衝區的 MDL。

若要讓 MDL 能夠支援一般緩衝區，必須符合下列條件：

MDL 必須有一律在一般緩衝區存留期且對應至系統地址空間的頁面。這可以透過下列方法來完成：
MDL 是從非分頁集區中的緩衝區，透過 MmBuildMdlForNonPagedPool 建立。
MDL 已透過 MmProbeAndLockPages 鎖定，並透過 MmGetSystemAddressForMdlSafe 對應至系統空間。
MDL 的實體頁面已透過 MmAllocatePagesForMdlEx 配置，並透過 MmGetSystemAddressForMdlSafe 對應至系統空間。
MDL 必須代表頁面對齊的區域，而且必須是PAGE_SIZE的倍數。
- 如果使用 SubSection 擴充組態，則所使用的 MDL 部分必須對齊頁面，而且是PAGE_SIZE的倍數。
MDL 不得為鏈結的 MDL。
- 如果使用 SubSection 擴充組態，則可以提供鏈結的 MDL，但所使用的 MDL 部分必須包含在鏈結中的單一 MDL 中。
如果未使用 DMA 重新對應，MDL 必須代表實際連續的記憶體，而且裝置可以存取。

[in] ExtendedConfigs

提供選擇性的DMA_COMMON_BUFFER_EXTENDED_CONFIGURATION 結構陣列，以進一步設定 MDL 支援的通用緩衝區建立。

如果在陣列中提供相同 DMA_COMMON_BUFFER_EXTENDED_CONFIGURATION_TYPE 的多個組態，建立將會失敗。

[in] ExtendedConfigsCount

提供 ExtendedConfigs 陣列中的擴充組態數目。

[out] LogicalAddress

成功時會提供所產生常見緩衝區的邏輯位址。

傳回值

如果呼叫成功，CreateCommonBufferFromMdl 會傳回STATUS_SUCCESS。可能的錯誤傳回值包括下列狀態代碼。

傳回碼	Description
STATUS_INVALID_PARAMETER	呼叫端已提供不相容的 MDL 或擴充組態。
STATUS_NOT_SUPPORTED	呼叫端已提供目前系統上不支援的擴充設定。
STATUS_INSUFFICIENT_RESOURCES	系統沒有足夠的記憶體來建立書籍保留和對應元數據。

備註

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

CreateCommonBufferFromMdl 所建立的通用緩衝區將會透過FreeCommonBuffer 移除。呼叫端必須提供系統虛擬位址作為虛擬位址，以確保一般緩衝區已正確從配接器的一般緩衝區記事結構中移除。驅動程式仍負責解除鎖定和釋放 MDL 及其支援頁面。

若要建立負責維護支援記憶體的 HAL 通用緩衝區，請使用 AllocateCommonBufferWithBounds。