Écrire un pilote client MBBCx

Fichiers INF pour les pilotes clients MBBCx

Les fichiers INF pour les pilotes clients MBBCx sont identiques aux autres pilotes clients NetAdapterCx. Pour plus d’informations, consultez les 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 du dispositif NetAdapter, un pilote client MBB doit également effectuer les tâches suivantes dans sa fonction de rappel EvtDriverDeviceAdd :

1. Appelez MBB_DEVICE_CONFIG_INIT après avoir appelé NetDeviceInitConfig , mais avant d’appeler WdfDeviceCreate, référençant le même objet WDFDEVICE_INIT passé par l’infrastructure.

2. Appelez MbbDeviceInitialize pour inscrire des fonctions de rappel spécifiques à l’appareil MBB à l’aide d’une structure de 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é écartée pour plus 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 à d’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 donnera instruction de le faire plus tard.

Ensuite, le pilote client doit appeler MbbDeviceSetMbimParameters, généralement dans la fonction de rappel EvtDevicePrepareHardware qui suit.

Ce diagramme de flux de message illustre le processus d’initialisation.

Ce diagramme de flux de message 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, les 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 de façon asynchrone cette demande d’envoi 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 termine de façon asynchrone cette demande get-response en appelant MbbRequestCompleteWithInformation.
• Le pilote client MBB peut notifier 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 que la façon dont il extrait 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 ne sera effectué par l’infrastructure tant que le pilote client n’appellera pas MbbRequestComplete ou MbbRequestCompleteWithInformation.

Bien qu’un pilote client ne reçoive pas de rappels EvtMbbDeviceSendMbimFragment ou EvtMbbDeviceReceiveMbimFragment superposés, il peut recevoir plusieurs appels en succession avant que la réponse d’une commande précédente soit disponible à partir de l’appareil.

Si l’appareil n’est pas dans l’état D0 , le framework MBBCx amène d’abord l’appareil à D0 (en d’autres termes, il appelle EvtDeviceD0Entry) avant d’appeler EvtMbbDeviceSendMbimFragment ou EvtMbbDeviceReceiveMbimFragment. Le framework MBBCx garantit également qu’il conservera l’appareil dans 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 porteur PDP context/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 de 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 nécessaires pour créer un objet NETADAPTER que tout pilote client NetAdapterCx. En outre, elle doit également effectuer les tâches supplémentaires suivantes :

1. Appelez MbbAdapterInitialize sur l’objet NETADAPTER créé par NetAdapterCreate.

2. Après avoir appelé MbbAdapterinitialize, appelez MbbAdapterGetSessionId pour récupérer l’ID de session de données pour lequel MBBCx envisage d’utiliser cet objet NETADAPTER. Par exemple, si la valeur retournée est 0, cela signifie que MBBCx utilise cette interface NETADAPTER pour la session de données établie par le porteur PDP principal/porteur EPS par défaut.

3. Il est recommandé que les pilotes clients MBBCx maintiennent un mappage interne entre l'objet NETADAPTER créé et le SessionId retourné. Cela permet de suivre la relation entre les objets de session et NETADAPTER, ce qui est particulièrement utile lorsque plusieurs contextes PDP et porteurs EPS ont été activés.

4. Avant de revenir de EvtMbbDeviceCreateAdapter, les pilotes clients doivent démarrer l’adaptateur en appelant NetAdapterStart. Si vous le souhaitez, ils peuvent également définir les fonctionnalités de l’adaptateur en appelant une ou plusieurs de ces fonctions avant d' l’appel à NetAdapterStart:

   • NetAdapterSetDatapathCapabilities
   • NetAdapterSetLinkLayerCapabilities
   • NetAdapterSetLinkLayerMtuSize

MBBCx appelle cette fonction de rappel (callback function) au moins une fois, de sorte qu'il y ait toujours un objet NETADAPTER pour le contexte PDP principal ou le porteur EPS par défaut. Si plusieurs contextes PDP/porteurs EPS sont activés, MBBCx peut appeler cette fonction de rappel plusieurs 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 la configuration des fonctionnalités de l’adaptateur sont laissés à l’écart pour la concision et la 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 montrant comment définir des fonctionnalités de chemin de données, consultez la gestion des mémoires tampons 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 initié par MBBCx lorsque EvtDevicePrepareHardware a terminé avec succès.

Le flux de création de l’objet NETADAPTER pour le porteur PDP secondaire/porteur EPS dédié est déclenché par WwanSvc chaque fois que les 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 une fois que des porteurs contexte PDP/EPS supplémentaires sont désactivés. Les pilotes clients MBBCx ne doivent pas appeler WdfObjectDelete sur les objets NETADAPTER qu’ils créent.

Si un pilote client doit nettoyer les 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 à l’appareil 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é, de sorte que MBBCx peut 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.

Exigences de conformité pour les pilotes Windows

• Respecter les principes de conception DCH
• Suivez les principes d’isolation des packages de pilotes
• Respecter les exigences de superposition d'API
• Certifiez-vous grâce au processus de certification du programme de compatibilité matérielle Windows à l’aide du Kit de laboratoire de matériel