Dichiarazione di funzioni tramite tipi di ruolo di funzione per i driver WDM
Nota
A partire da Windows 10 versione 2004, Static Driver Verifier (SDV) non richiede più annotazioni per identificare i tipi di ruolo delle routine dispatch per i driver WDM. Seguire le indicazioni nella sezione Inizializzazione di base e avanzata di questa pagina.
Per informare SDV sui punti di ingresso del driver quando si analizza un driver WDM, è necessario dichiarare funzioni usando dichiarazioni di tipo di ruolo funzione. I tipi di ruolo della funzione sono definiti in Wdm.h. Ogni punto di ingresso nella routine DriverEntry nel driver WDM deve essere dichiarato specificando il tipo di ruolo corrispondente. I tipi di ruolo sono typedef predefiniti che corrispondono ai punti di ingresso riconosciuti in un driver WDM.
Ad esempio, per creare una dichiarazione del tipo di ruolo della funzione per la routine Unload di un driver denominata CsampUnload, usare il typedef predefinito DRIVER_UNLOAD dichiarazione del tipo di ruolo. La dichiarazione del tipo di ruolo della funzione deve essere visualizzata prima della definizione della funzione.
DRIVER_UNLOAD CsampUnload;
La definizione della funzione CsampUnload rimane invariata:
VOID
CsampUnload(
IN PDRIVER_OBJECT DriverObject
)
{
...
}
SDV riconosce i tipi di punti di ingresso illustrati nella tabella seguente.
| Tipo di ruolo della funzione WDM | Routine WDM |
|---|---|
DRIVER_INITIALIZE |
|
DRIVER_STARTIO |
|
DRIVER_UNLOAD |
|
DRIVER_ADD_DEVICE |
|
| Dispatch_type( tipo ) DRIVER_DISPATCH | Routine di invio utilizzate dal driver. Vedere Scrittura di routine dispatch. |
IO_COMPLETION_ROUTINE |
La routine IoCompletion viene impostata chiamando IoSetCompletionRoutine o IoSetCompletionRoutineEx e passando il puntatore della funzione alla routine IoCompletion come secondo parametro. |
DRIVER_CANCEL |
La routine Cancel viene impostata chiamando IoSetCancelRoutine e passando il puntatore della funzione alla routine di annullamento per IRP come secondo parametro alla funzione. |
IO_DPC_ROUTINE |
La routine DpcForIsr viene registrata chiamando IoInitializeDpcRequest e passando il puntatore della funzione alla routine DpcForIsr come secondo parametro. Per accodare il DPC, chiamare IoQueueDpc dalla routine ISR usando lo stesso oggetto DPC. |
KDEFERRED_ROUTINE |
La routine CustomDpc viene impostata chiamando KeInitializeDpc e passando il puntatore della funzione a CustomDpc come secondo parametro. Per accodare CustomDpc per il driver, chiamare KeInsertQueueDpc dalla routine ISR usando lo stesso oggetto DPC. |
KSERVICE_ROUTINE |
La routine InterruptService (ISR) esegue un'interruzione del dispositivo e pianifica l'elaborazione post-interrupt dei dati ricevuti, se necessario. |
REQUEST_POWER_COMPLETE |
La routine di callback di PowerCompletion completa l'elaborazione di un IRP di alimentazione. Se il driver deve eseguire attività aggiuntive dopo che tutti gli altri driver hanno completato l'IRP, il driver registra una routine di callback di PowerCompletion durante la chiamata alla routine PoRequestPowerIrp che alloca l'IRP. |
WORKER_THREAD_ROUTINE |
Routine Routine è la routine di callback specificata nel secondo parametro della funzione ExInitializeWorkItem . La routine deve essere dichiarata in questo modo solo se il driver chiama ExQueueWorkItem per aggiungere l'elemento di lavoro a una coda di sistema. |
Dichiarazione di routine dispatch driver
A partire da Windows 10 versione 2004, le dichiarazioni del tipo di ruolo della funzione per le routine dispatch vengono perfezionate automaticamente con la categoria IRP in base all'inizializzazione della tabella DriverObject-MajorFunction> nella routine DriverEntry di un driver WDM.
Un driver Foo deve eseguire dichiarazioni di ruolo usando lo stile di dichiarazione di base o avanzato per essere conforme allo SDV.
Inizializzazione di base e avanzata
Lo stile di base è visibile nell'esempio seguente (si noti che i nomi di routine dispatch FooCreate e FooCleanup sono solo esempi, è possibile usare qualsiasi nome appropriato):
DriverObject->MajorFunction[IRP_MJ_CREATE] = FooCreate; //Basic style
DriverObject->MajorFunction[IRP_MJ_CLEANUP] = FooCleanup;
È possibile adottare un approccio più avanzato per abbreviare l'elenco necessario. Mentre la stessa routine dispatch viene usata per più di una categoria IRP, un driver può codificare due inizializzazioni in questo modo:
DriverObject->MajorFunction[IRP_MJ_CREATE] =
DriverObject->MajorFunction[IRP_MJ_CLEANUP] = FooCreateCleanup; // Advanced style for a multi-role dispatch routine
Affinché un driver sia in grado di eseguire correttamente SDV, il driver deve usare solo lo stile di base o avanzato illustrato in precedenza. La verifica SDV sul driver non funzionerà come previsto se uno di questi due metodi non viene usato.
Parametri di funzione e tipi di ruolo di funzione
Come richiesto nel linguaggio di programmazione C, i tipi di parametro usati nella definizione della funzione devono corrispondere ai tipi di parametro del prototipo di funzione o, in questo caso, al tipo di ruolo della funzione. SDV dipende dalle firme di funzione per l'analisi e ignora le funzioni le cui firme non corrispondono.
Ad esempio, è necessario dichiarare una routine IoCompletion usando il tipo di ruolo della funzione IO_COMPLETION_ROUTINE:
IO_COMPLETION_ROUTINE myCompletionRoutine;
Quando si implementa myCompletionRoutine, i tipi di parametro devono corrispondere a quelli usati da IO_COMPLETION_ROUTINE, vale a dire PDEVICE_OBJECT, PIRP e PVOID (vedere Routine IoCompletion per la sintassi).
NTSTATUS
myCompletionRoutine(
PDEVICE_OBJECT DeviceObject,
PIRP Irp,
PVOID Context
)
{
}
Esecuzione dell'analisi del codice per i driver per verificare le dichiarazioni di funzione
Per determinare se il codice sorgente è preparato, eseguire l'analisi del codice per i driver. L'analisi del codice per i driver verifica la presenza di dichiarazioni di tipo di ruolo della funzione e consente di identificare le dichiarazioni di funzione che potrebbero non essere state perse o avvisare quando i parametri della definizione della funzione non corrispondono a quelli nel tipo di ruolo della funzione.