Sémantique opérationnelle MB

Transactions asynchrones

Le modèle de pilote MB suppose une sémantique opérationnelle non bloquante entre le service MB 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 demandes OID au pilote miniport pour le traitement sans attendre la fin de l’opération actuelle.

Une transaction asynchrone est une négociation tridirectionnelle qui commence par la requête initiale, suivie d’une réponse d’état de demande, puis terminée par une indication transactionnelle finale. La réponse d’état de la demande est provisoire car elle reconnaît uniquement que le pilote miniport a reçu la demande. L’indication asynchrone de suivi est transactionnelle dans laquelle elle signale l’achèvement de la transaction. Le pilote miniport retourne le code d'état ainsi que les données résultantes dans l'indication de transaction.

Définition et Requêtes asynchrones

La plupart des requêtes OID de définition et de requête utilisées par le service MB 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 à WWAN » dans la rubrique Mb Data Model 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 MB et le pilote miniport. Les étiquettes en gras représentent les identificateurs OID, ou le contrôle de flux transactionnel, et les étiquettes en texte normal représentent les indicateurs importants dans la structure OID.

La négociation tridirectionnelle est la même pour les requêtes et les requêtes de configuration.

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

• Les pilotes miniport doivent immédiatement refuser une requête OID en cas de toute 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énement. Les pilotes miniport doivent également renseigner correctement les membres qui suivent le membre uStatus, selon les besoins. Par exemple, les pilotes miniport doivent renseigner le membre ContextState.uNwError de la structure NDIS_WWAN_CONTEXT_STATE , le cas échéant. Toutefois, dans le cas d’un échec lors du traitement des OID liés aux NIP, il est possible que les pilotes miniports ne disposent pas nécessairement des informations d'état de NIP 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 temporaire pour toutes les requêtes OID asynchrones.

• Les pilotes miniport doivent être en mesure de distinguer les modifications d’état de l’appareil causées par une requête OID d’autres causes. Les pilotes miniport doivent envoyer des notifications transactionnelles pour les modifications d’état résultant des demandes OID, et ils doivent envoyer des notifications d’événements non sollicitées pour les modifications 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 asynchrone de set entre le MB Service et le pilote miniport. Les étiquettes en gras représentent les identificateurs OID, ou le contrôle de flux transactionnel, et les étiquettes en texte normal représentent les indicateurs importants dans la structure OID.

Réponse asynchrone

La spécification NDIS 6.0 (publiée avec Windows Vista) a introduit un nouveau code d’état, NDIS_STATUS_INDICATION_REQUIRED, pour les pilotes miniports afin de transmettre la nature asynchrone d’une transaction au service Mb dans la réponse provisoire d’un pilote miniport à une demande OID.

Comme mentionné dans La vue d’ensemble de l’interface MO, le service Mb n’a pas 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 après que l’appel de fonction NdisMIndicateStatusEx retourne dans l’indication transactionnelle.

Les protocoles d'initialisation que les pilotes miniport et le service MB doivent suivre sont décrits dans la procédure ci-dessous.

Procédure du pilote de miniport MB

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, vérifiez 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. Retournez une réponse d’état provisoire NDIS_STATUS_INDICATION_REQUIRED pour informer le service MB que le pilote miniport terminera la requête de manière asynchrone.

4. Une fois l’opération terminée, stockez le résultat en 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 a été terminée. Les pilotes miniport doivent remplir les membres de la structure NDIS_STATUS_INDICATION comme suit :

   1. Définissez le membre StatusCode sur le type de notification d’état. 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 d’état NDIS_OID_REQUEST 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 par le 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 de WWAN_STATUS_XXX appropriée pour indiquer le type d’échec.

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

Procédure de maintenance 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 sauvegarde 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. Lors de la réception d’une notification avec NDIS_STATUS_WWAN_XXX comme valeur StatusCode , vérifiez si RequestId correspond à celle d’une 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ée.

5. Traitez les données retournées dans le membre StatusBuffer et apportez des modifications d’état au service Mb selon les besoins.

Indications

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

• Notifications d’événements résultant d’un changement d’état d’objet dans l’appareil MB.

• 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 modification d’état. La modification de l’état est due à une action provenant d’une entité autre que le service MB. Le MB Service suppose que les pilotes miniport sont en mesure de détecter la cause du changement.

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 dans l’appareil Mo qui a changé. 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 non-MB ne sont pas nécessairement soumises à l’exigence que leurs valeurs RequestId soient réglées à zéro.

Notifications transactionnelles

Les pilotes miniport utilisent des notifications transactionnelles pour informer le service MB qu’une transaction asynchrone est terminée, et le service MB utilise des notifications transactionnelles pour fermer les transactions ouvertes et mettre à jour sa machine d'état.

Le service Mb attend des notifications transactionnelles afin qu’elle puisse fermer les transactions ouvertes. Il s’agit de l’échange final de la négociation tridirectionnelle entre le service MB et le pilote miniport dans une transaction asynchrone. La valeur du membre RequestId de l’NDIS_STATUS_INDICATION dans toute notification transactionnelle doit être différente de zéro, qui est copiée à partir de la demande 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 Mb 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 afin que le service Mb soit en corrélation avec une transaction ouverte.

Structure d’indication d’état

La réponse asynchrone pour une requête OID spécifique et les structures de notification d'événements non sollicités partagent les membres de structure suivants, lesquels sont pointés par le membre StatusBuffer du paramètre StatusIndication à 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ée et peut se produire à tout moment.

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

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

Le tableau suivant présente les valeurs d'échec des codes de cause pour l'enregistrement, l'attachement de paquets et le 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 désactivation de contexte car 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 de la norme 3GPP TS 24.008 pour les réseaux à base 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 CDMA doivent utiliser les codes d’erreur réseau -specific ou spécifiques à 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 non nul qui a été passé au pilote miniport au moyen d’une demande de définition ou de requête. Le pilote miniport doit remplir le membre uStatus de manière appropriée. 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 remplir le membre uNwError lorsque cela est pertinent et disponible.

État de notification d’événement

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

Le tableau suivant présente des valeurs d’état spécifiques à SMS.

Note Ces codes d’état 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 MB d’un changement d’état d’objet dans leur appareil MB sans d'abord avoir reçu une demande OID. Le service MB utilise des notifications d'événements pour mettre à jour uniquement sa machine d'état.

Soyez conscient que bien que NDIS sérialise toutes les demandes envoyées aux pilotes miniport, ces derniers peuvent ne pas retourner les réponses dans le même ordre. Cela est dû au fait que les requêtes mises en file d’attente dans le pilote miniport peuvent être traitées en parallèle. Par conséquent, le service Mo garantit que si deux requêtes dépendent les unes des autres, elle n’envoie pas la deuxième requête tant que le pilote miniport n’a pas terminé la première requête.

Notification de modification 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 MB par le biais de notifications transactionnelles ou par le biais de notifications d’événements non sollicitées. Les scénarios suivants sont quelques exceptions où les pilotes de miniport ne doivent pas répondre avec des informations d'état actualisées. Le MB Service peut déterminer l’état mis à jour à partir de l’état 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 MB a demandé l'activation ou la désactivation du 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 définition OID_WWAN_PROVISIONED_CONTEXT.

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 set OID_WWAN_PREFERRED_PROVIDERS. Le service MB peut déterminer ces informations en fonction de la liste initiale et de l’état de réussite de l’opération de réglage.

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