Sémantique opérationnelle mb

Transactions asynchrones

Le modèle de pilote Mo suppose une sémantique opérationnelle non bloquante entre le service Mo et les pilotes miniport à l’aide du mécanisme de notification asynchrone fourni dans NDIS 6.x. Ce mécanisme permet au service MB de continuer à envoyer des requêtes OID au pilote miniport pour traitement sans attendre que l’opération actuelle se termine.

Une transaction asynchrone est une négociation à trois voies qui commence par la demande initiale, suivie d’une requête status réponse, puis terminée par une indication transactionnelle finale. La demande status réponse est provisoire dans la mesure où elle reconnaît uniquement que le conducteur du miniport a reçu la demande. L’indication asynchrone de suivi est transactionnelle en ce qu’elle signale l’achèvement de la transaction. Le pilote miniport retourne le code status ainsi que les données résultantes dans l’indication transactionnelle.

Requêtes de jeu et de requête asynchrones

La plupart des requêtes OID définies et de requête utilisées par le service Mo sont traitées de manière asynchrone. Pour plus d’informations sur les requêtes OID de définition et de requête , consultez NDIS_OID_REQUEST. La table « OID spécifiques au WWAN » de la rubrique Modèle de données MB identifie les OID qui sont traités de manière asynchrone.

Le diagramme suivant représente la séquence d’interaction d’une transaction de requête asynchrone entre le service Mo et le pilote miniport. Les étiquettes en gras représentent des identificateurs OID ou un contrôle de flux transactionnel, et les étiquettes en texte normal représentent les indicateurs importants au sein de la structure OID.

La négociation à trois voies est la même pour les requêtes de requête et de définition .

À l’exception de OID_WWAN_DRIVER_CAPS, toutes les autres demandes OID spécifiques à Mo suivent le mécanisme de transaction asynchrone pour l’échange d’informations entre les pilotes miniports et le service MB, avec les notes supplémentaires suivantes :

• Les pilotes miniport doivent immédiatement échouer une requête OID sur n’importe quelle condition d’erreur, telle qu’une requête OID non valide.

• Les pilotes miniport doivent retourner toutes les conditions d’erreur spécifiques à WWAN avec le code d’erreur correct (par exemple, WWAN_STATUS_XXX) spécifié dans le membre uStatus de la structure de notification d’événements. Les pilotes miniport doivent également renseigner correctement les membres qui suivent le membre uStatus , selon les besoins. Par exemple, les pilotes miniport doivent remplir le membre ContextState.uNwError de la structure NDIS_WWAN_CONTEXT_STATE , si disponible. Toutefois, en cas de défaillance lors du traitement d’OID liés aux codes CONFIDENTIELs, les pilotes miniports peuvent ne pas nécessairement avoir les informations d’état de code confidentiel actuelles à spécifier dans le membre PinInfo.PinState de NDIS_WWAN_PIN_INFO.

• Les pilotes miniport doivent retourner NDIS_STATUS_INDICATION_REQUIRED en tant que réponse provisoire pour toutes les requêtes OID asynchrones.

• Les pilotes miniport doivent être en mesure de distinguer les changements d’état de l’appareil provoqués par une requête OID d’autres causes. Les pilotes miniport doivent envoyer des notifications transactionnelles pour les changements d’état résultant de requêtes OID, et ils doivent envoyer des notifications d’événements non sollicités pour les changements d’état provenant d’autres causes.

• Les pilotes Miniport sont responsables de la gestion de la mémoire en mode noyau, bien que le service Mo alloue initialement la mémoire pour les requêtes. Une fois que le service MB reçoit une réponse d’un pilote miniport, le service peut libérer la mémoire en mode utilisateur qu’il a allouée pour la requête OID.

Le diagramme suivant représente la séquence d’interaction d’une transaction d’ensemble asynchrone entre le service Mo et le pilote miniport. Les étiquettes en gras représentent des identificateurs OID ou un contrôle de flux transactionnel, et les étiquettes en texte normal représentent les indicateurs importants au sein de la structure OID.

