Condividi tramite

Debug dei componenti del driver della stampante

Se si sviluppa un plug-in di rendering del driver della stampante o un plug-in dell'interfaccia utente, è possibile abilitare i messaggi di debug in questi componenti. Come illustrato nella sezione Variabile di debug globale, è possibile usare una variabile di debug globale per controllare il livello di dettaglio nei messaggi visualizzati nella finestra del debugger.

È possibile utilizzare le macro di messaggio di debug descritte nella sezione per inviare messaggi alla finestra del debugger in diverse condizioni. Inoltre, è possibile usare le informazioni contenute in questa sezione per abilitare i messaggi di debug nei renderer Microsoft Universal Printer Driver (Unidrv) o PostScript Printer Driver (Pscript), purché siano state controllate le build di queste DLL.

Nota

Le build controllate erano disponibili nelle versioni precedenti di Windows, precedenti a Windows 10 versione 1803. Usare strumenti come Driver Verifier e GFlags per controllare il codice driver nelle versioni successive di Windows.

I passaggi per il debug di un driver in modalità utente e alcuni suggerimenti generali per il debug sono inclusi nelle due sezioni successive.

Preparazione per il debug di User-Mode

Per avviare il debug dei driver della stampante e dei relativi componenti:

  1. Installare gli strumenti di debug più recenti. Vedere Scaricare gli strumenti di debug per Windows

  2. Installare i simboli corretti dai pacchetti di simboli Windows

Nota

È molto importante usare la versione più recente del debugger.

È consigliabile installare la compilazione controllata solo dei componenti a cui si è interessati al debug. In genere si sostituirebbero i file binari venduti al dettaglio seguenti con le compilazioni verificate corrispondenti:

  • Unidrv.dll

  • Unidrvui.dll

  • Unires.dll

È anche necessario installare la build controllata dell'esempio Oemuni o del driver della stampante di cui si sta eseguendo il debug. Il vantaggio di usare questo approccio, anziché installare un intero sistema di compilazione controllato, è che non si rallenta l'intero sistema.

Avvio di una sessione di debug di User-Mode

Per avviare il debug in modalità utente, nel menu File del debugger Windbg, selezionare Collega a un Processo. Il processo a cui si collega il debugger dipende dallo scenario in cui si sta tentando di eseguire il debug. Per i driver della stampante, devi collegare il debugger all'applicazione di stampa o al processo dello spooler (Spoolsv.exe). Tenere presente che l'applicazione di stampa carica il modulo di configurazione/interfaccia utente, mentre il processo di spooler carica il modulo di rendering. Tuttavia, esistono differenze per la stampa "FILE:", in cui lo spooling non viene eseguito e, di conseguenza, il modulo di rendering viene caricato direttamente dall'applicazione di stampa. È quindi necessario assicurarsi di collegarsi al processo corretto.

Nota

Non sono necessari due computer separati per il debug in modalità utente.

La procedura seguente consente di eseguire il debug dell'esempio Oemuni.

  1. Installare l'esempio Oemuni sulla porta "FILE:".

  2. Avviare l'applicazione WordPad facendo clic sul menu Start, selezionando Tutti i programmi, selezionando Accessorie quindi selezionando WordPad.

  3. Nel menu File di WinDbg, selezionare Collega a un processo. Nell'elenco dei processi disponibili selezionare WordPad.exe.

  4. Avviare un processo di stampa da WordPad. È ora possibile eseguire il debug dell'esempio Oemuni.

È possibile abilitare il debug dettagliato attivando la variabile giDebugLevel. Il valore predefinito è 3, che indica WARNING. Se impostato su 1, indica VERBOSE. Per impostare il secondo valore con Unidrv.dll, digitare il comando seguente nel debugger:

> ed unidrv!giDebugLevel 1

Quando si esegue l'esempio Oemuni, si applica anche la stessa variabile di debug, quindi per abilitare il debug dettagliato, digitare il comando seguente:

> ed oemuni!giDebugLevel 1

È anche possibile aggiungere istruzioni di debug personalizzate all'esempio Oemuni.

Per altre informazioni sull'impostazione dei valori di debug, vedere la documentazione di WinDbg, che descrive i comandi disponibili e i passaggi necessari per configurare il debug in modalità utente. Per accedere alla documentazione, nel menu Guida di WinDbg selezionare Contenuti.

Variabile di debug globale

La variabile globale giDebugLevel viene dichiarata dagli esempi Oemui e Oemuni nei file Debug.h e Debug.cpp. Il valore di giDebugLevel può essere modificato da:

  • Cambiare il suo valore nel debugger
  • Ridefinire il valore nel plug-in

È possibile impostare giDebugLevel su uno dei valori seguenti:

#define DBG_VERBOSE 1
#define DBG_TERSE   2
#define DBG_WARNING 3
#define DBG_ERROR   4
#define DBG_RIP     5

Eseguire il debug di macro di messaggi

Le macro seguenti vengono utilizzate a scopo di debug. Diverse di esse eseguono un'azione solo se la variabile globale giDebugLevel, che controlla quali messaggi di debug vengono generati, viene impostata su un valore specifico. Le macro si espandono in spazi vuoti in una compilazione libera. Di seguito sono riportate brevi descrizioni delle operazioni eseguite e dei relativi parametri.

ASSERT(cond)

  • Verifica se l'espressione booleana nel contesto di cond è VERO. In caso contrario, la macro forza un punto di interruzione.

ASSERTMSG(cond, (msg))

  • Verifica se l'espressione booleana in cond è TRUE. In caso contrario, la macro visualizza il messaggio in msg, e forza un punto di interruzione.

ERR((msg))

  • Visualizza il messaggio in msg se il livello di debug corrente è <= DBG_ERROR. Il formato del messaggio è:

    ERR filename (linenumber): msg

RIP((msg))

  • Visualizza il messaggio in msg e forza un punto di interruzione.

TERSE((msg))

  • Visualizza il messaggio in msg se il livello di debug corrente è <= DBG_TERSE.

VERBOSE ((msg))

  • Visualizza il messaggio in msg se il livello di debug corrente è <= DBG_VERBOSE.

AVVISO ((msg))

  • Visualizza il messaggio in msg se il livello di debug corrente è <= DBG_WARNING. Il formato del messaggio è:

    WRN filename (linenumber): msg

Si noti che tutte le macro con un argomento msg richiedono una coppia aggiuntiva di parentesi che lo circondano. Ecco due esempi che illustrano questo requisito:

ASSERTMSG(x > 0, ("x is less than 0\n"));

WARNING( ("App passed NULL pointer, ignoring...\n") );

Le macro che contengono un argomento msg sono definite dagli esempi Oemui e Oemuni nelle intestazioni Debug.h.