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.
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 |
|---|---|
|
MiniportInitializeEx configurato e configurato l'adattatore miniport e allocato tutte le risorse che il driver deve dover eseguire operazioni di I/O di rete. |
|
MiniportInitializeEx non è riuscito a ottenere l'adattatore miniport per accettare i parametri di configurazione ottenuti da MiniportInitializeEx dal Registro di sistema. |
|
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. |
|
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
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
- Blocchi di rotazione
- Timer
- Porte I/O
- DMA
- Shared Memory
- Interrompe
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 |