Réponse asynchrone

La spécification NDIS 6.0 (publiée avec Windows Vista) a introduit un nouveau code status, NDIS_STATUS_INDICATION_REQUIRED, permettant aux pilotes miniports de transmettre la nature asynchrone d’une transaction au service MB dans la réponse provisoire d’un pilote miniport à une requête OID.

Comme indiqué dans Vue d’ensemble de l’interface Mo, le service MO n’a pas d’accès direct à la mémoire en mode noyau allouée par un pilote miniport Mo. Le résultat d’exécution stocké dans la mémoire en mode noyau est supposé être copié et mis à la disposition du service Mo par un intermédiaire, tel que WMI ou un pilote de filtre NDIS. Par conséquent, les pilotes miniport peuvent libérer la mémoire allouée en mode noyau une fois que l’appel de fonction NdisMIndicateStatusEx est retourné dans l’indication transactionnelle.

Les procédures d’établissement d’une liaison que les pilotes miniport et le service MB doivent suivre sont décrites dans la procédure suivante.

Procédure de pilote miniport Mo

Lors de la réception d’une demande OID, les pilotes miniport doivent effectuer les étapes suivantes :

1. Allouez de la mémoire en mode noyau pour copier le contenu de la structure de données NDIS_OID_REQUEST associée à la requête OID.

2. Parmi les paramètres de la requête, assurez-vous que les membres RequestId et RequestHandle de la structure de requête OID sont également copiés. Ces membres seront utilisés ultérieurement dans l’indication transactionnelle.

3. Retourne une réponse NDIS_STATUS_INDICATION_REQUIRED status provisoire pour informer le service MB que le pilote miniport effectue la requête de manière asynchrone.

4. Une fois l’opération terminée, stockez le résultat dans la mémoire locale ou allouée au pilote, le cas échéant.

5. Appelez la fonction NdisMIndicateStatusEx pour informer le service MB que l’opération en attente est terminée. Les pilotes miniport doivent renseigner les membres de la structure NDIS_STATUS_INDICATION comme suit :

   1. Définissez le membre StatusCode sur le type de notification status. Par exemple, NDIS_STATUS_WWAN_XXX.
   2. Définissez le membre DestinationHandle sur le membre RequestHandle qui a été reçu dans la structure de données NDIS_OID_REQUEST lorsque le pilote miniport a reçu la requête OID correspondante.
   3. Définissez le membre RequestId pour qu’il corresponde au membre RequestId de la structure NDIS_OID_REQUEST status lorsque le pilote miniport a reçu la requête OID correspondante.
   4. Définissez les membres StatusBuffer et StatusBufferSize pour qu’ils pointent vers la mémoire allouée au pilote miniport et la taille de la mémoire tampon, respectivement. Cette mémoire tampon contient le résultat de l’opération terminée.
   5. Si l’opération se termine correctement, définissez le membre uStatus sur WWAN_STATUS_SUCCESS. Sinon, définissez le membre uStatus sur la valeur WWAN_STATUS_XXX appropriée pour indiquer le type de défaillance.

6. Lorsque l’appel de fonction est retourné, le pilote miniport doit libérer la mémoire qu’il a allouée pour la requête OID.

Procédure de service MB

Le service MB traite les transactions asynchrones à l’aide de la procédure suivante :

1. Allouez la mémoire tampon pour la requête en fonction de la structure de données OID. Renseignez les membres de la structure de données avec les valeurs appropriées.

2. Appelez la fonction NdisOidRequest avec le membre InformationBuffer pointant vers la structure de données OID pour la requête OID et attendez que le pilote miniport réponde.

3. À la réception d’une réponse provisoire NDIS_STATUS_INDICATION_REQUIRED du pilote miniport, le service MB enregistre l’id de requête, libère la mémoire allouée et marque la transaction comme ouverte. À ce stade, le service MB est libre de traiter les demandes et notifications OID suivantes.

