Schreiben eines MBBCx-Clienttreibers

Artikel
06/15/2023

Warnung

Die Sequenzdiagramme in diesem Thema dienen nur zur Veranschaulichung. Sie sind keine öffentlichen Aufträge und unterliegen künftigen Änderungen.

INF-Dateien für MBBCx-Clienttreiber

INF-Dateien für MBBCx-Clienttreiber sind identisch mit anderen NetAdapterCx-Clienttreibern. Weitere Informationen finden Sie unter INF-Dateien für NetAdapterCx-Clienttreiber.

Befolgen Sie die universelle Anleitung , um sicherzustellen, dass die INF-Dateien die universellen Anforderungen erfüllen.

Initialisieren des Geräts

Zusätzlich zu den Aufgaben, die von NetAdapterCx für die NetAdapter-Geräteinitialisierung erforderlich sind, muss ein MBB-Clienttreiber auch die folgenden Aufgaben in seiner EvtDriverDeviceAdd-Rückruffunktion ausführen:

Rufen Sie MBB_DEVICE_CONFIG_INIT nach dem Aufruf von NetDeviceInitConfig , aber vor dem Aufruf von WdfDeviceCreate auf, wobei auf dasselbe WDFDEVICE_INIT objekt verwiesen wird, das vom Framework übergeben wurde.
Rufen Sie MbbDeviceInitialize auf, um mbB-gerätespezifische Rückruffunktionen mithilfe einer initialisierten MBB_DEVICE_CONFIG-Struktur und des WDFDEVICE-Objekts zu registrieren, das von WdfDeviceCreate abgerufen wurde.

Im folgenden Beispiel wird veranschaulicht, wie das MBB-Gerät initialisiert wird. Die Fehlerbehandlung wurde aus Gründen der Übersichtlichkeit ausgelassen.

    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);

Im Gegensatz zu anderen Typen von NetAdapterCx-Treibern dürfen MBB-Clienttreiber das NETADAPTER-Objekt nicht aus der Rückruffunktion EvtDriverDeviceAdd erstellen. Stattdessen wird es von MBBCx angewiesen, dies später zu tun.

Als Nächstes muss der Clienttreiber MbbDeviceSetMbimParameters aufrufen, in der Regel in der folgenden Rückruffunktion EvtDevicePrepareHardware .

Dieses Nachrichtenflussdiagramm veranschaulicht den Initialisierungsprozess.

Diagramm, das den MBBCx-Clienttreiberinitialisierungsprozess zeigt.

Dieses Nachrichtenflussdiagramm veranschaulicht den Initialisierungsprozess.

Diagramm, das den MBBCx-Clienttreiberinitialisierungsprozess zeigt.

Behandeln von MBIM-Steuerelementmeldungen

MBBCx verwendet die MBIM-Standardsteuerungsbefehle, die in der MBIM-Spezifikation Rev 1.0( Abschnitte 8, 9 und 10) für die Steuerungsebene definiert sind. Befehle und Antworten werden über eine Reihe von Rückruffunktionen ausgetauscht, die vom Clienttreiber und von MBBCx bereitgestellten APIs bereitgestellt werden. MBBCx imitiert das Betriebsmodell eines MBIM-Geräts, wie in MBIM-Spezifikation Rev 1.0, Abschnitt 5.3 definiert, mithilfe der folgenden Funktionsaufrufe:

MBBCx sendet eine MBIM-Befehlsnachricht an den Clienttreiber, indem die Rückruffunktion EvtMbbDeviceSendMbimFragment aufgerufen wird. Der Clienttreiber schließt diese Sendeanforderung asynchron ab, indem MbbRequestComplete aufgerufen wird.
Der Clienttreiber signalisiert die Verfügbarkeit des Ergebnisses, indem er MbbDeviceResponseAvailable aufruft.
MBBCx ruft die MBIM-Antwortnachricht vom Clienttreiber ab, indem die Rückruffunktion EvtMbbDeviceReceiveMbimFragment aufgerufen wird . Der Clienttreiber schließt diese Get-Response-Anforderung asynchron ab, indem MbbRequestCompleteWithInformation aufgerufen wird.
Der MBB-Clienttreiber kann MBBCx über ein nicht angefordertes Geräteereignis benachrichtigen, indem er MbbDeviceResponseAvailable aufruft. MBBCx ruft dann die Informationen vom Clienttreiber ab, ähnlich wie beim Abrufen von MBIM-Antwortnachrichten.

