Развернуть Свернуть

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


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

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

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

WdfCommonBufferGetAlignedLogicalAddress
WdfCommonBufferGetAlignedVirtualAddress
WdfDeviceGetAlignmentRequirement

 

 

Send comments about this topic to Microsoft

Показ:
© 2014 Microsoft