EVT_SERCX2_CUSTOM_TRANSMIT_TRANSACTION_START Rückruffunktion (sercx.h)

Artikel
02/26/2024

Die Ereignisrückruffunktion EvtSerCx2CustomTransmitTransactionStart wird von Version 2 der seriellen Framework-Erweiterung (SerCx2) aufgerufen, um eine benutzerdefinierte Übertragungstransaktion zu starten.

Syntax

EVT_SERCX2_CUSTOM_TRANSMIT_TRANSACTION_START EvtSercx2CustomTransmitTransactionStart;

void EvtSercx2CustomTransmitTransactionStart(
  [in] SERCX2CUSTOMTRANSMITTRANSACTION CustomTransmitTransaction,
  [in] WDFREQUEST Request,
  [in] PMDL Mdl,
  [in] ULONG Offset,
  [in] ULONG Length
)
{...}

Parameter

[in] CustomTransmitTransaction

Ein SERCX2CUSTOMTRANSMITTRANSACTION Handle für ein benutzerdefiniertes Übertragungstransaktionsobjekt. Der serielle Controllertreiber hat zuvor die SerCx2CustomTransmitTransactionCreate-Methode aufgerufen, um dieses Objekt zu erstellen.

[in] Request

Ein Handle für das Frameworkanforderungsobjekt, das der Transaktion für die benutzerdefinierte Übertragung zugeordnet ist. Der Treiber ist für das Abschließen dieser Anforderung verantwortlich. Diese Anforderung ist möglicherweise nicht die IRP_MJ_WRITE Anforderung, die vom Client gesendet wird, und daher sollte der Treiber des seriellen Controllers nicht versuchen, diese Anforderung für den Zugriff auf den Schreibpuffer zu verwenden. Diese Anforderung wird in erster Linie für den Abbruch, die Vervollständigung und die Warteschlangenweiterleitung (falls erforderlich) verwendet. Verwenden Sie die Parameter Mdl, Offset und Length , um auf den Schreibpuffer für die Schreibanforderung des Clients zuzugreifen.

[in] Mdl

Ein Zeiger auf eine MDL , der die Speicherseiten beschreibt, die vom Schreibpuffer für die benutzerdefinierte Übertragungstransaktion überspannt werden. Die Punkt-/Erfassungsliste für die DMA-Übertragung verwendet den Bereich dieses Arbeitsspeichers, der durch die Parameter Offset und Length angegeben wird. Weitere Informationen zu MDL-Ketten finden Sie unter Verwenden von MDLs.

[in] Offset

Der Startoffset für die Datenübertragung. Dieser Parameter ist ein Byteoffset vom Anfang des Pufferbereichs, der von der MDL beschrieben wird. Wenn die MDL insgesamt N Byte Pufferspeicherplatz angibt, liegen die möglichen Werte von Offset im Bereich 0 bis N–1.

[in] Length

Die Größe der Datenübertragung in Bytes. Wenn die MDL insgesamt N Byte Pufferraum angibt, liegen die möglichen Werte von Length im Bereich von 1 bis N–Offset.

Rückgabewert

Keine

Bemerkungen

Ihr serieller Controllertreiber muss diese Funktion implementieren, wenn ein benutzerdefiniertes Übertragungstransaktionsobjekt erstellt wird. Bei Implementierung registriert der Treiber die Funktion im Aufruf SerCx2CustomTransmitTransactionCreate , der dieses Objekt erstellt.

Nachdem SerCx2 die EvtSerCx2CustomTransmitTransactionStart-Funktion aufgerufen hat, initiiert der serielle Controllertreiber die Transaktion, indem er den benutzerdefinierten Datenübertragungsmechanismus programmiert, um Daten aus dem Puffer in der Schreibanforderung an die Übertragungs-FIFO in der seriellen Controllerhardware zu verschieben. Es sei denn, die Anforderung kann sofort abgeschlossen werden, bevor die EvtSerCx2CustomTransmitTransactionStart-Funktion zurückgegeben wird, muss der Treiber eine Methode wie WdfRequestMarkCancelableEx aufrufen, um die Anforderung als abbruchfähig zu markieren.

Nachdem die Transaktion abgeschlossen ist und der Treiber die ausstehende Schreibanforderung abgeschlossen hat, ruft SerCx2 die Ereignisrückruffunktion EvtSerCx2CustomTransmitTransactionCleanup auf, wenn der Treiber diese Funktion implementiert.

Wenn der serielle Controllertreiber eine EvtSerCx2CustomTransmitTransactionInitialize-Ereignisrückruffunktion implementiert, ruft SerCx2 diese Funktion auf, bevor die EvtSerCx2CustomTransmitTransactionStart-Funktion aufgerufen wird . Kurz vor dem EvtSerCx2CustomTransmitTransactionStart-Aufruf und nach der Rückgabe des EvtSerCx2CustomTransmitTransactionInitialize-Aufrufs startet SerCx2 den Timer, der erkennt, ob ein Timeout für die Schreibanforderung aufgetreten ist. Weitere Informationen finden Sie in der Erläuterung der Gesamttimeouts in SERIAL_TIMEOUTS.

Der serielle Controllertreiber sollte die ausstehende Schreibanforderung erst abschließen, nachdem das letzte Byte in der Übertragungs-FIFO an das serial angeschlossene Peripheriegerät übertragen wurde. Es kann nicht garantiert werden, dass Daten, die in die Übertragungs-FIFO geschrieben werden, ohne erhebliche Verzögerung übertragen werden, und ein serieller Controllertreiber, der davon ausgeht, dass eine solche Garantie vorhanden ist, kann zu Zuverlässigkeitsproblemen für Peripherietreiber führen.

Wenn der benutzerdefinierte Datenübertragungsmechanismus ein Bus-master DMA-Gerät ist, kann die EvtSerCx2CustomTransmitTransactionStart-Funktion eine Methode wie WdfDmaTransactionInitializeUsingOffset aufrufen, um eine DMA-Transaktion zu initiieren, die den schreibpuffer verwendet, der durch die Parameter Mdl, Offset und Length beschrieben wird.

Weitere Informationen zu den Parametern Mdl, Offset und Length finden Sie unter Hinweise in EvtSerCx2CustomTransmitTransactionInitialize.

Wenn das durch den Request-Parameter identifizierte Anforderungsobjekt Speicher für einen privaten Kontext enthält, wird dieser Speicher möglicherweise nicht initialisiert, wenn der serielle Controllertreiber zum ersten Mal auf den Kontext zugreift. Beim ersten Zugriff sollte der Treiber den Kontext in der Regel mit Nullen füllen und dann, falls erforderlich, alle Felder im Kontext explizit festlegen, die Anfangswerte ungleich null erfordern.

Weitere Informationen finden Sie unter SerCx2 Custom-Transmit Transactions.

Beispiele

Um eine EvtSerCx2CustomTransmitTransactionStart-Rückruffunktion zu definieren, müssen Sie zunächst eine Funktionsdeklaration bereitstellen, die den Typ der Rückruffunktion identifiziert, die Sie definieren. Windows bietet eine Reihe von Rückruffunktionstypen für Treiber. Das Deklarieren einer Funktion mithilfe der Rückruffunktionstypen hilft der Codeanalyse für Treiber, der statischen Treiberüberprüfung (Static Driver Verifier , SDV) und anderen Überprüfungstools, Fehler zu finden, und es ist eine Voraussetzung für das Schreiben von Treibern für das Windows-Betriebssystem.

Um beispielsweise eine EvtSerCx2CustomTransmitTransactionStart-Rückruffunktion namens MyCustomTransmitTransactionStartzu definieren, verwenden Sie den Funktionstyp EVT_SERCX2_CUSTOM_TRANSMIT_TRANSACTION_START , wie in diesem Codebeispiel gezeigt:

EVT_SERCX2_CUSTOM_TRANSMIT_TRANSACTION_START  MyCustomTransmitTransactionStart;

Implementieren Sie dann Ihre Rückruffunktion wie folgt:

_Use_decl_annotations_
VOID
  MyCustomTransmitTransactionStart(
    SERCX2CUSTOMTRANSMITTRANSACTION  CustomTransmitTransaction,
    WDFREQUEST  Request,
    PMDL  Mdl,
    ULONG  Offset,
    ULONG  Length
    )
  {...}

Der EVT_SERCX2_CUSTOM_TRANSMIT_TRANSACTION_START Funktionstyp ist in der Sercx.h-Headerdatei definiert. Um Fehler beim Ausführen der Codeanalysetools genauer zu identifizieren, müssen Sie der Funktionsdefinition die anmerkung Use_decl_annotations hinzufügen. Die Use_decl_annotations-Anmerkung stellt sicher, dass die Anmerkungen verwendet werden, die auf den EVT_SERCX2_CUSTOM_TRANSMIT_TRANSACTION_START Funktionstyp in der Headerdatei angewendet werden. Weitere Informationen zu den Anforderungen für Funktionsdeklarationen finden Sie unter Deklarieren von Funktionen mithilfe von Funktionsrollentypen für KMDF-Treiber. Weitere Informationen zu Use_decl_annotations finden Sie unter Annotating Function Behavior.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Verfügbar ab Windows 8.1.
Zielplattform	Desktop
Kopfzeile	sercx.h
IRQL	Wird unter IRQL <= DISPATCH_LEVEL aufgerufen.