Condividi tramite

Interfacce driver IHV WDI

Il miniport IHV WDI è come qualsiasi altro driver miniport NDIS e seguirà le procedure di sviluppo e la documentazione per qualsiasi miniport NDIS. Le responsabilità di un driver Miniport WLAN nativo per i gestori NDIS vengono suddivise tra il componente MS e il driver IHV WDI. Il componente WLAN Microsoft si occupa dei requisiti NDIS applicabili a tutti i miniport Wi-Fi in modo che ogni IHV non deve ripetere tutto il lavoro. Il mapping e le modifiche di comportamento per gli handler NDIS per il miniport IHV WLAN nativo, quando applicati a un miniport IHV WDI, sono descritti di seguito.

Driver installation

Non ci sono modifiche al modo in cui il driver miniport IHV WDI viene caricato e installato nel sistema. Il processo INF e di installazione è simile a quello di un driver miniport WLAN nativo IHV. Come gli esistenti driver NDIS, quando il driver IHV deve essere caricato per funzionare con l'adattatore WLAN di IHV, il sistema operativo chiama la routine DriverEntry del miniport del driver IHV.

DriverEntry

Il sistema operativo chiama direttamente la routine DriverEntry del miniport WDI IHV. Il miniport IHV segue la maggior parte delle linee guida della routine DriverEntry di un normale miniport NDIS. L'unica eccezione è che invece di chiamare NdisMRegisterMiniportDriver, il miniport IHV chiama NdisMRegisterWdiMiniportDriver per indicare al sistema operativo di abilitare il componente WLAN Di Microsoft.

Di seguito sono riportati i parametri chiave di NdisMRegisterWdiMiniportDriver.

  • NDIS_MINIPORT_DRIVER_CHARACTERISTICS: si tratta della struttura NDIS originale USATA da un miniport Wi-Fi nativo per la registrazione con NDIS. Per un modello WDI, la maggior parte dei parametri del gestore è facoltativa. Gli unici gestori necessari sono MINIPORT_OID_REQUEST_HANDLER e MINIPORT_DRIVER_UNLOAD. MINIPORT_OID_REQUEST_HANDLER viene usato per passare messaggi WDI al driver IHV. Se viene specificato un altro gestore, il componente MICROSOFT WLAN chiama in genere il gestore dopo aver eseguito la propria elaborazione per il gestore.
  • NDIS_MINIPORT_DRIVER_WDI_CHARACTERISTICS: si tratta del nuovo set di gestori che deve essere implementato da un driver miniport WDI. Viene usato dal driver IHV per registrare gestori aggiuntivi per il percorso di controllo e il set completo di gestori per il percorso dati.

Quando il miniport IHV chiama NdisMRegisterWdiMiniportDriver, il componente WLAN Microsoft aggiorna i gestori di NDIS_MINIPORT_DRIVER_CHARACTERISTICS e chiama NdisMRegisterMiniportDriver di NDIS. Gli aggiornamenti vengono eseguiti in modo che il componente WLAN Microsoft possa intercettare i gestori per i quali può fornire assistenza/semplificazione al driver miniport IHV WDI.

Di seguito è riportato il flusso tipico del processo di DriverEntry per il driver miniport IHV WDI

Flusso DriverEntry WDI.

Per altre informazioni su DriverEntry, vedere DriverEntry dei driver miniport NDIS.

MiniportSetOptions

Come illustrato nel diagramma DriverEntry precedente, se il miniport IHV WDI ha registrato la funzione MiniportSetOptions, il sistema operativo chiama tale funzione nel contesto del driver miniport che chiama NdisMRegisterWdiMiniportDriver.

Se il driver miniport IHV registra i gestori di opzioni usando NdisSetOptionalHandlers, tali gestori potrebbero non essere serializzati tramite il livello WDI dal componente Microsoft. Pertanto, il componente IHV è responsabile della gestione dei requisiti di sincronizzazione per tali gestori.

MiniportInitializeEx

