MINIPORT_INITIALIZE Rückruffunktion (ndis.h)

Artikel
03/08/2023

NDIS ruft die MiniportInitializeEx-Funktion eines Miniporttreibers auf, um einen Miniportadapter für Netzwerk-E/A-Vorgänge zu initialisieren.

Hinweis Sie müssen die Funktion mit dem typ MINIPORT_INITIALIZE deklarieren. Weitere Informationen finden Sie im folgenden Abschnitt Beispiele.

Syntax

MINIPORT_INITIALIZE MiniportInitialize;

NDIS_STATUS MiniportInitialize(
  [in] NDIS_HANDLE NdisMiniportHandle,
  [in] NDIS_HANDLE MiniportDriverContext,
  [in] PNDIS_MINIPORT_INIT_PARAMETERS MiniportInitParameters
)
{...}

Parameter

[in] NdisMiniportHandle

Ein von NDIS bereitgestelltes Handle, das den Miniportadapter identifiziert, den der Miniporttreiber initialisieren soll.

[in] MiniportDriverContext

Ein Handle für einen vom Treiber zugewiesenen Kontextbereich, in dem der Treiber Zustands- und Konfigurationsinformationen verwaltet. Der Miniporttreiber hat diesen Kontextbereich an die NdisMRegisterMiniportDriver-Funktion .

[in] MiniportInitParameters

Ein Zeiger auf eine NDIS_MINIPORT_INIT_PARAMETERS Struktur, die die Initialisierungsparameter für den Miniportadapter definiert.

Rückgabewert

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

Rückgabecode	Beschreibung
NDIS_STATUS_SUCCESS	MiniportInitializeEx hat den Miniportadapter konfiguriert und eingerichtet und alle Ressourcen zugeordnet, die der Treiber zum Ausführen von Netzwerk-E/A-Vorgängen benötigt.
NDIS_STATUS_NOT_ACCEPTED	MiniportInitializeEx konnte den Miniportadapter nicht abrufen, um die Konfigurationsparameter zu akzeptieren, die MiniportInitializeEx aus der Registrierung abgerufen hat.
NDIS_STATUS_RESOURCES	MiniportInitializeEx konnte keine Ressourcen zum Ausführen von Netzwerk-E/A-Vorgängen zuordnen. MiniportInitializeEx sollte die NdisWriteErrorLogEntry-Funktion aufrufen, um den Ressourcenkonflikt zu identifizieren (z. B. E/A-Portbereich, Interruptvektor, Gerätespeicherbereich). Durch das Bereitstellen eines Fehlerprotokolldatensatzes erhalten benutzer- oder systemadministratoren Informationen, die zum Neukonfigurieren des Computers verwendet werden können, um solche Hardwareressourcenkonflikte zu vermeiden.
NDIS_STATUS_FAILURE	MiniportInitializeEx ist aus anderen Gründen als denen in der vorherigen Liste fehlgeschlagen. Der Treiber sollte NdisWriteErrorLogEntry mit Parametern aufrufen, die den Grund für den Fehler angeben.

Hinweise

NDIS ruft MiniportInitializeEx als Teil eines System-PnP-Vorgangs auf. Treiber geben den MiniportInitializeEx-Einstiegspunkt an, indem sie die NdisMRegisterMiniportDriver-Funktion aus der DriverEntry-Routine . NDIS kann MiniportInitializeEx aufrufen, nachdem DriverEntry zurückgegeben wurde. Weitere Informationen finden Sie unter DriverEntry of NDIS Miniport Drivers.

Für NDIS-Zwischentreiber kann NDIS MiniportInitializeEx im Kontext der NdisIMInitializeDeviceInstanceEx-Funktion oder nach der Rückgabe. Die ProtocolBindAdapterEx-Funktion eines solchen Treibers ruft in der Regel NdisIMInitializeDeviceInstanceEx auf.

