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) |