Il modello WDI suddivide il comportamento MiniportInitializeEx in più chiamate di interfaccia WDI.

  1. Call MiniportWdiAllocateAdapter.

    Quando il sistema operativo trova un'istanza dell'hardware IHV, questa è la prima chiamata verso il driver miniport IHV WDI. In questa chiamata, il miniport WDI esegue le azioni necessarie per creare una rappresentazione software (MiniportAdapterContext) del dispositivo. Determina anche le informazioni sul dispositivo da compilare nella struttura NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES . L'inizializzazione effettiva del dispositivo e dello stack di Wi-Fi viene eseguita in un secondo momento quando il componente Microsoft invia comandi WDI per eseguire inizializzazioni specifiche.

    Usando i dati ottenuti dal driver miniport IHV WDI, il componente Microsoft chiama NdisMSetMiniportAttributes e imposta il NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES su NDIS. La maggior parte dei campi di NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES viene compilata con le impostazioni predefinite del componente Microsoft. Il driver IHV deve popolare i campi MiniportAdapterContext e InterfaceType .

    Una volta restituita la chiamata dal driver miniport IHV, inizia a ricevere i comandi WDI tramite il relativo gestore MiniportOidRequest . Durante questa chiamata, il componente Microsoft potrebbe non essere in grado di eseguire operazioni di reimpostazione/ripristino, pertanto qualsiasi attività eseguita qui dovrebbe essere veloce e affidabile.

  2. Call MiniportWdiOpenAdapter.

    Dopo MiniportWdiAllocateAdapter, il componente Microsoft chiama MiniportWdiOpenAdapter per caricare il firmware e inizializzare l'hardware.

  3. Più comandi WDI con MiniportOidRequest.

    Dopo MiniportWdiOpenAdapter, il componente Microsoft invia le attività/proprietà/chiamate seguenti al miniport IHV.

    1. Chiamare MiniportWdiTalTxRxInitialize per inizializzare il percorso dei dati e i gestori di scambio.
    2. Chiamare OID_WDI_GET_ADAPTER_CAPABILITIES per ottenere le funzionalità dell'adattatore.
    3. Chiamare OID_WDI_SET_ADAPTER_CONFIGURATION per configurare l'adattatore.
    4. Chiamare OID_WDI_TASK_SET_RADIO_STATE per impostare lo stato di radio iniziale se non è già nello stato previsto.
    5. Chiama MiniportWdiTalTxRxStart per configurare il percorso dati.
    6. Chiamare OID_WDI_TASK_CREATE_PORT per creare la porta iniziale.

    È anche possibile inviare altri comandi al componente IHV come parte dell'elaborazione MiniportInitializeEx del componente Microsoft. Tuttavia, finché non viene chiamato MiniportWdiStartOperation, il componente Microsoft non invia alcuna attività che richiede comunicazione via etere. Ad eccezione del fatto che OID_WDI_TASK_OPEN viene inviato sempre per primo, l'ordine degli altri comandi/chiamate può cambiare.

    Usando i dati ottenuti dal driver miniport IHV WDI, il componente Microsoft chiama NdisMSetMiniportAttributes e imposta NDIS_MINIPORT_ADAPTER_GENERAL_ATTRIBUTES e NDIS_MINIPORT_ADAPTER_NATIVE_802_11_ATTRIBUTES su NDIS.

  4. Call MiniportWdiStartOperation.

    Si tratta di un gestore miniport WDI facoltativo all'interno di NDIS_MINIPORT_DRIVER_WDI_CHARACTERISTICS che il driver IHV può usare per eseguire eventuali attività MiniportInitializeEx aggiuntive. Può anche essere usato dal miniport IHV come suggerimento che il componente Microsoft ha completato l'inizializzazione del miniport e il miniport può avviare qualsiasi attività in background necessaria.

    Il diagramma seguente mostra il flusso di MiniportInitializeEx.

    flusso di inizializzazione WDI miniport.

    Se un'operazione intermedia ha esito negativo, il componente Microsoft annulla le operazioni precedenti e fallisce l'attivazione del miniport. Ad esempio, se OID_WDI_TASK_CREATE_PORT ha esito negativo, il percorso dati viene pulito, OID_WDI_TASK_CLOSE viene inviato e il miniport ha esito negativo.

MiniportHaltEx

