Come scrivere il primo driver client USB (KMDF)

In questo articolo si userà il modello driver usb in modalità kernel fornito con Microsoft Visual Studio per scrivere un semplice driver client basato su KERNEL (KMDF). Dopo aver compilato e installato il driver client, si visualizzerà il driver client in Gestione dispositivi e si visualizzerà l'output del driver in un debugger.

Per una spiegazione del codice sorgente generato dal modello, vedere Informazioni sul codice del modello kmDF per un driver client USB.

Prerequisiti

Per lo sviluppo, il debug e l'installazione di un driver in modalità kernel, sono necessari due computer:

• Un computer host che esegue Windows 7 o una versione successiva del sistema operativo Windows. Il computer host è l'ambiente di sviluppo, in cui si scrive ed esegue il debug del driver.
• Un computer di destinazione che esegue Windows Vista o una versione successiva di Windows. Il computer di destinazione ha il driver in modalità kernel di cui si vuole eseguire il debug.

Prima di iniziare, assicurarsi di soddisfare i requisiti seguenti:

Requisiti software

• Il computer host ospita l'ambiente di sviluppo e ha Visual Studio.
• Il computer host ha la versione più recente di Windows Driver Kit (WDK). Il kit include intestazioni, librerie, strumenti, documentazione e strumenti di debug necessari per sviluppare, compilare ed eseguire il debug di un driver KMDF. Per ottenere la versione più recente di WDK, vedi Scaricare Windows Driver Kit (WDK).To get the latest version of the WDK, see Download the Windows Driver Kit (WDK).
• Il computer host ha la versione più recente degli strumenti di debug per Windows. È possibile ottenere la versione più recente da WDK oppure scaricare e installare gli strumenti di debug per Windows.
• Il computer di destinazione esegue Windows Vista o una versione successiva di Windows.
• I computer host e di destinazione sono configurati per il debug del kernel. Per altre informazioni, vedere Configurazione di una connessione di rete in Visual Studio.

Requisiti hardware

Ottenere un dispositivo USB per il quale si scriverà il driver client. Nella maggior parte dei casi, viene fornito un dispositivo USB e la relativa specifica hardware. La specifica descrive le funzionalità del dispositivo e i comandi del fornitore supportati. Usare la specifica per determinare la funzionalità del driver USB e le decisioni di progettazione correlate.

Se non si ha familiarità con lo sviluppo di driver USB, usare il kit di apprendimento OSR USB FX2 per studiare gli esempi USB inclusi in WDK. È possibile ottenere il kit di apprendimento da OSR Online. Contiene il dispositivo USB FX2 e tutte le specifiche hardware necessarie per implementare un driver client.

È anche possibile ottenere dispositivi MICROSOFT USB Test Tool (MUTT). L'hardware MUTT può essere acquistato da JJG Technologies. Il dispositivo non ha installato il firmware. Per installare il firmware, scaricare il pacchetto software MUTT da questo sito Web ed eseguire MUTTUtil.exe. Per altre informazioni, vedere la documentazione inclusa nel pacchetto.

Argomenti consigliati

• Concetti per tutti gli sviluppatori di driver
• Nodi del dispositivo e stack di dispositivi
• Introduzione ai driver in Windows
• Framework driver in modalità kernel
• Sviluppo di driver con Windows Driver Foundation, scritto da Penny Orwick e Guy Smith. Per altre informazioni, vedere Sviluppo di driver con WDF.

Passaggio 1: Generare il codice del driver KMDF usando il modello di driver USB di Visual Studio

Per istruzioni sulla generazione del codice del driver KMDF, vedere la procedura descritta in Scrittura di un driver KMDF basato su un modello.

Per il codice specifico dell'USB, selezionare le opzioni seguenti in Visual Studio:

1. Nella casella di ricerca nella parte superiore della finestra di dialogo Nuovo progetto digitare USB.
2. Nel riquadro centrale selezionare Driver in modalità kernel, USB (KMDF).
3. Selezionare Avanti.
4. Immettere un nome di progetto, scegliere un percorso di salvataggio e selezionare Crea.

Le schermate seguenti mostrano la finestra di dialogo Nuovo progetto per il modello driver in modalità kernel USB.

Questo articolo presuppone che il nome del progetto di Visual Studio sia "MyUSBDriver_". Contiene i file seguenti:

File	Descrizione
Public.h	Fornisce dichiarazioni comuni condivise dal driver client e dalle applicazioni utente che comunicano con il dispositivo USB.
<>Nome progetto.inf	Contiene informazioni necessarie per installare il driver client nel computer di destinazione.
Trace.h	Dichiara le funzioni di traccia e le macro.
Driver.h; Driver.c	Dichiara e definisce i punti di ingresso del driver e le routine di callback degli eventi.
Device.h; Device.c	Dichiara e definisce la routine di callback degli eventi per l'evento prepare-hardware.
Queue.h; Queue.c	Dichiara e definisce una routine di callback di eventi per l'evento generato dall'oggetto queue del framework.

