PGET_DMA_TRANSFER_INFO回呼函式 (wdm.h)

發行項
02/29/2024

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 位移的範圍內。

[in] WriteOnly

指出傳輸是否為僅限寫入的作業 (，也就是從記憶體) 傳送到裝置。如果 WriteOnly 為 TRUE，則傳回有關傳輸的資訊可能對讀取交易無效。此參數可能表示緩衝區界限需要額外的快取控制作業，才能強制執行快取共置。

[in, out] TransferInfo

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

傳回值

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

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

備註

GetDmaTransferInfo 不是可直接依名稱呼叫的系統例程。此例程只能由DMA_OPERATIONS結構中傳回之位址的指標呼叫 驅動程式會呼叫IoGetDmaAdapter，並將DeviceDescription參數的Version成員設定為 DEVICE_DESCRIPTION_VERSION3，以取得此例程的位址。如果 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 所描述的虛擬記憶體區域是非連續的。如需 MDLs 和 MDL 鏈結的詳細資訊，請參閱使用 MDL。

規格需求

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