Semantica operativa MB
Transazioni asincrone
Il modello di driver MB prevede una semantica operativa non bloccante tra il Servizio MB e i driver Miniport, usando il meccanismo di notifica asincrono fornito in NDIS 6.x. Questo meccanismo consente al servizio MB di continuare a inviare richieste OID al driver miniport per l'elaborazione senza attendere il completamento dell'operazione corrente.
Una transazione asincrona è un handshake a tre vie che inizia con la richiesta iniziale, seguita da una risposta di stato della richiesta e quindi completata da un'indicazione transazionale finale. La risposta di stato della richiesta è provvisoria in quanto riconosce solo che il driver miniport ha ricevuto la richiesta. L'indicazione asincrona di follow-up è transazionale in quanto segnala il completamento della transazione. Il driver miniport restituisce il codice di stato e i dati risultanti nell'indicazione transazionale.
Set asincrono e richieste di query
Molte delle impostate e query richieste OID usate dal servizio MB vengono elaborate in modo asincrono. Per ulteriori informazioni su impostazioni e richieste di query OID, vedere NDIS_OID_REQUEST. La tabella "OID specifiche WWAN" nell'argomento MB Data Model identifica quali OID vengono elaborati in modo asincrono.
Il diagramma seguente rappresenta la sequenza di interazione per una transazione di query asincrona tra il servizio MB e il driver miniport. Le etichette in grassetto rappresentano identificatori OID o controllo del flusso transazionale e le etichette nel testo normale rappresentano i flag importanti all'interno della struttura OID.
L'handshake a tre vie è lo stesso per le richieste di query e impostazione.
Ad eccezione di OID_WWAN_DRIVER_CAPS, tutte le altre richieste OID specifiche di MB seguono il meccanismo di transazione asincrona per lo scambio di informazioni tra i driver miniport e il servizio MB, con le note aggiuntive seguenti:
I driver Miniport devono annullare immediatamente una richiesta OID in qualsiasi condizione di errore, ad esempio una richiesta OID non valida.
I driver Miniport devono restituire eventuali condizioni di errore specifiche di WWAN con il codice di errore corretto (ad esempio, WWAN_STATUS_XXX) specificato nel uStatus membro della struttura di notifica degli eventi. I driver Miniport devono anche completare in modo appropriato i membri che seguono il membro uStatus, in base alle esigenze. Ad esempio, i driver miniport dovrebbero compilare il membro ContextState.uNwError della struttura NDIS_WWAN_CONTEXT_STATE, se disponibile. Tuttavia, nel caso di un errore durante l'elaborazione di OID correlati ai PIN, i driver miniport potrebbero non avere necessariamente le informazioni sullo stato del PIN corrente da specificare nel PinInfo.PinState membro di NDIS_WWAN_PIN_INFO.
I driver Miniport devono restituire NDIS_STATUS_INDICATION_REQUIRED come risposta provvisoria per tutte le richieste OID asincrone.
I driver Miniport devono essere in grado di distinguere le modifiche dello stato del dispositivo causate da una richiesta OID da altre cause. I driver Miniport devono inviare notifiche transazionali per le modifiche dello stato risultanti dalle richieste OID e devono inviare notifiche di eventi non richieste per le modifiche dello stato da altre cause.
I driver Miniport sono responsabili della gestione della memoria in modalità kernel, anche se il servizio MB alloca inizialmente la memoria per le richieste. Dopo che il servizio MB riceve una risposta da un driver miniport, il servizio può rilasciare la memoria in modalità utente allocata per la richiesta OID.
Il diagramma seguente rappresenta la sequenza di interazione per un set asincrono della transazione tra il servizio MB e il driver del miniport. Le etichette in grassetto rappresentano identificatori OID o controllo del flusso transazionale e le etichette nel testo normale rappresentano i flag importanti all'interno della struttura OID.
Risposta asincrona
La specifica NDIS 6.0 (rilasciata con Windows Vista) ha introdotto un nuovo codice di stato, NDIS_STATUS_INDICATION_REQUIRED, per i driver miniport per indicare la natura asincrona di una transazione al servizio MB nella risposta provvisoria di un driver miniport a una richiesta OID.
Come indicato in MB Interface Overview, il servizio MB non ha accesso diretto alla memoria in modalità kernel allocata da un driver miniport MB. Si presuppone che il risultato dell'esecuzione archiviato nella memoria in modalità kernel venga copiato e reso disponibile al servizio MB da alcuni intermediari, ad esempio WMI o un driver di filtro NDIS . Di conseguenza, i driver miniport possono rilasciare la memoria in modalità kernel allocata dopo che la chiamata alla funzione NdisMIndicateStatusEx restituisce nell'indicazione transazionale.
Le procedure di handshake che i miniport driver e il servizio MB devono seguire sono descritte nella seguente procedura.
Procedura del driver miniport MB
Dopo aver ricevuto una richiesta OID, i driver miniport devono eseguire i passaggi seguenti:
Allocare memoria in modalità kernel per copiare il contenuto della struttura di dati NDIS_OID_REQUEST associata alla richiesta OID.
Tra i parametri della richiesta, assicurarsi di copiare anche i membri della struttura di richiesta OID RequestId e RequestHandle. Questi membri verranno usati più avanti nell'indicazione transazionale .
Restituire uno stato di risposta provvisoria NDIS_STATUS_INDICATION_REQUIRED per informare il MB Service che il driver miniport completerà la richiesta asincronamente.
Al termine dell'operazione, archiviare il risultato in memoria locale o allocata dal driver, in base alle esigenze.
Chiamare la funzione NdisMIndicateStatusEx per notificare al servizio MB che l'operazione in sospeso è stata completata. I driver miniport devono compilare i membri della struttura NDIS_STATUS_INDICATION come indicato di seguito:
- Impostare il membro StatusCode sul tipo di notifica dello stato. Ad esempio, NDIS_STATUS_WWAN_XXX.
- Impostare il membro DestinationHandle sul membro RequestHandle ricevuto nella struttura di dati NDIS_OID_REQUEST quando il driver miniport ha ricevuto la richiesta OID corrispondente.
- Impostare il membro RequestId in modo che corrisponda al membro RequestId della struttura di stato NDIS_OID_REQUEST quando il driver miniport ha ricevuto la richiesta OID corrispondente.
- Impostare i membri StatusBuffer e StatusBufferSize in modo che puntino rispettivamente alla memoria allocata dal driver miniport e alle dimensioni del buffer di memoria. Questo buffer di memoria contiene il risultato dell'operazione completata.
- Se l'operazione viene completata correttamente, impostare il membro uStatus su WWAN_STATUS_SUCCESS. In caso contrario, impostare il membro uStatus sul valore WWAN_STATUS_XXX appropriato per indicare il tipo di errore.
Quando la chiamata di funzione viene restituita, il driver miniport deve rilasciare la memoria allocata per la richiesta OID.
Procedura del servizio MB
Il servizio MB elabora transazioni asincrone utilizzando la procedura seguente:
Allocare memoria buffer per la richiesta in base alla struttura dei dati OID. Compilare i membri della struttura dei dati con i valori appropriati.
Chiamare la funzioneNdisOidRequest con il membro InformationBuffer che punta alla struttura di dati OID per la richiesta OID e attendere che il driver miniport risponda.
Dopo aver ricevuto una risposta provvisoria NDIS_STATUS_INDICATION_REQUIRED dal driver miniport, il servizio MB salva il RequestId, rilascia la memoria allocata e contrassegna la transazione come aperta. A questo punto, il servizio MB è libero di elaborare le richieste e le notifiche OID successive.
Dopo aver ricevuto una notifica con NDIS_STATUS_WWAN_XXX come valore StatusCode, verificare se il RequestId corrisponde a quello di qualsiasi transazione contrassegnata come aperta. Se esiste una corrispondenza, il servizio chiude la transazione. Se non viene trovata alcuna corrispondenza, considerare la notifica come una notifica di evento non richiesta.
Elaborare i dati restituiti nel membro StatusBuffer e apportare le modifiche dello stato al servizio MB in base alle esigenze.
Indicazioni
Esistono due tipi di indicazioni specifiche di WWAN che i driver miniport possono generare:
Notifiche degli eventi risultanti da una modifica dello stato dell'oggetto nel dispositivo MB.
Notifiche transazionali che segnalano il completamento di un'operazione asincrona.
In entrambi i casi, i driver miniport devono chiamare la funzione NdisMIndicateStatusEx.
Notifica eventi
La notifica degli eventi non è richiesta nel senso che il driver miniport invia in modo proattivo l'indicazione al servizio MB come evento di modifica dello stato. La modifica dello stato è causata da un'azione di un'entità diversa dal servizio MB. Il servizio MB presuppone che i driver miniport siano in grado di rilevare la causa della modifica.
Per qualsiasi notifica di evento specifica WWAN, i driver miniport devono impostare il membro RequestId della struttura NDIS_STATUS_INDICATION su zero. Il membro StatusCode specifica quale oggetto nel dispositivo MB è stato modificato. Il driver miniport può impostare questo oggetto su uno dei valori seguenti:
NDIS_STATUS_WWAN_HOME_PROVIDER
NDIS_STATUS_WWAN_PREFERRED_PROVIDERS
NDIS_STATUS_WWAN_VISIBLE_PROVIDERS
NDIS_STATUS_WWAN_REGISTER_STATE
NDIS_STATUS_WWAN_PACKET_SERVICE
NDIS_STATUS_WWAN_CONTEXT_STATE
NDIS_STATUS_WWAN_PROVISIONED_CONTEXTS
NDIS_STATUS_WWAN_SERVICE_ACTIVATION
NDIS_STATUS_WWAN_SMS_CONFIGURATION
NDIS_STATUS_WWAN_VENDOR_SPECIFIC
Il servizio MB può anche elaborare altre notifiche degli eventi da NDIS. Queste notifiche degli eventi non MB non sono necessariamente soggette al requisito che i valori di RequestId siano impostati su zero.
Notifiche transazionali
I driver Miniport usano notifiche transazionali per informare il MB Service che una transazione asincrona è stata completata e il MB Service usa le notifiche transazionali per chiudere le transazioni aperte e aggiornare la macchina degli stati.
Il servizio MB prevede notifiche transazionali in modo che possa chiudere le transazioni aperte. Si tratta dello scambio finale del "three-way handshake" tra il servizio MB e il driver miniport in una transazione asincrona. Il valore di RequestId membro del NDIS_STATUS_INDICATION in qualsiasi notifica transazionale deve essere diverso da zero, copiato dalla richiesta corrispondente nella stessa transazione.
Per il corretto funzionamento del meccanismo asincrono è necessario impostare il membro RequestId della struttura NDIS_STATUS_INDICATION. Il servizio MB garantisce che il valore RequestId sia univoco e diverso da zero tra tutte le richieste in sospeso. I driver Miniport devono restituire lo stesso valore RequestId nell'indicazione corrispondente per consentire al servizio MB di correlare l'indicazione con una transazione aperta.
Struttura di indicazione dello stato
Sia le risposte asincrone per una determinata richiesta OID sia le strutture di notifica di eventi non richiesti condividono i seguenti membri di struttura, indicati dal membro StatusBuffer del parametro StatusIndication per NdisMIndicateStatusEx:
typedef struct _NDIS_WWAN_XXX {
NDIS_OBJECT_HEADER Header;
WWAN_STATUS uStatus;
ULONG uNwError;//Optional. Only used for network operations.
WWAN_XXX XxxStruct;
} NDIS_WWAN_XXX, *PNDIS_WWAN_XXX;
Un valore pari a zero nel membro RequestId della struttura NDIS_STATUS_INDICATION indica che si tratta di una notifica di evento non richiesta e può verificarsi in qualsiasi momento.
Se il membro uStatus nell'indicazione restituita di qualsiasi set o richiesta OID di query non è uguale a WWAN_STATUS_SUCCESS, i membri della struttura associata NDIS_WWAN_XXX potrebbero non essere validi.
Nel caso di notifiche di eventi non richieste basati su eventi di rete, i driver miniport devono compilare il membro uNwError come appropriato, se applicabile.
La tabella seguente illustra i valori di errore dei codici di registrazione, attacco di pacchetti e distacco di pacchetti definiti nella specifica 3GPP TS 24.008 per le reti basate su GSM:
| 3GPP 24.008 Causa codice | Interpretazione del codice della causa |
|---|---|
2 - International Mobile Subscriber Identity (IMSI) non riconosciuto nell'HLR |
La SIM o il dispositivo non è attivato oppure la sottoscrizione è scaduta, che ha causato una disattivazione della rete. |
4 - IMSI sconosciuto in VLR |
La funzionalità di roaming non è attivata. |
6 - ME illegale |
MS bloccato dalla rete a causa di report rubati. |
7 - Servizi GPRS non consentiti |
L'utente non dispone di un abbonamento GPRS. L'utente ha solo una sottoscrizione di connessione vocale. |
8 - Servizi GPRS e non-GPRS non consentiti |
I servizi GPRS e non-GPRS non sono consentiti. |
11 - PLMN non consentito |
Il servizio è bloccato dalla rete a causa di una sottoscrizione scaduta o di un'altra causa. |
12 - Area di posizione non consentita |
La sottoscrizione utente non consente l'accesso nell'area di posizione corrente. |
13 - Roaming non consentito in questa area |
La sottoscrizione consente il roaming, ma il roaming non è consentito nell'area di posizione corrente. |
14 - I servizi GPRS non sono consentiti in questa rete mobile pubblica. |
Il provider di rete selezionato non fornisce il servizio GPRS alla MS. |
15 - Nessuna cella adatta nell'area di posizione |
Nessuna sottoscrizione per il servizio. |
17 - Errore di rete |
Registrazione non riuscita. |
22 - Congestione |
La registrazione non è riuscita a causa della congestione della rete. |
Ad esempio, se la rete avvia un evento di disattivazione del contesto perché il roaming non è consentito nell'area di posizione, i driver miniport devono impostare il membro uNwError su 13 conformemente ai Codici di causa del 3GPP TS 24.008 per le reti basate su GSM.
È consigliabile applicare logica simile anche alle reti basate su CDMA. Tuttavia, non esiste uno standard per i codici di errore di rete basati su CDMA. I dispositivi basati su CDMA devono usare il -specific di rete o i codici di errore specifici del dispositivo.
Nel caso di una risposta asincrona di un driver miniport alle richieste OID, il membro RequestId della struttura NDIS_STATUS_INDICATION è un numero diverso da zero passato al driver miniport come parte di un set o query. Il driver miniport deve riempire il membro uStatus in base alle esigenze. Ad esempio, WWAN_STATUS_SUCCESS o uno dei valori di errore appropriati elencati nella sezione seguente. Oltre a questo, il driver miniport deve compilare il uNwError membro, se appropriato e disponibile.
Lo stato della notifica dell'evento
Nella tabella seguente sono elencati i codici WWAN_STATUS che i driver miniport MB possono specificare nel membro uStatus delle strutture di notifica degli eventi NDIS_WWAN_XXX.
| Valore | Significato |
|---|---|
WWAN_STATUS_SUCCESS |
Operazione riuscita. |
Stato_WWAN_Fallimento |
Operazione non riuscita (errore generico). |
WWAN_STATUS_BUSY |
L'operazione non è riuscita perché il dispositivo è occupato. |
WWAN_STATUS_SIM_NOT_INSERTED |
L'operazione non è riuscita perché la scheda SIM non è stata inserita completamente nel dispositivo. |
WWAN_STATUS_BAD_SIM |
L'operazione non è riuscita perché la scheda SIM non è valida e non può essere usata ulteriormente. |
WWAN_STATO_PIN_RICHIESTO |
L'operazione non è riuscita perché è necessario immettere un PIN per continuare. |
Stato WWAN: PIN disabilitato |
L'operazione non è riuscita perché il PIN è disabilitato. |
WWAN_STATO_NON_REGISTRATO |
L'operazione non è riuscita perché il dispositivo non è registrato con alcuna rete. |
WWAN_STATUS_PROVIDERS_NOT_FOUND |
L'operazione non è riuscita perché non è stato possibile trovare provider di rete. |
Stato WWAN: Nessun supporto del dispositivo |
L'operazione non è riuscita perché il dispositivo non supporta l'operazione. |
WWAN_STATUS_PROVIDER_NOT_VISIBLE |
Operazione non riuscita perché il provider di servizi non è attualmente visibile. |
WWAN_STATO_CLASSE_DATI_NON_DISPONIBILE |
L'operazione non è riuscita perché la classe di dati richiesta non era disponibile. |
STATO_WWAN_SERVIZIO_PACCHETTI_DISCONNESSO |
Operazione non riuscita perché il servizio pacchetti è scollegato. |
WWAN_STATUS_MAX_ACTIVATED_CONTEXTS |
L'operazione non è riuscita perché è stato raggiunto il numero massimo di contesti attivati. |
WWAN_STATO_NON_INIZIALIZZATO |
L'operazione non è riuscita perché il dispositivo è in fase di inizializzazione. Ripetere l'operazione dopo che lo stato di prontezza del dispositivo cambia a WwanReadyStateInitialized. |
WWAN_STATUS_CHIAMATA_VOCALE_IN_CORSO |
L'operazione non è riuscita perché è in corso una chiamata vocale. |
WWAN_STATUS_CONTEXT_NOT_ACTIVATED |
L'operazione non è riuscita perché il contesto non è attivato. |
STATO_WWAN_SERVIZIO_NON_ATTIVATO |
L'operazione non è riuscita perché il servizio non è attivato. |
WWAN_STATUS_INVALID_ACCESS_STRING |
L'operazione non è riuscita perché la stringa di accesso non è valida. |
WWAN_STATUS_INVALID_USER_NAME_PWD (Nome utente o password non validi) |
L'operazione non è riuscita perché il nome utente e/o la password specificati non sono validi. |
WWAN_STATUS_RADIO_POWER_OFF |
L'operazione non è riuscita perché la radio è attualmente spenta. |
WWAN_STATUS_PARAMETRI_NON_VALIDI |
L'operazione non è riuscita a causa di parametri non validi. |
Errore lettura stato WWAN (WWAN_STATUS_READ_FAILURE) |
L'operazione non è riuscita a causa di un errore di lettura. |
Errore Scrittura Stato WWAN |
L'operazione non è riuscita a causa di un errore di scrittura. |
Nella tabella seguente vengono illustrati i valori di stato specifici di SMS.
| Valore | Significato |
|---|---|
WWAN_STATUS_SMS_OPERATION_NOT_ALLOWED |
L'operazione SMS non è riuscita perché l'operazione non è consentita. |
Errore di memoria SMS WWAN |
L'operazione SMS non è riuscita a causa di un errore di memoria. |
WWAN_STATUS_SMS_INDICE_MEMORIA_NON_VALIDO |
L'operazione SMS non è riuscita a causa di un indice di memoria non valido: WwanSmsFlagIndex per OID_WWAN_SMS_READ. |
WWAN_STATUS_SMS_UNKNOWN_SMSC_ADDRESS |
L'operazione SMS non è riuscita perché il numero del centro servizi non è valido o sconosciuto. |
Stato di timeout rete SMS WWAN |
L'operazione SMS non è riuscita a causa di un timeout di rete. |
WWAN_STATO_MEMORIA_SMS_PIENA |
L'operazione SMS non è riuscita perché l'archivio messaggi SMS è pieno. |
Stato WWAN: Errore sconosciuto SMS |
L'operazione SMS non è riuscita a causa di un errore sconosciuto (errore generico). |
Stato WWAN: Filtro SMS non supportato |
L'operazione SMS non è riuscita perché il tipo di filtro richiesto non è supportato. |
WWAN_STATUS_SMS_MORE_DATA |
La transazione non è ancora stata completata. Alcuni dati sono stati restituiti e sono disponibili altri dati da restituire. |
WWAN_STATUS_SMS_LANG_NOT_SUPPORTED |
L'operazione SMS non è riuscita perché la lingua SMS non è supportata. Questo vale solo per i dispositivi basati su CDMA. |
WWAN_STATUS_SMS_ENCODING_NOT_SUPPORTED (codifica SMS non supportata) |
L'operazione SMS non è riuscita perché la codifica SMS non è supportata. Questo vale solo per i dispositivi basati su CDMA. |
WWAN_STATUS_FORMATO_SMS_NON_SUPPORTATO |
L'operazione SMS non è riuscita perché il formato SMS non è supportato. |
Nota Questi codici di stato specifici di WWAN vengono usati solo per le transazioni asincrone nel membro uStatus delle strutture di NDIS_WWAN_XXX.
I driver Miniport usano le notifiche degli eventi per informare il servizio MB di una modifica dello stato dell'oggetto nel dispositivo MB senza prima aver ricevuto una richiesta OID. Il servizio MB usa le notifiche degli eventi solo per aggiornare la macchina a stati.
Tenere presente che mentre NDIS serializza tutte le richieste inviate ai driver miniport, i driver miniport potrebbero non restituire le risposte nello stesso ordine. Ciò è dovuto al fatto che le richieste in coda nel driver miniport potrebbero essere elaborate in parallelo. Di conseguenza, il servizio MB garantisce che se due richieste dipendono l'una dall'altra, non invierà la seconda richiesta finché il driver miniport non completa la prima richiesta.
Notifica di modifica dello stato
In generale, i driver miniport devono sempre notificare al servizio MB lo stato aggiornato del dispositivo MB tramite notifiche transazionali o tramite notifiche di eventi non richieste. Gli scenari seguenti sono alcune eccezioni in cui i driver miniport non devono rispondere con informazioni aggiornate sullo stato. Il servizio MB può determinare lo stato aggiornato dallo stato di completamento di altre operazioni:
I driver miniport non devono inviare un'indicazione di evento NDIS_STATUS_WWAN_PIN_LIST quando lo stato del PIN cambia perché il servizio MB ha richiesto di abilitare o disabilitare il PIN.
I driver miniport non hanno bisogno di restituire l'elenco aggiornato dei contesti di cui è stato effettuato il provisioning nelle risposte transazionali alle operazioni di impostazione di OID_WWAN_PROVISIONED_CONTEXT.
I driver Miniport non devono rispondere con l'elenco aggiornato dei provider preferiti nelle risposte transazionali alle operazioni di impostazione OID_WWAN_PREFERRED_PROVIDERS . Il servizio MB può determinare queste informazioni in base all'elenco iniziale e al successo dell'operazione del set di.
I driver Miniport non devono rispondere con il valore corrente di WWAN_SMS_CONFIGURATION per le operazioni di impostazione OID_WWAN_SMS_CONFIGURATION .