Treiber können sich als kombinierter Miniporttreiber und Zwischentreiber registrieren (siehe NdisMRegisterMiniportDriver). Ein solcher Miniport-Intermediate-Treiber funktioniert ähnlich wie ein Zwischentreiber, der über einen physischen Miniporttreiber übergelagert ist. Wenn der IMMiniport-Registrierungsschlüssel für jedes virtuelle oder physische Gerät instance eines Miniport-Intermediate-Treibers auf DWORD:0x0000001 festgelegt ist, ruft NDIS die MiniportInitializeEx-Funktion auf, die der Treiber für das virtuelle Gerät registriert hat. Andernfalls ruft NDIS die MiniportInitializeEx-Funktion des Treibers auf, die der Treiber für das physische Gerät registriert hat.

Bis MiniportInitializeEx zurückgibt, sendet NDIS keine Anforderungen für den zu initialisierenden Miniportadapter. Der Miniportadapter befindet sich im Initialisierungszustand .

Um Konfigurationsinformationen für den Miniportadapter zu erhalten, ruft ein Treiber die Funktionen NdisOpenConfigurationEx und NdisReadConfiguration auf . Der Treiber kann die NdisMGetBusData-Funktion aufrufen, um busspezifische Informationen zu erhalten.

Miniporttreiber müssen den NdisMSetMiniportAttributes-Funktion und bereitstellen NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES Struktur, die die folgenden Attribute enthält:

Ein Handle für einen vom Treiber zugewiesenen Kontextbereich.
Entsprechende Attributflags.
Das Timeoutintervall für den Aufruf von MiniportCheckForHangEx-Funktion .
Der Schnittstellentyp.

Der Miniporttreiber übergibt NdisMSetMiniportAttributes ein Handle am MiniportAdapterContext-Member von NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES. Der Treiber verwaltet Zustandsinformationen für den angegebenen Miniportadapter in diesem Kontextbereich. NDIS übergibt dieses Handle als Eingabeparameter an andere MiniportXxx-Funktionen .

Miniport-Treiber müssen die Attribute in der NDIS_MINIPORT_ADAPTER_GENERAL_ATTRIBUTES Struktur nach dem Festlegen der Registrierungsattribute in der NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES-Struktur und vor dem Festlegen zusätzlicher Attribute.

MiniportInitializeEx kann auch Ressourcen wie die folgenden zuordnen:

Nicht ausgelagerter Poolspeicher
NET_BUFFER- und NET_BUFFER_LIST-Strukturpools
Spin-Sperren
Timer
E/A-Ports
Gerätespeicheradresse
Shared Memory
Interrupts

Wenn der Treiber angibt, dass mit dem Die NdisMIndicateReceiveNetBufferLists-Funktion sollte die MiniportInitializeEx-Funktion aufrufen. NdisAllocateNetBufferListPool und NdisAllocateNetBufferPool-Funktionen und speichern die Handles, die von diesen NDIS-Funktionen zurückgegeben werden. In der Regel verweisen die Netzwerkdaten, die der Treiber anschließend mit NdisMIndicateReceiveNetBufferLists angibt, auf Strukturen, die dem zugeordnet wurden. NdisAllocateNetBufferAndNetBufferList-Funktion . Ein Treiber kann auch Strukturen verwenden, die dem NdisAllocateNetBuffer zugeordnet wurden, und NdisAllocateNetBufferList-Funktionen .

Wenn Treiberfunktionen außer der MiniportInterrupt-Funktion Ressourcen freigeben, sollte MiniportInitializeEx die NdisAllocateSpinLock-Funktion aufrufen, um alle Spinsperren einzurichten, die zum Synchronisieren des Zugriffs auf solche freigegebenen Ressourcen erforderlich sind. Ressourcen, die andere Treiberfunktionen mit MiniportInterrupt teilen, z. B. NIC-Register, werden durch das Interruptobjekt geschützt, das der Treiber mit dem NdisMRegisterInterruptEx-Funktion . Treiberfunktionen greifen auf diese Ressourcen zu, indem sie die NdisMSynchronizeWithInterruptEx-Funktion .

MiniportInitializeEx kann die NdisAllocateTimerObject-Funktion mit einer vom Treiber bereitgestellten NetTimerCallback-Funktion und einem Zeiger auf den vom Treiber zugewiesenen Arbeitsspeicher für ein Timerobjekt aufrufen. Treiber können mehrere NetTimerCallback-Funktionen einrichten, von denen jede über ein eigenes Timerobjekt verfügt. Ein Treiber kann die NdisSetTimerObject-Funktion aufrufen, um eine regelmäßige NetTimerCallback-Funktion zu aktivieren. Ein Treiber kann auch die NdisSetTimerObject-Funktion aufrufen, um eine einmalige NetTimerCallback-Funktion zu aktivieren.

