WdfDeviceSetAlignmentRequirement 函式 (wdfdevice.h)

[僅適用於 KMDF]

WdfDeviceSetAlignmentRequirement 方法會針對裝置在記憶體傳輸作業期間使用的數據緩衝區，註冊驅動程式慣用的位址對齊方式。

語法

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

參數

[in] Device

架構裝置物件的句柄。

[in] AlignmentRequirement

數據緩衝區的硬體相依對齊需求。 此值必須小於對齊界限。 例如，您可以為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

傳回值

無

備註

如果驅動程式提供無效的物件句柄，就會發生錯誤檢查。

使用直接 I/O 的驅動程式可以呼叫 WdfDeviceSetAlignmentRequirement 來註冊慣用的對齊需求。 對齊方式適用於透過 I/O 管理員的 I/O 要求，而不是從另一個呼叫 IoCallDriver 的驅動程式傳送至驅動程式的要求。

因為 I/O 管理員不一定會使用要求的對齊方式，所以應該為未對齊的緩衝區準備驅動程式。

驅動程式可以呼叫 WdfDeviceGetAlignmentRequirement ，以取得裝置對齊需求的目前值。

當驅動程式呼叫 WdfDeviceCreate 時，I/O 管理員會設定裝置的對齊需求值。 如需裝置對齊需求值和驅動程式必須變更值的詳細資訊，請參閱 WDM 檔中的 初始化 Device Object 。

如果您的驅動程式指定的對齊需求大於計算機的頁面大小 (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
                                 );
}

規格需求

另請參閱

WdfCommonBufferGetAlignedLogicalAddress

WdfCommonBufferGetAlignedVirtualAddress

WdfDeviceGetAlignmentRequirement