MINIPORT_INITIALIZE funzione di callback (ndis.h)

Articolo
02/26/2024

NDIS chiama la funzione MiniportInitializeEx di un driver miniport per inizializzare una scheda miniport per le operazioni di I/O di rete.

Nota È necessario dichiarare la funzione usando il tipo di MINIPORT_INITIALIZE . Per altre informazioni, vedere la sezione Esempi seguenti.

Sintassi

MINIPORT_INITIALIZE MiniportInitialize;

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

Parametri

[in] NdisMiniportHandle

Handle fornito da NDIS che identifica l'adattatore miniport che il driver miniport deve inizializzare.

[in] MiniportDriverContext

Handle in un'area di contesto allocata dal driver in cui il driver gestisce le informazioni sullo stato e sulla configurazione. Il driver miniport ha passato questa area di contesto all'oggetto Funzione NdisMRegisterMiniportDriver .

[in] MiniportInitParameters

Puntatore a un oggetto NDIS_MINIPORT_INIT_PARAMETERS struttura che definisce i parametri di inizializzazione per l'adattatore miniport.

Valore restituito

MiniportInitializeEx può restituire uno dei valori di stato seguenti:

Codice restituito	Descrizione
NDIS_STATUS_SUCCESS	MiniportInitializeEx configurato e configurato l'adattatore miniport e allocato tutte le risorse che il driver deve dover eseguire operazioni di I/O di rete.
NDIS_STATUS_NOT_ACCEPTED	MiniportInitializeEx non è riuscito a ottenere l'adattatore miniport per accettare i parametri di configurazione ottenuti da MiniportInitializeEx dal Registro di sistema.
NDIS_STATUS_RESOURCES	MiniportInitializeEx non è riuscito a allocare risorse per eseguire operazioni di I/O di rete. MiniportInitializeEx deve chiamare la funzione NdisWriteErrorLogEntry per identificare il conflitto di risorse, ad esempio l'intervallo di porte I/O, il vettore di interruzione, l'intervallo di memoria del dispositivo, come appropriato. La fornitura di un record di log degli errori fornisce all'utente o all'amministratore di sistema informazioni che possono essere usate per riconfigurare il computer per evitare conflitti di risorse hardware.
NDIS_STATUS_FAILURE	MiniportInitializeEx non è riuscito per motivi diversi da quelli dell'elenco precedente. Il driver deve chiamare NdisWriteErrorLogEntry con parametri che specificano il motivo dell'errore.

Commenti

NDIS chiama MiniportInitializeEx come parte di un'operazione PnP di sistema. I driver specificano il punto di ingresso MiniportInitializeEx chiamando il Funzione NdisMRegisterMiniportDriver dalla routine DriverEntry . NDIS può chiamare MiniportInitializeEx dopo la restituzione di DriverEntry . Per altre informazioni, vedere DriverEntry of NDIS Miniport Driver.

Per i driver intermedi NDIS, NDIS può chiamare MiniportInitializeEx nel contesto di Funzione NdisIMInitializeDeviceInstanceEx o dopo la restituzione. Tale funzione ProtocolBindAdapterEx di tale driver chiama in genere NdisIMInitializeDeviceInstanceEx.

I driver possono registrarsi come driver miniport combinati e driver intermedi (vedere NdisMRegisterMiniportDriver). Tale miniport-intermedio funzioni analogamente a un driver intermedio a livelli su un driver fisico miniport. Per ogni istanza del dispositivo virtuale o fisico di un driver intermedio miniport, se la chiave del Registro di sistema IMMiniport è impostata su DWORD:0x0000001, NDIS chiama la funzione MiniportInitializeEx registrata per il dispositivo virtuale. In caso contrario, NDIS chiama la funzione MiniportInitializeEx del driver registrata per il dispositivo fisico.

