EVT_SERCX2_CUSTOM_TRANSMIT_TRANSACTION_START Rückruffunktion (sercx.h)

Artikel
10/30/2024

Die EvtSerCx2CustomTransmitTransactionStart Ereignisrückruffunktion 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 zu einem benutzerdefinierten Übertragungstransaktionsobjekt. Der serielle Controllertreiber hat zuvor den SerCx2CustomTransmitTransactionCreate Methode aufgerufen, um dieses Objekt zu erstellen.

[in] Request

Ein Handle zum Framework-Anforderungsobjekt, das der benutzerdefinierten Übertragungstransaktion zugeordnet ist. Der Treiber ist für die Durchführung dieser Anforderung verantwortlich. Diese Anforderung ist möglicherweise nicht die vom Client gesendete IRP_MJ_WRITE Anforderung, und daher sollte der serielle Controllertreiber nicht versuchen, diese Anforderung für den Zugriff auf den Schreibpuffer zu verwenden. Diese Anforderung wird in erster Linie für die Abbruch-, Abschluss- und Warteschlangenweiterleitung (falls erforderlich) verwendet. Um auf den Schreibpuffer für die Schreibanforderung des Clients zuzugreifen, verwenden Sie die Parameter Mdl, Offsetund Length Parameter.

[in] Mdl

Ein Zeiger auf eine MDL-, die die Speicherseiten beschreibt, die vom Schreibpuffer für die benutzerdefinierte Übertragungstransaktion überspannt werden. Die Punkt/Gather-Liste für die DMA-Übertragung verwendet den Bereich dieses Speichers, 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 Byte-Offset vom Anfang des Pufferbereichs, der von der MDL beschrieben wird. Wenn die MDL insgesamt N Bytes Pufferraum angibt, befinden sich mögliche Werte von Offset im Bereich 0 bis N-1.

[in] Length

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

Rückgabewert

Nichts

Bemerkungen

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

Nachdem SerCx2 den EvtSerCx2CustomTransmitTransactionStart--Funktion aufruft, initiiert der serielle Controllertreiber die Transaktion, indem der benutzerdefinierte Datenübertragungsmechanismus programmiert wird, um Daten aus dem Puffer in der Schreibanforderung an die FiFO-Übertragung in der seriellen Controllerhardware zu verschieben. Sofern die Anforderung nicht sofort abgeschlossen werden kann, muss der Treiber eine Methode wie WdfRequestMarkCancelableEx- aufrufen, um die Anforderung als abbruchfähig zu kennzeichnen, bevor die EvtSerCx2CustomTransmitTransactionStart- funktion zurückgegeben wird.

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

Wenn der serielle Controllertreiber einen EvtSerCx2CustomTransmitTransactionInitialize Ereignisrückruffunktion implementiert, ruft SerCx2 diese Funktion vor dem Aufrufen der EvtSerCx2CustomTransmitTransactionStart-Funktion auf. Unmittelbar vor dem EvtSerCx2CustomTransmitTransactionStart Aufruf, und nach dem EvtSerCx2CustomTransmitTransactionInitialize Aufruf wird der Timer gestartet, der erkennt, ob die Schreibanforderung timeout ist. Weitere Informationen finden Sie in der Diskussion über totale Timeouts in SERIAL_TIMEOUTS.

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

Wenn es sich bei dem benutzerdefinierten Datenübertragungsmechanismus um ein Busmaster-DMA-Gerät handelt, die EvtSerCx2CustomTransmitTransactionStart--Funktion kann eine Methode wie WdfDmaTransactionInitializeUsingOffset- aufrufen, um eine DMA-Transaktion zu initiieren, die den vom Mdlbeschriebenen Schreibpuffer verwendet, Offsetund Length Parameter.

Weitere Informationen zu den Parametern Mdl, Offsetund Length Parameter finden Sie in den Hinweisen in EvtSerCx2CustomTransmitTransactionInitialize.

Wenn das vom parameter 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 bei Bedarf explizit alle Felder im Kontext festlegen, für die nichtzero-Anfangswerte erforderlich sind.

Weitere Informationen finden Sie unter SerCx2 Custom-Transmit Transactions.

Beispiele

Um eine EvtSerCx2CustomTransmitTransactionStart Rückruffunktion zu definieren, müssen Sie zuerst eine Funktionsdeklaration bereitstellen, die den Typ der rückruffunktion identifiziert, die Sie definieren. Windows stellt eine Reihe von Rückruffunktionstypen für Treiber bereit. Durch das Deklarieren einer Funktion mithilfe der Rückruffunktionstypen können Codeanalyse für Treiber, statische Treiberüberprüfung (SDV) und andere Überprüfungstools Fehler finden, und es ist eine Anforderung zum Schreiben von Treibern für das Windows-Betriebssystem.

Um beispielsweise eine EvtSerCx2CustomTransmitTransactionStart- Rückruffunktion zu definieren, die MyCustomTransmitTransactionStartheißt, verwenden Sie den EVT_SERCX2_CUSTOM_TRANSMIT_TRANSACTION_START Funktionstyp, wie in diesem Codebeispiel gezeigt:

EVT_SERCX2_CUSTOM_TRANSMIT_TRANSACTION_START  MyCustomTransmitTransactionStart;

Implementieren Sie dann die 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 wird in der Headerdatei Sercx.h definiert. Um Fehler genauer zu identifizieren, wenn Sie die Codeanalysetools ausführen, müssen Sie der Funktionsdefinition die Use_decl_annotations Anmerkung hinzufügen. Die Use_decl_annotations Anmerkung stellt sicher, dass die Anmerkungen, die auf den Funktionstyp EVT_SERCX2_CUSTOM_TRANSMIT_TRANSACTION_START in der Headerdatei angewendet werden, verwendet 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_annotationsfinden Sie unter Annotating Function Behavior.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Verfügbar ab Windows 8.1.
Zielplattform-	Desktop
Header-	sercx.h
IRQL-	Wird bei IRQL <= DISPATCH_LEVEL aufgerufen.