Fonction WdfIoQueueAssignForwardProgressPolicy (wdfio.h)

Article
08/08/2023

[S’applique à KMDF uniquement]

La méthode WdfIoQueueAssignForwardProgressPolicy permet au framework de garantir la progression vers l’avant pour une file d’attente d’E/S spécifiée.

Syntaxe

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

Paramètres

[in] Queue

Handle pour un objet de file d’attente d’infrastructure.

[in] ForwardProgressPolicy

Pointeur vers une structure de WDF_IO_QUEUE_FORWARD_PROGRESS_POLICY allouée par le pilote.

Valeur retournée

WdfIoQueueAssignForwardProgressPolicy retourne STATUS_SUCCESS si l’opération réussit. Sinon, cette méthode peut retourner l’une des valeurs suivantes :

Code de retour	Description
STATUS_INVALID_PARAMETER	Un paramètre d’entrée n’est pas valide.
STATUS_INFO_LENGTH_MISMATCH	La taille de la structure WDF_IO_QUEUE_FORWARD_PROGRESS_POLICY est incorrecte.
STATUS_INSUFFICIENT_RESOURCES	La quantité de mémoire disponible est trop faible.

Cette méthode peut également retourner d’autres valeurs NTSTATUS. En outre, si la fonction de rappel EvtIoAllocateResourcesForReservedRequest de votre pilote retourne une erreur status valeur, WdfIoQueueAssignForwardProgressPolicy retourne cette valeur.

Un bogue case activée se produit si le pilote fournit un handle d’objet non valide.

Remarques

La méthodeWdfIoQueueAssignForwardProgressPolicy crée des objets de requête que l’infrastructure réserve pour les situations de mémoire insuffisante et enregistre les fonctions de rappel que l’infrastructure appelle pour gérer les situations de mémoire insuffisante.

Dans KMDF version 1.9, la file d’attente d’E/S que représente le paramètre Queue doit être la file d’attente d’E/S par défaut d’un appareil, ou une file d’attente pour laquelle votre pilote a appelé WdfDeviceConfigureRequestDispatching. Le pilote peut appeler WdfIoQueueAssignForwardProgressPolicy à tout moment après avoir appelé WdfDeviceConfigureRequestDispatching.

Dans KMDF versions 1.11 et ultérieures, la file d’attente d’E/S que représente le paramètre File d’attente peut être toute file d’attente qui reçoit une requête directement de l’infrastructure. Par exemple, le pilote peut spécifier une file d’attente vers laquelle il transférera dynamiquement les IRPs.

Avant que WdfIoQueueAssignForwardProgressPolicy ne retourne, l’infrastructure effectue les opérations suivantes :

Crée et stocke le nombre d’objets de requête que le pilote a spécifiés pour le membre TotalForwardProgressRequests de la structure WDF_IO_QUEUE_FORWARD_PROGRESS_POLICY .
Si le pilote a précédemment appelé WdfDeviceInitSetRequestAttributes, chaque allocation inclut l’espace de contexte spécifié par WdfDeviceInitSetRequestAttributes .
Appelle la fonction de rappel EvtIoAllocateResourcesForReservedRequest du pilote pour chaque objet de requête créé par l’infrastructure.

Une fois que le pilote a appelé WdfIoQueueAssignForwardProgressPolicy pour créer des objets de requête réservés, l’infrastructure utilise ces objets réservés chaque fois que sa tentative de création d’un nouvel objet de requête échoue. (En règle générale, de tels échecs sont dus à des situations de mémoire insuffisante.)

Le framework supprime ses objets de requête réservés uniquement lorsqu’il supprime l’objet de file d’attente du framework auquel ils appartiennent. Si votre pilote appelle WdfDeviceInitSetRequestAttributes et spécifie une fonction de rappel EvtCleanupCallback ou EvtDestroyCallback pour ses objets de requête, le framework appelle ces fonctions de rappel pour ses objets de requête réservés lorsqu’il supprime les objets.

Pour plus d’informations sur la méthode WdfIoQueueAssignForwardProgressPolicy et sur l’utilisation de la fonctionnalité de progression vers l’avant garantie de l’infrastructure, consultez Garantie de la progression des opérations d’E/S.

Exemples

Cet exemple de code configure une file d’attente d’E/S créée précédemment pour recevoir des demandes d’écriture, puis permet une progression de transfert garantie pour la file d’attente.

#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;
}

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
Version KMDF minimale	1,9
En-tête	wdfio.h (inclure Wdf.h)
Bibliothèque	Wdf01000.sys (consultez Gestion des versions de la bibliothèque d’infrastructure).)
IRQL	PASSIVE_LEVEL
Règles de conformité DDI	DriverCreate(kmdf)

Voir aussi

EvtIoAllocateResourcesForReservedRequest

WDF_IO_QUEUE_FORWARD_PROGRESS_POLICY

WdfDeviceConfigureRequestDispatching

Partager via