Passaggio 2: Modificare il file INF per aggiungere informazioni sul dispositivo

Prima di compilare il driver, è necessario modificare il file INF del modello con informazioni sul dispositivo, in particolare la stringa id hardware.

In Esplora soluzioni, in File driver fare doppio clic sul file INF.

Nel file INF è possibile fornire informazioni quali il produttore e il nome del provider, la classe di installazione del dispositivo e così via. Una parte delle informazioni da fornire è l'identificatore hardware del dispositivo.

Per specificare la stringa ID hardware:

1. Collegare il dispositivo USB al computer host e consentire a Windows di enumerare il dispositivo.

2. Aprire Gestione dispositivi e aprire le proprietà per il dispositivo.

3. Nella scheda Dettagli selezionare Hardward Ids in Proprietà.

   L'ID hardware per il dispositivo viene visualizzato nella casella di riepilogo. Selezionare e tenere premuto (o fare clic con il pulsante destro del mouse) e copiare la stringa dell'ID hardware.

4. Sostituire USB\VID_vvvv&PID_pppp nella riga seguente con la stringa ID hardware.

   [Standard.NT$ARCH$] %MyUSBDriver_.DeviceDesc%=MyUSBDriver__Device, USB\VID_vvvv&PID_pppp

Passaggio 3: Compilare il codice del driver client USB

Per compilare il driver:

1. Aprire il progetto o la soluzione driver in Visual Studio
2. Selezionare e tenere premuto (o fare clic con il pulsante destro del mouse) sulla soluzione nel Esplora soluzioni e selezionare Configuration Manager.
3. Da Configuration Manager selezionare la configurazione della soluzione attiva (ad esempio Debug o Versione) e la piattaforma soluzione attiva (ad esempio Win32) che corrispondono al tipo di compilazione a cui si è interessati.
4. Dal menu Compila scegliere Compila soluzione.

Per altre informazioni, vedere Compilazione di un driver.

Passaggio 4: Configurare un computer per il test e il debug

Per testare ed eseguire il debug di un driver, eseguire il debugger nel computer host e nel driver nel computer di destinazione. Finora è stato usato Visual Studio nel computer host per compilare un driver. Successivamente è necessario configurare un computer di destinazione. Per configurare un computer di destinazione, seguire le istruzioni riportate in Effettuare il provisioning di un computer per la distribuzione e il test dei driver.

Passaggio 5: Abilitare la traccia per il debug del kernel

Il codice del modello contiene diversi messaggi di traccia (TraceEvents) che consentono di tenere traccia delle chiamate di funzione. Tutte le funzioni nel codice sorgente contengono messaggi di traccia che contrassegnano la voce e l'uscita di una routine. Per gli errori, il messaggio di traccia contiene il codice di errore e una stringa significativa. Poiché la traccia WPP è abilitata per il progetto driver, il file di simboli PDB creato durante il processo di compilazione contiene istruzioni di formattazione dei messaggi di traccia. Se si configurano i computer host e di destinazione per la traccia WPP, il driver può inviare messaggi di traccia a un file o al debugger.

Per configurare il computer host per la traccia WPP:

1. Creare file TMF (Trace Message Format) estraendo le istruzioni di formattazione dei messaggi di traccia dal file di simboli PDB.

   È possibile usare Tracepdb.exe per creare file TMF. Lo strumento si trova nella <cartella di installazione di Windows Kits\10.0\bin\<architecture> della cartella>WDK. Il comando seguente crea file TMF per il progetto driver.

   tracepdb -f <PDBFiles> -p <TMFDirectory>

   L'opzione -f specifica il percorso e il nome del file di simboli PDB. L'opzione -p specifica il percorso per i file TMF creati da Tracepdb. Per altre informazioni, vedere Comandi tracepdb.

   Nel percorso specificato verranno visualizzati tre file (uno per ogni file con estensione c nel progetto). Vengono assegnati nomi di file GUID.

2. Nel debugger digitare i comandi seguenti:

   1. .load Wmitrace

      Carica l'estensione Wmitrace.dll.

   2. .catena

      Verificare che l'estensione del debugger sia caricata.

   3. Percorso del file !wmitrace.searchpath +<TMF>

      Aggiungere il percorso dei file TMF al percorso di ricerca dell'estensione del debugger.

      L'output è simile al seguente:

      Trace Format search path is: 'C:\Program Files (x86)\Microsoft Visual Studio 14.0\Common7\IDE;c:\drivers\tmf'

