Функция WdfIoQueueAssignForwardProgressPolicy (wdfio.h)

Статья
08/08/2023

[Применяется только к KMDF]

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

Синтаксис

NTSTATUS WdfIoQueueAssignForwardProgressPolicy(
  [in] WDFQUEUE                              Queue,
  [in] PWDF_IO_QUEUE_FORWARD_PROGRESS_POLICY ForwardProgressPolicy
);

Параметры

[in] Queue

Дескриптор объекта очереди платформы.

[in] ForwardProgressPolicy

Указатель на структуру WDF_IO_QUEUE_FORWARD_PROGRESS_POLICY , выделенную драйвером.

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

WdfIoQueueAssignForwardProgressPolicy возвращает STATUS_SUCCESS, если операция выполнена успешно. В противном случае этот метод может вернуть одно из следующих значений:

Код возврата	Описание
STATUS_INVALID_PARAMETER	Входной параметр недопустим.
STATUS_INFO_LENGTH_MISMATCH	Неправильный размер структуры WDF_IO_QUEUE_FORWARD_PROGRESS_POLICY.
STATUS_INSUFFICIENT_RESOURCES	Объем доступной памяти слишком мал.

Этот метод также может возвращать другие значения NTSTATUS. Кроме того, если функция обратного вызова EvtIoAllocateResourcesForReservedRequest вашего драйвера возвращает значение состояния ошибки, WdfIoQueueAssignForwardProgressPolicy возвращает это значение.

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

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

В KMDF версии 1.9 очередь ввода-вывода, представляющая параметр Queue , должна быть очередью ввода-вывода устройства по умолчанию или очередью, для которой драйвер вызвал WdfDeviceConfigureRequestDispatching. Драйвер может вызывать WdfIoQueueAssignForwardProgressPolicy в любое время после вызова WdfDeviceConfigureRequestDispatching.

В KMDF версии 1.11 и более поздних очередью ввода-вывода, которую представляет параметр Queue , может быть любая очередь, получающая запрос непосредственно от платформы. Например, драйвер может указать очередь, в которую он будет динамически пересылать IRP.

Перед возвратом WdfIoQueueAssignForwardProgressPolicy платформа выполняет следующие действия:

Создает и сохраняет количество объектов запроса, указанное драйвером для элемента TotalForwardProgressRequestsструктуры WDF_IO_QUEUE_FORWARD_PROGRESS_POLICY .
Если драйвер ранее назывался WdfDeviceInitSetRequestAttributes, каждое выделение включает в себя контекстное пространство, указанное WdfDeviceInitSetRequestAttributes .
Вызывает функцию обратного вызова EvtIoAllocateResourcesForReservedRequest драйвера для каждого объекта запроса, создаваемого платформой.

После того как драйвер вызвал WdfIoQueueAssignForwardProgressPolicy для создания зарезервированных объектов запроса, платформа использует эти зарезервированные объекты всякий раз, когда попытка создать новый объект запроса завершается сбоем. (Как правило, такие сбои вызваны нехваткой памяти.)

Платформа удаляет свои зарезервированные объекты запросов только при удалении объекта очереди платформы, к которому они относятся. Если драйвер вызывает WdfDeviceInitSetRequestAttributes и задает функцию обратного вызова EvtCleanupCallback или EvtDegradCallback для объектов запроса, платформа вызывает эти функции обратного вызова для зарезервированных объектов запроса при удалении объектов.

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

Примеры

В этом примере кода настраивается ранее созданная очередь ввода-вывода для получения запросов на запись, а затем она обеспечивает гарантированное перенаправление хода выполнения для очереди.

#define MAX_RESERVED_REQUESTS 10

WDF_IO_QUEUE_FORWARD_PROGRESS_POLICY queueForwardProgressPolicy;
WDFQUEUE writeQueue;
NTSTATUS status = STATUS_SUCCESS;
...
status = WdfDeviceConfigureRequestDispatching(
             device,
             writeQueue,
             WdfRequestTypeWrite
             );
if(!NT_SUCCESS(status)) {
    return status;
}
WDF_IO_QUEUE_FORWARD_PROGRESS_POLICY_DEFAULT_INIT(
    &queueForwardProgressPolicy,
    MAX_RESERVED_REQUESTS
    );
status = WdfIoQueueAssignForwardProgressPolicy(
             writeQueue,
             &queueForwardProgressPolicy
             );
if(!NT_SUCCESS(status)) {
    return status;
}

Требования

Требование	Значение
Целевая платформа	Универсальное
Минимальная версия KMDF	1,9
Верхняя часть	wdfio.h (включая Wdf.h)
Библиотека	Wdf01000.sys (см. раздел Управление версиями библиотеки платформы).
IRQL	PASSIVE_LEVEL
Правила соответствия DDI	DriverCreate(kmdf)

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

EvtIoAllocateResourcesForReservedRequest

WDF_IO_QUEUE_FORWARD_PROGRESS_POLICY

WdfDeviceConfigureRequestDispatching

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