IRP_MN_DEVICE_USAGE_NOTIFICATION
Systemkomponenten senden diese IRP, um die Treiber für ein Gerät zu fragen, ob das Gerät eine spezielle Datei unterstützen kann. Spezielle Dateien umfassen Auslagerungsdateien, Dumpdateien und Ruhezustandsdateien. Wenn alle Treiber für das Gerät mit dem IRP erfolgreich sind, erstellt das System die spezielle Datei. Das System sendet auch diese IRP, um Treiber darüber zu informieren, dass eine spezielle Datei vom Gerät entfernt wurde.
Funktionstreiber müssen diese IRP verarbeiten, wenn ihr Gerät eine Auslagerungsdatei, eine Dumpdatei oder eine Ruhezustandsdatei enthalten kann. Filtertreiber müssen diese IRP verarbeiten, wenn der von ihnen gefilterte Funktionstreiber die IRP verarbeitet. Bustreiber müssen diese IRP für ihren Adapter oder Controller (Bus-FDO) und für ihre untergeordneten Geräte (untergeordnete PDOs) verarbeiten.
Wert
0x16
Hauptcode
Sendebedingungen
Das System sendet diese IRP, wenn es eine Auslagerungsdatei, eine Dumpdatei oder eine Ruhezustandsdatei erstellt oder löscht. Wenn ein Gerät über eine Energieverwaltungsbeziehung verfügt, die außerhalb der herkömmlichen Beziehung zwischen übergeordnetem und untergeordnetem Element liegt, kann der Treiber diese IRP senden, um Informationen zur Gerätenutzung an einen anderen Gerätestapel zu verteilen. Weitere Informationen finden Sie in der Beschreibung der PowerRelations-Anforderung in IRP_MN_QUERY_DEVICE_RELATIONS.
Systemkomponenten und Treiber senden diese IRP bei IRQL PASSIVE_LEVEL in einem beliebigen Threadkontext.
Eingabeparameter
Das Parameters.UsageNotification.InPath-Element der IO_STACK_LOCATION-Struktur ist ein BOOLEAN. Wenn dieser Parameter TRUE ist, erstellt das System eine Auslagerungs-, Absturzabbild- oder Ruhezustandsdatei auf dem Gerät. Wenn InPathFALSE ist, wurde eine solche Datei vom Gerät entfernt.
Parameters.UsageNotification.Type ist eine Enumeration, die die Art der Datei angibt. Dieser Parameter verfügt über einen der folgenden Werte: DeviceUsageTypePaging, DeviceUsageTypeDumpFile oder DeviceUsageTypeHibernation.
Ausgabeparameter
Keine
E/A-Statusblock
Treiber legen Irp-IoStatus.Status> auf STATUS_SUCCESS oder auf einen entsprechenden Fehler status fest.
Treiber ändern das Feld Irp-IoStatus.Information> nicht. Es bleibt bei null, wie durch die Komponente festgelegt, die den IRP sendet.
Vorgang
Ein Treiber verarbeitet diese IRP auf dem Weg des IRP nach unten im Gerätestapel und auf dem Weg des IRP zurück in den Stapel.
Ein Treiber antwortet auf diese IRP mit einer Prozedur wie der folgenden:
Wenn Parameters.UsageNotification.InPathTRUE ist, bestimmen Sie, ob das Gerät die spezielle Datei unterstützt.
Ein Treiber sollte auf die spezifischen Parameter.UsageNotification.Type(s) testen, die der Treiber unterstützen kann. In Zukunft können weitere Benachrichtigungstypen hinzugefügt werden.
Weitere Informationen finden Sie weiter unten, die die erforderlichen Aktionen zur Unterstützung der einzelnen Benachrichtigungstypen beschreiben.
Wenn Parameters.UsageNotification.InPathTRUE ist und der Treiber die spezielle Datei auf dem Gerät nicht unterstützen kann, muss der Treiber die IRP mit einem Fehler status abschließen.
Wenn das Gerät die spezielle Datei unterstützt:
Ergreifen Sie geeignete Aktionen, um zu reflektieren, dass das Gerät jetzt eine spezielle Datei enthält oder nicht mehr enthält.
Ein Treiber erhöht oder dekrementiert in der Regel einen Zähler. Wenn Parameters.UsageNotification.Type beispielsweise DeviceUsageTypePaging und Parameters.UsageNotification.InPathtrue ist, erhöhen Sie die Anzahl der Auslagerungsdateien auf dem Gerät. Bestimmte Treiberverteilungsroutinen müssen die Zähler überprüfen.
Ein Gerät, das eine spezielle Datei enthält, sollte nicht deaktiviert werden. Ein Treiber kann IoInvalidateDeviceState aufrufen und den PnP-Manager auffordern, die PnP-Gerätestatusinformationen des Geräts erneut abzufragen. Als Reaktion auf die resultierende IRP_MN_QUERY_PNP_DEVICE_STATE IRP sollte der Treiber das PNP_DEVICE_NOT_DISABLEABLE-Flag festlegen.
Wenn InPathFALSE ist, legt ein Treiber das DO_POWER_PAGABLE Bit in seinem Geräteobjekt für das Gerät fest.
Verteilen Sie die Gerätenutzungsinformationen an alle zugehörigen Geräte, die die Informationen benötigen.
Im Rahmen der Verarbeitung eines IRP_MN_DEVICE_USAGE_NOTIFICATION IRP muss ein Treiber die Informationen möglicherweise an einen oder mehrere andere Gerätestapel übergeben. Ein solcher Treiber erstellt eine neue IRP_MN_DEVICE_USAGE_NOTIFICATION IRP (oder IRPs) und sendet sie an den entsprechenden Gerätestapel (oder -stapel). Der Treiber muss auf den Abschluss aller IRP(s) der Gerätenutzungsbenachrichtigung warten, die er sendet, bevor der Treiber die Verarbeitung der empfangenen IRP für die Gerätenutzung beendet.
Die Identifizierung der zugehörigen Geräte ist geräte- und treiberspezifisch. In der Regel sendet ein Treiber den IRP an andere Treiber, an die er E/A-Anforderungen für die Datei senden würde. Wenn ein Bustreiber diese Anforderung für ein untergeordnetes Gerät verarbeitet, muss er eine Nutzungsbenachrichtigungs-IRP an den Gerätestapel für das übergeordnete Gerät senden.
Wenn ftdisk beispielsweise einen Stripesatz mit fünf Datenträgern ausführt, werden Pagingbenachrichtigungen an jeden dieser fünf Datenträger weitergegeben, da jedes dieser Geräte für die Verarbeitung von Auslagerungsdateivorgängen erforderlich sein kann.
Legen Sie in einer Funktion oder einem Filtertreiber eine IoCompletion-Routine fest.
Legen Sie in einem Funktions- oder Filtertreiber Irp-IoStatus.Status> auf STATUS_SUCCESS fest, richten Sie den nächsten Stapelspeicherort ein, und übergeben Sie den IRP mit IoCallDriver an den nächstniedrigen Treiber. Schließen Sie die IRP nicht ab.
Legen Sie in einem Bustreiber, der die IRP für ein untergeordnetes PDO verarbeitet, Irp-IoStatus.Status> fest, und schließen Sie die IRP (IoCompleteRequest) ab.
Während der IRP-Abschlussverarbeitung:
Wenn eine IoCompletion-Routine erkennt, dass bei einem niedrigeren Treiber ein Fehler beim IRP aufgetreten ist, muss die Funktion oder der Filtertreiber alle Vorgänge rückgängig machen, die als Reaktion auf die IRP ausgeführt wurden, und den Fehler weitergeben. Wenn der Funktions- oder Filtertreiber die Nutzungsinformationen an andere Gerätestapel weitergegeben hat, muss der Treiber eine andere Nutzungs-IRP an diese Stapel senden, um sie über den Fehler zu informieren.
Wenn status STATUS_SUCCESS und InPathTRUE ist, löschen Sie das DO_POWER_PAGABLE Bit.
Die allgemeinen Regeln für die Behandlung Plug & Play untergeordneten IRPs finden Sie unter Plug & Play.
Unterstützung von Paging-, Absturzabbild- und Ruhezustandsdateien auf einem Gerät
Wenn eine der speziellen Dateianzahlen eines Treibers nichtzero ist, muss der Treiber das Vorhandensein der speziellen Dateien auf seinem Gerät (oder einem untergeordneten Gerät) unterstützen.
Für eine DeviceUsageTypePaging-Datei, die auf ihrem Gerät erstellt wird, muss ein Treiber folgendes tun:
Sperren Sie Code im Arbeitsspeicher für die Routinen DispatchRead, DispatchWrite, DispatchDeviceControl und DispatchPower .
Löschen Sie das DO_POWER_PAGABLE Bit in seinem Geräteobjekt für das Gerät (auf dem Weg des IRP im Gerätestapel nach oben).
Fehler beim IRP_MN_QUERY_STOP_DEVICE und IRP_MN_QUERY_REMOVE_DEVICE Anforderungen für das Gerät.
Für eine DeviceUsageTypeDumpFile-Datei auf dem Gerät muss ein Treiber die folgenden Schritte ausführen:
Sperren Sie Code im Arbeitsspeicher für die Routinen DispatchRead, DispatchWrite, DispatchDeviceControl und DispatchPower .
Nehmen Sie das Gerät nicht aus dem D0-Zustand.
Registrieren Sie das Gerät nicht für die Leerlauferkennung (PoRegisterDeviceForIdleDetection). Wenn das Gerät bereits registriert ist, brechen Sie die Registrierung ab. Wenn der Treiber eine eigene Leerlauferkennung für das Gerät durchführt, setzen Sie diese Erkennung an.
Löschen Sie das DO_POWER_PAGABLE Bit in seinem Geräteobjekt für das Gerät (auf dem Weg des IRP im Gerätestapel nach oben).
Fehler beim IRP_MN_QUERY_STOP_DEVICE und IRP_MN_QUERY_REMOVE_DEVICE Anforderungen für das Gerät.
Für eine DeviceUsageTypeHibernation-Datei auf dem Gerät muss ein Treiber folgendes tun:
Sperren Sie Code im Arbeitsspeicher für die Routinen DispatchRead, DispatchWrite, DispatchDeviceControl und DispatchPower .
Stellen Sie sicher, dass sich das Gerät im Zustand D0 befindet, wenn der Treiber eine S4-Systemleistungs-IRP empfängt, die angibt, dass das System in den Ruhezustand versetzt wird.
Schalten Sie das Gerät nicht als Reaktion auf einen D3-IRP-Satz aus, der Teil einer S4-Ruhezustandsaktion ist. Weitere Informationen finden Sie unter System Power Actions .
Führen Sie nach Erhalt einer solchen D3-Set-Power-IRP alle Aufgaben aus, die erforderlich sind, um das Gerät in den D3-Zustand zu versetzen, außer das Ausschalten des Geräts und die Benachrichtigung des Energiemanagers (PoSetPowerState). Das Gerät muss die Stromversorgung beibehalten, bis die Ruhezustandsdatei geschrieben wurde.
Löschen Sie das DO_POWER_PAGABLE Bit in seinem Geräteobjekt für das Gerät (auf dem Weg des IRP im Gerätestapel nach oben).
Fehler beim IRP_MN_QUERY_STOP_DEVICE und IRP_MN_QUERY_REMOVE_DEVICE Anforderungen für das Gerät.
Weitere Informationen zu Gerätestromzuständen, Power IRPs und unterstützung der Energieverwaltung in Treibern finden Sie unter Energieverwaltung .
Senden dieses IRP
Ein Treiber kann eine IRP_MN_DEVICE_USAGE_INFORMATION IRP senden, aber nur, um Informationen zur Gerätenutzung an einen anderen Gerätestapel zu verteilen. Ein Treiber ist nie die erste Quelle für Gerätenutzungsinformationen.
Anforderungen
Header |
Wdm.h (einschließlich Wdm.h, Ntddk.h oder Ntifs.h) |