Condividi tramite

Interfacce del driver IHV WDI

  • Articolo

Il miniport IHV WDI è come qualsiasi altro driver miniport NDIS e seguirebbe le procedure di sviluppo e la documentazione per qualsiasi miniport NDIS. Le responsabilità di un driver Miniport WLAN nativo per i gestori NDIS sono suddivise tra il componente MS e il driver IHV WDI. Il componente MICROSOFT WLAN 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 delle modifiche di comportamento e per i gestori NDIS per il miniport IHV WLAN nativo quando applicato a un miniport IHV WDI sono descritti di seguito.

Installazione del driver

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

DriverEntry

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

Di seguito sono riportati i parametri chiave di NdisMRegisterWdiMiniportDriver.

  • NDIS_MINIPORT_DRIVER_CHARACTERISTICS: si tratta della struttura NDIS originale usata da un miniport nativo Wi-Fi per eseguire 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 che ha eseguito la propria elaborazione per il gestore.
  • NDIS_MINIPORT_DRIVER_WDI_CHARACTERISTICS: questo è il nuovo set di gestori che un driver miniport WDI deve implementare. 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 MICROSOFT WLAN aggiorna i gestori di NDIS_MINIPORT_DRIVER_CHARACTERISTICS e chiama NDIS's NdisMRegisterMiniportDriver. 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 WDI IHV.

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

flusso wdi driverentry.

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 il gestore 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. Chiama MiniportWdiAllocateAdapter.

    Quando il sistema operativo trova un'istanza dell'hardware IHV, questa è la prima chiamata al 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 in 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 .

    Quando questa chiamata viene restituita dal driver miniport IHV, inizia a ricevere 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 rapida e affidabile.

  2. Chiama MiniportWdiOpenAdapter.

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

  3. Più comandi WDI che usano MiniportOidRequest.

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

    1. Chiamare MiniportWdiTalTxRxInitialize per inizializzare il percorso 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 opzione iniziale, se non è già nello stato previsto.
    5. Chiamare MiniportWdiTalTxRxStart per configurare il percorso dati.
    6. Chiamare OID_WDI_TASK_CREATE_PORT per creare la porta iniziale.

    Altri comandi possono anche essere inviati al componente IHV come parte dell'elaborazione MiniportInitializeEx del componente Microsoft. Tuttavia, fino a quando non viene chiamato MiniportWdiStartOperation , il componente Microsoft non invia alcuna attività che richiede comunicazioni over-the-air. Ad eccezione di OID_WDI_TASK_OPEN viene sempre inviato per primo, l'ordine degli altri comandi/chiamate può cambiare.

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

  4. Chiamare 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 non riesce a visualizzare il 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 nativo Wi-Fi , 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. Chiama 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 usando MiniportOidRequest.

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

    1. Chiamare OID_WDI_TASK_DISCONNECT OID_WDI_TASK_STOP_AP/ per rimuovere le connessioni esistenti.
    2. Chiamare OID_WDI_TASK_DELETE_PORT per eliminare tutte le porte create.
    3. Chiamare MiniportWdiTalTxRxStop per arrestare il percorso dati.
    4. Chiamare MiniportWdiTalTxRxDeinitialize per denitializzare il percorso dati.
    5. Chiamare per pulire lo stato hardware. Questo viene inviato all'IHV usando 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 mostra il flusso di MiniportHaltEx.

wdi miniport stop flow.wdi miniport stop flow.

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 wdi miniport.

MiniportPause

I requisiti NDIS MiniportPause vengono gestiti dal componente Microsoft. Nell'ambito di MiniportPause, il componente Microsoft arresta il percorso dei dati e attende la pulizia. Il miniport IHV WDI può facoltativamente registrarsi per un callback MiniportWdiPostAdapterPause chiamato dal componente Microsoft al termine della pulizia del percorso dati.

Il diagramma seguente mostra il flusso di MiniportPause.

wdi miniport pause flow.wdi miniport pause flow.

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.

