WdfDeviceSetAlignmentRequirement function

[Applies to KMDF only]

The WdfDeviceSetAlignmentRequirement method registers the driver's preferred address alignment for the data buffers that the device uses during memory transfer operations.

Syntax

VOID WdfDeviceSetAlignmentRequirement(
  _In_ WDFDEVICE Device,
  _In_ ULONG     AlignmentRequirement
);

Parameters

Device

A handle to a framework device object.

AlignmentRequirement

The alignment requirement for a data buffer. This value must be one less than the alignment boundary. For example, you can specify 15 for a 16-byte alignment boundary and 31 for a 32-byte alignment boundary. You can also use one of the FILE_Xxxx_ALIGNMENT constants that are defined in Wdm.h.

Return Value

None.

A bug check occurs if the driver supplies an invalid object handle.

Remarks

A driver that uses direct I/O can call WdfDeviceSetAlignmentRequirement to register a preferred alignment requirement. The alignment applies to I/O requests that go through the I/O Manager, and not those sent to your driver from another driver that calls IoCallDriver.

Because the I/O manager does not always use the requested alignment, the driver should be prepared for unaligned buffers.

The driver can call WdfDeviceGetAlignmentRequirement to obtain the current value for the device's alignment requirement.

The I/O manager sets an alignment requirement value for the device when the driver calls WdfDeviceCreate. For more information about a device's alignment requirement value and when a driver must change the value, see Initializing a Device Object in the WDM documentation.

If your driver specifies an alignment requirement that is greater that the computer's page size (PAGE_SIZE), the logical addresses that the WdfCommonBufferGetAlignedLogicalAddress method returns are always aligned to the specified alignment requirement, but the virtual addresses that the WdfCommonBufferGetAlignedVirtualAddress method returns might not be aligned to the alignment requirement.

If your driver specifies an alignment requirement that is less than the computer's page size, all logical and virtual addresses are aligned to the specified alignment requirement.

For more information about calling WdfDeviceSetAlignmentRequirement, see Enabling DMA Transactions and Using Common Buffers.

Examples

The following code example is from the AMCC5933 sample driver. This example checks a device's current alignment requirement and sets the alignment requirement to a new value, if necessary.

ULONG alignReq;

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

Requirements

   
Target Platform Universal
Minimum KMDF version 1.0
Header wdfdevice.h (include Wdf.h)
Library Wdf01000.sys (see Framework Library Versioning.)
IRQL "<= DISPATCH_LEVEL"
DDI compliance rules DriverCreate, KmdfIrql, KmdfIrql2

See Also

WdfDeviceGetAlignmentRequirement

WdfCommonBufferGetAlignedLogicalAddress

WdfCommonBufferGetAlignedVirtualAddress

Send comments about this topic to Microsoft