EVT_SERCX2_PIO_TRANSMIT_DRAIN_FIFO Rückruffunktion (sercx.h)
Die EvtSerCx2PioTransmitDrainFifo Ereignisrückruffunktion wird von Version 2 der seriellen Framework-Erweiterung (SerCx2) aufgerufen, um das Übertragungs-FIFO in der seriellen Controllerhardware zu entwässern.
Syntax
EVT_SERCX2_PIO_TRANSMIT_DRAIN_FIFO EvtSercx2PioTransmitDrainFifo;
void EvtSercx2PioTransmitDrainFifo(
[in] SERCX2PIOTRANSMIT PioTransmit
)
{...}
Parameter
[in] PioTransmit
Ein SERCX2PIOTRANSMIT Handle für ein PIO-Übertragungsobjekt. Der serielle Controllertreiber hat zuvor den SerCx2PioTransmitCreate Methode aufgerufen, um dieses Objekt zu erstellen.
Rückgabewert
Nichts
Bemerkungen
Ihr serieller Controllertreiber kann diese Funktion als Option implementieren. Wenn Ihr Treiber diese Funktion implementiert, muss er auch die EvtSerCx2PioTransmitCancelDrainFifo und EvtSerCx2PioTransmitPurgeFifo Ereignisrückruffunktionen implementieren. Ein Treiber, der diese Funktionen implementiert, registriert sie im SerCx2PioTransmitCreate Aufruf, der das PIO-Übertragungsobjekt erstellt.
SerCx2 ruft die EvtSerCx2PioTransmitDrainFifo Funktion auf, um die FiFO-Übertragung in der seriellen Controllerhardware am Ende einer PIO-Übertragungstransaktion zu entwässern. Diese Funktion stellt sicher, dass alle Datenbytes, die sich im Übertragungs-FIFO befinden, an das serial angeschlossene Peripheriegerät übertragen werden. Nachdem das letzte Byte vom FIFO übertragen wurde, ruft die EvtSerCx2PioTransmitDrainFifo Funktion die SerCx2PioTransmitDrainFifoComplete Methode auf, um SerCx2 zu benachrichtigen.
Wenn der serielle Controllertreiber eine EvtSerCx2PioTransmitDrainFifo-Funktion implementiert, führt SerCx2 keine ausstehende Schreib- (IRP_MJ_WRITE) Anforderung aus, bis der Treiber SerCx2PioTransmitDrainFifoCompleteaufruft.
Wenn ihr serieller Controller über einen Hardware-FIFO (oder einen ähnlichen Puffermechanismus) zum Speichern von Übertragungsdaten verfügt, sollte Ihr Treiber eine EvtSerCx2PioTransmitDrainFifo-Funktion implementieren. Andernfalls kann SerCx2 nicht bestätigen, dass das Übertragungs-FIFO abgelaufen ist, bevor die ausstehende Schreibanforderung abgeschlossen ist. Stattdessen schließt SerCx2 diese Anforderung ab, nachdem das letzte Byte im Schreibpuffer in den FiFO-Sendevorgang geschrieben wurde. Es kann keine Garantie geben, dass daten, die in das Übermittlungs-FIFO geschrieben wurden, ohne erhebliche Verzögerung übermittelt werden. Alle Daten, die nach Abschluss der Schreibanforderung im FIFO verbleiben, gehen möglicherweise verloren, bevor sie an das serial angeschlossene Peripheriegerät übertragen werden können. Dieser unerwartete Datenverlust in einer erfolgreich abgeschlossenen Schreibanforderung kann Zuverlässigkeitsprobleme für den Peripherietreiber verursachen.
Ein Peripherietreiber sendet z. B. Schreibanforderungen an einen seriellen Anschluss, an den ein Peripheriegerät angeschlossen ist. Bis alle ausstehenden Schreibanforderungen abgeschlossen sind, sollte dieser Treiber das Senden eines IOCTL verzögern, um die Baudrate zu ändern, mit der der serielle Port Daten überträgt. Wenn jedoch keine EvtSerCx2PioTransmitDrainFifo-Funktion implementiert wird, kann eine Schreibanforderung zum Übertragen von 100 Bytes an Daten abgeschlossen werden, während 50 Datenbyte weiterhin im FiFO übertragen werden. Wenn der Peripherietreiber dann eine IOCTL sendet, um eine neue Baudrate festzulegen, werden einige der verbleibenden Bytes im FIFO möglicherweise mit der neuen Baudrate übertragen, was zu einem Fehler führt.
Wenn eine Schreibanforderung zum Übertragen von 100 Byte Daten abgeschlossen ist, während 50 Datenbytes weiterhin im FIFO verbleiben, und der serielle Controller beendet D0, um einen Energiespargerätzustand einzugeben, bevor die verbleibenden Bytes im FIFO übertragen werden können, weiß der Peripherietreiber nicht, dass diese Bytes verloren gehen.
Weitere Informationen finden Sie unter SerCx2 PIO-Transmit Transactions.
Beispiele
Um eine EvtSerCx2PioTransmitDrainFifo 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 EvtSerCx2PioTransmitDrainFifo Rückruffunktion zu definieren, die MyPioTransmitDrainFifoheißt, verwenden Sie den funktionstyp EVT_SERCX2_PIO_TRANSMIT_DRAIN_FIFO, wie in diesem Codebeispiel gezeigt:
EVT_SERCX2_PIO_TRANSMIT_DRAIN_FIFO MyPioTransmitDrainFifo;
Implementieren Sie dann die Rückruffunktion wie folgt:
_Use_decl_annotations_
VOID
MyPioTransmitDrainFifo(
SERCX2PIOTRANSMIT PioTransmit
)
{...}
Der EVT_SERCX2_PIO_TRANSMIT_DRAIN_FIFO 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_PIO_TRANSMIT_DRAIN_FIFO 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. |