wdi miniport restart flow.wdi miniport restart flow.

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 di un dispositivo a sorpresa. 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 inoltrata al componente IHV non viene serializzata con altre attività e callback.

Il diagramma seguente mostra il flusso di MiniportDevicePnPEventNotify.

wdi miniport drive pnp notification flow.

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.

wdi miniport shutdown flow.wdi miniport shutdown flow.

MiniportOidRequest

Il gestore MiniportOidRequest è un gestore obbligatorio che il miniport IHV WDI deve implementare. Viene usato dal componente Microsoft per inviare comandi WDI al miniport IHV. Viene usato anche per inoltrare gli URI che il componente Microsoft non gestisce al 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 un valore non PENDING restituito da MiniportOidRequest) deve essere considerato come messaggio M3 per un'attività/un 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 OID o tramite NdisMIndicateStatusEx). Il componente Microsoft esamina sempre il NDIS_STATUS dal 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 usando un NDIS_OID_REQUESTRequestType di NdisRequestMethod e la lunghezza del messaggio e del messaggio corrispondente si trovano nei DATI. METHOD_INFORMATION. InformationBuffer e DATA. METHOD_INFORMATION. Campi InputBufferLength rispettivamente.
  2. Il componente IHV segnala un errore nel completamento OID se si verifica un errore durante l'elaborazione del comando e imposta il campo Stato del WDI_MESSAGE_HEADER su non riuscito se si verifica un errore a livello di 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 nei DATI. METHOD_INFORMATION. Il campo OutputBufferLength per riempire la risposta completa l'OID con NDIS_STATUS_BUFFER_TOO_SHORT e popola i DATI. METHOD_INFORMATION. Campo ByteNeeded. 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 valore M4 dell'attività (NdisMIndicateStatusEx) deve essere indicato solo se l'attività è stata segnalata come avviata correttamente. Il completamento dell'OID ha esito positivo e lo stato del WDI_MESSAGE_HEADER nel completamento dell'OID è stato completato.

Il diagramma seguente mostra un esempio di richiesta OID NDIS che esegue il mapping 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.

wdi miniport oid request sequence for single wdi command.

Se OriginalOidRequest esegue il mapping a più OidRequest WDI e una delle richieste WDI ha esito negativo, anche OriginalOidRequest ha esito negativo. Se un subset delle operazioni intermedie è già terminato, il componente Microsoft tenta di annullare le operazioni che supportano 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 WDI IHV.

wdi miniport oid request sequence for oids handle by microsoft component.wdi miniport oid request sequence for oids handled by microsoft component.

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

wdi miniport oid request sequence for oids not handled by microsoft component.wdi miniport oid request sequence for oids not handled by microsoft component.

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 URI non mappati ai messaggi WDI. Questo gestore non viene usato per gli OID WDI. Gli OID 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 dell'attività di annullamento appropriata. Per gli OID non mappati, il comportamento previsto viene definito da NDIS.

NdisMIndicateStatusEx

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

Il diagramma seguente mostra un esempio di indicazione WDI con un'indicazione NDIS/Nativa corrispondente 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 di Wi-Fi NDIS/Nativa corrispondente. Viene gestito dal componente Microsoft.

indicazione di stato wdi senza mapping diretto a ndis.

Il diagramma seguente mostra un'indicazione che non è riconosciuta dal componente Microsoft. L'indicazione viene inoltrata così come è 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 nativo Wi-Fi).

MiniportDirectOidRequest

Si tratta di un gestore facoltativo registrato da un driver miniport IHV WDI se deve gestire gli OID diretti non mappati ai messaggi WDI. Tutti gli URI diretti 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 viene definito da NDIS.

MiniportSendNetBufferLists

Questo gestore non viene usato in un driver miniport IHV WDI e non deve essere fornito. Il componente Microsoft usa i gestori dei percorsi 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 dei percorsi 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 Apri attività 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 Chiudi attività 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 dell'oggetto MiniportWdiAllocateAdapter.