MINIPORT_PNP_IRP Rückruffunktion (ndis.h)

Artikel
08/07/2023

Die MiniportPnpIrp-Funktion ermöglicht es einem Miniporttreiber, seine Plug & Play (PnP)-Ressourcen optional zu verwalten. MiniportPnpIrp selbst wird nie direkt von Miniporttreibern definiert. Stattdessen wird es entweder als MiniportFilterResourceRequirequirements oder MiniportStartDevice definiert.

Wenn diese Funktion als MiniportFilterResourceRequirements definiert ist, kann ein Miniporttreiber die Ressourcenanforderungen für ein Gerät ändern. Wenn diese Funktion als MiniportStartDevice definiert ist, ermöglicht diese Funktion dem Miniporttreiber das Entfernen von Ressourcen, die er im MiniportFilterResourceRequirements-Funktion .

Hinweis Sie müssen diese Funktion deklarieren, indem Sie entweder den MINIPORT_FILTER_RESOURCE_REQUIREMENTS-Typ oder den MINIPORT_START_DEVICE-Typ verwenden. Weitere Informationen finden Sie im folgenden Abschnitt Beispiele.

Syntax

MINIPORT_PNP_IRP MiniportPnpIrp;

NDIS_STATUS MiniportPnpIrp(
  [in] NDIS_HANDLE MiniportAddDeviceContext,
  [in] PIRP Irp
)
{...}

Parameter

[in] MiniportAddDeviceContext

Ein Handle für einen vom Treiber zugewiesenen Kontextbereich, den der Miniporttreiber bei NDIS in der MiniportAddDevice-Funktion registriert hat .

[in] Irp

Wenn diese Funktion als MiniportFilterResourceRequirements definiert ist, ist dieser Parameter ein Zeiger auf die IRP_MN_FILTER_RESOURCE_REQUIREMENTS , die der Treiber verarbeiten soll.

Wenn diese Funktion als MiniportStartDevice definiert ist, ist dieser Parameter ein Zeiger auf eine IRP_MN_START_DEVICE IRP.

Rückgabewert

MiniportPnpIrp gibt einen der folgenden Werte zurück:

Rückgabecode	Beschreibung
NDIS_STATUS_SUCCESS	Der Miniporttreiber hat die Anforderung zum Starten des Geräts erfolgreich verarbeitet.
NDIS_STATUS_RESOURCES	Der Miniporttreiber konnte die Anforderung des Startgeräts aufgrund geringer Ressourcen nicht verarbeiten.
NDIS_STATUS_FAILURE	MiniportFilterResourceRequirements ist aus anderen Gründen als unzureichenden Ressourcen fehlgeschlagen.

Hinweise

Hinweise zu MiniportFilterResourceRequirements

Die MiniportFilterResourceRequirements-Funktion ist eine optionale Funktion. Miniport-Treiber sollten diese Funktion registrieren, wenn sie MSI-X unterstützen und mindestens einer der folgenden Punkte zutrifft:

Der Treiber erfordert die Möglichkeit, die Interruptaffinität für jede MSI-X-Nachricht zu ändern.
Der Treiber registriert sich für zeilenbasierte Interrupts in der MiniportInitializeEx-Funktion .

Um MiniportFilterResourceRequirements zu registrieren, geben Sie den Einstiegspunkt im NDIS_MINIPORT_PNP_CHARACTERISTICS-Struktur .

NDIS ruft die MiniportFilterResourceRequirements-Funktion auf, nachdem NDIS eine empfangen hat. IRP_MN_FILTER_RESOURCE_REQUIREMENTS IRP für eine Netzwerkschnittstelle Karte (NIC). NDIS ruft MiniportFilterResourceRequirements auf, nachdem die zugrunde liegenden Funktionstreiber im Gerätestapel die Verarbeitung des IRP abgeschlossen haben.

Der Miniporttreiber muss darauf vorbereitet sein, IRP_MN_FILTER_RESOURCE_REQUIREMENTS von MiniportFilterResourceRequirements sofort zu verarbeiten, nachdem die MiniportAddDevice-Funktion NDIS_STATUS_SUCCESS zurückgegeben hat.

Ein Miniporttreiber kann eine Affinitätsrichtlinie für jede Ressource vom Typ CmResourceTypeInterrupt festlegen, die eine MSI-X-Nachricht beschreibt. Wenn eine Affinitätsrichtlinie eine bestimmte Gruppe von Prozessoren anfordert, legt der Miniporttreiber auch eine KAFFINITY-Maske am Interrupt.TargetedProcessors-Member in der IO_RESOURCE_DESCRIPTOR-Struktur fest.

