PnP-Tests (Gerätegrundlagen)

Die PnP-Tests für Gerätegrundlagen zwingen einen Treiber, fast alle PnP-IRPs zu verarbeiten. Es gibt jedoch drei Bereiche, die speziell betont werden: Entfernung, Neugewichtung und unerwartete Entfernung. Der PnP-Test stellt einen Mechanismus bereit, um jede dieser Beiden separat zu testen oder sie alle zusammen zu testen (d. h. als Stresstest). Diese PnP-Tests werden mithilfe einer Kombination aus Benutzermodus-API-Aufrufen (über die Testanwendung) und Kernelmodus-API-Aufrufen (über einen oberen Filtertreiber) durchgeführt.

PNP-Tests

Die Plug and Play-Tests (PnP) führen verschiedene PnP-bezogene Codepfade in den Treiber- und Benutzermoduskomponenten aus. Die PnP-Tests sollten mit aktivierter Treiberüberprüfung auf dem Testcomputer ausgeführt werden. Informationen zum Aktivieren von Driver Verifier finden Sie unter Driver Verifier-Eigenschaften für Treiberprojekte.

Informationen zu den Tests zum Entfernen von Geräten

• PNP-Gerät-Entfernungstest
• PNP Gerät Entfernen Abbrechen Prüfung

Der Test zum Entfernen von Geräten umfasst IRP_MN_QUERY_REMOVE_DEVICE, IRP_MN_CANCEL_REMOVE_DEVICE und IRP_MN_REMOVE_DEVICE.

Der Test versucht, den oberen Filtertreiber auf dem Zielgerätestapel zu installieren. Dieser Versuch führt zu einem Query-Remove-IRP.

Wenn dieses Query-Remove-IRP fehlschlägt, startet der Test den Computer neu, um den Filtertreiber auf den Gerätestapel zu laden. Wenn der Widerspruch zur Entfernungsanforderung nicht vorliegt, wird der Gerätestapel entfernt und mit dem Filtertreiber auf dem Gerätestapel neu gestartet.

Der Test bewirkt, dass mithilfe von Setup-APIs ein IRP zum Entfernen von Abfragen an den Gerätestapel gesendet wird. Der Filtertreiber schlägt diese Remove-Anforderung fehl, sodass ein Cancel-Remove-IRP gesendet wird. Der Filtertreiber sichert zu, dass das Abbrechen-Entfernen erfolgreich war.

Als Nächstes ruft die Testanwendung das entsprechende Klasseninstallationsprogramm sowie alle registrierten Co-Installer auf, um das Gerät zu deaktivieren, zu aktivieren, zu entfernen oder neu aufzuzählen (dies testet die Verarbeitung von DIF_PROPERTYCHANGE mit DICS_DISABLE, DICS_ENABLE und DICS_PROPCHANGE). Beim Empfang von IRP_MN_REMOVE_DEVICE stellt der Filtertreiber sicher, dass die darunterliegenden Treiber ihn erfolgreich abgeschlossen haben.

Jeder dieser Schritte umfasst eine vorläufige Entfernungsanforderung. Wenn diese Anforderung vetoiert ist, wird das Gerät nicht entfernt. Sie können bei Bedarf eine Entfernungsanforderung vetoieren, z. B. beim Streamen von Video auf einer USB-Kamera oder wenn sich das Zielgerät im Start- oder Auslagerungspfad befindet. Denken Sie daran, dass es in der Regel nicht empfehlenswert ist, alle Entfernungsanforderungen abzulehnen. Das Scheitern aller Entfernungsanforderungen garantiert nicht, dass der Treiber keine Entfernung erhält, da nach einer unerwarteten Entfernung immer noch ein IRP zum Entfernen ausgegeben wird oder wenn jemand im Geräte-Stack ein Start-IRP fehlschlägt.

Über den Überraschungsentfernungstest

• Test zur überraschenden Entfernung von PNP-Geräten

Der Überraschungsentfernungstest umfasst IRP_MN_SURPRISE_REMOVAL, gefolgt von IRP_MN_REMOVE_DEVICE.

Wie bei den vorherigen Tests versucht die Testanwendung, dem Zielgerätestapel einen oberen Filter hinzuzufügen und dann den Stapel neu zu starten. Wenn dieser Versuch nicht erfolgreich ist, startet der Test den Computer neu.

Wenn sie von der Testanwendung ausgelöst wird, bewirkt der Filtertreiber, dass das System eine IRP_MN_SURPRISE_REMOVAL an den Gerätestapel sendet, gefolgt von einer IRP_MN_REMOVE_DEVICE. Der Filtertreiber bestätigt, dass beide dieser IRPs erfolgreich von untergeordneten Treibern abgeschlossen werden.