Fino a quando miniportInitializeEx restituisce, NDIS non invia richieste per l'inizializzazione dell'adattatore miniport. L'adattatore miniport si trova nello stato di inizializzazione .

Per ottenere informazioni di configurazione per la scheda miniport, un driver chiama le funzioni NdisOpenConfigurationEx e NdisReadConfiguration. Il driver può chiamare la funzione NdisMGetBusData per ottenere informazioni specifiche del bus.

I driver miniport devono chiamare il Funzione NdisMSetMiniportAttributes e fornire un NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES struttura che contiene gli attributi seguenti:

Handle per un'area di contesto allocata dal driver.
Flag di attributi appropriati.
Intervallo di timeout per la chiamata Funzione MiniportCheckForHangEx .
Tipo di interfaccia

Il driver miniport passa NdisMSetMiniportAttributes un handle al membro MiniportAdapterContext di NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES. Il driver gestisce le informazioni sullo stato per l'adattatore miniport specificato in questa area di contesto. NDIS passa questo handle come parametro di input ad altre funzioni MiniportXxx .

I driver miniport devono impostare gli attributi nell'oggetto NDIS_MINIPORT_ADAPTER_GENERAL_ATTRIBUTES struttura dopo aver impostato gli attributi di registrazione nella struttura NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES e prima di impostare eventuali attributi aggiuntivi.

MiniportInitializeEx può anche allocare risorse, ad esempio quanto segue:

Memoria del pool non a pagina
pool di strutture NET_BUFFER e NET_BUFFER_LIST
Blocchi di rotazione
Timer
Porte I/O
DMA
Shared Memory
Interrompe

Se il driver indica la ricezione con Funzione NdisMIndicateReceiveNetBufferLists , la funzione MiniportInitializeEx deve chiamare la funzione NdisAllocateNetBufferListPool e Funzioni NdisAllocateNetBufferPool e salvare gli handle restituiti da queste funzioni NDIS. In genere, i dati di rete che il driver indica successivamente con i riferimenti NdisMIndicateReceiveNetBufferLists allocati con Funzione NdisAllocateNetBufferAndNetBufferList . Un driver può anche usare strutture allocate con NdisAllocateNetBuffer e Funzioni NdisAllocateNetBufferList .

Se funzioni driver, diversa dalla funzione MiniportInterrupt , condividere le risorse, MiniportInitializeEx deve chiamare la funzione NdisAllocateSpinLock per configurare eventuali blocchi di spin necessari per sincronizzare l'accesso a tali risorse condivise. Le risorse condivise da altre funzioni driver con MiniportInterrupt, ad esempio i registri della scheda di interfaccia di rete, sono protette dall'oggetto interrupt configurato con il driver Funzione NdisMRegisterInterruptEx . Le funzioni driver accedono a queste risorse chiamando Funzione NdisMSynchronizeWithInterruptEx .

MiniportInitializeEx può chiamare la funzione NdisAllocateTimerObject con una funzione NetTimerCallback fornita dal driver e un puntatore alla memoria allocata dal driver per un oggetto timer. I driver possono configurare più funzioni NetTimerCallback , ognuna con il proprio oggetto timer. Un driver può chiamare la funzione NdisSetTimerObject per abilitare una funzione NetTimerCallback periodica. Un driver può anche chiamare la funzione NdisSetTimerObject per abilitare una funzione NetTimerCallback una volta.

MiniportInitializeEx deve chiamare Funzione NdisMSetMiniportAttributes prima di chiamare qualsiasi funzione NdisMXxx , ad esempio NdisMRegisterIoPortRange o NdisMMapIoSpace , che richiede risorse hardware per l'adattatore miniport. MiniportInitializeEx deve chiamare NdisMSetMiniportAttributes prima di cercare di allocare risorse per le operazioni DMA.

