EVT_SERCX2_PIO_RECEIVE_READ_BUFFER Rückruffunktion (sercx.h)

Artikel
10/30/2024

Die EvtSerCx2PioReceiveReadBuffer Ereignisrückruffunktion wird von Version 2 der seriellen Framework-Erweiterung (SerCx2) aufgerufen, um programmierte E/A (PIO) zum Übertragen von Daten vom empfangenen FIFO im seriellen Controller in einen Lesepuffer zu verwenden.

Syntax

EVT_SERCX2_PIO_RECEIVE_READ_BUFFER EvtSercx2PioReceiveReadBuffer;

ULONG EvtSercx2PioReceiveReadBuffer(
  [in]  SERCX2PIORECEIVE PioReceive,
  [out] PUCHAR Buffer,
  [in]  ULONG Length
)
{...}

Parameter

[in] PioReceive

Ein SERCX2PIORECEIVE Handle für ein PIO-Empfangsobjekt. Der serielle Controllertreiber hat zuvor den SerCx2PioReceiveCreate Methode aufgerufen, um dieses Objekt zu erstellen.

[out] Buffer

Ein Zeiger auf den Lesepuffer. Dieser Parameter ist die virtuelle Adresse eines gesperrten Puffers im Systemspeicher.

[in] Length

Die Anzahl der Bytes im Lesepuffer, die zum Speichern empfangener Daten verfügbar sind.

Rückgabewert

Die EvtSerCx2PioReceiveReadBuffer Funktion gibt die Anzahl der Daten zurück, die sie erfolgreich vom empfangenen FIFO in der seriellen Controllerhardware an den Lesepuffer übertragen hat.

Bemerkungen

Der serielle Controllertreiber muss diese Funktion implementieren. Der Treiber registriert die Funktion im SerCx2PioReceiveCreate Aufruf, der das PIO-Empfangsobjekt erstellt.

SerCx2 ruft möglicherweise die EvtSerCx2PioReceiveReadBuffer--Funktion während einer PIO-Empfangstransaktion mehrmals auf. Ein einzelner EvtSerCx2PioReceiveReadBuffer Aufruf ist ausreichend, wenn dieser Aufruf den Lesepuffer mit Daten aus dem EMPFANGENden FIFO füllen kann. Andernfalls ruft SerCx2 diese Funktion weiterhin auf, da weitere Daten im Empfangen-FIFO verfügbar werden, bis der Lesepuffer gefüllt ist.

Die EvtSerCx2PioReceiveReadBuffer Funktion verwendet PIO, um so viele Bytes wie vom Empfangen fiFO in den Lesepuffer zu übertragen. Die Funktion überträgt weiterhin Daten aus dem FIFO, solange der an diese Funktion übergebene Puffer nicht vollständig ist, und das Zeilenstatusregister (LSR) gibt an, dass mehr Daten aus dem FIFO verfügbar sind. Wenn der LSR angibt, dass das FIFO leer ist, gibt die Funktion zurück, ohne den Puffer zu füllen. Andernfalls füllt die Funktion den Puffer und gibt den Wert zurück. In beiden Fällen ist der von dieser Funktion zurückgegebene Wert die Anzahl der Bytes von Daten, die erfolgreich aus dem Empfangen-FIFO in den Lesepuffer übertragen wurden.

In der Regel aktiviert die EvtSerCx2PioReceiveReadBuffer Funktion keine Unterbrechungen. Wenn der Empfangen-FIFO nicht mehr daten vorhanden ist, bevor die Funktion den Lesepuffer ausfüllen kann, ruft SerCx2 den EvtSerCx2PioReceiveEnableReadyNotification Ereignisrückruffunktion auf, um eine bereite Benachrichtigung zu aktivieren, und diese Funktion ermöglicht einen Interrupt, der auftritt, wenn weitere Daten im EMPFANGEN-FIFO verfügbar sind.

Für jeden aufeinander folgenden Aufruf des EvtSerCx2PioReceiveReadBuffer--Funktion passt SerCx2 Puffer- so an, dass er auf den nächsten zu füllenden Pufferbereich zeigt, und legt Length auf die Anzahl der Bytes des nicht ausgefüllten Speicherplatzes fest, die im Puffer verbleiben.

Die bereite Benachrichtigung wird nie aktiviert, wenn SerCx2 die EvtSerCx2PioReceiveEnableReadyNotification-Funktion aufruft. SerCx2 kann diese Funktion jedoch aus demselben Thread aufrufen, aus dem der Treiber die SerCx2PioReceiveReady--Methode aufgerufen hat.

Wenn der Treiber eine EvtSerCx2PioReceiveInitializeTransaction-Funktion implementiert, ruft SerCx2 diese Funktion zu Beginn einer PIO-Übertragungstransaktion vor dem ersten Aufruf der EvtSerCx2PioReceiveReadBuffer Funktion auf. Wenn der Treiber eine EvtSerCx2PioReceiveCleanupTransaction-Funktion implementiert, ruft SerCx2 diese Funktion am Ende einer PIO-Empfangstransaktion nach dem letzten Aufruf der EvtSerCx2PioReceiveReadBuffer-Funktion auf.

Zusätzlich zum Aufrufen der EvtSerCx2PioReceiveReadBuffer Funktion während PIO-Empfangstransaktionen ruft SerCx2 diese Funktion auf, um den Zustand des Empfangs-FIFO direkt vor dem Beenden des D0-Gerätestromzustands zu speichern. Weitere Informationen finden Sie unter SerCx2SaveReceiveFifoOnD0Exit.

Weitere Informationen zu PIO-Empfangstransaktionen finden Sie unter SerCx2 PIO-Receive Transactions.

Beispiele

Um eine EvtSerCx2PioReceiveReadBuffer 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 EvtSerCx2PioReceiveReadBuffer Rückruffunktion zu definieren, die MyPioReceiveReadBufferbenannt ist, verwenden Sie den funktionstyp EVT_SERCX2_PIO_RECEIVE_READ_BUFFER, wie in diesem Codebeispiel gezeigt:

EVT_SERCX2_PIO_RECEIVE_READ_BUFFER  MyPioReceiveReadBuffer;

Implementieren Sie dann die Rückruffunktion wie folgt:

_Use_decl_annotations_
ULONG
  MyPioReceiveReadBuffer(
    SERCX2PIORECEIVE  PioReceive,
    PUCHAR  Buffer,
    ULONG  Length

    )
  {...}

Der EVT_SERCX2_PIO_RECEIVE_READ_BUFFER 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_RECEIVE_READ_BUFFER 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.