PGET_DMA_TRANSFER_INFO回呼函式（wdm.h）

發行項
02/07/2025

GetDmaTransferInfo 例程會計算散佈/收集 DMA 傳輸的配置需求。

語法

PGET_DMA_TRANSFER_INFO PgetDmaTransferInfo;

NTSTATUS PgetDmaTransferInfo(
  [in]      PDMA_ADAPTER DmaAdapter,
  [in]      PMDL Mdl,
  [in]      ULONGLONG Offset,
  [in]      ULONG Length,
  [in]      BOOLEAN WriteOnly,
  [in, out] PDMA_TRANSFER_INFO TransferInfo
)
{...}

參數

[in] DmaAdapter

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

[in] Mdl

MDL 鏈結的指標，描述要傳輸的記憶體分頁。如需詳細資訊，請參閱一節。

[in] Offset

散佈圖/收集 DMA 傳輸的起始位移。此參數是 MDL 鏈結中第一個 MDL 中緩衝區開頭的位元組位移。如果 MDL 鏈結中的 MDL 指定緩衝區空間的 N 個字節總計，則 Offset 的有效值介於 0 到 N–1 的範圍內。

[in] Length

DMA 傳輸的長度，以位元組為單位。如果 MDL 鏈結指定緩衝區空間的 N 個字節總計，Length 的有效值範圍介於 1 到 N–Offset。

[in] WriteOnly

指出傳輸是否為唯寫作業（也就是從記憶體傳輸至裝置）。如果 WriteOnly 為 TRUE，則傳回的傳輸資訊對讀取交易可能無效。此參數可能表示緩衝區界限需要額外的快取控制作業，才能強制執行快取一致性。

[in, out] TransferInfo

呼叫端配置的 DMA_TRANSFER_INFO 結構的指標。呼叫者必須先將結構的 Version 成員設定為DMA_TRANSFER_INFO_VERSION1，才能 呼叫 getDmaTransferInfo。

傳回值

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

傳回碼	描述
STATUS_NOT_SUPPORTED	例程不支援指定版本的 DMA_TRANSFER_INFO_XXX 結構。

言論

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

使用 GetDmaTransferInfo 來計算散佈/收集緩衝區的大小，以配置給 BuildScatterGatherListEx 和 MapTransferEx 例程。

GetDmaTransferInfo 會取代 CalculateScatterGatherList 例程，而且更方便搭配 BuildScatterGatherListEx使用。

Mdl、Offset和 Length 參數一起指定實體記憶體區域的集合，以作為散佈/收集 DMA 傳輸的緩衝區。每個實體記憶體區域通常是頁面或頁面的一部分。 GetDmaTransferInfo 決定此傳輸的配置需求。這些需求包括下列各項：

散佈/收集清單中的項目數目。每個元素都是描述記憶體實體連續區塊的 SCATTER_GATHER_ELEMENT 結構。
要配置以保存指定散佈/收集清單的記憶體數量。（此記憶體配置包含散佈/收集清單所需的空間，該清單描述 I/O 緩衝區，但不適用於 I/O 緩衝區本身。
將散佈/收集清單中實體位址轉譯為邏輯位址所需的對應緩存器數目。

如需 DMA_TRANSFER_INFO_XXX 結構第 1 版所提供的 DMA 傳輸資訊相關信息，請參閱 DMA_TRANSFER_INFO_V1。

MDL 描述實體記憶體頁面，這些分頁是鎖定的連續虛擬記憶體區塊。通常，這些實體記憶體頁面是非連續的。 MDL 鏈結是 MDL 的已排序集合，描述可用來緩衝 I/O 數據的記憶體。一般而言，鏈結中 MDL 所描述的虛擬記憶體區域不是連續的。如需 MDL 和 MDL 鏈結的詳細資訊，請參閱使用 MDL。

要求

要求	價值
最低支援的用戶端	從 Windows 8 開始提供。
目標平臺	桌面
標頭	wdm.h （包括 Wdm.h、Ntddk.h、Ntifs.h）
IRQL	<= DISPATCH_LEVEL