Se il dispositivo supporta DMA master del bus, MiniportInitializeEx deve chiamare l'oggetto Funzione NdisMRegisterScatterGatherDma dopo che chiama NdisMSetMiniportAttributes e prima di chiamare la funzione Funzione NdisMAllocateSharedMemory . Se il dispositivo supporta DMA subordinato, MiniportInitializeEx deve chiamare NdisMSetMiniportAttributes prima di chiamarlo Funzione NdisMRegisterDmaChannel .

Dopo la chiamata di MiniportInitializeEx Funzione NdisMRegisterInterruptEx, NDIS può chiamare la funzione MiniportInterrupt del driver. NDIS chiama MiniportInterrupt se la scheda di interfaccia di rete genera un interruzione o se qualsiasi altro dispositivo con cui la scheda di interfaccia di rete condivide un interruzione. Si noti che un driver miniport può ottenere un interruzione non appena chiama NdisMRegisterInterruptEx e mantiene l'interruzione fino a quando la chiamata al La funzione NdisMDeregisterInterruptEx restituisce .

MiniportInitializeEx deve testare la scheda di interfaccia di rete per assicurarsi che l'hardware sia configurato correttamente. Se il driver deve attendere che si verifichino modifiche dello stato nell'hardware, MiniportInitializeEx può usare la funzione NdisWaitEvent o la funzione NdisMSleep .

Dopo che MiniportInitializeEx restituisce correttamente, l'adattatore miniport è nello stato sospeso . NDIS può chiamare la funzione MiniportRestart per passare l'adattatore miniport allo stato In esecuzione .

Se MiniportInitializeEx restituisce NDIS_STATUS_SUCCESS, il driver deve rilasciare tutte le risorse per l'adattatore miniport nella funzione MiniportHaltEx .

Il driver deve chiamare NdisMSetMiniportAttributes e impostare GeneralAttributes nella struttura NDIS_MINIPORT_ADAPTER_ATTRIBUTES se restituisce NDIS_STATUS_SUCCESS.

Se MiniportInitializeEx non è riuscito, MiniportInitializeEx deve rilasciare tutte le risorse allocate prima che venga restituito e l'adattatore miniport restituisce lo stato Stoped .

NDIS chiama MiniportInitializeEx in IRQL = PASSIVE_LEVEL.

Esempi

Per definire una funzione MiniportInitializeEx , è prima necessario fornire una dichiarazione di funzione che identifica il tipo di funzione che si sta definendo. Windows fornisce un set di tipi di funzione per i driver. La dichiarazione di una funzione usando i tipi di funzione consente l'analisi del codice per i driver, il verifica driver statico (SDV) e altri strumenti di verifica trovano errori ed è un requisito per la scrittura di driver per il sistema operativo Windows.

Ad esempio, per definire una funzione MiniportInitializeEx denominata "MyInitializeEx ", usare il tipo di MINIPORT_INITIALIZE come illustrato in questo esempio di codice:

MINIPORT_INITIALIZE MyInitializeEx;

Implementare quindi la funzione come indicato di seguito:

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

Il tipo di funzione MINIPORT_INITIALIZE è definito nel file di intestazione Ndis.h. Per identificare in modo più accurato gli errori durante l'esecuzione degli strumenti di analisi del codice, assicurarsi di aggiungere l'annotazione Use_decl_annotations alla definizione della funzione. L'annotazione Use_decl_annotations garantisce che vengano usate le annotazioni applicate al tipo di funzione MINIPORT_INITIALIZE nel file di intestazione. Per altre informazioni sui requisiti per le dichiarazioni di funzione, vedere Dichiarazione di funzioni tramite tipi di ruolo per i driver NDIS.

Per informazioni su Use_decl_annotations, vedere Annotazione del comportamento della funzione.

Requisiti

Requisito	Valore
Client minimo supportato	Supportato in NDIS 6.0 e versioni successive.
Piattaforma di destinazione	Windows
Intestazione	ndis.h (includere Ndis.h)
IRQL	PASSIVE_LEVEL