MINIPORT_RESET Rückruffunktion (ndis.h)

Artikel
02/26/2024

Warnung

Von den Rückruffunktionen MiniportResetEx und MiniportCheckForHangEx wird für alle NDIS 6.83- und höher-Treiber abgeraten. Weitere Informationen finden Sie unter Check-for-Hang- und Reset-Vorgänge in NDIS 6.83 und höher.

NDIS ruft die MiniportResetEx-Funktion eines NDIS-Miniporttreibers auf, um das Zurücksetzen einer Netzwerkschnittstelle Karte (NIC) zu initiieren. Weitere Informationen finden Sie unter Miniport Adapter Check-for-Hang and Reset Operations und Miniport Driver Hardware Reset.

Hinweis Ein NDIS-Miniporttreiber kann diese Funktion mithilfe des MINIPORT_RESET Typs deklarieren.

Syntax

MINIPORT_RESET MiniportReset;

NDIS_STATUS MiniportReset(
  [in]  NDIS_HANDLE MiniportAdapterContext,
  [out] PBOOLEAN AddressingReset
)
{...}

Parameter

[in] MiniportAdapterContext

Ein Handle für einen Kontextbereich, den der Miniporttreiber in seiner MiniportInitializeEx-Funktion zugeordnet hat. Der Miniporttreiber verwendet diesen Kontextbereich, um Zustandsinformationen für einen Miniportadapter zu verwalten.

[out] AddressingReset

Ein Zeiger auf eine boolesche Variable. Der Miniporttreiber legt diese Variable auf TRUE fest, wenn NDIS die MiniportOidRequest-Funktion aufrufen soll, um die Adressierung und andere Konfigurationseinstellungen auf die aktuellen Werte wiederherzustellen. Weitere Informationen finden Sie unter Hardwarezurücksetzung.

Rückgabewert

MiniportResetEx kann einen der folgenden status-Werte zurückgeben:

Rückgabecode	Beschreibung
NDIS_STATUS_SUCCESS	MiniportResetEx hat den Miniportadapter erfolgreich auf einen Betriebszustand zurückgesetzt.
NDIS_STATUS_PENDING	Der Treiber schließt den Zurücksetzungsvorgang asynchron ab, indem er die NdisMResetComplete-Funktion aufruft , wenn der Vorgang abgeschlossen ist.
NDIS_STATUS_RESET_IN_PROGRESS	MiniportResetEx hat ermittelt, dass der Miniportadapter derzeit zurückgesetzt wird, sodass dieser Aufruf überflüssig ist.
NDIS_STATUS_SOFT_ERRORS	MiniportResetEx hat den Miniportadapter erfolgreich zurückgesetzt, aber während des Vorgangs ist ein wiederherstellbarer Fehler aufgetreten. MiniportResetEx sollte die NdisWriteErrorLogEntry-Funktion mit weiteren Informationen zum Fehler aufgerufen haben.
NDIS_STATUS_HARD_ERRORS	MiniportResetEx hat versucht, den Miniportadapter zurückzusetzen, aber während des Vorgangs ist ein nicht behebbarer Fehler aufgetreten. MiniportResetEx sollte NdisWriteErrorLogEntry mit weiteren Informationen zum Fehler aufgerufen haben.

Hinweise

Ein Treiber gibt den MiniportResetEx-Einstiegspunkt an, wenn er die NdisMRegisterMiniportDriver-Funktion .

MiniportResetEx ist für fortgeschrittene Treiber nicht erforderlich.

MiniportResetEx kann die Parameter des Miniportadapters zurücksetzen. Wenn eine Zurücksetzung eine Änderung der Stationsadresse des Miniportadapters verursacht, stellt der Miniporttreiber nach Abschluss des Zurücksetzens automatisch den vorherigen Wert der Stationsadresse wieder her. Alle Multicast- oder funktionalen Adressierungsmasken, die von der Hardware zurückgesetzt werden, müssen in dieser Funktion nicht zurückgesetzt werden.

Wenn durch einen Zurücksetzungsvorgang andere Informationen wie Multicast- oder funktionale Adressierungsinformationen geändert werden, muss MiniportResetEx die Variable unter AddressingReset auf TRUE festlegen, bevor sie zurückgegeben wird. Dies bewirkt, dass NDIS die MiniportOidRequest-Funktion aufruft, um die Informationen wiederherzustellen. NDIS stellt auch die WoL-Musterliste (Wake on the LAN) wieder her, indem OID_PNP_ADD_WAKE_UP_PATTERN aufgerufen wird. Der Treiber sollte die WoL-Musterliste aus dem Adapterkontext befreien, da die Hardwareliste bereits zurückgesetzt wurde.

