Функция WdfDeviceSetAlignmentRequirement (wdfdevice.h)

Статья
02/27/2024

[Относится только к KMDF]

Метод WdfDeviceSetAlignmentRequirement регистрирует предпочтительное выравнивание адресов драйвера для буферов данных, которые устройство использует во время операций передачи памяти.

Синтаксис

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

Параметры

[in] Device

Дескриптор объекта устройства платформы.

[in] AlignmentRequirement

Аппаратно-зависимое требование выравнивания для буфера данных. Это значение должно быть на один меньше границы выравнивания. Например, можно указать 15 для 16-байтовой границы выравнивания и 31 для 32-байтовой границы. Можно также использовать одну из констант FILE_Xxxx_ALIGNMENT которые определены в Wdm.h, например:

//
// 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

Возвращаемое значение

None

Remarks

Ошибка проверка возникает, если драйвер предоставляет недопустимый дескриптор объекта.

Драйвер, использующий прямой ввод-вывод, может вызвать WdfDeviceSetAlignmentRequirement , чтобы зарегистрировать предпочтительное требование выравнивания. Выравнивание применяется к запросам ввода-вывода, которые проходят через диспетчер ввода-вывода, а не к тем, которые отправляются вашему драйверу из другого драйвера, который вызывает IoCallDriver.

Так как диспетчер ввода-вывода не всегда использует запрошенное выравнивание, драйвер должен быть подготовлен к несровненным буферам.

Драйвер может вызвать WdfDeviceGetAlignmentRequirement , чтобы получить текущее значение для требования к выравниванию устройства.

Диспетчер ввода-вывода задает значение требования к выравниванию для устройства, когда драйвер вызывает WdfDeviceCreate. Дополнительные сведения о значении требования к выравниванию устройства и о том, когда драйвер должен изменить это значение, см. в разделе Инициализация объекта устройства документации по 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)
Библиотека	Wdf01000.sys (см. раздел Управление версиями библиотеки Платформы).
IRQL	<= DISPATCH_LEVEL
Правила соответствия DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

См. также раздел

WdfCommonBufferGetAlignedLogicalAddress

WdfCommonBufferGetAlignedVirtualAddress

WdfDeviceGetAlignmentRequirement

Поделиться через