Das folgende Diagramm veranschaulicht den Nachrichtenaustauschfluss des MBBCx-Client-Treibers.

Diagramm, das den MBIM-Nachrichtenaustausch zwischen MBBCx und dem Clienttreiber zeigt.

Synchronisierung von MBIM-Steuernachrichten

Das MBBCx-Framework serialisiert Aufrufe immer in den Rückruffunktionen EvtMbbDeviceSendMbimFragment und EvtMbbDeviceReceiveMbimFragment des Clienttreibers . Es werden keine neuen Aufrufe vom Framework ausgeführt, bis der Clienttreiber mbbRequestComplete oder MbbRequestCompleteWithInformation aufruft.

Während ein Clienttreiber garantiert keine überlappenden EvtMbbDeviceSendMbimFragment - oder EvtMbbDeviceReceiveMbimFragment-Rückrufe empfängt , erhält er möglicherweise mehrere Aufrufe nacheinander, bevor die Antwort für einen vorherigen Befehl vom Gerät verfügbar ist.

Wenn sich das Gerät nicht im D0-Zustand befindet, bringt das MBBCx-Framework das Gerät zunächst zu D0 (d. h. es ruft EvtDeviceD0Entry auf), bevor evtMbbDeviceSendMbimFragment oder EvtMbbDeviceReceiveMbimFragment aufgerufen wird. Das MBBCx-Framework garantiert auch, dass das Gerät im D0-Zustand beibehalten wird, d. h . evtDeviceD0Exit wird erst aufgerufen, wenn der Client MbbRequestComplete oder MbbRequestCompleteWithInformation aufruft.

Erstellen der NetAdapter-Schnittstelle für den PDP-Kontext/EPS-Bearer

Vor dem Einrichten einer Datensitzung weist MBBCx den Clienttreiber an, ein NETADAPTER-Objekt zu erstellen, und es wird von MBBCx verwendet, um die Netzwerkschnittstelle für die aktivierte Datensitzung darzustellen. Dies wird erreicht, indem MBBCx die Rückruffunktion EvtMbbDeviceCreateAdapter des Clienttreibers aufruft.

In der Implementierung der Rückruffunktion EvtMbbDeviceCreateAdapter muss der MBBCx-Clienttreiber zunächst die gleichen Aufgaben ausführen, die zum Erstellen eines NETADAPTER-Objekts erforderlich sind wie jeder NetAdapterCx-Clienttreiber. Darüber hinaus müssen die folgenden zusätzlichen Aufgaben ausgeführt werden:

Rufen Sie MbbAdapterInitialize für das von NetAdapterCreate erstellte NETADAPTER-Objekt auf.
Rufen Sie nach dem Aufruf von MbbAdapterinitializeMbbAdapterGetSessionId auf, um die Datensitzungs-ID erneut anzuzeigen, für die MBBCx dieses NETADAPTER-Objekt verwenden möchte. Wenn der zurückgegebene Wert beispielsweise 0 ist, bedeutet dies, dass MBBCx diese NETADAPTER-Schnittstelle für die Datensitzung verwendet, die vom primären PDP-Kontext bzw. standardmäßigen EPS-Bearer eingerichtet wurde.
Es wird empfohlen, dass MBBCx-Clienttreiber eine interne Zuordnung zwischen dem erstellten NETADAPTER-Objekt und der zurückgegebenen SessionId beibehalten. Dies hilft beim Nachverfolgen der Datensitzung-zu-NETADAPTER-Objektbeziehung, die besonders nützlich ist, wenn mehrere PDP-Kontexte/EPS-Bearer aktiviert wurden.
Vor der Rückkehr von EvtMbbDeviceCreateAdapter müssen Clienttreiber den Adapter starten, indem sie NetAdapterStart aufrufen. Optional können sie auch die Funktionen des Adapters festlegen, indem sie vor dem Aufruf von NetAdapterStart eine oder mehrere dieser Funktionen aufrufen:

