WdfDeviceSetAlignmentRequirement 函数 (wdfdevice.h)

  • 项目

[仅适用于 KMDF]

WdfDeviceSetAlignmentRequirement 方法为设备在内存传输操作期间使用的数据缓冲区注册驱动程序的首选地址对齐方式。

语法

void WdfDeviceSetAlignmentRequirement(
  [in] WDFDEVICE Device,
  [in] ULONG     AlignmentRequirement
);

参数

[in] Device

框架设备对象的句柄。

[in] AlignmentRequirement

数据缓冲区的硬件相关对齐要求。 此值必须小于对齐边界的 1。 例如，可以为 16 字节对齐边界指定 15，为 32 字节对齐边界指定 31。 还可以使用 Wdm.h 中定义的FILE_Xxxx_ALIGNMENT常量之一，例如：

//
// Define alignment requirement values
//
#define FILE_BYTE_ALIGNMENT             0x00000000
#define FILE_WORD_ALIGNMENT             0x00000001
#define FILE_LONG_ALIGNMENT             0x00000003
#define FILE_QUAD_ALIGNMENT             0x00000007
#define FILE_OCTA_ALIGNMENT             0x0000000f
#define FILE_32_BYTE_ALIGNMENT          0x0000001f
#define FILE_64_BYTE_ALIGNMENT          0x0000003f
#define FILE_128_BYTE_ALIGNMENT         0x0000007f
#define FILE_256_BYTE_ALIGNMENT         0x000000ff
#define FILE_512_BYTE_ALIGNMENT         0x000001ff

返回值

无

备注

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

使用直接 I/O 的驱动程序可以调用 WdfDeviceSetAlignmentRequirement 来注册首选对齐要求。 对齐方式适用于通过 I/O 管理器的 I/O 请求，不适用于从另一个调用 IoCallDriver 的驱动程序发送到驱动程序的请求。

由于 I/O 管理器并不总是使用请求的对齐方式，因此应为未对齐的缓冲区准备驱动程序。

驱动程序可以调用 WdfDeviceGetAlignmentRequirement 以获取设备的对齐要求的当前值。

当驱动程序调用 WdfDeviceCreate 时，I/O 管理器为设备设置对齐要求值。 有关设备的对齐要求值以及驱动程序何时必须更改该值的详细信息，请参阅 WDM 文档中的 初始化设备对象 。

如果驱动程序指定的对齐要求大于计算机的页大小 (PAGE_SIZE) ，则 WdfCommonBufferGetAlignedLogicalAddress 方法返回的逻辑地址始终与指定的对齐要求对齐，但 WdfCommonBufferGetAlignedVirtualAddress 方法返回的虚拟地址可能与对齐要求不一致。

如果驱动程序指定的对齐要求小于计算机的页面大小，则所有逻辑地址和虚拟地址都与指定的对齐要求保持一致。

有关调用 WdfDeviceSetAlignmentRequirement 的详细信息，请参阅启用 DMA 事务和使用通用缓冲区。

示例

下面的代码示例来自 AMCC5933 示例驱动程序。 此示例检查设备的当前对齐要求，并将对齐要求设置为新值（如有必要）。 请注意，确切的对齐值取决于硬件。

ULONG alignReq;

alignReq = WdfDeviceGetAlignmentRequirement(device);
if (alignReq < AMCC5933_ALIGNMENT__32BITS) {
//
// Set the S5933 alignment requirement to a new value.
//
WdfDeviceSetAlignmentRequirement(
                                 device,
                                 AMCC5933_ALIGNMENT__32BITS
                                 );
}

要求

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

另请参阅

WdfCommonBufferGetAlignedLogicalAddress

WdfCommonBufferGetAlignedVirtualAddress

WdfDeviceGetAlignmentRequirement