Scrivere un driver di Windows universale (KMDF) in base a un modello

  • Articolo

Questo argomento descrive come scrivere un driver windows universale usando Kernel-Mode Driver Framework (KMDF). Si inizierà con un modello di Microsoft Visual Studio e quindi si distribuisce e si installa il driver in un computer separato.

Prima di procedere, è necessario seguire i passaggi di installazione elencati in Scaricare Windows Driver Kit (WDK).

Gli strumenti di debug per Windows vengono inclusi quando si installa WDK.

Creare e compilare un driver

  1. Aprire Microsoft Visual Studio. Nel menu File scegliere Nuovo > progetto.

  2. Nella finestra di dialogo Crea un nuovo progetto selezionare C++ nell'elenco a discesa a sinistra, scegliere Windows nell'elenco a discesa centrale e scegliere Driver nell'elenco a discesa a destra.

  3. Selezionare Driver in modalità kernel (KMDF) nell'elenco dei tipi di progetto. Selezionare Avanti.

    Screenshot della finestra di dialogo nuovo progetto che mostra il driver in modalità kernel selezionato.

  4. Nella finestra di dialogo Configura nuovo progetto immettere "KmdfDriver" nel campo Nome progetto .

    Nota

    Quando si crea un nuovo driver KMDF o UMDF, è necessario selezionare un nome del driver con 32 caratteri o meno. Questo limite di lunghezza è definito in wdfglobals.h.  

  5. Nel campo Percorso immettere la directory in cui si vuole creare il nuovo progetto.

  6. Selezionare Posiziona soluzione e progetto nella stessa directory e selezionare Crea.

    Screenshot della finestra di dialogo configurazione del progetto.

    Visual Studio crea un progetto e una soluzione. I file sono visibili nella finestra Esplora soluzioni. Se la finestra Esplora soluzioni non è visibile, scegliere Esplora soluzioni dal menu Visualizza. La soluzione ha un progetto driver denominato KmdfDriver. Per visualizzare il codice sorgente del driver, aprire uno dei file in File di origine. Driver.c e Device.c sono luoghi adatti per iniziare.

    Screenshot di Esplora soluzioni che mostra i file nel progetto driver.

  7. Nella finestra Esplora soluzioni selezionare e tenere premuto (o fare clic con il pulsante destro del mouse) KmdfDriver e scegliere Proprietà. Passare a Impostazioni driver proprietà > configurazione Generale e notare che le impostazioni >predefinite della piattaforma di destinazione sono universali.

  8. Per compilare il driver, scegliere Compila soluzione dal menu Compila . Microsoft Visual Studio visualizza lo stato di avanzamento della compilazione nella finestra Output . Se la finestra Output non è visibile, scegliere Output dal menu Visualizza .

    Verificare che l'output della compilazione includa:

    >    Driver is 'Universal'.

    Dopo aver verificato che la soluzione compilata correttamente, è possibile chiudere Visual Studio.

  9. Per visualizzare il driver compilato, in Esplora file, passare alla cartella KmdfDriver e quindi a x64\Debug\KmdfDriver. La directory include i file seguenti:

    • KmdfDriver.sys - il file del driver in modalità kernel
    • KmdfDriver.inf - un file di informazioni usato da Windows quando si installa il driver

Distribuire il driver

In genere, quando si esegue il test e il debug di un driver, il debugger e il driver vengono eseguiti in computer separati. Il computer che esegue il debugger viene chiamato computer host e il computer che esegue il driver viene chiamato computer di destinazione. Il computer di destinazione viene chiamato anche il computer di test. Per altre informazioni sui driver di debug, vedere Strumenti di debug per Windows.