In un miniport Wi-Fi nativo, MiniportHaltEx viene usato per indicare al miniport di arrestare le operazioni e pulire l'istanza dell'adattatore. Nel modello WDI il componente Microsoft gestisce la chiamata MiniportHaltEx originale e la suddivide in più chiamate di interfaccia WDI.

  1. Call MiniportWdiStopOperation.

    Si tratta di un gestore miniport WDI facoltativo all'interno di NDIS_MINIPORT_DRIVER_WDI_CHARACTERISTICS che il driver IHV può usare per annullare le operazioni eseguite in MiniportWdiStartOperation.

  2. Più comandi WDI con MiniportOidRequest.

    Dopo MiniportWdiStopOperation, il componente Microsoft invia attività/proprietà al miniport IHV per ripulire lo stato corrente del driver IHV. Questa pulizia può includere quanto segue.

    1. Chiamare OID_WDI_TASK_DISCONNECT/OID_WDI_TASK_STOP_AP per interrompere le connessioni esistenti.
    2. Chiamare OID_WDI_TASK_DELETE_PORT per eliminare tutte le porte create.
    3. Chiama MiniportWdiTalTxRxStop per interrompere il flusso dati.
    4. Chiama MiniportWdiTalTxRxDeinitialize per denitializzare il percorso dei dati.
    5. Richiamare per ripulire lo stato dell'hardware. Questo viene inviato all'IHV tramite il MiniportWdiCloseAdapter registrato dal driver IHV.

  3. Dopo aver chiamato tutti i comandi precedenti, il componente Microsoft chiama MiniportWdiFreeAdapter per fare in modo che il driver IHV elimini qualsiasi stato software che potrebbe avere.

Il diagramma seguente illustra il flusso di MiniportHaltEx.

arresto del miniport WDI.

L'elaborazione MiniportHaltEx non viene eseguita se il dispositivo viene rimosso a sorpresa o se il sistema è spento. Per la rimozione a sorpresa, fare riferimento al comportamento del gestore MiniportDevicePnPEventNotify . Per l'arresto del sistema, fare riferimento al comportamento del gestore MiniportShutdownEx .

MiniportDriverUnload

MiniportDriverUnload è il gestore chiamato prima che il miniport IHV WDI venga scaricato. Il driver miniport IHV WDI chiama il componente Microsoft per annullare la registrazione. Il componente Microsoft chiama NdisMDeregisterMiniportDriver.

Il diagramma seguente mostra il flusso di MiniportDriverUnload.

flusso di scaricamento del driver miniport WDI.

MiniportPause

I requisiti NDIS MiniportPause vengono gestiti dal componente Microsoft. Come parte di MiniportPause, il componente Microsoft arresta il percorso dei dati e attende che venga pulito. Il miniport IHV WDI può facoltativamente registrarsi per un callback MiniportWdiPostAdapterPause chiamato dal componente Microsoft dopo aver completato la pulizia del percorso dati.

Il diagramma seguente mostra il flusso di MiniportPause.

flusso di pausa wdi miniport.

MiniportRestart

I requisiti NDIS MiniportRestart vengono gestiti dal componente Microsoft. Come parte di MiniportRestart, il componente Microsoft annulla il lavoro di sospensione del percorso dati eseguito come parte di MiniportPause. Il miniport IHV WDI può facoltativamente registrarsi per un callback MiniportWdiPostAdapterRestart chiamato dal componente Microsoft al termine del riavvio del percorso dati.

Il diagramma seguente mostra il flusso di MiniportRestart.

Flusso di riavvio del miniport wdi.

MiniportResetEx

MiniportResetEx non viene gestito dal componente Microsoft. Il miniport IHV WDI può facoltativamente registrarsi per un callback MiniportResetEx chiamato dal componente Microsoft.

MiniportDevicePnPEventNotify

MiniportDevicePnPEventNotify viene usato per notificare a un driver NDIS eventi PNP, ad esempio la rimozione a sorpresa di un dispositivo. Quando NDIS invia questa notifica, viene prima inoltrata al miniport IHV WDI per l'elaborazione. Al termine dell'elaborazione del componente IHV, il componente Microsoft esegue l'elaborazione appropriata per questo evento. La chiamata che viene inoltrata al componente IHV non è serializzata con altre attività e callback.

Il diagramma seguente mostra il flusso di MiniportDevicePnPEventNotify.

flusso di notifica pnp dell'unità miniport wdi.

MiniportShutdownEx

MiniportShutdownEx viene usato per notificare a un driver NDIS gli eventi di arresto del sistema. Quando NDIS invia questa notifica, viene gestita per la prima volta dal componente Microsoft. Al termine dell'elaborazione, il componente Microsoft passa l'evento al miniport WDI IHV per l'elaborazione.

Il diagramma seguente mostra il flusso di MiniportShutdownEx.

flusso di spegnimento della miniport WDI.

MiniportOidRequest

Il gestore MiniportOidRequest è un gestore obbligatorio che deve implementare il miniport WDI IHV. Viene usato dal componente Microsoft per inviare i comandi WDI al miniport IHV. Viene usato anche per inoltrare gli ID OID che il componente Microsoft non gestisce nel miniport IHV.

