Come scrivere il primo driver client USB (KMDF)

  • Articolo

In questo articolo si userà il modello di driver USB Kernel-Mode fornito con Microsoft Visual Studio per scrivere un semplice driver in modalità kernel (KMDF) basato su client. Dopo aver compilato e installato il driver client, verrà visualizzato il driver client in Gestione dispositivi e visualizzare l'output del driver in un debugger.

Per una spiegazione sul codice sorgente generato dal modello, vedere Informazioni sul codice 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 che 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 dispone di Visual Studio.
  • Il computer host ha l'ultimo 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, vedere Scaricare 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 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 esempi USB inclusi con 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.

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

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

Per codice specifico usb, selezionare le opzioni seguenti in Visual Studio:

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

Le schermate seguenti mostrano la finestra di dialogo Nuovo progetto per il modello di driver di Kernel-Mode USB .

Visual Studio nuove opzioni di progetto.

seconda schermata delle opzioni di progetto di visual studio.

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 funzioni di traccia e 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 evento per l'evento generato dall'oggetto coda 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 come 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 Id hardward 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 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 nella Esplora soluzioni e selezionare Configuration Manager.
  3. Dal 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 selezionare Compila soluzione.

Per altre informazioni, vedere Compilazione di un driver.

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

Per testare e eseguire il debug di un driver, eseguire il debugger nel computer host e il driver nel computer di destinazione. Finora, è stato usato Visual Studio nel computer host per compilare un driver. È quindi 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 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 gli host e i computer 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 installazioneWindows 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 dei 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. !wmitrace.searchpath +<percorso> file 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 Configuration Properties Driver Install > Deployment (Installazione driver di > proprietà di configurazione).
  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 di informazioni del driver (INF).

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 è dotato di 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 . Apre quindi 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