4. À la réception d’une notification avec NDIS_STATUS_WWAN_XXX comme valeur StatusCode, case activée si le RequestId correspond à celui de toute transaction marquée comme ouverte. S’il existe une correspondance, le service ferme la transaction. Si aucune correspondance n’est trouvée, traitez la notification comme une notification d’événement non sollicité.

5. Traitez les données retournées dans le membre StatusBuffer et apportez des modifications d’état au service MB le cas échéant.

Indications

Il existe deux types d’indications spécifiques à WWAN que les pilotes miniports peuvent générer :

• Notifications d’événements qui résultent d’un changement d’état d’objet dans l’appareil Mo.

• Notifications transactionnelles signalant l’achèvement d’une opération asynchrone.

Dans les deux cas, les pilotes miniport doivent appeler la fonction NdisMIndicateStatusEx.

Notification d'événement

La notification d’événement n’est pas sollicitée dans le sens où le pilote miniport envoie de manière proactive l’indication au service MB en tant qu’événement de changement d’état. Le changement d’état est dû à une action d’une entité autre que le service Mo. Le service MB suppose que les pilotes miniports sont en mesure de détecter la cause de la modification.

Pour toute notification d’événement spécifique à WWAN, les pilotes miniport doivent définir le membre RequestId de la structure NDIS_STATUS_INDICATION sur zéro. Le membre StatusCode spécifie l’objet de l’appareil Mo qui a été modifié. Le pilote miniport peut définir cet objet sur l’une des valeurs suivantes :

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

Le service MB peut également traiter d’autres notifications d’événements à partir de NDIS. Ces notifications d’événements autres que Mo ne sont pas nécessairement soumises à l’exigence que leurs valeurs RequestId soient définies sur zéro.

Notifications transactionnelles

Les pilotes Miniport utilisent des notifications transactionnelles pour informer le service Mo qu’une transaction asynchrone est terminée, et le service Mo utilise des notifications transactionnelles pour fermer les transactions ouvertes et mettre à jour son ordinateur d’état.

Le service Mo attend des notifications transactionnelles afin de pouvoir fermer les transactions ouvertes. Il s’agit de l’échange final de l’établissement d’une liaison triple entre le service Mb et le pilote miniport dans une transaction asynchrone. La valeur du membre RequestId du NDIS_STATUS_INDICATION dans toute notification transactionnelle doit être différente de zéro, qui est copiée à partir de la requête correspondante dans la même transaction.

Vous devez définir correctement le membre RequestId de la structure NDIS_STATUS_INDICATION pour que le mécanisme asynchrone fonctionne correctement. Le service Mo garantit que la valeur RequestId est unique et différente de zéro parmi toutes les demandes en attente. Les pilotes Miniport doivent retourner la même valeur RequestId dans l’indication correspondante pour que le service Mo corrèle l’indication avec une transaction ouverte.

Structure d’indication d’état

La réponse asynchrone pour une demande OID donnée et les structures de notification d’événements non sollicitées partagent les membres de structure suivants qui sont pointés par le membre StatusBuffer du paramètre StatusIndication vers 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;

La valeur zéro dans le membre RequestId de la structure NDIS_STATUS_INDICATION signifie qu’il s’agit d’une notification d’événement non sollicité qui peut se produire à tout moment.

Si le membre uStatus dans l’indication retournée d’une requête OID de jeu ou de requête n’est pas égal WWAN_STATUS_SUCCESS les membres de la structure NDIS_WWAN_XXX associée n’ont pas besoin d’être valides.

Dans le cas de notifications d’événements non sollicités basées sur des événements réseau, les pilotes miniport doivent renseigner le membre uNwError comme il convient, le cas échéant.