Nach Abschluss des unvorhergesehenen Entfernungstests wird das Gerät deinstalliert und erneut aufgezählt, wobei auch der Filtertreiber aus dem Stapel entfernt wird.

Über die Rebalance Tests

• Test für PNP-Stop (Rebalance)-Gerät
• PNP-Ausgleichsanfrage für neue Ressourcentests am Gerät
• PNP-Rebalance-Fehler-Gerät-neu-starten-Test
• PNP-Test zum Abbrechen der Stoppvorrichtung

Wie beim Entfernungstest versucht die Testanwendung, dem Zielgerätestapel einen oberen Filter hinzuzufügen und dann den Gerätestapel mithilfe von SetupDiCallClassInstaller mit DIF_PROPERTYCHANGE neu zu starten. Wenn dieser Versuch nicht erfolgreich ist (d. h., wenn jemand auf dem Zielgerätestapel den IRP für die Abfrage entfernen fehlgeschlagen ist), startet der Test den Computer neu, um die Neuausgewogenierung zu testen.

Je nachdem, welcher Rebalancetest Sie auswählen, treten die folgenden Ereignisse auf:

1. PNP Stop (Rebalance) Gerätetest Dieser Test initiiert eine Ausgleichsprozedur, die zu dem IRP_MN_QUERY_STOP_DEVICE PnP-IRP an den Gerätetreiber führt.

   Wenn ein Treiber im Stapel fehlschlägt, wird das Rebalance-Verfahren abgebrochen. Bitte beachten Sie, dass in Windows Vista Unterstützung für mehrstufige Neukalibrierung vorhanden ist. Wenn ein Neuausgleich auf einem nicht blattförmigen Geräteknoten gestartet wird, durchlaufen alle Gerätestapel, die in der Gerätestruktur mit diesem Geräteknoten als Stamm vorhanden sind, ebenfalls einen Neuausgleich. Und wenn eines der untergeordneten Gerätestapel den Abfragestopp fehlschlägt, wird das gesamte Rebalance-Verfahren abgebrochen. Die Treiber dürfen den Abfragestopp nicht ohne einen echten Grund ausführen. Wenn dieser Fehler auftritt, sendet der PnP-Manager den Abbruchstopp (IRP_MN_CANCEL_STOP) an alle Gerätestapel, die eine Abfrage für den Stopp erhalten hatten.

   Wenn alle Gerätestapel den Abfrage-Stopp bestehen, wird der Test mit der Neugewichtung fortgeführt und sendet die IRP_MN_QUERY_RESOURCE_REQUIREMENTS und IRP_MN_FILTER_RESOURCE_REQUIREMENTS IRPS, um die Ressourcenanforderungen der Geräte zu ermitteln.

   Nach diesem Punkt sind zwei unterschiedliche Pfade möglich, je nachdem, ob das Zielgerät Ressourcen verbraucht oder nicht:

   • Wenn das Gerät keine Ressourcen verbraucht, sendet der PnP-Manager selbst einen Abbruchstopp (IRP_MN_CANCEL_STOP_DEVICE) als Optimierung.

     Wenn das Gerät tatsächlich Ressourcen verbraucht, wird das Rebalance-Verfahren mit dem IRP_MN_STOP_DEVICE und IRP_MN_START_DEVICE IRP abgeschlossen.

   Bei dieser Option ändern sich die Ressourcen des Geräts nicht.

2. PNP Cancel Stop Device Test: Dieser Test initiiert eine Neuausgewogenierungsprozedur, aber der Filtertreiber schlägt absichtlich den Abfragestopp-IRP fehl. Die Abfolge der IRPs sieht aus wie IRP_MN_QUERY_STOP_DEVICE (das beim Hochfahren durch den Filtertreiber fehlschlägt, was zu einer Stornierung der Ausbalancierung führt) und IRP_MN_CANCEL_STOP_DEVICE.

   Bei dieser Option ändern sich die Ressourcen des Geräts nicht.