Wenn ein NDIS 6.1- oder höher-Miniporttreiber mehr Nachrichtenunterbrechungsressourcen erfordert, kann er der Ressourcenliste weitere Nachrichtenunterbrechungsressourcen hinzufügen. Wenn das Betriebssystem mehr Nachrichtenunterbrechungsressourcen bereitstellen kann, empfängt der Miniportadapter beim Starten die hinzugefügten Nachrichtenunterbrechungsressourcen.

Jeder Nachrichtenunterbrechungsressource in der Liste wird eine Nachrichtennummer zugewiesen, die der Reihenfolge in der Ressourcenliste entspricht. Die Nachrichten werden von 0 bis zur Gesamtzahl der Nachrichtenunterbrechungsressourcen minus 1 nummeriert.

Um einer CPU zur Laufzeit einen MSI-X-Tabelleneintrag zuzuweisen, kann der Miniporttreiber den NdisMConfigMSIXTableEntry-Funktion .

Ein Miniporttreiber kann alle Ressourcen des Typs CmResourceTypeInterrupt entfernen, bei denen es sich um Nachrichtenunterbruchressourcen handelt. Der Treiber kann dann für zeilenbasierte Interrupts in der MiniportInitializeEx-Funktion registrieren. Wenn der Miniporttreiber diese Nachrichtenunterbrechungsressourcen nicht entfernt, schlägt das Betriebssystem fehl, wenn der Treiber versucht, den zeilenbasierten Interrupt in MiniportInitializeEx zu registrieren.

Um Arbeitsspeicher für eine neue Ressourcenanforderungenliste zuzuweisen, verwenden Sie die NdisAllocateMemoryWithTagPriority-Funktion . Der Miniporttreiber kann den Arbeitsspeicher für die alte Ressourcenanforderungsliste mit der NdisFreeMemory-Funktion freigeben. Der PnP-Manager gibt alle vom Treiber zugewiesenen Arbeitsspeicher frei, nachdem die zugehörige IRP abgeschlossen ist.

Miniport-Treiber sollten keine anderen Ressourcen ändern, z. B. CmResourceTypeMemory - und CmResourceTypePort-Ressourcen . Miniport-Treiber sollten vermeiden, der Ressourcenliste eine neue Ressource hinzuzufügen. Miniporttreiber können jedoch weitere Nachrichtenunterbrechungsressourcen hinzufügen. Wenn der Miniporttreiber weitere Nachrichtenunterbrechungsressourcen hinzufügt, darf der Treiber diese nicht aus der MiniportStartDevice-Funktion entfernen.

Wenn ein Miniporttreiber NDIS_STATUS_RESOURCES oder NDIS_STATUS_FAILURE von MiniportFilterResourceRequirements zurückgibt, verwendet NDIS die vom übergeordneten Bustreiber angegebenen Ressourcenanforderungen.

NDIS kann MiniportFilterResourceRequirements mehrmals aufrufen, bevor NDIS die MiniportRemoveDevice-Funktion aufruft . NDIS ruft MiniportFilterResourceRequirements jedoch nur auf, wenn sich ein Gerät im angehaltenen Zustand befindet.

NDIS ruft MiniportFilterResourceRequirements unter IRQL = PASSIVE_LEVEL auf.

MiniportFilterResourceRequirements-Beispiel

Um eine MiniportFilterResourceRequirements-Funktion zu definieren, müssen Sie zunächst eine Funktionsdeklaration bereitstellen, die den Typ der zu definierenden Funktion identifiziert. Windows bietet eine Reihe von Funktionstypen für Treiber. Das Deklarieren einer Funktion mithilfe der Funktionstypen hilft der Codeanalyse für Treiber, der statischen Treiberüberprüfung (Static Driver Verifier , SDV) und anderen Überprüfungstools, Fehler zu finden, und es ist eine Voraussetzung für das Schreiben von Treibern für das Windows-Betriebssystem.

Wenn Sie beispielsweise eine MiniportFilterResourceRequirements-Funktion mit dem Namen "MyFilterResourceRequirements" definieren möchten, verwenden Sie den typ MINIPORT_FILTER_RESOURCE_REQUIREMENTS , wie in diesem Codebeispiel gezeigt:

MINIPORT_FILTER_RESOURCE_REQUIREMENTS MyFilterResourceRequirements;

Implementieren Sie dann Ihre Funktion wie folgt:

_Use_decl_annotations_
NDIS_STATUS
 MyFilterResourceRequirements(
    NDIS_HANDLE  MiniportAddDeviceContext,
    PIRP  Irp
    )
  {...}

