MINIPORT_PNP_IRP Rückruffunktion (ndis.h)

Artikel
02/07/2025

Mit der MiniportPnpIrp--Funktion kann ein Miniporttreiber optional seine Plug and Play-Ressourcen (PnP) verwalten. MiniportPnpIrp selbst wird nie von Miniporttreibern direkt definiert. Stattdessen wird sie entweder als MiniportFilterResourceRequirements oder MiniportStartDevicedefiniert.

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

Hinweis Sie müssen diese Funktion entweder mit dem typ MINIPORT_FILTER_RESOURCE_REQUIREMENTS oder dem MINIPORT_START_DEVICE typ deklarieren. 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 im 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 ein 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 des Startgeräts erfolgreich verarbeitet.
NDIS_STATUS_RESOURCES	Der Miniporttreiber konnte die Anforderung des Startgeräts aufgrund geringer Ressourcen nicht verarbeiten.
NDIS_STATUS_FAILURE	MiniportFilterResourceRequirequirements aus anderen Gründen als unzureichenden Ressourcen fehlgeschlagen.

Bemerkungen

MiniportFilterResourceRequirequirements Hinweise

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

Der Treiber erfordert die Möglichkeit, die Unterbrechungsaffinität für jede MSI-X Nachricht zu ändern.
Der Treiber registriert sich für zeilenbasierte Unterbrechungen im MiniportInitializeEx Funktion.

Um MiniportFilterResourceRequirementszu registrieren, geben Sie den Einstiegspunkt in der NDIS_MINIPORT_PNP_CHARACTERISTICS Struktur.

