WdfDmaEnablerGetFragmentLength 函数 (wdfdmaenabler.h)

  • 项目

[仅适用于 KMDF]

WdfDmaEnablerGetFragmentLength 方法返回操作系统支持单个 DMA 传输的最大传输长度。

语法

size_t WdfDmaEnablerGetFragmentLength(
  [in] WDFDMAENABLER     DmaEnabler,
  [in] WDF_DMA_DIRECTION DmaDirection
);

参数

[in] DmaEnabler

驱动程序从上一次调用 WdfDmaEnablerCreate 获取的 DMA 启用程序对象的句柄。

[in] DmaDirection

一个WDF_DMA_DIRECTION类型的值，该值指定 DMA 传输操作的方向。 有关更多信息，请参见下面的“备注”部分。

返回值

WdfDmaEnablerGetFragmentLength 返回操作系统可以支持的 DMA 传输的最大长度（以字节为单位），如果 DmaDirection 参数的值无效，则返回零。

如果驱动程序提供无效的对象句柄，则会发生 bug 检查。

注解

操作系统可以支持的最大 DMA 传输长度取决于可用的 映射寄存器 数。 如果有足够的映射寄存器可用， WdfDmaEnablerGetFragmentLength 将返回 与 WdfDmaEnablerGetMaximumLength 返回的值相同。 否则， WdfDmaEnablerGetFragmentLength 返回的值将小于 WdfDmaEnablerGetMaximumLength 返回的值。

驱动程序可以使用 BYTE_TO_PAGES 宏确定可用的映射寄存器数，如下所示：

BYTE_TO_PAGES(WdfDmaEnablerGetFragmentLength()) + 1

如果驱动程序在调用 WdfDmaEnablerCreate 时指定了双工配置文件， 则 DmaDirection 参数的值必须为 WdfDmaDirectionReadFromDevice 以获取读取操作的最大传输长度， WdfDmaDirectionWriteToDevice 以获取写入操作的最大传输长度。 如果驱动程序未指定双工配置文件，驱动程序可以为 DmaDirection 指定 WdfDmaDirectionReadFromDevice 或 WdfDmaDirectionWriteToDevice。

请注意，如果驱动程序的设备支持双工操作， 则 WdfDmaEnablerGetFragmentLength 可以为 DmaDirection 参数指定的读取和写入方向返回不同的值。 这种差异是因为框架为每个方向创建一个单独的 适配器对象 ，并且操作系统可能会为每个适配器对象提供不同数量的映射寄存器。

示例

下面的代码示例确定处理 NIC 设备的读取操作所需的最小映射寄存器数，计算可用的映射寄存器数，如果分配的映射寄存器数不足，则报告错误。

ULONG  minimumMapRegisters;
ULONG  maxLengthSupported;
ULONG  mapRegistersAllocated;

miniMapRegisters = BYTES_TO_PAGES(NIC_MAX_PACKET_SIZE) + 1;

maxLengthSupported = 
    (ULONG) WdfDmaEnablerGetFragmentLength(
                                           FdoData->WdfDmaEnabler,
                                           WdfDmaDirectionReadFromDevice
                                           );

mapRegistersAllocated = BYTES_TO_PAGES(maxLengthSupported) + 1;

if (mapRegistersAllocated < minimumMapRegisters) {
    status = STATUS_INSUFFICIENT_RESOURCES;
    return status;
}

要求

要求 值
目标平台 通用
最低 KMDF 版本 1.1
标头 wdfdmaenabler.h (包括 Wdf.h)
Library Wdf01000.sys (请参阅框架库版本控制.)
IRQL <=DISPATCH_LEVEL
DDI 符合性规则 DriverCreate (kmdf) 、 KmdfIrql (kmdf) 、 KmdfIrql2 (kmdf) 、 KmdfIrqlExplicit (kmdf)

另请参阅

WDF_DMA_DIRECTION

WdfDmaEnablerCreate

WdfDmaEnablerGetMaximumLength