MINIPORT_MESSAGE_INTERRUPT Rückruffunktion (ndis.h)

Artikel
02/26/2024

NDIS ruft die MiniportMessageInterrupt-Funktion auf, wenn eine NIC einen nachrichtenbasierten Interrupt generiert.

Hinweis Sie müssen die Funktion mit dem MINIPORT_MESSAGE_INTERRUPT-Typ deklarieren. Weitere Informationen finden Sie im folgenden Abschnitt Beispiele.

Syntax

MINIPORT_MESSAGE_INTERRUPT MiniportMessageInterrupt;

BOOLEAN MiniportMessageInterrupt(
  [in]  NDIS_HANDLE MiniportInterruptContext,
  [in]  ULONG MessageId,
  [out] PBOOLEAN QueueDefaultInterruptDpc,
  [out] PULONG TargetProcessors
)
{...}

Parameter

[in] MiniportInterruptContext

Ein Handle für einen Block von Interruptkontextinformationen. Der Miniporttreiber hat dieses Handle im MiniportInterruptContext-Parameter angegeben, den der Miniporttreiber an den übergeben hat. NdisMRegisterInterruptEx-Funktion .

[in] MessageId

Ein MSI-Nachrichtenbezeichner (Message-Signaled Interrupt). MessageId ist ein Index zu einem IO_INTERRUPT_MESSAGE_INFO_ENTRY Struktur in einem IO_INTERRUPT_MESSAGE_INFO Struktur. NDIS übergibt einen Zeiger auf die zugeordnete IO_INTERRUPT_MESSAGE_INFO-Struktur am MessageInfoTable-Member , wenn sich der Treiber erfolgreich für MSI mit der NdisMRegisterInterruptEx-Funktion registriert.

[out] QueueDefaultInterruptDpc

Ein Zeiger auf eine boolesche Variable, die der Miniporttreiber vor der Rückgabe von diesem Aufruf festlegt. Ein Miniporttreiber legt diesen Wert auf TRUE fest, um anzugeben, dass der Treiber einen DPC für die (aktuelle) Standard-CPU erfordert. Wenn auf TRUE festgelegt ist, ignoriert NDIS den Wert des TargetProcessors-Parameters . Wenn auf FALSE festgelegt ist, verwendet NDIS den Wert des TargetProcessors-Parameters , um DPCs zu planen.

[out] TargetProcessors

Eine Bitmaske, die die Zielprozessoren angibt, für die NDIS einen DPC planen soll. Diese Bitmaske stellt die ersten 32 Prozessoren in der Prozessorgruppe 0 dar. Jedes Bit in der Bitmaske identifiziert eine CPU. Wenn der Aufrufer Bit 0 festlegt, plant NDIS einen DPC für CPU 0. Wenn der Aufrufer Bit 1 festlegt, plant NDIS einen DPC für CPU 1 usw.

Hinweis NDIS 6.20 und höhere Treiber sollten diesen Parameter nicht verwenden, um DPCs zu planen. Stattdessen sollten sie diesen Parameter auf 0 festlegen und die NdisMQueueDpcEx-Funktion verwenden, um DPCs zu planen.

Rückgabewert

MiniportMessageInterrupt gibt TRUE zurück, wenn die zugrunde liegende NIC den Interrupt generiert hat. Andernfalls wird FALSE zurückgegeben.

Hinweise

Miniport-Treiber, die sich für msi-Unterstützung (Message-Signaled Interrupts) mit der NdisMRegisterInterruptEx-Funktion registrieren, müssen eine MiniportMessageInterrupt-Funktion bereitstellen.

Ein Miniporttreiber sollte in seiner MiniportMessageInterrupt-Funktion so wenig Wie möglich arbeiten. E/A-Vorgänge für die Interrupts, die von der NIC generiert werden, sollten auf die MiniportMessageInterruptDPC-Funktion .

Wenn eine NIC eine MSI generiert, ruft NDIS die MiniportMessageInterrupt-Funktion des Miniporttreibers auf .

MiniportMessageInterrupt speichert erforderliche Zustandsinformationen über den Interrupt und verschiebt so viel der E/A-Verarbeitung wie möglich auf die MiniportMessageInterruptDPC-Funktion .

Wenn der Miniporttreiber verzögerte Prozeduraufrufe (DPCs) für eine angegebene Nachricht anfordert, sollte der Miniporttreiber alle weiteren Interrupts für diese Nachricht deaktivieren und die Interrupts erneut aktivieren, nachdem alle DPCs abgeschlossen sind.

Der Miniporttreiber sollte QueueDefaultInterruptDpc auf TRUE festlegen, um einen DPC nur für die Standard-CPU zu planen. Der Treiber kann dies beispielsweise tun, wenn:

Die NIC hat den Interrupt generiert, um den Abschluss eines Sendevorgangs oder einer anderen Anforderung zu signalisieren, die nicht auf anderen CPUs ausgeführt wird.
Die NIC hat den Interrupt generiert, um empfangene Daten zu signalisieren, und der Miniporttreiber kann empfangene Pakete nicht in separaten DPCs verarbeiten.
Der Interrupt gibt an, dass empfangene Pakete empfangen werden und der Miniporttreiber empfangene Pakete in separaten DPCs verarbeiten kann, aber die empfangsseitige Skalierung (RSS) ist für den Miniporttreiber nicht aktiviert. Weitere Informationen finden Sie unter OID_GEN_RECEIVE_SCALE_CAPABILITIES und OID_GEN_RECEIVE_SCALE_PARAMETERS.
Die empfangsseitige Skalierung ist für den Miniporttreiber aktiviert, und der Miniporttreiber kann unterschiedliche Nachrichten für jede Empfangswarteschlange generieren.

Wenn ein Miniporttreiber empfangene Pakete in separaten DPCs verarbeitet, legt der Miniporttreiber den Parameter QueueDefaultInterruptDpc auf FALSE fest. Der Miniporttreiber sollte das TargetProcessors-Bit für die CPU festlegen, die jeder nicht erlösenden Empfangswarteschlange zugeordnet ist. NDIS plant einen DPC für jede der angegebenen CPUs in Prozessorgruppe 0.

Wenn MiniportMessageInterrupt Ressourcen für eine angegebene Nachricht teilt, z. B. NIC-Register oder Zustandsvariablen, mit einer anderen MiniportXxx-Funktion , die mit einem niedrigeren IRQL ausgeführt wird, muss diese MiniportXxx-Funktion die aufrufen NdisMSynchronizeWithInterruptEx-Funktion . Dadurch wird sichergestellt, dass die MiniportSynchronizeMessageInterrupt-Funktion des Treibers synchronisiert und mit mehreren Prozessoren auf die freigegebenen Ressourcen zugreift.

Ein Miniporttreiber kann die NdisMDeregisterInterruptEx-Funktion aus der MiniportInitializeEx - oder MiniportHaltEx-Funktion , um Ressourcen freizugeben, die sie mit NdisMRegisterInterruptEx zugeordnet hat. Nachdem NdisMDeregisterInterruptEx zurückgegeben wurde , ruft NDIS die Funktion MiniportMessageInterrupt oder MiniportMessageInterruptDPC eines Miniporttreibers nicht auf.

NDIS ruft MiniportMessageInterrupt an der DIRQL der MSI auf, die der Miniporttreiber in einem vorherigen Aufruf von NdisMRegisterInterruptEx registriert hat. Daher muss MiniportMessageInterrupt die Teilmenge der NDIS-Funktionen aufrufen, z. B. die Xxx-Funktionen NdisRaw oder NdisRead/WriteRegisterRegister, die bei jedem IRQL sicher aufgerufen werden können.

Beispiele

Um eine MiniportMessageInterrupt-Funktion zu definieren, müssen Sie zuerst eine Funktionsdeklaration bereitstellen, die den Typ der zu definierenden Funktion identifiziert. Windows stellt eine Reihe von Funktionstypen für Treiber bereit. 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 Anforderung zum Schreiben von Treibern für das Windows-Betriebssystem.

Um beispielsweise eine MiniportMessageInterrupt-Funktion mit dem Namen "MyMessageInterrupt" zu definieren, verwenden Sie den MINIPORT_MESSAGE_INTERRUPT-Typ , wie in diesem Codebeispiel gezeigt:

MINIPORT_MESSAGE_INTERRUPT MyMessageInterrupt;

Implementieren Sie dann Ihre Funktion wie folgt:

_Use_decl_annotations_
BOOLEAN
 MyMessageInterrupt(
    NDIS_HANDLE  MiniportInterruptContext,
    ULONG  MessageId,
    PBOOLEAN  QueueDefaultInterruptDpc,
    PULONG  TargetProcessors
    )
  {...}

Der MINIPORT_MESSAGE_INTERRUPT Funktionstyp ist in der Headerdatei Ndis.h definiert. Um Fehler beim Ausführen der Codeanalysetools genauer zu identifizieren, fügen Sie der Funktionsdefinition die Use_decl_annotations Anmerkung hinzu. Die Use_decl_annotations Anmerkung stellt sicher, dass die Anmerkungen verwendet werden, die auf den MINIPORT_MESSAGE_INTERRUPT 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	Siehe Abschnitt "Hinweise"