Per configurare il computer di destinazione per la traccia WPP:

1. Assicurarsi di disporre dello strumento Tracelog nel computer di destinazione. Lo strumento si trova nella cartella install_folder>Windows Kits\8.0\Tools\<arch> di WDK.< Per altre informazioni, vedere Sintassi dei comandi tracelog.

2. Aprire una finestra di comando ed eseguire come amministratore.

3. Digitare il comando seguente:

   tracelog -start MyTrace -guid #c918ee71-68c7-4140-8f7d-c907abbcb05d -flag 0xFFFF -level 7-rt -kd

   Il comando avvia una sessione di traccia denominata MyTrace.

   L'argomento GUID specifica il GUID del provider di traccia, ovvero il driver client. È possibile ottenere il GUID da Trace.h nel progetto Visual Studio Professional 2019. Come altra opzione, è possibile digitare il comando seguente e specificare il GUID in un file con estensione guid. Il file contiene il GUID in formato trattino:

   tracelog -start MyTrace -guid c:\drivers\Provider.guid -flag 0xFFFF -level 7-rt -kd

   È possibile arrestare la sessione di traccia digitando il comando seguente:

   tracelog -stop MyTrace

Passaggio 6: Distribuire il driver nel computer di destinazione

1. Nella finestra Esplora soluzioni selezionare e tenere premuto (o fare clic con il pulsante destro del mouse) sul *<nome> progetto*Pacchetto e scegliere Proprietà.
2. Nel riquadro sinistro passare a Proprietà > di configurazione Installazione driver > Distribuzione.
3. Selezionare Abilita distribuzione e selezionare Importa nell'archivio driver.
4. Per Remote Computer Name (Nome computer remoto) specificare il nome del computer di destinazione.
5. Selezionare Installa e verifica.
6. Selezionare OK.
7. Scegliere Avvia debug dal menu Debug oppure premere F5 sulla tastiera.

Nota

Non specificare l'ID hardware del dispositivo in Aggiornamento driver ID hardware. L'ID hardware deve essere specificato solo nel file INF (Information) del driver.

Per altre informazioni sulla distribuzione del driver nel sistema di destinazione in Visual Studio, vedere Distribuzione di un driver in un computer di test.

È anche possibile installare manualmente il driver nel computer di destinazione usando Gestione dispositivi. Se si vuole installare il driver da un prompt dei comandi, sono disponibili queste utilità:

• PnPUtil

  Questo strumento viene fornito con Windows. Si trova in Windows\System32. È possibile usare questa utilità per aggiungere il driver all'archivio driver.

  C:\>pnputil /a m:\MyDriver_.inf
  Microsoft PnP Utility
  
  Processing inf : MyDriver_.inf
  Driver package added successfully.
  Published name : oem22.inf
  

  Per altre informazioni, vedere Esempi di PnPUtil.

• DevCon Update

  Questo strumento viene fornito con WDK. È possibile usarlo per installare e aggiornare i driver.

  devcon update c:\windows\inf\MyDriver_.inf USB\VID_0547&PID_1002\5&34B08D76&0&6
  

Passaggio 7: Visualizzare il driver in Gestione dispositivi

1. Immettere il comando seguente per aprire Gestione dispositivi:

   devmgmt
   

2. Verificare che Gestione dispositivi mostri un nodo per il nodo seguente:

   Esempi

   MyUSBDriver_Device

Passaggio 8: Visualizzare l'output nel debugger

Visual Studio visualizza prima lo stato di avanzamento nella finestra Output . Verrà quindi aperta la finestra immediata del debugger. Verificare che i messaggi di traccia vengano visualizzati nel debugger nel computer host. L'output dovrebbe essere simile al seguente, dove "MyUSBDriver_" è il nome del modulo driver:

[3]0004.0054::00/00/0000-00:00:00.000 [MyUSBDriver_]MyUSBDriver_EvtDriverContextCleanup Entry
[1]0004.0054::00/00/0000-00:00:00.000 [MyUSBDriver_]MyUSBDriver_EvtDriverDeviceAdd Entry
[1]0004.0054::00/00/0000-00:00:00.000 [MyUSBDriver_]MyUSBDriver_EvtDriverDeviceAdd Exit
[0]0004.0054::00/00/0000-00:00:00.000 [MyUSBDriver_]DriverEntry Entry
[0]0004.0054::00/00/0000-00:00:00.000 [MyUSBDriver_]DriverEntry Exit

Argomenti correlati

• Informazioni sul codice del modello KMDF per un driver client USB
• Introduzione allo sviluppo di driver client USB