WdfDeviceSetAlignmentRequirement method

[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

C++


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

Parameters

Device [in]: A handle to a framework device object.
AlignmentRequirement [in]: 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

Your driver can call WdfDeviceSetAlignmentRequirement to register a preferred alignment requirement. However, the I/O manager does not always use the requested alignment. As such, 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

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