PGET_DMA_TRANSFER_INFO回调函数 (wdm.h)

项目
08/08/2023

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 结构的指针。调用方必须在调用 GetDmaTransferInfo 之前将结构的 Version 成员设置为 DMA_TRANSFER_INFO_VERSION1。

返回值

如果调用成功，GetDmaTransferInfo 将返回STATUS_SUCCESS。可能的错误返回值包括以下状态代码。

返回代码	说明
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 描述的虚拟内存区域是不连续的。有关 MDL 和 MDL 链的详细信息，请参阅使用 MDL。

要求

要求	值
最低受支持的客户端	从Windows 8开始可用。
目标平台	桌面
标头	wdm.h（包括 Wdm.h、Ntddk.h、Ntifs.h）
IRQL	<= DISPATCH_LEVEL