Semantica operativa MB

Transazioni asincrone

Il modello di driver MB presuppone una semantica operativa non bloccanti tra il servizio MB e i driver miniport usando il meccanismo di notifica asincrona 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 dello stato della richiesta è provvisoria in quanto riconosce solo che il driver miniport ha ricevuto la richiesta. L'indicazione asincrona di completamento è 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 richieste OID set e query usate dal servizio MB vengono elaborate in modo asincrono. Per altre informazioni sulle richieste OID set e query , vedere NDIS_OID_REQUEST. La tabella "ID specifici della rete WAN WWAN" nell'argomento Modello di dati MB identifica gli OID 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 set .

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 avere immediatamente esito negativo per 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 membro uStatus della struttura di notifica degli eventi. I driver Miniport devono anche compilare in modo appropriato i membri che seguono il membro uStatus , in base alle esigenze. Ad esempio, i driver miniport devono compilare il membro ContextState.uNwError della struttura NDIS_WWAN_CONTEXT_STATE , se disponibile. Tuttavia, in caso di errore durante l'elaborazione di OID correlati ai PIN, i driver miniport potrebbero non avere necessariamente le informazioni sullo stato del PIN correnti da specificare nel membro PinInfo.PinState 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 degli 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 una transazione set 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.

Risposta asincrona

La specifica NDIS 6.0 (rilasciata con Windows Vista) ha introdotto un nuovo codice di stato, NDIS_STATUS_INDICATION_REQUIRED, per consentire ai driver miniport di trasmettere la natura asincrona di una transazione al servizio MB in una risposta provvisoria del driver miniport a una richiesta OID.

Come indicato in Panoramica dell'interfaccia MB, 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 per il 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 di funzione NdisMIndicateStatusEx restituisce nell'indicazione transazionale.

Le procedure di handshake che i driver miniport e il servizio MB devono seguire sono descritte nella procedura seguente.

Procedura del driver miniport MB

Al momento della ricezione di una richiesta OID, i driver miniport devono seguire questa procedura:

1. Allocare memoria in modalità kernel per copiare il contenuto della struttura dei dati NDIS_OID_REQUEST associata alla richiesta OID.

2. Tra i parametri della richiesta, assicurarsi che vengano copiati anche i membri RequestId e RequestHandle della struttura di richiesta OID. Questi membri verranno usati più avanti nell'indicazione transazionale.

3. Restituisce una risposta provvisoria NDIS_STATUS_INDICATION_REQUIRED stato per informare il servizio MB che il driver miniport completerà la richiesta in modo asincrono.

4. Al termine dell'operazione, archiviare il risultato in memoria allocata localmente o driver, in base alle esigenze.

5. 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:

   1. Impostare il membro StatusCode sul tipo di notifica di stato. Ad esempio, NDIS_STATUS_WWAN_XXX.
   2. 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.
   3. 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.
   4. 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.
   5. Se l'operazione viene completata correttamente, impostare il membro uStatus su WWAN_STATUS_SUCCESS. In caso contrario, impostare il membro uStatus sul valore di WWAN_STATUS_XXX appropriato per indicare il tipo di errore.

6. 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 le transazioni asincrone usando la procedura seguente:

1. Allocare memoria buffer per la richiesta in base alla struttura dei dati OID. Compilare i membri della struttura dei dati con i valori appropriati.

2. Chiamare la funzione NdisOidRequest con il membro InformationBuffer che punta alla struttura di dati OID per la richiesta OID e attendere che il driver miniport risponda.

3. Al ricevimento di una NDIS_STATUS_INDICATION_REQUIRED risposta provvisoria dal driver miniport, il servizio MB salva l'ID richiesta, 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.

4. Al ricevimento di una notifica con NDIS_STATUS_WWAN_XXX come valore statusCode , verificare se 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.

5. Elaborare i dati restituiti nel membro StatusBuffer e apportare modifiche allo 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 dell'evento

La notifica degli eventi non viene 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 da 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 l'oggetto nel dispositivo MB modificato. Il driver miniport può impostare questo oggetto su uno dei valori seguenti:

NDIS_STATUS_WWAN_DEVICE_CAPS

NDIS_STATUS_WWAN_READY_INFO

NDIS_STATUS_WWAN_RADIO_STATE

NDIS_STATUS_WWAN_PIN_INFO

NDIS_STATUS_WWAN_PIN_LIST

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_SIGNAL_STATE

NDIS_STATUS_WWAN_CONTEXT_STATE

NDIS_STATUS_WWAN_PROVISIONED_CONTEXTS

NDIS_STATUS_WWAN_SERVICE_ACTIVATION

NDIS_STATUS_WWAN_SMS_CONFIGURATION