MiniportInitializeEx muss aufrufen Die NdisMSetMiniportAttributes-Funktion , bevor sie eine NdisMXxx-Funktion aufruft, z. B. die Funktionen NdisMRegisterIoPortRange oder NdisMMapIoSpace , die Hardwareressourcen für den Miniportadapter beansprucht. MiniportInitializeEx muss NdisMSetMiniportAttributes aufrufen, bevor versucht wird, Ressourcen für DMA-Vorgänge zuzuweisen.

Wenn das Gerät bus-master DMA unterstützt, muss MiniportInitializeEx die aufrufen. NdisMRegisterScatterGatherDma-Funktion nach dem Aufruf von NdisMSetMiniportAttributes und vor dem Aufruf der NdisMAllocateSharedMemory-Funktion . Wenn das Gerät untergeordnete DMA unterstützt, muss MiniportInitializeExNdisMSetMiniportAttributes aufrufen, bevor die NdisMRegisterDmaChannel-Funktion .

Nachdem MiniportInitializeEx aufgerufen hat NdisMRegisterInterruptEx-Funktion , NDIS kann die MiniportInterrupt-Funktion des Treibers aufrufen. NDIS ruft MiniportInterrupt auf, wenn die NIC einen Interrupt generiert oder wenn ein anderes Gerät, mit dem die NIC einen Interrupt teilt, einen Interrupt generiert. Beachten Sie, dass ein Miniporttreiber einen Interrupt erhalten kann, sobald er NdisMRegisterInterruptEx aufruft und bis zum Aufruf des Die NdisMDeregisterInterruptEx-Funktion gibt zurück.

MiniportInitializeEx sollte die NIC testen, um sicherzustellen, dass die Hardware ordnungsgemäß konfiguriert ist. Wenn der Treiber auf Zustandsänderungen in der Hardware warten muss, kann MiniportInitializeEx die NdisWaitEvent-Funktion oder die NdisMSleep-Funktion verwenden.

Nachdem MiniportInitializeEx erfolgreich zurückgegeben wurde, befindet sich der Miniportadapter im Zustand Angehalten . NDIS kann die MiniportRestart-Funktion aufrufen, um den Miniportadapter in den Status Running zu überstellen.

Wenn MiniportInitializeEx NDIS_STATUS_SUCCESS zurückgibt, sollte der Treiber alle Ressourcen für den Miniportadapter in der MiniportHaltEx-Funktion freigeben.

Der Treiber muss NdisMSetMiniportAttributes aufrufen und generalAttributes in der NDIS_MINIPORT_ADAPTER_ATTRIBUTES-Struktur festlegen, wenn er NDIS_STATUS_SUCCESS zurückgibt.

Wenn MiniportInitializeEx fehlgeschlagen ist, muss MiniportInitializeEx alle zugeordneten Ressourcen freigeben, bevor es zurückgibt, und der Miniportadapter kehrt in den Zustand Angehalten zurück.

NDIS ruft MiniportInitializeEx unter IRQL = PASSIVE_LEVEL auf.

Beispiele

Um eine MiniportInitializeEx-Funktion zu definieren, müssen Sie zunächst 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 MiniportInitializeEx-Funktion mit dem Namen "MyInitializeEx" zu definieren, verwenden Sie den MINIPORT_INITIALIZE-Typ , wie in diesem Codebeispiel gezeigt:

MINIPORT_INITIALIZE MyInitializeEx;

Implementieren Sie dann Ihre Funktion wie folgt:

_Use_decl_annotations_
NDIS_STATUS
 MyInitializeEx(
    NDIS_HANDLE  NdisMiniportHandle,
    NDIS_HANDLE  MiniportDriverContext,
    PNDIS_MINIPORT_INIT_PARAMETERS  MiniportInitParameters
    )
  {...}

Der MINIPORT_INITIALIZE Funktionstyp wird 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_INITIALIZE 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