DMA_COMPLETION_ROUTINE funzione di callback (wdm.h)
La routine di callback DmaCompletionRoutine notifica al driver che in precedenza richiedeva un trasferimento DMA di sistema che il trasferimento è stato completato.
Sintassi
DMA_COMPLETION_ROUTINE DmaCompletionRoutine;
void DmaCompletionRoutine(
[in] PDMA_ADAPTER DmaAdapter,
[in] PDEVICE_OBJECT DeviceObject,
[in] PVOID CompletionContext,
[in] DMA_COMPLETION_STATUS Status
)
{...}
Parametri
[in] DmaAdapter
Puntatore a una struttura DMA_ADAPTER . Questa struttura è l'oggetto adapter che rappresenta il canale DMA di sistema del driver.
[in] DeviceObject
Puntatore a una struttura DEVICE_OBJECT . Questa struttura è l'oggetto dispositivo fisico (PDO) che rappresenta il dispositivo di destinazione per l'operazione DMA richiesta.
[in] CompletionContext
Puntatore a un contesto determinato dal driver per la routine DmaCompletionRoutine . Questo contesto è il valore del parametro CompletionContext passato in precedenza al driver alla chiamata MapTransferEx che ha avviato il trasferimento DMA di sistema.
[in] Status
Stato di completamento del trasferimento DMA. Questo parametro è un valore di enumerazione DMA_COMPLETION_STATUS che indica se il trasferimento DMA è stato completato correttamente.
Valore restituito
nessuno
Osservazioni
Come opzione, un driver può implementare una routine DmaCompletionRoutine . Quando il driver richiede un trasferimento DMA di sistema, il driver può fornire un puntatore a questa routine con la richiesta. Al termine del trasferimento DMA, la routine DmaCompletionRoutine viene chiamata automaticamente per notificare al driver.
La routine DmaCompletionRoutine di un driver viene chiamata solo se il trasferimento DMA richiesto dal driver usa un controller DMA di sistema che può generare un'interruzione al termine del trasferimento DMA. Un driver che usa un dispositivo DMA master del bus o che usa un controller DMA di sistema che non genera interruzioni, deve usare altri mezzi per determinare quando viene completato un trasferimento DMA. Ad esempio, questo driver potrebbe usare un interrupt timer per eseguire periodicamente il polling dello stato del trasferimento DMA.
Un driver può fornire un puntatore a una routine DmaCompletionRoutine come parametro facoltativo per la routine MapTransferEx .
Esempio
Per definire una routine di callback DmaCompletionRoutine , è necessario innanzitutto fornire una dichiarazione di funzione che identifica il tipo di routine di callback che si sta definendo. Windows fornisce un set di tipi di funzione di callback per i driver. La dichiarazione di una funzione tramite i tipi di funzione di callback consente di analizzare il codice per i driver, l'SDV ( Static Driver Verifier ) e altri strumenti di verifica di trovare errori ed è un requisito per la scrittura di driver per il sistema operativo Windows.
Ad esempio, per definire una routine di callback DmaCompletionRoutine denominata MyDmaCompletionRoutine, usare il tipo di DMA_COMPLETION_ROUTINE come illustrato nell'esempio di codice seguente:
DMA_COMPLETION_ROUTINE MyDmaCompletionRoutine;
Implementare quindi la routine di callback come indicato di seguito:
_Use_decl_annotations_
VOID
MyDmaCompletionRoutine(
PDMA_ADAPTER DmaAdapter,
PDEVICE_OBJECT DeviceObject,
PVOID CompletionContext,
DMA_COMPLETION_STATUS Status
)
{
// Function body
}
Il tipo di funzione DMA_COMPLETION_ROUTINE è definito nel file di intestazione Wdm.h. Per identificare in modo più accurato gli errori quando si eseguono gli strumenti di analisi del codice, assicurarsi di aggiungere l'annotazione _Use_decl_annotations_ alla definizione della funzione. L'annotazione _Use_decl_annotations_ garantisce che vengano usate le annotazioni applicate al tipo di funzione DMA_COMPLETION_ROUTINE nel file di intestazione. Per altre informazioni sui requisiti per le dichiarazioni di funzione, vedere Dichiarazione di funzioni tramite tipi di ruolo di funzione per i driver WDM. Per informazioni sulle _Use_decl_annotations_, vedere Annotazione del comportamento della funzione.
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Disponibile a partire da Windows 8. |
| Piattaforma di destinazione | Desktop |
| Intestazione | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| IRQL | Chiamato in DISPATCH_LEVEL. |