La chiamata MiniportOidRequest al miniport IHV WDI deve essere considerata come messaggio M1 per un comando WDI. Il completamento dell'OID (tramite NdisMOidRequestComplete o tramite una restituzione con esito diverso da PENDING da MiniportOidRequest) deve essere considerato come il messaggio di tipo M3 per un'attività/comando WDI.

Per ogni comando WDI sono disponibili due campi potenziali in cui è possibile restituire un codice NDIS_STATUS per l'operazione, ovvero il codice di stato della chiamata MiniportOidRequest (o NdisMOidRequestComplete) e il codice di stato nel campo WDI_MESSAGE_HEADER (sul completamento dell'OID o tramite NdisMIndicateStatusEx). Il componente Microsoft esamina sempre il NDIS_STATUS dallo stato di completamento dell'OID prima di esaminare il campo WDI_MESSAGE_HEADERStatus. Di seguito sono riportate le aspettative del componente IHV per l'elaborazione OID WDI.

  1. Gli OID WDI vengono inviati al componente IHV utilizzando un NDIS_OID_REQUESTRequestType di NdisRequestMethod, e il messaggio corrispondente e la lunghezza del messaggio sono contenuti rispettivamente nei campi DATA.METHOD_INFORMATION.InformationBuffer e DATA.METHOD_INFORMATION.InputBufferLength.
  2. Il componente IHV segnala un errore nel completamento dell'OID se si verifica un errore durante l'elaborazione del comando, e configura il campo Stato del WDI_MESSAGE_HEADER su uno stato di insuccesso in caso di guasto di livello Wi-Fi.
  3. Per le attività e le proprietà, il numero di porta per la richiesta si trova nel campo WDI_MESSAGE_HEADERPortId . PortNumber nel NDIS_OID_REQUEST è sempre impostato su 0.
  4. Per il completamento dell'OID, è accettabile che MiniportOidRequest restituisca NDIS_STATUS_PENDING e completi l'OID in un secondo momento (in modo sincrono o asincrono) con NdisMOidRequestComplete.
  5. Se il componente IHV completa l'OID con NDIS_STATUS_SUCCESS, deve popolare il campo BytesWritten della richiesta OID con il numero appropriato di byte, incluso lo spazio per il WDI_MESSAGE_HEADER.
  6. Se il componente IHV non dispone di spazio sufficiente nel campo DATA.METHOD_INFORMATION.OutputBufferLength per riempire la risposta, completa OID con NDIS_STATUS_BUFFER_TOO_SHORT e popola il campo DATA.METHOD_INFORMATION.BytesNeeded. Il componente Microsoft può tentare di allocare un buffer delle dimensioni richieste e inviare una nuova richiesta all'IHV.
  7. Se si tratta di un'attività, il M4 dell'attività (NdisMIndicateStatusEx) deve essere indicato solo se l'attività è stata segnalata come avviata correttamente -- il completamento dell'OID ha avuto successo e lo stato nella WDI_MESSAGE_HEADER di completamento dell'OID è stato positivo.

Il diagramma seguente mostra un esempio di una richiesta OID NDIS che si mappa a un singolo comando WDI. Quando la richiesta OID viene inviata dal sistema operativo, il componente Microsoft lo converte in una richiesta OID WDI e invia la richiesta OID WDI al miniport IHV. Quando il miniport IHV completa l'OID, il componente Microsoft completa in modo appropriato la richiesta OID originale.

sequenza di richiesta del miniport WDI OID per un singolo comando WDI.

Se OriginalOidRequest si mappa a più OidRequests WDI e una delle richieste WDI fallisce, anche OriginalOidRequest fallisce. Se un sottoinsieme delle operazioni intermedie è già terminato, il componente Microsoft tenta di annullare le operazioni che consentono la pulizia.

Il diagramma seguente mostra un esempio di richiesta OID NDIS gestita dal componente Microsoft. Quando la richiesta OID viene inviata dal sistema operativo, il componente Microsoft elabora e completa l'OID. Questo OID non viene passato al miniport IHV WDI.

wdi miniport oid request sequence for oids gestita dal componente di Microsoft.

Gli URI non riconosciuti dal componente Microsoft vengono inoltrati direttamente al componente IHV per l'elaborazione.

sequenza di richieste oid del miniport wdi per oid non gestite dal componente Microsoft.

Il comportamento di MiniportOidRequest è invariato per il driver miniport IHV WDI (rispetto a un miniport nativo Wi-Fi). Le chiamate vengono serializzate e il miniport IHV può completarlo in modo sincrono o asincrono con una chiamata a NdisMOidRequestComplete.