Le tableau suivant montre les valeurs d’inscription, d’attachement de paquets et de détachement de paquets qui sont définies dans la spécification 3GPP TS 24.008 pour les réseaux gsm :

Par exemple, si le réseau lance un événement de contexte de désactivation parce que l’itinérance n’est pas autorisée dans la zone d’emplacement, les pilotes miniport doivent définir le membre uNwError sur 13 conformément aux codes de cause 3GPP TS 24.008 pour les réseaux gsm.

Une logique similaire doit également être appliquée aux réseaux basés sur CDMA. Toutefois, il n’existe aucune norme pour les codes d’erreur réseau basés sur CDMA. Les appareils basés sur CDMA doivent utiliser les codes d’erreur spécifiques au réseau ou à l’appareil.

Dans le cas d’une réponse asynchrone d’un pilote miniport aux requêtes OID, le membre RequestId de la structure NDIS_STATUS_INDICATION est un nombre différent de zéro qui a été passé au pilote miniport dans le cadre d’une demande de jeu ou de requête . Le pilote miniport doit remplir le membre uStatus comme il convient. Par exemple, WWAN_STATUS_SUCCESS ou l’une des valeurs d’erreur appropriées répertoriées dans la section suivante. En outre, le pilote miniport doit renseigner le membre uNwError le cas échéant et disponible.

État de la notification d’événement

Le tableau suivant répertorie les codes WWAN_STATUS que les pilotes de miniport mo peuvent spécifier dans le membre uStatus des structures de notification d’événements NDIS_WWAN_XXX.

Le tableau suivant montre les valeurs status spécifiques à SMS.

Note Ces codes de status spécifiques à WWAN sont utilisés uniquement pour les transactions asynchrones dans le membre uStatus des structures NDIS_WWAN_XXX.

Les pilotes Miniport utilisent des notifications d’événements pour informer le service MO d’un changement d’état d’objet dans leur appareil Mo sans avoir reçu au préalable une demande OID. Le service MB utilise des notifications d’événements pour mettre à jour son ordinateur d’état uniquement.

N’oubliez pas que même si NDIS sérialise toutes les demandes envoyées aux pilotes miniport, les pilotes miniports peuvent ne pas retourner les réponses dans le même ordre. Cela est dû au fait que les demandes mises en file d’attente dans le pilote miniport peuvent être traitées en parallèle. Par conséquent, le service MB garantit que si deux requêtes dépendent l’une de l’autre, il n’enverra pas la deuxième requête tant que le pilote miniport n’aura pas terminé la première requête.

Notification de changement d’état

En règle générale, les pilotes miniport doivent toujours informer le service MB de l’état mis à jour de leur appareil Mo par le biais de notifications transactionnelles ou de notifications d’événements non sollicités. Les scénarios suivants sont quelques exceptions où les pilotes miniport ne sont pas censés répondre avec des informations d’état mises à jour. Le service MB peut déterminer l’état mis à jour à partir de la status d’achèvement d’autres opérations :

1. Les pilotes miniport n’ont pas besoin d’envoyer une indication d’événement NDIS_STATUS_WWAN_PIN_LIST lorsque l’état du code confidentiel change, car le service Mo a demandé d’activer ou de désactiver le code confidentiel.

2. Les pilotes miniport n’ont pas besoin de retourner la liste mise à jour des contextes provisionnés dans les réponses transactionnelles aux opérations de OID_WWAN_PROVISIONED_CONTEXT set .

3. Les pilotes miniport n’ont pas besoin de répondre avec la liste mise à jour des fournisseurs préférés dans les réponses transactionnelles aux opérations de OID_WWAN_PREFERRED_PROVIDERS set . Le service MB peut déterminer ces informations en fonction de la liste initiale et de la réussite status de l’opération set.

4. Les pilotes miniports n’ont pas besoin de répondre avec la valeur WWAN_SMS_CONFIGURATION actuelle pour OID_WWAN_SMS_CONFIGURATION opérations de jeu .