MBBCx ruft diese Rückruffunktion mindestens einmal auf, sodass immer ein NETADPATER-Objekt für den primären PDP-Kontext bzw. den standardmäßigen EPS-Bearer vorhanden ist. Wenn mehrere PDP-Kontexte/EPS-Bearer aktiviert sind, ruft MBBCx diese Rückruffunktion möglicherweise mehrmals auf, einmal für jede zu erstellende Datensitzung. Es muss eine 1:1-Beziehung zwischen der durch das NETADAPTER-Objekt dargestellten Netzwerkschnittstelle und einer Datensitzung bestehen, wie im folgenden Diagramm dargestellt.

Diagramm, das mehrere NETADAPTER-Objekte für verschiedene Datensitzungen zeigt.

Das folgende Beispiel zeigt, wie Sie ein NETADAPTER-Objekt für eine Datensitzung erstellen. Beachten Sie, dass Fehlerbehandlung und Code, der zum Einrichten von Adapterfunktionen erforderlich ist, aus Gründen der Übersichtlichkeit und Übersichtlichkeit weggelassen werden.

    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;
    }

Ein Codebeispiel zum Festlegen von Datapath-Funktionen finden Sie unter Netzwerkdatenpufferverwaltung.

MBBCx garantiert, dass EvtMbbDeviceCreateAdapter aufgerufen wird, bevor MBIM_CID_CONNECT mit derselben Sitzungs-ID angefordert wird. Das folgende Flussdiagramm zeigt die Interaktionen zwischen dem Clienttreiber und der Klassenerweiterung beim Erstellen des NETADAPTER-Objekts.

Diagramm, das die NETADAPTER-Erstellung und -Aktivierung für einen MBB-Clienttreiber zeigt.

Der Flow zum Erstellen des NETADAPTER-Objekts für den primären PDP-Kontext bzw. den standardmäßigen EPS-Bearer wird von MBBCx initiiert, wenn EvtDevicePrepareHardware erfolgreich abgeschlossen wurde.

Der Flow zum Erstellen des NETADAPTER-Objekts für den sekundären PDP-Kontext/dedizierten EPS-Bearer wird von WwanSvc ausgelöst, wenn Bedarfsverbindungen von Anwendungen angefordert werden.

Lebensdauer des NETADAPTER-Objekts

Das vom Clienttreiber erstellte NETADAPTER-Objekt wird von MBBCx automatisch zerstört, wenn es nicht mehr verwendet wird. Dies geschieht beispielsweise, nachdem zusätzliche PDP-Kontext-/EPS-Bearer deaktiviert wurden. MBBCx-Clienttreiber dürfen WdfObjectDelete nicht für die von ihnen erstellten NETADAPTER-Objekte aufrufen.

Wenn ein Clienttreiber Kontextdaten sauber muss, die an ein NETADAPTER-Objekt gebunden sind, sollte er beim Aufrufen von NetAdapterCreate eine EvtDestroyCallback-Funktion in der Objektattributestruktur bereitstellen.

Energieverwaltung des MBB-Geräts

Für die Energieverwaltung sollten Clienttreiber das NETPOWERSETTINGS-Objekt wie andere Typen von NetAdapterCx-Clienttreibern verwenden.

Behandeln von Gerätedienstsitzungen

Wenn eine Anwendung DSS-Daten an das Modemgerät sendet, ruft MBBCx die Rückruffunktion EvtMbbDeviceSendServiceSessionData des Clienttreibers auf. Der Clienttreiber sollte die Daten dann asynchron an das Gerät senden und MbbDeviceSendDeviceServiceSessionDataComplete aufrufen, sobald die Übermittlung abgeschlossen ist, damit MBBCx dann den für die Daten zugeordneten Arbeitsspeicher freigeben kann.

Umgekehrt ruft der Clienttreiber MbbDeviceReceiveDeviceServiceSessionData auf, um alle Daten über MBBCx an die Anwendung zu übergeben.

Anforderungen für Windows-Treiber

Einhaltung der DCH-Entwurfsprinzipien
Befolgen Sie die Prinzipien der Treiberpaketisolation .
Api Layering-Anforderungen befolgen
Zertifizieren mit dem Zertifizierungsprozess für das Windows-Hardwarekompatibilitätsprogramm mithilfe des Hardware Lab Kits

Freigeben über