MiniportCancelOidRequest

Si tratta di un gestore facoltativo usato da un miniport IHV WDI che deve gestire gli ID predefiniti non mappati ai messaggi WDI. Questo gestore non viene usato per alcun OID WDI. Gli ID WDI devono essere completati rapidamente e non è necessario che il driver miniport IHV tenti di annullare un OID in sospeso. L'annullamento delle attività WDI viene gestito usando la richiesta OID appropriata per l'annullamento delle attività. Per gli OID non mappati, il comportamento previsto è definito da NDIS.

NdisMIndicateStatusEx

NdisMIndicateStatusEx viene usato dal miniport WDI IHV per inviare indicazioni al componente Microsoft. Le segnalazioni possono essere segnalazioni non richieste, ad esempio fallimenti MIC TKIP, o segnalazioni richieste per il completamento di un'attività (M4).

Il diagramma seguente mostra un esempio di un indicatore WDI che ha un corrispondente indicatore NDIS/Native Wi-Fi. Quando l'indicazione viene inviata dal miniport IHV al componente Microsoft, il componente Microsoft lo converte in un'indicazione esistente e lo inoltra al sistema operativo.

flusso di indicazione dello stato del miniport wdi.

Il diagramma seguente mostra un esempio di indicazione WDI che non ha alcuna indicazione NDIS/Native Wi-Fi corrispondente. Questa operazione viene gestita dal componente Microsoft.

Indicazione di stato WDI senza mappatura diretta a NDIS.

Il diagramma seguente mostra un'indicazione che non è riconosciuta dal componente Microsoft. La segnalazione viene inoltrata as-is al sistema operativo.

indicazione di stato wdi non riconosciuta dal componente Microsoft.

Il comportamento di NdisMIndicateStatusEx è invariato per il driver miniport IHV WDI (rispetto a un miniport Wi-Fi nativo).

MiniportDirectOidRequest

Si tratta di un gestore facoltativo registrato da un driver miniport IHV WDI se è necessario gestire gli OID diretti non mappati ai messaggi WDI. Tutti gli URI Direct esistenti per Wi-Fi Direct vengono mappati ai messaggi WDI, quindi questo gestore non è necessario per supportare tale funzionalità. Gli OID diretti non supportati non vengono serializzati dal componente Microsoft.

MiniportCancelDirectOidRequest

Si tratta di un gestore facoltativo usato da un miniport IHV WDI che deve gestire gli OID diretti non mappati ai messaggi WDI. Per gli OID non mappati, il comportamento previsto è definito da NDIS.

MiniportSendNetBufferLists

Questo gestore non viene usato in un driver miniport IHV WDI e non deve essere fornito. Il componente Microsoft utilizza i gestori del percorso dei dati registrati tramite NDIS_MINIPORT_DRIVER_WDI_CHARACTERISTICS per inviare pacchetti al miniport IHV.

MiniportCancelSend

Questo gestore non viene usato in un driver miniport IHV WDI e non deve essere fornito.

MiniportReturnNetBufferLists

Questo gestore non viene usato in un driver Miniport IHV WDI e non deve essere fornito. Il componente Microsoft usa i gestori del percorso dati registrati tramite NDIS_MINIPORT_DRIVER_WDI_CHARACTERISTICS per restituire i pacchetti ricevuti al miniport IHV.

Gestore WDI: MiniportWdiOpenAdapter

Il gestore MiniportWdiOpenAdapter viene usato dal componente Microsoft per avviare l'operazione di apertura del Task sul driver IHV. Questa chiamata deve essere completata rapidamente e, se l'operazione di apertura è stata avviata correttamente, l'IHV deve restituire NDIS_STATUS_SUCCESS in questa chiamata e chiamare il gestore OpenAdapterComplete passato al parametro NDIS_WDI_INIT_PARAMETERS di MiniportWdiAllocateAdapter.

Gestore WDI: MiniportWdiCloseAdapter

Il gestore MiniportWdiCloseAdapter viene usato dal componente Microsoft per avviare l'operazione Close Task sul driver IHV. Questa chiamata deve essere completata rapidamente e, se l'operazione di apertura è stata avviata correttamente, l'IHV deve restituire NDIS_STATUS_SUCCESS in questa chiamata e chiamare il gestore CloseAdapterComplete passato al parametro NDIS_WDI_INIT_PARAMETERS del MiniportWdiAllocateAdapter.

  • Last updated on