Scrittura di un driver client MBBCx
Avviso
I diagrammi di sequenza in questo argomento sono solo a scopo di illustrazione. Non sono contratti pubblici e sono soggetti a modifiche in futuro.
File INF per i driver client MBBCx
I file INF per i driver client MBBCx sono uguali ad altri driver client NetAdapterCx. Per altre informazioni, vedere File INF per i driver client NetAdapterCx.
Seguire le indicazioni universali per assicurarsi che i file INF soddisfino i requisiti universali.
Inizializzare il dispositivo
Oltre a queste attività richieste da NetAdapterCx per l'inizializzazione dei dispositivi NetAdapter, un driver client MBB deve eseguire anche le attività seguenti nella relativa funzione EvtDriverDeviceAdd callback:
Chiamare MBB_DEVICE_CONFIG_INIT dopo aver chiamato NetDeviceInitConfig , ma prima di chiamare WdfDeviceCreate, facendo riferimento allo stesso oggetto WDFDEVICE_INIT passato dal framework.
Chiamare MbbDeviceInitialize per registrare funzioni di callback specifiche del dispositivo MBB usando una struttura di MBB_DEVICE_CONFIG inizializzata e l'oggetto WDFDEVICE ottenuto da WdfDeviceCreate.
Nell'esempio seguente viene illustrato come inizializzare il dispositivo MBB. La gestione degli errori è stata eliminata per chiarezza.
status = NetDeviceInitConfig(deviceInit);
status = MbbDeviceInitConfig(deviceInit);
// Set up other callbacks such as Pnp and Power policy
status = WdfDeviceCreate(&deviceInit, &deviceAttributes, &wdfDevice);
MBB_DEVICE_CONFIG mbbDeviceConfig;
MBB_DEVICE_CONFIG_INIT(&mbbDeviceConfig,
EvtMbbDeviceSendMbimFragment,
EvtMbbDeviceReceiveMbimFragment,
EvtMbbDeviceSendServiceSessionData,
EvtMbbDeviceCreateAdapter);
status = MbbDeviceInitialize(wdfDevice, &mbbDeviceConfig);
A differenza di altri tipi di driver NetAdapterCx, i driver client MBB non devono creare l'oggetto NETADAPTER dall'interno della funzione EvtDriverDeviceAdd callback. Verrà invece incaricato da MBBCx di farlo in un secondo momento.
Successivamente, il driver client deve chiamare MbbDeviceSetMbimParameters, in genere nella funzione di callback EvtDevicePrepareHardware che segue.
Questo diagramma del flusso di messaggi illustra il processo di inizializzazione.
Questo diagramma del flusso di messaggi illustra il processo di inizializzazione.
Gestione dei messaggi di controllo MBIM
MBBCx usa i comandi di controllo MBIM standard definiti nella specifica MBIM Rev 1.0, sezioni 8, 9 e 10, per il piano di controllo. I comandi e le risposte vengono scambiati tramite un set di funzioni di callback fornite dal driver client e dalle API fornite da MBBCx. MBBCx simula il modello operativo di un dispositivo MBIM, come definito nella specifica MBIM Rev 1.0, sezione 5.3, usando queste chiamate di funzione:
- MBBCx invia un messaggio di comando MBIM al driver client richiamando la funzione di callback EvtMbbDeviceSendMbimFragment . Il driver client completa in modo asincrono questa richiesta di invio chiamando MbbRequestComplete.
- Il driver client segnala la disponibilità del risultato chiamando MbbDeviceResponseAvailable.
- MBBCx recupera il messaggio di risposta MBIM dal driver client richiamando la funzione di callback EvtMbbDeviceReceiveMbimFragment . Il driver client completa in modo asincrono questa richiesta di risposta get chiamando MbbRequestCompleteWithInformation.
- Il driver client MBB può notificare ABBCx di un evento dispositivo non richiesto chiamando MbbDeviceResponseAvailable. MBBCx recupera quindi le informazioni dal driver client in modo analogo a come recupera i messaggi di risposta MBIM.
Il diagramma seguente illustra il flusso di scambio dei messaggi del driver MBBCx-client.
Sincronizzazione dei messaggi di controllo MBIM
Il framework MBBCx serializza sempre le chiamate alle funzioni di callback del driver client EvtMbbDeviceSendMbimFragment e EvtMbbDeviceReceiveMbimFragment . Nessuna nuova chiamata verrà effettuata dal framework finché il driver client chiama MbbRequestComplete o MbbRequestCompleteWithInformation.
Anche se un driver client non riceve sovrapposizioni evtMbbDeviceSendMbimFragment o EvtMbbDeviceReceiveMbimFragment , può ricevere più chiamate in successione prima che la risposta per un comando precedente sia disponibile dal dispositivo.
Se il dispositivo non è nello stato D0 , il framework MBBCx porterà prima il dispositivo a D0 (in altre parole, chiama EvtDeviceD0Entry) prima di chiama EvtMbbDeviceSendMbimFragment o EvtMbbDeviceReceiveMbimFragment. Il framework MBBCx garantisce inoltre che manterrà il dispositivo nello stato D0, ovvero non chiamerà EvtDeviceD0Exit, finché il client chiama MbbRequestComplete o MbbRequestCompleteWithInformation.
Creazione dell'interfaccia NetAdapter per il contesto PDP/bearer EPS
Prima di stabilire una sessione dati, MBBCx indicherà al driver client di creare un oggetto NETADAPTER e verrà usato da MBBCx per rappresentare l'interfaccia di rete per la sessione di dati attivata. Questa operazione viene eseguita dalla chiamata MBBCx alla funzione di callback del driver client EvtMbbDeviceCreateAdapter .
Nell'implementazione della funzione di callback EvtMbbDeviceCreateAdapter , il driver client MBBCx deve prima eseguire le stesse attività necessarie per la creazione di un oggetto NETADAPTER come qualsiasi driver client NetAdapterCx. Inoltre, deve eseguire anche le attività aggiuntive seguenti:
Chiamare MbbAdapterInitialize nell'oggetto NETADAPTER creato da NetAdapterCreate.
Dopo aver chiamato MbbAdapterinitialize, chiamare MbbAdapterGetSessionId per ripetere l'ID sessione dati per cui MBBCx intende usare questo oggetto NETADAPTER. Ad esempio, se il valore restituito è 0, significa che MBBCx userà questa interfaccia NETADAPTER per la sessione di dati stabilita dal contesto PDP primario/il bearer EPS predefinito.
È consigliabile che i driver client MBBCx mantengano un mapping interno tra l'oggetto NETADAPTER creato e il SessionId restituito. Ciò consente di tenere traccia della relazione dell'oggetto data session-to-NETADAPTER, particolarmente utile quando sono stati attivati più contesti PDP/bearer EPS.
Prima di tornare da EvtMbbDeviceCreateAdapter, i driver client devono avviare la scheda chiamando NetAdapterStart. Facoltativamente, possono anche impostare le funzionalità dell'adapter chiamando una o più di queste funzioni prima della chiamata a NetAdapterStart:
MBBCx richiama almeno una volta questa funzione di callback, quindi è sempre presente un oggetto NETADPATER per il contesto PDP primario/il bearer EPS predefinito. Se vengono attivati più contesti PDP/bearer EPS, MBBCx potrebbe richiamare più volte questa funzione di callback, una volta per ogni sessione dati da stabilire. Deve essere presente una relazione uno-a-uno tra l'interfaccia di rete rappresentata dall'oggetto NETADAPTER e una sessione dati, come illustrato nel diagramma seguente.
Nell'esempio seguente viene illustrato come creare un oggetto NETADAPTER per una sessione dati. Si noti che la gestione degli errori e il codice necessari per la configurazione delle funzionalità dell'adattatore non sono disponibili per brevità e chiarezza.
NTSTATUS
EvtMbbDeviceCreateAdapter(
WDFDEVICE Device,
PNETADAPTER_INIT AdapterInit
)
{
// Get the client driver defined per-device context
PMY_DEVICE_CONTEXT deviceContext = MyGetDeviceContext(Device);
// Set up the client driver defined per-adapter context
WDF_OBJECT_ATTRIBUTES adapterAttributes;
WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&adapterAttributes,
MY_NETADAPTER_CONTEXT);
// Create the NETADAPTER object
NETADAPTER netAdapter;
NTSTATUS status = NetAdapterCreate(AdapterInit,
&adapterAttributes,
&netAdapter);
// Initialize the adapter for MBB
status = MbbAdapterInitialize(netAdapter);
// Retrieve the Session ID and use an array to store
// the session <-> NETADAPTER object mapping
ULONG sessionId;
PMY_NETADAPTER_CONTEXT netAdapterContext = MyGetNetAdapterContext(netAdapter);
netAdapterContext->NetAdapter = netAdapter;
sessionId = MbbAdapterGetSessionId(netAdapter);
netAdapterContext->SessionId = sessionId;
deviceContext->Sessions[sessionId].NetAdapterContext = netAdapterContext;
//
// Optional: set adapter capabilities
//
...
NetAdapterSetDatapathCapabilities(netAdapter,
&txCapabilities,
&rxCapabilities);
...
NetAdapterSetLinkLayerCapabilities(netAdapter,
&linkLayerCapabilities);
...
NetAdapterSetLinkLayerMtuSize(netAdapter,
MY_MAX_PACKET_SIZE - ETHERNET_HEADER_LENGTH);
//
// Required: start the adapter
//
status = NetAdapterStart(netAdapter);
return status;
}
Per un esempio di codice di impostazione delle funzionalità del percorso dati, vedere Gestione del buffer dei dati di rete.
MBBCx garantisce che chiami EvtMbbDeviceCreateAdapter prima di richiedere MBIM_CID_CONNECT con lo stesso ID sessione. Il diagramma di flusso seguente illustra le interazioni tra il driver client e l'estensione della classe nella creazione dell'oggetto NETADAPTER.
Il flusso per la creazione dell'oggetto NETADAPTER per il contesto PDP primario/il bearer EPS predefinito viene avviato da MBBCx quando EvtDevicePrepareHardware è stato completato correttamente.
Il flusso per la creazione dell'oggetto NETADAPTER per il contesto PDP secondario/il supporto EPS dedicato viene attivato da WwanSvc ogni volta che vengono richieste connessioni su richiesta dalle applicazioni.
Durata dell'oggetto NETADAPTER
L'oggetto NETADAPTER creato dal driver client verrà eliminato automaticamente da MBBCx quando non è più in uso. Si verifica, ad esempio, dopo la disattivazione di altri bearer PDP/EPS. I driver client MBBCx non devono chiamare WdfObjectDelete negli oggetti NETADAPTER creati.
Se un driver client deve pulire i dati di contesto associati a un oggetto NETADAPTER, deve fornire una funzione EvtDestroyCallback nella struttura degli attributi dell'oggetto quando si chiama NetAdapterCreate.
Risparmio energia del dispositivo MBB
Per la gestione delle energia, i driver client devono usare l'oggetto NETPOWERSETTINGS come altri tipi di driver client NetAdapterCx.
Gestione delle sessioni del servizio dispositivi
Quando un'applicazione invia i dati DSS al dispositivo modem, MBBCx richiama la funzione di callback EvtMbbDeviceSendServiceSessionData del driver client. Il driver client deve quindi inviare i dati in modo asincrono al dispositivo e chiamare MbbDeviceSendDeviceServiceSessionDataComplete dopo il completamento dell'invio, quindi MBBCx può liberare la memoria allocata per i dati.
Al contrario, il driver client chiama MbbDeviceReceiveDeviceServiceSessionData per passare i dati fino all'applicazione tramite MBBCx.
Requisiti conformi ai driver Di Windows
- Conformità ai principi di progettazione DCH
- Seguire i principi di isolamento del pacchetto driver
- Seguire i requisiti di livello API
- Certificare con il processo di certificazione del programma di compatibilità hardware Di Windows usando Hardware Lab Kit
Commenti e suggerimenti
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedere https://aka.ms/ContentUserFeedback.
Invia e visualizza il feedback per