Funzione WdfIoQueueAssignForwardProgressPolicy (wdfio.h)

Articolo
02/27/2024

[Si applica solo a KMDF]

Il metodo WdfIoQueueAssignForwardProgressPolicy consente al framework di garantire lo stato di avanzamento per una coda di I/O specificata.

Sintassi

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

Parametri

[in] Queue

Handle a un oggetto code del framework.

[in] ForwardProgressPolicy

Puntatore a una struttura di WDF_IO_QUEUE_FORWARD_PROGRESS_POLICY allocata dal driver.

Valore restituito

WdfIoQueueAssignForwardProgressPolicy restituisce STATUS_SUCCESS se l'operazione ha esito positivo. In caso contrario, questo metodo potrebbe restituire uno di questi valori:

Codice restituito	Descrizione
STATUS_INVALID_PARAMETER	Un parametro di input non è valido.
STATUS_INFO_LENGTH_MISMATCH	Le dimensioni della struttura WDF_IO_QUEUE_FORWARD_PROGRESS_POLICY non sono corrette.
STATUS_INSUFFICIENT_RESOURCES	La quantità di memoria disponibile è troppo bassa.

Questo metodo potrebbe restituire anche altri valori NTSTATUS. Inoltre, se la funzione di callback EvtIoAllocateResourcesForReservedRequest restituisce un valore di stato di errore, WdfIoQueueAssignForwardProgressPolicy restituisce tale valore.

Un controllo di bug si verifica se il driver fornisce un handle di oggetti non valido.

Commenti

Il metodoWdfIoQueueAssignForwardProgressPolicy crea oggetti richiesta che il framework riserva per situazioni di memoria ridotta e registra le funzioni di callback chiamate dal framework per gestire situazioni di memoria ridotta.

In KMDF versione 1.9, la coda di I/O rappresentata dal parametro Queue deve essere una coda di I/O predefinita di un dispositivo o una coda per cui il driver ha chiamato WdfDeviceConfigureRequestDispatching. Il driver può chiamare WdfIoQueueAssignForwardProgressPolicy in qualsiasi momento dopo aver chiamato WdfDeviceConfigureRequestDispatching.

Nelle versioni kmDF 1.11 e successive, la coda di I/O rappresentata dal parametro Queue può essere qualsiasi coda che riceve una richiesta direttamente dal framework. Ad esempio, il driver potrebbe specificare una coda a cui inoltrare dinamicamente i provider di integrazione.

Prima che WdfIoQueueAssignForwardProgressPolicy restituisca, il framework esegue le operazioni seguenti:

Crea e archivia il numero di oggetti richiesta specificati dal driver per il membro TotalForwardProgressRequests della struttura WDF_IO_QUEUE_FORWARD_PROGRESS_POLICY .
Se il driver precedentemente denominato WdfDeviceInitSetRequestAttributes, ogni allocazione include spazio di contesto specificato da WdfDeviceInitSetRequestAttributes .
Chiama la funzione di callback EvtIoAllocateResourcesForReservedRequest per ogni oggetto richiesta creato dal framework.

Dopo che il driver ha chiamato WdfIoQueueAssignForwardProgressPolicy per creare oggetti di richiesta riservati, il framework usa tali oggetti riservati ogni volta che il tentativo di creare un nuovo oggetto richiesta ha esito negativo. In genere, tali errori sono causati da situazioni di memoria ridotta.

Il framework elimina gli oggetti di richiesta riservati solo quando elimina l'oggetto coda del framework a cui appartengono. Se il driver chiama WdfDeviceInitSetRequestAttributes e specifica una funzione di callback EvtCleanupCallback o EvtDestroyCallback per gli oggetti di richiesta, il framework chiama queste funzioni di callback per gli oggetti di richiesta riservata quando elimina gli oggetti.

Per altre informazioni sul metodo WdfIoQueueAssignForwardProgressPolicy e su come usare la funzionalità di avanzamento in avanti garantita del framework, vedere Garanzia dello stato di avanzamento in avanti delle operazioni di I/O.

Esempio

Questo esempio di codice configura una coda di I/O creata in precedenza per ricevere richieste di scrittura e quindi abilita lo stato di avanzamento in avanti garantito per la coda.

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

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Versione KMDF minima	1,9
Intestazione	wdfio.h (includere Wdf.h)
Libreria	Wdf01000.sys (vedere Framework Library Versioning).
IRQL	PASSIVE_LEVEL
Regole di conformità DDI	DriverCreate(kmdf)

Vedi anche

EvtIoAllocateResourcesForReservedRequest

WDF_IO_QUEUE_FORWARD_PROGRESS_POLICY

WdfDeviceConfigureRequestDispatching

Condividi tramite