NDIS ruft die MiniportFilterResourceRequirements Funktion auf, nachdem NDIS eine IRP_MN_FILTER_RESOURCE_REQUIREMENTS IRP für eine Netzwerkschnittstellenkarte (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 MiniportFilterResourceRequire ments direkt nach dem MiniportAddDevice- Funktion NDIS_STATUS_SUCCESS zurückzugeben.

Ein Miniporttreiber kann eine Affinitätsrichtlinie für jede Ressource vom Typ CmResourceTypeInterrupt festlegen, die eine MSI-X Nachricht beschreibt. Wenn eine Affinitätsrichtlinie die Zielbestimmung für eine bestimmte Gruppe von Prozessoren anfordert, legt der Miniporttreiber auch ein KAFFINITY- Mask an der 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 die hinzugefügten Nachrichtenunterbruchressourcen, wenn er gestartet wird.

Jeder Nachricht, die die Ressource in der Liste unterbricht, wird eine Nachrichtennummer zugewiesen, die der Reihenfolge entspricht, die sie in der Ressourcenliste hat. Die Nachrichten werden von 0 bis zur Gesamtzahl der Nachrichtenunterbruchressourcen minus 1 nummeriert.

Zum Zuweisen eines MSI-X Tabelleneintrags zu einer CPU zur Laufzeit kann der Miniporttreiber die NdisMConfigMSIXTableEntry Funktion.

Ein Miniporttreiber kann alle Ressourcen vom Typ CmResourceTypeInterrupt entfernen, die Nachrichtenunterbruchressourcen sind. Der Treiber kann dann für zeilenbasierte Unterbrechungen in der MiniportInitializeEx--Funktion registrieren. Wenn der Miniport-Treiber diese Meldung nicht entfernt, unterbrechen Ressourcen, schlägt das Betriebssystem fehl, wenn der Treiber versucht, einen zeilenbasierten Interrupt in MiniportInitializeExzu registrieren.

Verwenden Sie zum Zuweisen von Arbeitsspeicher für eine neue Ressourcenanforderungen-Liste die NdisAllocateMemoryWithTagPriority Funktion. Der Miniporttreiber kann den Speicher für die alte Ressourcenanforderungsliste mit der funktion NdisFreeMemory freigeben. Der PnP-Manager gibt alle vom Treiber zugewiesenen Speicher frei, nachdem das zugeordnete IRP abgeschlossen ist.

Miniport-Treiber sollten keine anderen Ressourcen ändern, z. B. CmResourceTypeMemory und CmResourceTypePort Ressourcen. Miniporttreiber 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 sie nicht aus der MiniportStartDevice--Funktion entfernen.

Wenn ein Miniporttreiber NDIS_STATUS_RESOURCES oder NDIS_STATUS_FAILURE von MiniportFilterResourceRequirequirementszurückgibt, verwendet NDIS die Ressourcenanforderungen, wie vom übergeordneten Bustreiber angegeben.

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

NDIS ruft MiniportFilterResourceRequirequirements bei IRQL = PASSIVE_LEVEL auf.

MiniportFilterResourceRequirequirements (Beispiel)

Um eine MiniportFilterResourceRequirements Funktion zu definieren, müssen Sie zuerst eine Funktionsdeklaration bereitstellen, die den Typ der Funktion identifiziert, die Sie definieren. Windows stellt eine Reihe von Funktionstypen für Treiber bereit. Durch das Deklarieren einer Funktion mithilfe der Funktionstypen können Codeanalyse für Treiber, statische Treiberüberprüfung (SDV) und andere Überprüfungstools Fehler finden, und es ist eine Anforderung zum Schreiben von Treibern für das Windows-Betriebssystem.

Wenn Sie beispielsweise eine MiniportFilterResourceRequirements Funktion mit dem Namen "MyFilterResourceRequirements" definieren möchten, verwenden Sie den MINIPORT_FILTER_RESOURCE_REQUIREMENTS Typ 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 wird in der Ndis.h-Headerdatei definiert. Um Fehler genauer zu identifizieren, wenn Sie die Codeanalysetools ausführen, müssen Sie der Funktionsdefinition die Use_decl_annotations Anmerkung hinzufügen. Die Use_decl_annotations Anmerkung stellt sicher, dass die Anmerkungen, die auf den Funktionstyp MINIPORT_FILTER_RESOURCE_REQUIREMENTS in der Headerdatei angewendet werden, verwendet 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_annotationsfinden Sie unter Annotating Function Behavior.

MiniportStartDevice Hinweise

MiniportStartDevice ist eine optionale Funktion. Miniporttreiber, die MSI-X unterstützen, können einen Einstiegspunkt für diese Funktion in der NDIS_MINIPORT_PNP_CHARACTERISTICS Struktur. Wenn NDIS eine Anforderung vom Plug and Play-Manager (PnP) empfängt, um ein Gerät zu starten, ruft NDIS ggf. die MiniportStartDevice-Funktion auf. Wenn ein Miniporttreiber neue Ressourcen in der MiniportFilterResourceRequirements Funktion sollte eine MiniportStartDevice--Funktion bereitgestellt werden, um die Ressourcen zu entfernen.

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 Startgeräteanforderung fehl, wenn nicht erkannt wird, dass ein Miniporttreiber in MiniportFilterResourceRequirementshinzugefügt wurde. Wenn der Miniporttreiber Nachrichtenunterbrechungsressourcen hinzufügt, darf er sie nicht aus MiniportStartDeviceentfernen.

NDIS ruft MiniportStartDevice auf, bevor die Anforderung des Startgeräts an die zugrunde liegenden Treiber weitergeleitet wird. Wenn ein zugrunde liegender Treiber die Anforderung erfolgreich abgeschlossen hat, ruft NDIS die MiniportInitializeEx--Funktion auf, um den Miniportadapter zu initialisieren.

NDIS ruft MiniportStartDevice bei IRQL = PASSIVE_LEVEL auf.

MiniportStartDevice-Beispiel

Um eine MiniportStartDevice--Funktion zu definieren, müssen Sie zuerst eine Funktionsdeklaration bereitstellen, die den Typ der Funktion identifiziert, die Sie definieren. Windows stellt eine Reihe von Funktionstypen für Treiber bereit. Durch das Deklarieren einer Funktion mithilfe der Funktionstypen können Codeanalyse für Treiber, statische Treiberüberprüfung (SDV) und andere Überprüfungstools Fehler finden, und es ist eine Anforderung zum Schreiben von Treibern für das Windows-Betriebssystem.

Um beispielsweise eine MiniportStartDevice--Funktion zu definieren, die den Namen "MyStartDevice" hat, verwenden Sie den MINIPORT_START_DEVICE Typ, 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 wird in der Ndis.h-Headerdatei definiert. Um Fehler genauer zu identifizieren, wenn Sie die Codeanalysetools ausführen, müssen Sie der Funktionsdefinition die Use_decl_annotations Anmerkung hinzufügen. Die Use_decl_annotations Anmerkung stellt sicher, dass die Anmerkungen, die auf den Funktionstyp MINIPORT_START_DEVICE in der Headerdatei angewendet werden, verwendet 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_annotationsfinden Sie unter Annotating Function Behavior.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Unterstützt in NDIS 6.0 und höher.
Zielplattform-	Fenster
Header-	ndis.h (include Ndis.h)
IRQL-	PASSIVE_LEVEL