NDIS_STATUS_WWAN_SMS_RECEIVE

NDIS_STATUS_WWAN_SMS_SEND

NDIS_STATUS_WWAN_SMS_DELETE

NDIS_STATUS_WWAN_SMS_STATUS

NDIS_STATUS_WWAN_VENDOR_SPECIFIC

Il servizio MB può anche elaborare altre notifiche degli eventi da NDIS. Queste notifiche di eventi non MB non sono necessariamente soggetti al requisito che i valori RequestId siano impostati su zero.

Notifiche transazionali

I driver miniport usano notifiche transazionali per informare il servizio MB che una transazione asincrona è stata completata e il servizio MB usa le notifiche transazionali per chiudere le transazioni aperte e aggiornare il computer di stato.

Il servizio MB prevede notifiche transazionali in modo da poter chiudere le transazioni aperte. È lo scambio finale dell'handshake a tre vie tra il servizio MB e il driver miniport in una transazione asincrona. Il valore del membro RequestId del NDIS_STATUS_INDICATION in qualsiasi notifica transazionale deve essere diverso da zero, copiato dalla richiesta corrispondente nella stessa transazione.

È necessario impostare il membro RequestId della struttura NDIS_STATUS_INDICATION correttamente per il meccanismo asincrono per funzionare correttamente. 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 la risposta asincrona per una determinata richiesta OID che le strutture di notifica degli eventi non richieste condividono i membri della struttura seguenti a cui punta il membro StatusBuffer del parametro StatusIndication a 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 significa che è una notifica evento non richiesta e può verificarsi in qualsiasi momento.

Se il membro uStatus nell'indicazione restituita di qualsiasi richiesta OID di set o query non è uguale WWAN_STATUS_SUCCESS i membri della struttura NDIS_WWAN_XXX associata non devono essere validi.

Nel caso di notifiche di eventi non richieste in base agli eventi di rete, i driver miniport devono compilare il membro uNwError , se necessario.

La tabella seguente illustra i valori di errore del codice definiti nella specifica 3GPP TS 24.008 per le reti basate su GSM:

Ad esempio, se la rete avvia un evento di contesto disattivato perché il roaming non è consentito nell'area di posizione, i driver miniport devono impostare il membro uNwError su 13 in base al 3GPP TS 24.008 Cause codici per reti basate su GSM.

La logica simile deve essere applicata 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 i codici di errore specifici della rete o specifici del dispositivo.

Nel caso di una risposta asincrona del driver miniport alle richieste OID, il membro RequestId della struttura NDIS_STATUS_INDICATION è un numero non zero passato al driver miniport come parte di un set o di una richiesta di query . Il driver miniport deve riempire il membro uStatus come appropriato. 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 membro uNwError dove appropriato e disponibile.

Stato notifica eventi

Nella tabella seguente sono elencati i codici di WWAN_STATUS che i driver miniport MB possono specificare nel membro uStatus delle strutture di notifica degli eventi NDIS_WWAN_XXX.

La tabella seguente mostra i valori di stato specifici di SMS.

Nota Questi codici di stato specifici di WWAN vengono usati solo per le transazioni asincrone nel membro uStatus delle strutture NDIS_WWAN_XXX.

I driver Miniport usano le notifiche degli eventi per informare il servizio MB su una modifica dello stato dell'oggetto nel dispositivo MB senza aver prima ricevuto una richiesta OID. Il servizio MB usa le notifiche degli eventi per aggiornare solo il computer di stato.

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 tra loro, non invierà la seconda richiesta finché il driver miniport 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 eventi non richieste. Gli scenari seguenti sono alcune eccezioni in cui i driver miniport non devono rispondere con informazioni sullo stato aggiornate. Il servizio MB può determinare lo stato aggiornato dallo stato di completamento di altre operazioni:

1. I driver miniport non devono inviare un'indicazione evento NDIS_STATUS_WWAN_PIN_LIST quando si verificano modifiche dello stato del PIN perché il servizio MB richiesto per abilitare o disabilitare il PIN.

2. I driver miniport non devono restituire l'elenco aggiornato dei contesti di cui è stato effettuato il provisioning nelle risposte transazionali alle operazioni OID_WWAN_PROVISIONED_CONTEXT set .

3. I driver miniport non devono rispondere con l'elenco aggiornato dei provider preferiti nelle risposte transazionali alle operazioni OID_WWAN_PREFERRED_PROVIDERS set . Il servizio MB può determinare queste informazioni in base all'elenco iniziale e allo stato di esito positivo dell'operazione impostata .

4. I driver miniport non devono rispondere con il valore di WWAN_SMS_CONFIGURATION corrente per le operazioni del set di OID_WWAN_SMS_CONFIGURATION.