Angeben von WDF-Anweisungen in INF-Dateien

  • Artikel

Eine INF-Datei, die einen WDF-Treiber installiert, muss zwei WDF-spezifische Abschnitte enthalten:

  • [DDInstall.wdf] Abschnitt für jeden Abschnitt [DDInstall]
  • Abschnitt [wdf-service-install] mit abschnittsname, der in einer KmdfService- oder UmdfService-Direktive in [DDInstall.wdf] angegeben ist

Diese Abschnitte enthalten WDF-spezifische Anweisungen. UMDF-spezifische Anweisungen beginnen mit dem UMDF-Präfix, und KMDF-spezifische Anweisungen beginnen mit dem KMDF-Präfix.

Das folgende Codebeispiel zeigt UMDF-spezifische Anweisungen:

[ECHO_Device.NT.Wdf]
UmdfService = Echo, Echo_service_wdfsect
UmdfServiceOrder = Echo

[Echo_service_wdfsect]
UmdfLibraryVersion = $UMDFVERSION$
ServiceBinary = %13%\echo.dll

Das folgende Codebeispiel zeigt KMDF-spezifische Anweisungen:

[ECHO_Device.NT.Wdf]
KmdfService = Echo, Echo_service_wdfsect

[Echo_service_wdfsect]
KmdfLibraryVersion = $KMDFVERSION$

[UMDF-Anweisungen für DDInstall.WDF-Abschnitte]

Es folgt ein Codebeispiel. Jede UMDF-spezifische Direktive im Abschnitt DDInstall.WDF wird unten beschrieben.

[ECHO_Device.NT.Wdf]
UmdfService = Echo, Echo_service_wdfsect
UmdfServiceOrder = Echo

UmdfService

