Condividi tramite

Esercitazione: Scrivere un driver di Windows universale (KMDF) basato su un modello

  • Articolo

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

Prerequisiti

  • Seguire la procedura per installare Windows Driver Kit (WDK). Strumenti di debug per Windows viene incluso quando si installa WDK.

  • Installare Visual Studio 2022. Quando si installa Visual Studio 2022, selezionare il carico di lavoro Sviluppo desktop con C++ e quindi in Componenti individuali aggiungere:

    • MSVC v143 - VS 2022 C++ ARM64/ARM64EC librerie con mitigazioni per Spectre (versione più recente)
    • MSVC v143 - VS 2022 C++ x64/x86 Librerie con mitigazione Spectre (più recente)
    • ATL C++ per gli strumenti di compilazione v143 più recenti con mitigazioni Spectre (ARM64/ARM64EC)
    • ATL C++ per gli strumenti di compilazione v143 più recenti con mitigazioni Spectre (x86 & x64)
    • MFC C++ per gli strumenti di compilazione v143 più recenti con mitigazioni Spectre (ARM64/ARM64EC)
    • MFC C++ per gli strumenti di compilazione v143 più recenti con mitigazioni Spectre (x86 & x64)
    • Windows Driver Kit

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. Seleziona Driver in modalità Kernel (KMDF) dall'elenco dei tipi di progetto. Selezionare Avanti.

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

    Suggerimento

    Se non è possibile trovare modelli di progetto driver in Visual Studio, l'estensione WDK di Visual Studio non è stata installata correttamente. Per risolvere questo problema, avviare Visual Studio Installer, selezionare Modifica, aggiungere Windows Driver Kits nella scheda Componenti individuali e selezionare Modifica.

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

    Nota

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

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

  6. Selezionare Posizionare la soluzione e il progetto nella stessa directory e selezionare Crea.

    schermata della finestra di dialogo di configurazione del progetto.

    Visual Studio crea un progetto e una soluzione. È possibile visualizzarli 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 ottimi punti di partenza.

    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) KmdfDrivere scegliere Proprietà . Passare a Proprietà di configurazione > Impostazioni driver > Generalee notare che Piattaforma di Destinazione per impostazione predefinita è Universale.

  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 di compilazione includa:

    >    Driver is 'Universal'.

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

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

    • KmdfDriver.sys - file del driver in modalità kernel
    • KmdfDriver.inf - un file di informazioni usato da Windows durante l'installazione del 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 il 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 compilare un driver nel computer host. È ora necessario configurare un computer di destinazione.

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

    Suggerimento

    Quando si seguono i passaggi per configurare automaticamente il computer di destinazione usando un cavo di rete, annotare la porta e la chiave. Verranno usati più avanti nel passaggio di debug. In questo esempio si userà 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 Debug Drivers - Step by Step Lab (Sysvad Kernel Mode).

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

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

  4. Nella finestra pagine delle proprietà del pacchetto KmdfDriver, nel riquadro di sinistra, vai a Proprietà di configurazione > Driver Install > Deployment.

  5. Controllare Rimuovere le versioni precedenti del driver prima della distribuzione.

  6. Per il nome del computer remoto , selezionare il nome del computer che avete configurato per i test e il debugging. In questo esercizio si usa un computer denominato MyTestComputer.

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

    Schermata delle pagine delle proprietà del pacchetto kmdfdriver, con l'installazione del driver di distribuzione selezionata

    Nota

    In questo esercizio l'ID hardware non identifica un componente hardware reale. 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. L'ID hardware verrà visualizzato 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 può richiedere un minuto o due.

    Quando si distribuisce un driver, i file del 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, certificato di test 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

Dopo aver distribuito il driver KMDF nel computer di destinazione, si installerà il driver. Quando in precedenza è stato effettuato il provisioning del computer di destinazione con Visual Studio usando l'opzione automatica , Visual Studio ha configurato il computer di destinazione per eseguire driver firmati per i 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 di WDK e individuare lo strumento DevCon. Ad esempio, cercare nella cartella seguente:

    C:\Program Files (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 del driver, quindi eseguendo lo strumento DevCon.

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

      devcon installare <file INF><ID hardware>

      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. Tenere presente che l'ID hardware, che si trova nel file INF, è Root\KmdfDriver.

    2. Apri una finestra del Prompt dei comandi come amministratore. Passare alla cartella del pacchetto driver e quindi immettere questo comando:

      devcon install kmdfdriver.inf root\kmdfdriver

      Se ricevi un messaggio di errore che dice che devcon non viene riconosciuto, prova ad aggiungere il percorso dello 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 non firmato. Selezionare Installare questo driver comunque per continuare.

      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. Sul computer host, aprire la finestra del Prompt dei Comandi come Amministratore. Passare alla directory WinDbg.exe. Useremo la versione x64 di WinDbg.exe del Driver Kit (WDK) di Windows installato come parte dell'installazione di Windows Kit. Ecco il percorso predefinito di 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 corrispondere a quello usato per effettuare il provisioning del computer di destinazione. Si useranno 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 Interrompi. Il debugger sul computer host creerà un'interruzione nel computer di destinazione. Nella finestra comando del debugger è possibile visualizzare il prompt dei comandi di debug del kernel: kd>.

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

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

  6. Per arrestare la sessione di debug, scegliere Distacca il programma in debug dal menu Debug.

    Importante

    Assicurati di usare il comando "go" per consentire al computer di destinazione di riprendere l'esecuzione prima di uscire dal debugger; altrimenti il computer di destinazione non risponderà agli input di mouse e tastiera poiché sta ancora comunicando con il debugger.

Per una guida dettagliata passo per passo del processo di debug dei driver, vedere Debug dei driver universali - Laboratorio Passo per Passo (Echo Kernel-Mode).

Per altre informazioni sul debug remoto, vedere debug remoto tramite WinDbg.

Uso di Driver Module Framework (DMF)

Il DMF (Driver Module Framework) di è un'estensione di WDF che consente funzionalità aggiuntive per uno sviluppatore di driver WDF. Consente agli sviluppatori di scrivere qualsiasi tipo di driver WDF in modo migliore e 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. DMF aggrega inoltre una libreria di moduli DMF sviluppati per i driver e si ritiene che fornisca valore ad altri sviluppatori di driver.

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

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