3. PNP Rebalance Request New Resources Device test Dieser Test initiiert eine Neuausgleichung und ändert auch die Ressourcenanforderung des Geräts, um die Wahrscheinlichkeit zu maximieren, dass dem Gerät tatsächlich neue Ressourcen zugeordnet werden. Diese Option hilft auch einem Gerät ohne Ressourcen, das vollständige Rebalance-Verfahren tatsächlich durchzugehen:

   1. Zunächst wird die einfache Neugewichtung gestartet, was zu folgenden IRPs führt:

      • IRP_MN_QUERY_STOP_DEVICE (vorausgesetzt, dieses IRP wird von allen Treibern übergeben. Der Test hat bereits den Fall abgedeckt, in dem dieses IRP fehlgeschlagen ist.)
      • IRP_MN_QUERY_RESOURCE_REQUIREMENTS
      • IRP_MN_FILTER_RESOURCE_REQUIREMENTS. Als Antwort auf dieses IRP ergreift der Filtertreiber während des Aufstiegs Maßnahmen, je nachdem, ob das Gerät Ressourcen verbraucht oder nicht.
        • Wenn das Gerät keine Ressourcenanforderung hat, weist der Filter eine gefälschte Ressource zu.
        • Wenn das Gerät über eine Ressourcenanforderung verfügt, versucht es, die Ressourcenanforderungsliste so neu zu strukturieren, dass die Wahrscheinlichkeit einer Änderung der aktuellen Zuordnung maximiert wird. Wenn ein Gerät beispielsweise zwischen 00 und FF 2 Byte Arbeitsspeicher benötigt und derzeit 3A-3B zugewiesen ist, ändern Sie so, dass die neue Ressourcenanforderung (in der Reihenfolge der Voreinstellung) wie 00-39 oder 3C-FF oder 3A-3B aussieht. Wenn die Geräteressourcenanforderungsliste über alternative Anforderungen verfügt, ändert sie ihre Reihenfolge, sodass die alternative Anforderung früher in der Liste enthalten ist.

   2. Jetzt sollte das Gerät immer den Rebalance-Vorgang abschließen.

      IRP_MN_STOP_DEVICE

      IRP_MN_START_DEVICE (Die neuen zugeordneten Ressourcen. Wenn gefälschte Anforderungen erstellt wurden, masken Sie die neuen Ressourcen von den tatsächlichen Treibern.)

4. PNP Rebalance Fail Restart Device Test Dieser Test löst eine Neugewichtung aus, aber wenn der Filtertreiber den Start nach der Neugewichtung erhält, schlägt er absichtlich fehl, was eine Überraschungsentfernungs-IRP und danach eine Entfernungs-IRP verursacht.

   Zunächst startet er das Rebalance-Verfahren und stellt sicher, dass der Treiber durch das Generieren gefälschter Ressourcenanforderungen für ein Gerät, das keine Ressourcen verbraucht, einen Stopp und einen Start erhält.

   • IRP_MN_QUERY_STOP_DEVICE (vorausgesetzt, dieser IRP wird von allen Treibern übergeben. Der Test behandelte bereits den Fall, in dem dieses IRP fehlgeschlagen ist.)
   • IRP_MN_QUERY_RESOURCE_REQUIREMENTS
   • IRP_MN_FILTER_RESOURCE_REQUIREMENTS (Wenn die tatsächlichen Ressourcenanforderungen null sind, wird eine gefälschte Ressourcenanforderung zugewiesen, sodass ein Stopp und ein Start vorhanden sind.)
   • IRP_MN_STOP_DEVICE
   • IRP_MN_START_DEVICE (Der Filter schlägt diesen IRP-Vorgang fehl, während er nach oben geht. Diese Aktion bewirkt, dass das Überraschungs-IRP entfernt wird.)
   • IRP_MN_SURPRISE_REMOVAL
   • IRP_MN_REMOVE

   Nach Abschluss des Rebalance-Tests wird das Gerät deinstalliert und erneut aufgezählt, wobei auch der Filtertreiber aus dem Stapel entfernt wird.

Gerätefehlercodes

Wenn beim Test eine Fehlermeldung angezeigt wird, die besagt, dass der Gerätestatus nicht OK ist, erfahren Sie mehr über den Gerätestatus über den Geräte-Manager. Eine Zusammenfassung der verschiedenen Gerätefehlercodes finden Sie unter Device Manager-Fehlermeldungen.

Debuggen von Installationsfehlern mithilfe der Setup-API-Protokolle

Die Setup-API-Protokolle (setupapi.app.log und setupapi.dev.log) enthalten möglicherweise nützliche Informationen zum Debuggen von Treiberinstallationsfehlern, die von diesem Test protokolliert werden. Die Setup-API-Protokolle finden Sie unter %windir%\inf\-Verzeichnis im Testsystem.

Um die Ausführlichkeit und potenzielle Nützlichkeit dieser Protokolle zu erhöhen, legen Sie den folgenden Registrierungsschlüssel auf 0x2000FFFF fest, bevor Sie den Test erneut installieren:

HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Setup\LogLevel

Zugehörige Themen

Wie testet man einen Treiber zur Laufzeit mit Visual Studio

Auswahl und Konfiguration der Gerätegrundlagen-Tests

Grundlagentests für Geräte

Bereitgestellte WDTF Simple I/O Plug-ins

So testen Sie einen Treiber zur Laufzeit von einer Eingabeaufforderung aus