Condividi tramite

Compilazione di un driver WDF per più versioni di Windows

  • Articolo

WDF ha sempre consentito di compilare un driver una sola volta e di usare il file binario risultante in più versioni di Windows, ma prima di Windows 10 versione 1803 (Redstone 4), questo era limitato a "build on older, run on newer". A partire da Windows 10 versione 1803, WDF aggiunge "build on newer, run on older", con il vantaggio aggiuntivo dell'esecuzione condizionale. Per concludere:

  • Esistente: i file binari compilati con le versioni precedenti del framework vengono eseguiti in versioni di Windows che includono versioni più recenti del framework, purché le versioni principali corrispondano. Ad esempio, un driver compilato con KMDF 1.9 (Windows 7) viene eseguito in un sistema di Windows 8 (KMDF 1.11). Nell'esempio il driver è limitato alle funzionalità di KMDF 1.9.
  • Aggiunta: a partire da KMDF versione 1.25 e UMDF versione 2.25 in Windows 10 versione 1803, è possibile compilare un driver con una versione più recente del framework e il file binario del driver risultante viene eseguito nelle versioni precedenti di Windows (almeno Windows 10 versione 1803). Inoltre, il driver può usare in modo condizionale funzionalità disponibili solo nelle versioni più recenti del framework.

Ciò significa che non solo il driver viene eseguito nelle versioni future di Windows, come sempre, ma viene eseguito anche nelle versioni precedenti, fino a Windows 10 versione 1803.

Per eseguire questa operazione sono necessari due passaggi: specificare le impostazioni di compilazione in Visual Studio ed eseguire un controllo di runtime prima di richiamare un'API o accedere a una struttura o a un campo che potrebbe essere presente o meno.

Nota: questa funzionalità è facoltativa e un driver deve abilitarlo solo per compilare un driver che usa la funzionalità WDF più recente, mentre rimane caricabile nelle versioni precedenti di Windows che non hanno la funzionalità WDF più recente.

Se non si imposta Version Minor (Target Version) o Version Minor (Minimum Required), il controllo delle versioni rimane invariato in precedenza.

Specifica del requisito minimo

Le nuove impostazioni di configurazione in Visual Studio sono:

  • Versione secondaria di KMDF (minima richiesta)
  • Versione secondaria di UMDF (minima richiesta)

In base a questa modifica, i nomi di due impostazioni esistenti sono stati aggiornati:

  • Versione secondaria di KMDF ->KMDF versione secondaria (versione di destinazione)
  • Versione secondaria di UMDF ->UMDF versione secondaria (versione di destinazione)

Se non si imposta Il requisito minimo, Visual Studio compila per versione di destinazione e versioni successive e non offre supporto di livello inferiore. Corrisponde al comportamento delle proprietà precedenti della versione secondaria .

Se si imposta Il requisito minimo, si applicano i requisiti seguenti:

  • 25 <= Minimo obbligatorio <= Versione di destinazione
  • In Proprietà di configurazione-Impostazioni> driver-Generale> impostare su _NT_TARGET_VERSION0x0A000005 (RS4) o versione successiva.

Verifica se la funzionalità è presente

Prima di ogni uso di un'API, di una struttura o di un membro che potrebbe essere presente o meno, è necessario chiamare una delle macro seguenti, definite in WdfFuncEnum.h:

BOOLEAN
WDF_IS_FUNCTION_AVAILABLE (
    FunctionName
    );

BOOLEAN
WDF_IS_STRUCTURE_AVAILABLE (
    StructName
    );

BOOLEAN
WDF_IS_FIELD_AVAILABLE (
    StructName,
    FieldName
    );

Si consideri l'esempio seguente. Quando WDF v29 viene rilasciato, aggiunge una nuova API: WdfSomeNewFeature. Se si imposta La versione di destinazione su 29 e Minima richiesta su 25, il driver risultante viene caricato in qualsiasi versione del framework da 25 a 29 (e versioni successive, purché la versione principale non cambi), chiama le API della versione 25 come prima e effettua il controllo seguente prima di ogni chiamata di qualsiasi API v29:

if (WDF_IS_FUNCTION_AVAILABLE(WdfSomeNewFeature)) {
    WdfSomeNewFeature();
}

Se non si esegue il controllo condizionale, è possibile che venga visualizzato quanto segue:

  • Se l'API restituisce NTSTATUS, la chiamata restituisce un codice di errore.
  • Se l'API restituisce un valore diverso da NTSTATUS:
    • KMDF: verifica dei bug del computer.
    • UMDF: il processo WudfHost si arresta in modo anomalo con un errore DriverStop.
  • Se Driver Verifier è abilitato, anche il driver si arresta in modo anomalo. Ciò consente di identificare il problema in un ambiente di test.
  • Danneggiamento della memoria invisibile all'utente (quando si accede a una struttura o a un campo).

Un arresto anomalo del driver contiene il nome del driver non riuscito, il nome del framework e l'indice API non riuscito. È possibile recuperare il nome dell'API cercando il valore di WDFFUNCENUM in WdfFuncEnum.h.

Per altre informazioni sulle proprietà di Visual Studio per WDF, vedere Proprietà delle impostazioni del modello di driver per i progetti driver.