`UmdfService = <serviceName>, <sectionName>

Ordnet einen UMDF-Treiber einem Abschnitt [wdf-service-install] zu, der Informationen enthält, die zum Installieren des UMDF-Treibers erforderlich sind. Der ServiceName-Parameter gibt den UMDF-Treiber an und ist auf maximal 31 Zeichen lang. Der sectionName-Parameter verweist auf den Abschnitt [wdf-service-install]. Eine gültige INF-Datei erfordert in der Regel mindestens eine UmdfService-Direktive . Wenn jedoch ein UMDF-Treiber Teil des Betriebssystems ist, ist keine UmdfService-Direktive für den UMDF-Treiber erforderlich. Daher verfügt eine gültige INF-Datei möglicherweise über keine UmdfService-Direktiven , obwohl die meisten INF-Dateien eine UmdfService-Direktive für jeden UMDF-Treiber haben.

UmdfHostProcessSharing

Diese Direktive wird in UMDF-Versionen 1.11 und höher unterstützt.

UmdfHostProcessSharing = <ProcessSharingDisabled | ProcessSharingEnabled>

Bestimmt, ob ein Gerätestapel in einem freigegebenen Prozesspool (ProcessSharingEnabled) oder einem eigenen individuellen Prozess (ProcessSharingDisabled) platziert wird. Der Standardwert ist ProcessSharingEnabled. Diese Anweisung ist gerätespezifisch und nicht treiberspezifisch.

Weitere Informationen zum Gerätepooling finden Sie unter Verwenden von Gerätepooling in UMDF-Treibern.

UmdfDirectHardwareAccess

Diese Direktive wird in UMDF-Versionen 1.11 und höher unterstützt.

UmdfDirectHardwareAccess = <AllowDirectHardwareAccess | RejectDirectHardwareAccess>

Gibt an, ob das Framework dem Treiber die Verwendung von Features für den direkten Hardwarezugriff ermöglichen soll, z. B. zugriff auf Geräteregister und -ports, Überprüfen der dem Gerät zugewiesenen Hardwareressourcen, Behandeln von Hardwareunterbrechungen oder Abrufen von Verbindungsressourcen.

Wenn UmdfDirectHardwareAccess auf AllowDirectHardwareAccess festgelegt ist, ermöglicht das Framework dem Treiber die Verwendung von UMDF-Schnittstellen, die direkten Hardwarezugriff ausführen.

Sie müssen AllowDirectHardwareAccess angeben, wenn Ihr UMDF-Treiber auf Hardwareressourcen wie Register oder Ports, Interrupts, GPIO-Pins (Universelle E/A ) oder serielle Busverbindungen wie I2C, SPI und seriellen Port zugreift. Ihr Treiber empfängt alle diese Ressourcen über die Parameter ResourcesRaw und ResourcesTranslated seiner EvtDevicePrepareHardware-Rückruffunktion .

Hinweis

Ab UMDF Version 2.15 muss ein UMDF-Treiber keine AllowDirectHardwareAccess angeben, um Hardwareressourcenlisten in seiner EvtDevicePrepareHardware-Rückrufroutine zu empfangen. Wenn Sie es nicht angeben, verfügt der Treiber nicht über die Zugriffsrechte für die Verwendung dieser Ressourcen, mit einer Ausnahme: Wenn dem Gerät eine oder mehrere Verbindungsressourcen (CmResourceTypeConnection) und eine oder mehrere Interruptressourcen (CmResourceTypeInterrupt) zugewiesen sind, kann der Treiber WdfInterruptCreate über seine EvtDevicePrepareHardware-Rückrufroutine (aber nicht über EvtDriverDeviceAdd) aufrufen.

Informationen zum Verbinden eines UMDF-Treibers mit bestimmten Ressourcentypen finden Sie unter:

Wenn UmdfDirectHardwareAccess auf RejectDirectHardwareAccess festgelegt ist, erlaubt das Framework Treibern nicht die Verwendung von Features für direkten Hardwarezugriff. Der Standardwert ist RejectDirectHardwareAccess.

Informationen dazu, wie ein UMDF-Treiber auf Hardwareressourcen zugreift, finden Sie unter Suchen und Zuordnen von Hardwareressourcen.

UmdfHostPriority

Diese Direktive wird in UMDF-Versionen 2.15 und höher unterstützt.

UmdfHostPriority = <PriorityHigh>

Ein UMDF HID-Clienttreiber kann UmdfHostPriority auf PriorityHigh festlegen, um die Threadpriorität zu erhöhen. Diese Anweisung sollte nur für Touch- oder Eingabetreiber verwendet werden, die für die Antwortzeit des Benutzers sensibel sind. Wenn ein Treiber PriorityHigh angibt, platziert das System ihn zusammen mit anderen Treibern mit ähnlicher Priorität in einem separaten Gerätepool. Da der zusätzliche Gerätepool mehr Arbeitsspeicher benötigt, sollten Sie diese Einstellung mit Vorsicht verwenden. Weitere Informationen zum Gerätepooling finden Sie unter Verwenden von Gerätepooling in UMDF-Treibern.

UmdfRegisterAccessMode

Diese Direktive wird in UMDF-Versionen 1.11 und höher unterstützt.

UmdfRegisterAccessMode = <RegisterAccessUsingSystemCall | RegisterAccessUsingUserModeMapping>

Gibt an, ob das Framework die Register dem Adressraum im Benutzermodus zuordnen soll (sodass kein Systemaufruf am Zugriff auf Register beteiligt ist) oder ob ein Systemaufruf für den Zugriff auf Register verwendet werden soll.

Wenn UmdfRegisterAccessMode auf RegisterAccessUsingSystemCall festgelegt ist, verwendet das Framework einen Systemaufruf, um auf Register zuzugreifen.

Wenn UmdfRegisterAccessMode auf RegisterAccessUsingUserModeMapping festgelegt ist, ordnet das Framework die Register dem Adressraum im Benutzermodus zu, sodass kein Systemaufruf für den Zugriff auf Register erforderlich ist. Der Standardwert ist RegisterAccessUsingSystemCall.

UmdfServiceOrder

UmdfServiceOrder = <serviceName1> [, <serviceName2> ...]

Listet die Reihenfolge auf, in der das Co-Installer die UMDF-Treiber auf dem Gerätestapel installiert. Auch wenn das Co-Installationsprogramm nur einen UMDF-Treiber auf dem Gerätestapel installiert, muss die INF-Datei diese Anweisung enthalten. Die serviceNameXx-Parameter entsprechen den serviceName-Parametern für jede UmdfService-Direktive . Da die UMDF-Treiber dem Gerätestapel in der Reihenfolge hinzugefügt werden, in der sie aufgelistet werden, gibt der erste Parameter den niedrigsten UMDF-Treiber im Gerätestapel an.

Um sicherzustellen, dass ein UMDF-Co-Installer das Gerät installiert, muss nur eine UmdfServiceOrder-Direktive in einem bestimmten WDF-spezifischen DDInstall-Abschnitt vorhanden sein. Das heißt, die UmdfServiceOrder-Direktive kann nicht mit den Include - und Needs-Anweisungen importiert werden.

UmdfImpersonationLevel

UmdfImpersonationLevel = <level>

Informiert das Framework über die maximale Identitätswechselebene, die der UMDF-Treiber haben kann. Eine UmdfImpersonationLevel-Direktive ist optional. wenn keine Identitätswechselebene angegeben wird, ist die Standardeinstellung Identifikation. Wenn eine Anwendung ein Dateihandle öffnet, kann die Anwendung dem Treiber eine höhere Identitätswechselebene gewähren. Der Treiber kann jedoch nicht die IWDFIoRequest::Impersonate-Methode aufrufen, um eine Identitätswechselebene anzufordern, die größer als die von UmdfImpersonationLevel festgelegte Ebene ist. Die möglichen Werte für diese Direktive sind:

  • Anonym

  • Identifikation

  • Identitätswechsel

  • Delegierung

Diese Werte entsprechen den Werten, die in der SECURITY_IMPERSONATION_LEVEL-Enumeration angegeben werden.

UmdfMethodNeitherAction

UmdfMethodNeitherAction = <Copy | Reject>

Gibt an, ob das Framework die E/A-Anforderungen eines Geräts akzeptiert (Kopieren) oder ablehnt (Ablehnen), wenn die Anforderungsobjekte E/A-Steuerungscodes enthalten, die die METHOD_NEITHER Pufferzugriffsmethode angeben. Eine UmdfMethodNeitherAction-Direktive ist optional. Wenn die Direktive nicht angegeben ist, lautet der Standardwert Ablehnen.

Weitere Informationen zur Unterstützung der METHOD_NEITHER Pufferzugriffsmethode in UMDF-basierten Treibern finden Sie unter Verwenden weder gepufferter E/A noch direkter E/A in UMDF-Treibern.

UmdfDispatcher

UmdfDispatcher = <FileHandle | WinUsb | NativeUSB>

Informiert das Framework, wo E/A gesendet werden soll, nachdem die E/A den Benutzermodusteil des Gerätestapels durchlaufen hat. Standardmäßig werden E/A an den Reflektor (WUDFRd.sys) gesendet. Durch Festlegen von UmdfDispatcher auf WinUsb weist der Treiber UMDF an, E/A an die WinUsb-Architektur zu senden. Ab UMDF 2.15 führt die Angabe von NativeUSB dazu, dass der Reflektor USB-E/A verarbeitet.

  • Wenn ein Treiber im Stapel ein dateihandlesbasiertes Ziel verwendet, legen Sie diese Anweisung auf FileHandle fest.
  • Wenn der Treiber UMDF 2.15 oder höher verwendet und USB-E/A-Ziele verwendet, legen Sie diese Direktive auf NativeUSB fest.
  • Wenn der Treiber pre-UMDF 2.15 ist und USB-E/A-Ziele verwendet, legen Sie diese Direktive auf WinUsb fest.

Eine UmdfDispatcher-Direktive ist optional.

Das folgende Codebeispiel zeigt die UmdfDispatcher-Direktive in einem WDF-spezifischen DDInstall-Abschnitt .

[Xxx_Install.Wdf]
UmdfDispatcher=NativeUSB

UmdfKernelModeClientPolicy

Diese Direktive wird in UMDF-Versionen 1.9 und höher unterstützt.

UmdfKernelModeClientPolicy = <AllowKernelModeClients | RejectKernelModeClients>

Informationen zum Laden von Kernelmodustreibern über einem Benutzermodustreiber in früheren UMDF-Versionen finden Sie unter Kernelmodusclientunterstützung in früheren UMDF-Versionen.

Gibt an, ob das Framework dem Treiber erlauben soll, E/A-Anforderungen von Kernelmodustreibern zu empfangen.

Wenn UmdfKernelModeClientPolicy auf AllowKernelModeClients festgelegt ist, ermöglicht das Framework das Laden von Kernelmodustreibern über einem Benutzermodustreiber und übermittelt E/A-Anforderungen von Kernelmodustreibern an den Benutzermodustreiber.

Wenn UmdfKernelModeClientPolicy auf RejectKernelModeClients festgelegt ist, lässt das Framework das Laden von Kernelmodustreibern über einem Benutzermodustreiber nicht zu und übermittelt keine E/A-Anforderungen von Kernelmodustreibern an den Benutzermodustreiber. Wenn die INF-Datei eines Treibers diese Anweisung nicht enthält, lautet der Standardwert RejectKernelModeClients. Weitere Informationen finden Sie unter Unterstützen von Kernelmodusclients.

UmdfFileObjectPolicy

Diese Direktive wird in UMDF-Versionen 1.11 und höher unterstützt.

UmdfFileObjectPolicy = <RejectNullAndUnknownFileObjects | AllowNullAndUnknownFileObjects>

Gibt an, ob das Framework die Verarbeitung von E/A-Anforderungen (IWDFIoRequest) zulassen soll, die entweder nicht einem Dateiobjekt (IWDFFile) zugeordnet oder einem unbekannten Dateiobjekt zugeordnet sind (ein Dateiobjekt, für das ein Treiber zuvor keine Erstellungsanforderung gesehen hat).

Wenn UmdfFileObjectPolicy auf RejectNullAndUnknownFileObjects festgelegt ist, lässt das Framework keine Verarbeitung von Anforderungen zu, die einem NULL- oder unbekannten Dateiobjekt zugeordnet sind.

Wenn UmdfFileObjectPolicy auf AllowNullAndUnknownFileObjects festgelegt ist, lässt das Framework die Verarbeitung von Anforderungen zu, die einem NULL- oder unbekannten Dateiobjekt zugeordnet sind.

Der Standardwert ist RejectNullAndUnknownFileObjects.

UmdfFsContextUsePolicy

Diese Direktive wird in UMDF-Versionen 1.11 und höher unterstützt.

UmdfFsContextUsePolicy = <CanUseFsContext | CanUseFsContext2 | CannotUseFsContexts>

Gibt an, ob das Framework interne Informationen in bestimmten Kontextelementen eines WDM-Dateiobjekts speichern kann. Wenn ein Kernelmodustreiber im selben Stapel ein bestimmtes Element des Dateiobjekts verwendet, können Sie diese Direktive verwenden, um anzufordern, dass das Framework nicht denselben Speicherort verwendet.

Wenn UmdfFsContextUsePolicy auf CanUseFsContext festgelegt ist, speichert das Framework Informationen im FsContext-Member des WDM-Dateiobjekts.

Wenn UmdfFsContextUsePolicy auf CanUseFsContext2 festgelegt ist, speichert das Framework Informationen im FsContext2-Member des WDM-Dateiobjekts.

Wenn UmdfFsContextUsePolicy auf CannotUseFsContexts festgelegt ist, verwendet das Framework weder FsContext noch FsContext2.

Der Standardwert ist CanUseFsContext.

[UMDF-Anweisungen für den Abschnitt wdf-service-install]

Es folgt ein Codebeispiel. Jede UMDF-spezifische Direktive im Abschnitt [wdf-service-install] wird unten beschrieben. Der Abschnittsname wird in einer UmdfService-Direktive im Abschnitt [DDInstall.wdf] angegeben.

[Echo_service_wdfsect]
UmdfLibraryVersion = $UMDFVERSION$
ServiceBinary = %13%\echo.dll

UmdfLibraryVersion

UmdfLibraryVersion = <Version>

Informiert den Co-Installer über die Versionsnummer des Frameworks, das der UMDF-Treiber verwendet. Das Format der Versionszeichenfolge ist <Haupt>.<nebensächtlich>.<dienst>. Wenn Treiber auf dem Gerätestapel mehr als eine Version des Frameworks verwenden, kopiert die INF-Datei mehrere Co-Installer - eins für jede Frameworkversion - an den gleichen Speicherort auf dem Festplattenlaufwerk. Die INF-Datei fügt dem Registrierungswert CoInstallers32 jedoch nur den Co-Installer der höchsten Version hinzu. Weitere Informationen zum Kopieren von Co-Installern finden Sie unter Verwenden des UMDF-Co-Installers.

Der Co-Installer überprüft die Versionszeichenfolge und verwendet sie, um den versionsspezifischen Co-Installer für den UMDF-Treiber zu suchen. Das Co-Installer extrahiert dann das Framework aus dem versionsspezifischen Co-Installer.

ServiceBinary

ServiceBinary = <binarypath>

Informiert UMDF darüber, wo die UMDF-Treiberbinärdatei auf der Festplatte platziert werden soll.

UMDF-Treiber sollten in das Verzeichnis kopiert und aus diesem Windows\System32\Drivers\UMDF ausgeführt werden.

DriverCLSID

Hinweis Diese Direktive wird nur in UMDF 1.x unterstützt, das veraltet ist. Weitere Informationen finden Sie im UMDF 1.x-Entwurfshandbuch.

DriverCLSID = <{CLSID}>

Informiert UMDF über den Klassenbezeichner (CLSID) des UMDF-Treibers. Wenn UMDF den UMDF-Treiber lädt, verwendet der UMDF-Host die CLSID des UMDF-Treibers, um eine instance der IDriverEntry-Schnittstelle des UMDF-Treibers zu erstellen.

UmdfExtensions

UmdfExtensions = <cxServiceName>

Erforderlich für Treiber, die mit von Microsoft bereitgestellten Klassenerweiterungstreibern kommunizieren. Der cxServiceName-Parameter entspricht dem Dienst, der der Binärdatei des Klassenerweiterungstreibers zugeordnet ist.

Dienstnamen für die Klassenerweiterungstreiber können sich als Unterschlüssel unter dem folgenden Registrierungsschlüssel befinden: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services

[KMDF-Anweisungen für DDInstall.WDF-Abschnitte]

Es folgt ein Codebeispiel. Jede KMDF-spezifische Direktive im Abschnitt DDInstall.WDF wird unten beschrieben.

[ECHO_Device.NT.Wdf]
KmdfService = Echo, Echo_service_wdfsect

KmdfService

KmdfService = <serviceName>, <sectionName>

Ordnet einen KMDF-Treiber einem Abschnitt [wdf-service-install] zu, der Informationen enthält, die zum Installieren des KMDF-Treibers erforderlich sind. Der serviceName-Parameter gibt den KMDF-Treiber an und ist auf maximal 31 Zeichen länge beschränkt. Der sectionName-Parameter verweist auf den Abschnitt [wdf-service-install]. Für eine gültige INF-Datei ist in der Regel mindestens eine KmdfService-Direktive erforderlich. Wenn jedoch ein KMDF-Treiber Teil des Betriebssystems ist, ist keine KmdfService-Anweisung für den KMDF-Treiber erforderlich. Daher verfügt eine gültige INF-Datei möglicherweise über keine KmdfService-Direktiven , obwohl die meisten INF-Dateien eine KmdfService-Direktive für jeden KMDF-Treiber aufweisen.

[KMDF-Anweisungen für den Abschnitt wdf-service-install]

Es folgt ein Codebeispiel. Jede KMDF-spezifische Direktive im Abschnitt [wdf-service-install] wird unten beschrieben. Der Abschnittsname stammt aus der KmdfService-Direktive im Abschnitt DDInstall.wdf.

[Echo_service_wdfsect]
KmdfLibraryVersion = $KMDFVERSION$

KmdfLibraryVersion

KmdfLibraryVersion = <version>

Das Format der Versionszeichenfolge ist major.minor. Normalerweise sollten Sie angeben $KMDFVERSION$ , und dann ersetzt der WDK-Buildprozess ihn durch die richtige Versionsnummer.