Finora è stato usato Visual Studio per creare un driver nel computer host. È ora necessario configurare un computer di destinazione.

  1. Seguire le istruzioni riportate in Effettuare il provisioning di un computer per la distribuzione e il test dei driver (WDK 10).

    Suggerimento

    Quando si seguono i passaggi per effettuare il provisioning automatico del computer di destinazione usando un cavo di rete, prendere nota della porta e della chiave. Verranno usati più avanti nel passaggio di debug. In questo esempio si useranno 50000 come porta e 1.2.3.4 come chiave.

    Negli scenari di debug dei driver reali è consigliabile usare una chiave generata da KDNET. Per altre informazioni su come usare KDNET per generare una chiave casuale, vedere l'argomento Driver di debug - Passaggio per lab (modalità kernel Sysvad).

  2. Nel computer host aprire la soluzione in Visual Studio. È possibile fare doppio clic sul file di soluzione, KmdfDriver.sln, nella cartella KmdfDriver.

  3. Nella finestra Esplora soluzioni selezionare e tenere premuto (o fare clic con il pulsante destro del mouse) il progetto KmdfDriver e scegliere Proprietà.

  4. Nella finestra Pagine delle proprietà del pacchetto KmdfDriver , nel riquadro sinistro passare a Configuration Properties > Driver Install Deployment(Installazione > driver proprietà configurazione).

  5. Selezionare Rimuovi versioni precedenti del driver prima della distribuzione.

  6. Per Nome computer remoto selezionare il nome del computer configurato per il test e il debug. In questo esercizio viene usato un computer denominato MyTestComputer.

  7. Selezionare Aggiornamento driver ID hardware e immettere l'ID hardware per il driver. In questo esercizio l'ID hardware è Root\KmdfDriver. Selezionare OK.

    schermata della finestra delle pagine delle proprietà del pacchetto kmdfdriver, che mostra l'installazione del driver di distribuzione selezionata

    Nota

    In questo esercizio l'ID hardware non identifica una parte reale di hardware. Identifica un dispositivo immaginario che verrà assegnato un posto nell'albero dei dispositivi come figlio del nodo radice. Per l'hardware reale, non selezionare Aggiornamento driver ID hardware; Selezionare invece Installa e Verifica. Verrà visualizzato l'ID hardware nel file INF (Information) del driver. Nella finestra Esplora soluzioni passare a KmdfDriver Driver Files e fare doppio clic su KmdfDriver.inf>. L'ID hardware si trova in [Standard.NT$ARCH$].

    [Standard.NT$ARCH$]
%KmdfDriver.DeviceDesc%=KmdfDriver_Device, Root\KmdfDriver

  8. Nel menu Compila scegliere Distribuisci soluzione. Visual Studio copia automaticamente i file necessari per installare ed eseguire il driver nel computer di destinazione. L'operazione potrebbe richiedere un paio di minuti.

    Quando si distribuisce un driver, i file driver vengono copiati nella cartella %Systemdrive%\drivertest\drivers nel computer di test. Se si verifica un errore durante la distribuzione, è possibile verificare se i file vengono copiati nel computer di test. Verificare che i file con estensione inf, cat, test cert e .sys e tutti gli altri file necessari siano presenti nella cartella %systemdrive%\drivertest\drivers.

    Per altre informazioni sulla distribuzione dei driver, vedere Distribuzione di un driver in un computer di test.

Installare il driver