Der MINIPORT_FILTER_RESOURCE_REQUIREMENTS Funktionstyp ist in der Ndis.h-Headerdatei definiert. Um Fehler beim Ausführen der Codeanalysetools genauer zu identifizieren, müssen Sie der Funktionsdefinition die anmerkung Use_decl_annotations hinzufügen. Die Use_decl_annotations-Anmerkung stellt sicher, dass die Anmerkungen verwendet werden, die auf den MINIPORT_FILTER_RESOURCE_REQUIREMENTS Funktionstyp in der Headerdatei angewendet werden. Weitere Informationen zu den Anforderungen für Funktionsdeklarationen finden Sie unter Deklarieren von Funktionen mithilfe von Funktionsrollentypen für NDIS-Treiber.

Informationen zu Use_decl_annotations finden Sie unter Verhalten von Funktionen mit Anmerkungen.

MiniportStartDevice-Hinweise

MiniportStartDevice ist eine optionale Funktion. Miniporttreiber, die MSI-X unterstützen, können einen Einstiegspunkt für diese Funktion im NDIS_MINIPORT_PNP_CHARACTERISTICS-Struktur . Wenn NDIS eine Anforderung vom PnP-Manager (Plug & Play) zum Starten eines Geräts empfängt, ruft NDIS ggf. die MiniportStartDevice-Funktion auf. Wenn ein Miniporttreiber neue Ressourcen in der MiniportFilterResourceRequirements-Funktion sollte eine MiniportStartDevice-Funktion zum Entfernen der Ressourcen bereitstellen.

Wenn ein Miniporttreiber Ressourcen so ändert, dass ein zugrunde liegender Bustreiber die Ressourcen nicht erkennen kann, sollte der Treiber eine MiniportStartDevice-Funktion bereitstellen, um die Ressourcen zu entfernen. Ein zugrunde liegender Bustreiber schlägt möglicherweise eine Gerätestartanforderung fehl, wenn er keine Ressourcen erkennt, die ein Miniporttreiber in MiniportFilterResourceRequirements hinzugefügt hat. Wenn der Miniporttreiber Nachrichtenunterbrechungsressourcen hinzufügt, dürfen sie nicht aus MiniportStartDevice entfernt werden.

NDIS ruft MiniportStartDevice auf, bevor die Startgeräteanforderung an die zugrunde liegenden Treiber weitergeleitet wird. Wenn ein zugrunde liegender Treiber die Anforderung erfolgreich abschließt, ruft NDIS die MiniportInitializeEx-Funktion auf, um den Miniportadapter zu initialisieren.

NDIS ruft MiniportStartDevice unter IRQL = PASSIVE_LEVEL auf.

MiniportStartDevice-Beispiel

Um eine MiniportStartDevice-Funktion zu definieren, müssen Sie zunächst eine Funktionsdeklaration bereitstellen, die den Typ der funktion identifiziert, die Sie definieren. Windows bietet eine Reihe von Funktionstypen für Treiber. Das Deklarieren einer Funktion mithilfe der Funktionstypen hilft der Codeanalyse für Treiber, der statischen Treiberüberprüfung (Static Driver Verifier , SDV) und anderen Überprüfungstools, Fehler zu finden, und es ist eine Voraussetzung für das Schreiben von Treibern für das Windows-Betriebssystem.

Um beispielsweise eine MiniportStartDevice-Funktion mit dem Namen "MyStartDevice" zu definieren, verwenden Sie den typ MINIPORT_START_DEVICE , wie in diesem Codebeispiel gezeigt:

MINIPORT_START_DEVICE MyStartDevice;

Implementieren Sie dann Ihre Funktion wie folgt:

_Use_decl_annotations_
NDIS_STATUS
 MyStartDevice(
    NDIS_HANDLE  MiniportAddDeviceContext,
    PIRP  Irp
    )
  {...}

Der MINIPORT_START_DEVICE Funktionstyp ist in der Headerdatei Ndis.h definiert. Um Fehler beim Ausführen der Codeanalysetools genauer zu identifizieren, müssen Sie der Funktionsdefinition die anmerkung Use_decl_annotations hinzufügen. Die Use_decl_annotations-Anmerkung stellt sicher, dass die Anmerkungen verwendet werden, die auf den MINIPORT_START_DEVICE Funktionstyp in der Headerdatei angewendet werden. Weitere Informationen zu den Anforderungen für Funktionsdeklarationen finden Sie unter Deklarieren von Funktionen mithilfe von Funktionsrollentypen für NDIS-Treiber.

Informationen zu Use_decl_annotations finden Sie unter Verhalten von Funktionen mit Anmerkungen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Unterstützt in NDIS 6.0 und höher.
Zielplattform	Windows
Kopfzeile	ndis.h (einschließlich Ndis.h)
IRQL	PASSIVE_LEVEL