NDIS bricht keine ausstehenden OID-Anforderungen ab oder sendet keine Anforderungen. Wenn der Treiber ausstehende OID sicher abschließen oder Anforderungen nach einem Zurücksetzen senden kann, kann der Treiber ausstehende OID halten oder Anforderungen senden, bis der Zurücksetzungsvorgang abgeschlossen ist. Andernfalls sollte der Treiber die ausstehende OID abschließen oder Anforderungen senden, indem er NdisMOidRequestComplete oder aufruft . NdisMSendNetBufferListsComplete-Funktionen bzw. vor der Rückgabe von MiniportResetEx .

Hinweis Ab NDIS 6.30 darf der Miniporttreiber die ausstehende OID nicht halten oder Anforderungen senden, bis der Zurücksetzungsvorgang abgeschlossen ist. Stattdessen muss der Treiber diese ausstehenden Anforderungen ausführen, indem er die Funktionen NdisMOidRequestComplete bzw. NdisMSendNetBufferListsComplete aufruft , bevor der Zurücksetzungsvorgang abgeschlossen ist. Wenn der Treiber den Zurücksetzungsvorgang asynchron abschließt, muss er die ausstehende OID abschließen und Anforderungen senden, bevor der Treiber NdisMResetComplete aufruft.

Ein Miniporttreiber sollte die NdisMIndicateStatusEx-Funktion nicht aufrufen, um den Start und das Ende jedes Zurücksetzungsvorgangs zu signalisieren. NDIS benachrichtigt gebundene Protokolltreiber, wenn eine Zurücksetzung beginnt und endet.

Wenn MiniportResetEx während der Zurücksetzungsvorgänge auf Zustandsänderungen im Miniportadapter warten muss, kann die Funktion NdisStallExecution aufgerufen werden. Allerdings ist ein
Die MiniportResetEx-Funktion darf NdisStallExecution nicht mit einem Zeitintervall aufrufen, das größer als 50 Mikrosekunden ist. Wenn der Treiber länger als 50 Mikrosekunden warten muss (oder wenn er abruft), sollte er stattdessen einen Timer festlegen und NDIS_STATUS_PENDING zurückgeben.

Wenn MiniportResetEx NDIS_STATUS_PENDING zurückgibt, muss der Treiber das Zurücksetzen durch Aufrufen der Funktion NdisMResetComplete abschließen.

Wenn sich ein Miniportadapter im MediaConnectStateConnected-Zustand befindet und sich sein Zustand aufgrund einer Zurücksetzung ändert, einschließlich einer Änderung des MediaConnectStateUnknown-Zustands, muss der Miniporttreiber die Zustandsänderung mit einer NDIS_STATUS_LINK_STATE status Anzeigen melden. Der Miniporttreiber muss auch einen MediaConnectStateConnected-status angeben, wenn der Link nach dem Zurücksetzen wiederhergestellt wird.

MiniportResetEx kann durch einen Interrupt vorzeitig entfernt werden.

NDIS ruft die MiniportCheckForHangEx-Funktion in regelmäßigen Abständen auf, um zu bestimmen, ob MiniportResetEx aufgerufen werden soll. Das Standardtimeout für den Aufruf von MiniportCheckForHangEx beträgt 2 Sekunden. Wenn diese Standardeinstellung zu kurz ist, kann ein Miniporttreiber beim Aufrufen von einen größeren CheckForHangTimeInSeconds-Wert festlegen.
NdisMSetMiniportAttributes-Funktion während der Initialisierung. Weitere Informationen finden Sie unter Miniport Adapter Check-for-Hang- und Reset-Vorgänge.

NDIS kann nicht ermitteln, ob eine NIC nicht mehr auf Empfangsvorgänge reagiert. Um diese Art von Fehler zu behandeln, kann die MiniportCheckForHangEx-Funktion Empfangsvorgänge überwachen und bei Bedarf TRUE zurückgeben, um ein Zurücksetzen zu erzwingen. Ein Miniport kann auch eine Zurücksetzung anfordern, indem er NdisMResetMiniport aufruft.

NDIS ruft MiniportResetEx am IRQL <= DISPATCH_LEVEL auf.

Beispiele

Um eine MiniportResetEx-Funktion zu definieren, müssen Sie zunächst eine Funktionsdeklaration bereitstellen, die den Typ der von Ihnen definierten 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.

Um beispielsweise eine MiniportResetEx-Funktion mit dem Namen "MyResetEx" zu definieren, verwenden Sie den typ MINIPORT_RESET , wie in diesem Codebeispiel gezeigt:

MINIPORT_RESET MyResetEx;

Implementieren Sie dann Ihre Funktion wie folgt:

_Use_decl_annotations_
NDIS_STATUS
 MyResetEx(
    NDIS_HANDLE  MiniportAdapterContext,
    PBOOLEAN  AddressingReset
    )
  {...}

Der MINIPORT_RESET 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_RESET 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 (include Ndis.h)
IRQL	<= DISPATCH_LEVEL