Con il driver KMDF distribuito nel computer di destinazione, ora si installerà il driver. Quando in precedenza si esegue il provisioning del computer di destinazione con Visual Studio usando l'opzione automatica , Visual Studio configura il computer di destinazione per eseguire i driver firmati di test come parte del processo di provisioning. Ora è sufficiente installare il driver usando lo strumento DevCon.

  1. Nel computer host passare alla cartella Strumenti nell'installazione WDK e individuare lo strumento DevCon. Ad esempio, cercare nella cartella seguente:

    C:\Programmi (x86)\Windows Kits\10\Tools\x64\devcon.exe

    Copiare lo strumento DevCon nel computer remoto.

  2. Nel computer di destinazione installare il driver passando alla cartella contenente i file driver e quindi eseguendo lo strumento DevCon.

    1. Ecco la sintassi generale per lo strumento devcon che si userà per installare il driver:

      Devcon install <INF file><HARDWARE ID>

      Il file INF necessario per l'installazione di questo driver è KmdfDriver.inf. Il file INF contiene l'ID hardware per l'installazione del file binario del driver, KmdfDriver.sys. Si ricordi che l'ID hardware, situato nel file INF, è Root\KmdfDriver.

    2. Aprire una finestra del prompt dei comandi come amministratore. Passare alla cartella del pacchetto driver, quindi immettere questo comando:

      devcon install kmdfdriver.inf root\kmdfdriver

      Se viene visualizzato un messaggio di errore relativo a devcon non riconosciuto, provare ad aggiungere il percorso allo strumento devcon . Ad esempio, se è stato copiato in una cartella nel computer di destinazione denominato C:\Tools, provare a usare il comando seguente:

      c:\tools\devcon install kmdfdriver.inf root\kmdfdriver

      Verrà visualizzata una finestra di dialogo che indica che il driver di test è un driver senza segno. Selezionare Installa questo driver comunque per procedere.

      screenshot dell'avviso di installazione del driver.

Eseguire il debug del driver

Dopo aver installato il driver KMDF nel computer di destinazione, si collega un debugger in remoto dal computer host.

  1. Nel computer host aprire una finestra del prompt dei comandi come amministratore. Passare alla directory WinDbg.exe. Useremo la x64version di WinDbg.exe da Windows Driver Kit (WDK) installata come parte dell'installazione del kit di Windows. Ecco il percorso predefinito per WinDbg.exe:

    C:\Programmi (x86)\Windows Kits\10\Debuggers\x64

  2. Avviare WinDbg per connettersi a una sessione di debug del kernel nel computer di destinazione usando il comando seguente. Il valore della porta e della chiave deve essere uguale a quello usato per effettuare il provisioning del computer di destinazione. Verranno usati 50000 per la porta e 1.2.3.4 per la chiave, i valori usati durante il passaggio di distribuzione. Il flag k indica che si tratta di una sessione di debug del kernel.

    WinDbg -k net:port=50000,key=1.2.3.4

  3. Nel menu Debug scegliere Interruzione. Il debugger nel computer host si interromperà nel computer di destinazione. Nella finestra Comando debugger è possibile visualizzare il prompt dei comandi di debug del kernel: kd>.

  4. A questo punto, è possibile sperimentare con il debugger immettendo i comandi al prompt kd> . Ad esempio, è possibile provare questi comandi:

  5. Per consentire l'esecuzione del computer di destinazione, scegliere Vai dal menu Debug o premere "g", quindi premere "invio".

  6. Per arrestare la sessione di debug, scegliere Scollega debug dal menu Debug .

    Importante

    Assicurarsi di usare il comando "go" per consentire l'esecuzione del computer di destinazione prima di uscire dal debugger oppure il computer di destinazione rimarrà non rispondente al mouse e all'input della tastiera perché sta ancora parlando con il debugger.

Per una procedura dettagliata del processo di debug del driver, vedere Debug di driver universali - Passaggio per lab (Echo Kernel-Mode).

Per altre informazioni sul debug remoto, vedere Debug remoto con WinDbg.

Uso di Driver Module Framework (DMF)

Driver Module Framework (DMF) è un'estensione di WDF che consente funzionalità aggiuntive per uno sviluppatore di driver WDF. Consente agli sviluppatori di scrivere qualsiasi tipo di driver WDF migliore e più veloce.

DMF come framework consente la creazione di oggetti WDF denominati moduli DMF. Il codice per questi moduli DMF può essere condiviso tra driver diversi. Inoltre, DMF raggruppa una libreria di moduli DMF sviluppati per i driver e si sente di fornire valore ad altri sviluppatori di driver.

DMF non sostituisce WDF. DMF è un secondo framework usato con WDF. Lo sviluppatore che sfrutta DMF usa ancora WDF e tutte le sue primitive per scrivere driver di dispositivo.

Per altre informazioni, vedere Driver Module Framework (DMF).