MINIPORT_INITIALIZE funzione di callback (ndis.h)

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 virtuale o fisica del dispositivo 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:

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 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 la restituzione di MiniportInitializeEx , l'adattatore miniport è nello stato Sospeso . NDIS può chiamare la funzione MiniportRestart per eseguire la transizione dell'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 .

Se MiniportInitializeEx non è riuscito, MiniportInitializeEx deve rilasciare tutte le risorse allocate prima che venga restituito e l'adattatore miniport torna allo stato Arrestato.

NDIS chiama MiniportInitializeEx in IRQL = PASSIVE_LEVEL.

Esempi

Per definire una funzione MiniportInitializeEx , è innanzitutto 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 con i tipi di funzione consente di eseguire l'analisi del codice per i driver, l'SDV ( Static Driver Verifier ) e altri strumenti di verifica rilevano gli errori ed è un requisito per la scrittura dei driver per il sistema operativo Windows.

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

MINIPORT_INITIALIZE MyInitializeEx;

Implementare quindi la funzione come segue:

_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 quando si eseguono gli 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 utilizzate 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 di funzione per i driver NDIS.

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

Requisiti

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

Vedi anche

DriverEntry

MiniportCheckForHangEx

MiniportHaltEx

MiniportInterrupt

MiniportRestart

NDIS_MINIPORT_ADAPTER_GENERAL_ATTRIBUTES NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES

NDIS_MINIPORT_INIT_PARAMETERS

NET_BUFFER

NET_BUFFER_LIST

NdisAllocateNetBuffer

NdisAllocateNetBufferAndNetBufferList

NdisAllocateNetBufferList

NdisAllocateNetBufferListPool

NdisAllocateNetBufferPool

NdisAllocateSpinLock

NdisAllocateTimerObject

NdisMAllocateSharedMemory

NdisMDeregisterInterruptEx

NdisMGetBusData

NdisMIndicateReceiveNetBufferLists

NdisMMapIoSpace

NdisMRegisterDmaChannel

NdisMRegisterInterruptEx

NdisMRegisterIoPortRange

NdisMRegisterMiniportDriver

NdisMRegisterScatterGatherDma

NdisMSetMiniportAttributes

NdisMSleep

NdisMSynchronizeWithInterruptEx

NdisOpenConfigurationEx

NdisReadConfiguration

NdisSetTimerObject

NdisWaitEvent

NdisWriteErrorLogEntry

NetTimerCallback

ProtocolBindAdapterEx