Écriture d’un pilote client MBBCx
Avertissement
Les diagrammes de séquence de cette rubrique sont à des fins d’illustration uniquement. Il ne s’agit pas de marchés publics et sont susceptibles de changer à l’avenir.
Fichiers INF pour les pilotes clients MBBCx
Les fichiers INF pour les pilotes clients MBBCx sont identiques à d’autres pilotes clients NetAdapterCx. Pour plus d’informations, consultez Fichiers INF pour les pilotes clients NetAdapterCx.
Suivez les instructions universelles pour vous assurer que les fichiers INF répondent aux exigences universelles.
Initialiser l’appareil
Outre les tâches requises par NetAdapterCx pour l’initialisation d’appareil NetAdapter, un pilote client MBB doit également effectuer les tâches suivantes dans sa fonction de rappel EvtDriverDeviceAdd :
Appelez MBB_DEVICE_CONFIG_INIT après avoir appelé NetDeviceInitConfig , mais avant d’appeler WdfDeviceCreate, en référençant le même WDFDEVICE_INIT objet transmis par l’infrastructure.
Appelez MbbDeviceInitialize pour inscrire des fonctions de rappel spécifiques aux appareils MBB à l’aide d’une structure MBB_DEVICE_CONFIG initialisée et de l’objet WDFDEVICE obtenu à partir de WdfDeviceCreate.
L’exemple suivant montre comment initialiser l’appareil MBB. La gestion des erreurs a été laissée de côté pour des motifs de clarté.
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);
Contrairement aux autres types de pilotes NetAdapterCx, les pilotes clients MBB ne doivent pas créer l’objet NETADAPTER à partir de la fonction de rappel EvtDriverDeviceAdd . Au lieu de cela, MBBCx lui demandera de le faire ultérieurement.
Ensuite, le pilote client doit appeler MbbDeviceSetMbimParameters, généralement dans la fonction de rappel EvtDevicePrepareHardware qui suit.
Ce diagramme de flux de messages illustre le processus d’initialisation.
Ce diagramme de flux de messages illustre le processus d’initialisation.
Gestion des messages de contrôle MBIM
MBBCx utilise les commandes de contrôle MBIM standard définies dans la spécification MBIM Rev 1.0, sections 8, 9 et 10, pour le plan de contrôle. Les commandes et les réponses sont échangées via un ensemble de fonctions de rappel fournies par le pilote client et les API fournies par MBBCx. MBBCx imite le modèle opérationnel d’un appareil MBIM, tel que défini dans la spécification MBIM Rev 1.0, section 5.3, à l’aide des appels de fonction suivants :
- MBBCx envoie un message de commande MBIM au pilote client en appelant sa fonction de rappel EvtMbbDeviceSendMbimFragment . Le pilote client termine cette demande d’envoi de manière asynchrone en appelant MbbRequestComplete.
- Le pilote client signale la disponibilité du résultat en appelant MbbDeviceResponseAvailable.
- MBBCx extrait le message de réponse MBIM du pilote client en appelant sa fonction de rappel EvtMbbDeviceReceiveMbimFragment . Le pilote client effectue de manière asynchrone cette demande get-response en appelant MbbRequestCompleteWithInformation.
- Le pilote client MBB peut informer MBBCx d’un événement d’appareil non sollicité en appelant MbbDeviceResponseAvailable. MBBCx récupère ensuite les informations du pilote client de la même façon qu’il récupère les messages de réponse MBIM.
Le diagramme suivant illustre le flux d’échange de messages du pilote client MBBCx.
Synchronisation des messages de contrôle MBIM
L’infrastructure MBBCx sérialise toujours les appels dans les fonctions de rappel EvtMbbDeviceSendMbimFragment et EvtMbbDeviceReceiveMbimFragment du pilote client. Aucun nouvel appel n’est effectué par l’infrastructure tant que le pilote client n’appelle pas MbbRequestComplete ou MbbRequestCompleteWithInformation.
Bien qu’un pilote client ne reçoive pas de rappels EvtMbbDeviceSendMbimFragment ou EvtMbbDeviceReceiveMbimFragment , il peut recevoir plusieurs appels successivement avant que la réponse d’une commande précédente soit disponible à partir de l’appareil.
Si l’appareil n’est pas à l’état D0 , l’infrastructure MBBCx l’amène d’abord sur D0 (en d’autres termes, elle appelle EvtDeviceD0Entry) avant d’appeler EvtMbbDeviceSendMbimFragment ou EvtMbbDeviceReceiveMbimFragment. L’infrastructure MBBCx garantit également qu’elle maintient l’appareil à l’état D0, ce qui signifie qu’il n’appellera pas EvtDeviceD0Exit, tant que le client n’appelle pas MbbRequestComplete ou MbbRequestCompleteWithInformation.
Création de l’interface NetAdapter pour le contexte PDP/porteur EPS
Avant d’établir une session de données, MBBCx demande au pilote client de créer un objet NETADAPTER et il sera utilisé par MBBCx pour représenter l’interface réseau pour la session de données activée. Pour ce faire, MBBCx appelle la fonction de rappel EvtMbbDeviceCreateAdapter du pilote client.
Dans l’implémentation de la fonction de rappel EvtMbbDeviceCreateAdapter , le pilote client MBBCx doit d’abord effectuer les mêmes tâches requises pour créer un objet NETADAPTER que tout pilote client NetAdapterCx. En outre, il doit également effectuer les tâches supplémentaires suivantes :
Appelez MbbAdapterInitialize sur l’objet NETADAPTER créé par NetAdapterCreate.
Après avoir appelé MbbAdapterinitialize, appelez MbbAdapterGetSessionId pour récupérer l’ID de session de données pour lequel MBBCx a l’intention d’utiliser cet objet NETADAPTER. Par exemple, si la valeur retournée est 0, cela signifie que MBBCx utilisera cette interface NETADAPTER pour la session de données établie par le contexte PDP principal/le porteur EPS par défaut.
Nous recommandons que les pilotes clients MBBCx conservent un mappage interne entre l’objet NETADAPTER créé et le SessionId retourné. Cela permet de suivre la relation entre l’objet session de données et NETADAPTER, ce qui est particulièrement utile lorsque plusieurs contextes PDP/porteurs EPS ont été activés.
Avant de retourner à partir d’EvtMbbDeviceCreateAdapter, les pilotes clients doivent démarrer l’adaptateur en appelant NetAdapterStart. Éventuellement, ils peuvent également définir les fonctionnalités de l’adaptateur en appelant une ou plusieurs de ces fonctions avant l’appel à NetAdapterStart :
MBBCx appelle cette fonction de rappel au moins une fois, de sorte qu’il existe toujours un objet NETADPATER pour le contexte PDP principal/porteur EPS par défaut. Si plusieurs contextes PDP/porteurs EPS sont activés, MBBCx peut appeler cette fonction de rappel plus de fois, une fois pour chaque session de données à établir. Il doit y avoir une relation un-à-un entre l’interface réseau représentée par l’objet NETADAPTER et une session de données, comme illustré dans le diagramme suivant.
L’exemple suivant montre comment créer un objet NETADAPTER pour une session de données. Notez que la gestion des erreurs et le code requis pour configurer les fonctionnalités de l’adaptateur sont laissés de côté par souci de concision et de clarté.
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;
}
Pour obtenir un exemple de code de définition des fonctionnalités de chemin de données, consultez Gestion de la mémoire tampon de données réseau.
MBBCx garantit qu’il appelle EvtMbbDeviceCreateAdapter avant de demander MBIM_CID_CONNECT avec le même ID de session. Le diagramme de flux suivant montre les interactions entre le pilote client et l’extension de classe lors de la création de l’objet NETADAPTER.
Le flux de création de l’objet NETADAPTER pour le contexte PDP principal/le porteur EPS par défaut est lancé par MBBCx lorsque EvtDevicePrepareHardware s’est terminé avec succès.
Le flux de création de l’objet NETADAPTER pour le contexte PDP secondaire/le porteur EPS dédié est déclenché par WwanSvc chaque fois que des connexions à la demande sont demandées par les applications.
Durée de vie de l’objet NETADAPTER
L’objet NETADAPTER créé par le pilote client est automatiquement détruit par MBBCx lorsqu’il n’est plus utilisé. Par exemple, cela se produit après la désactivation du contexte PDP/des porteurs EPS supplémentaires. Les pilotes clients MBBCx ne doivent pas appeler WdfObjectDelete sur les objets NETADAPTER qu’ils créent.
Si un pilote client doit propre données de contexte liées à un objet NETADAPTER, il doit fournir une fonction EvtDestroyCallback dans la structure des attributs d’objet lors de l’appel de NetAdapterCreate.
Gestion de l’alimentation de l’appareil MBB
Pour la gestion de l’alimentation, les pilotes clients doivent utiliser l’objet NETPOWERSETTINGS comme d’autres types de pilotes clients NetAdapterCx.
Gestion des sessions de service d’appareil
Lorsqu’une application envoie des données DSS au périphérique modem, MBBCx appelle la fonction de rappel EvtMbbDeviceSendServiceSessionData du pilote client. Le pilote client doit ensuite envoyer les données de manière asynchrone à l’appareil et appeler MbbDeviceSendDeviceServiceSessionDataComplete une fois l’envoi terminé, afin que MBBCx puisse libérer la mémoire allouée pour les données.
À l’inverse, le pilote client appelle MbbDeviceReceiveDeviceServiceSessionData pour transmettre toutes les données à l’application via MBBCx.
Configuration requise pour la conformité des pilotes Windows
- Respecter les principes de conception DCH
- Suivez les principes d’isolation du package de pilotes
- Suivre les exigences de la couche d’API
- Certifier avec le processus de certification du programme de compatibilité matérielle Windows à l’aide du Kit de laboratoire matériel
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour