Freigeben über

EVT_SPB_CONTROLLER_SEQUENCE Rückruffunktion (spbcx.h)

  • Artikel

Ein SPB-Controllertreiber EvtSpbControllerIoSequence Ereignisrückruffunktion führt eine Abfolge von Datenübertragungen zwischen dem angegebenen Zielgerät und den Puffern aus, die mit der Sequenzanforderung bereitgestellt werden.

Syntax

EVT_SPB_CONTROLLER_SEQUENCE EvtSpbControllerSequence;

void EvtSpbControllerSequence(
  [in] WDFDEVICE Controller,
  [in] SPBTARGET Target,
  [in] SPBREQUEST Request,
  [in] ULONG TransferCount
)
{...}

Parameter

[in] Controller

Ein WDFDEVICE-Handle für das Framework-Geräteobjekt, das den SPB-Controller darstellt.

[in] Target

Eine SPBTARGET- für das Ziel für diese E/A-Anforderung. Das Ziel ist ein Peripheriegerät oder port, das an den Bus angeschlossen ist. Die SPB-Frameworkerweiterung (SpbCx) hat diesem Handle zuvor im EvtSpbTargetConnect Rückruf zugewiesen, der die Verbindung mit dem Ziel geöffnet hat.

[in] Request

Die SPBREQUEST die E/A-Anforderung verarbeiten. Ihr SPB-Controllertreiber muss diese Anforderung entweder durch Ausführen des angeforderten Vorgangs oder durch Zurückgeben eines Fehlerstatus abschließen. Weitere Informationen finden Sie unter Anmerkungen.

[in] TransferCount

Die Anzahl der einzelnen Übertragungen in dieser E/A-Übertragungssequenz. Jede einzelne Übertragung ist ein einfacher Lese- oder Schreibvorgang.

Rückgabewert

Nichts

Bemerkungen

SpbCx verwaltet die E/A-Warteschlange für den SPB-Controller. SpbCx ruft die EvtSpbControllerIoSequence Rückruffunktion auf, wenn ein Client (Peripherietreiber) des SPB-Controllers eine IOCTL_SPB_EXECUTE_SEQUENCE Anforderung an ein Zielgerät sendet, das an den Bus angeschlossen ist. Der wert des Request Parameter ist ein Handle, das diese Anforderung kapselt.

Ein EvtSpbControllerIoSequence Rückruf gibt keinen Statuswert zurück. Stattdessen gibt der SPB-Controllertreiber den Status des Sequenzvorgangs im Abschlussstatus für die E/A-Anforderung an.

Ein EvtSpbControllerIoSequence Rückruf ist asynchron. Das heißt, die Rückruffunktion sollte die angeforderte Sequenz (oder den ersten Teil der Sequenz) initiieren und dann zurückgeben, ohne auf den Abschluss des Vorgangs zu warten. Später verarbeitet der SPB-Controllertreiber die Anforderung weiter oder schließt sie während der Unterbrechung von DPCs oder Timer-DPCs ab.

Der SPB-Controllertreiber kann die Parameterwerte aus der E/A-Anforderung abrufen, um die maximale Länge der Übertragungen innerhalb der Sequenz zu ermitteln. Der Treiber kann diese Länge verwenden, um DMA-Ressourcen zuzuweisen, die er für jede Übertragung innerhalb der Sequenz wiederverwenden kann.

Der SPB-Controllertreiber kann die SpbRequestGetTransferParameters- Methode aufrufen, um die Steuerungsparameter und den Datenpuffer für jede Übertragung in der Sequenz abzurufen. Der Puffer ist ein WDFMEMORY-Objekt, das in der aktuellen Implementierung eine verkettete MDL kapselt. Weitere Informationen zu verketteten MDLs finden Sie unter Verwenden von MDLs.

Der SPB-Controller sollte das Zielgerät für den gesamten Sequenzvorgang ausgewählt lassen. Wenn das Ziel von einer Geräteauswahllinie ausgewählt wird, kann die Zeile kontinuierlich vom Anfang der ersten Übertragung in der Sequenz bis zum Ende der letzten Übertragung bestätigt werden. Diese Zeile kann so früh wie der Sperrvorgang am Anfang der Sequenz bestätigt werden und kann bis zum Entsperrvorgang am Ende der Sequenz bestätigt werden.

Für jede Übertragung in einer Sequenz kann eine optionale Verzögerung angegeben werden. Der SPB-Controllertreiber ist dafür verantwortlich, mindestens diese Anzahl von Mikrosekunden zu verzögern, bevor die Übertragung gestartet wird. Wenn die erste Übertragung in der Sequenz eine zugeordnete Verzögerung aufweist, sollte der Treiber zuerst die Adresse übertragen oder die Geräteauswahlzeile des Zielgeräts bestätigen und dann für die angegebene Zeit verzögert werden, bevor die Datenübertragung gestartet wird. Während dieser Verzögerung sollte das Ziel ausgewählt bleiben, aber der Controller sollte die Uhr nicht auf dem Bus ausführen.

Wenn das Zielgerät einen NACK während einer Übertragung in einer Sequenz signalisiert, stoppt der SPB-Controller die Sequenz. (Dies bedeutet, dass der Controller die fehlerhafte Übertragung nicht wiederholt und nicht versucht, die verbleibenden Übertragungen in der Sequenz auszuführen.) Wenn dies geschieht, sollte der SPB-Controllertreiber den Abschlussstatus der E/A-Anforderung auf STATUS_SUCCESS festlegen, das feld Informationen Feld im E/A-Statusblock auf die Anzahl der tatsächlich übertragenen Bytes festlegen (nicht zählen, die in der Übertragung verloren gegangenen Daten, die den NACK empfangen haben), und die Anforderung abschließen.

Der SPB-Controllertreiber sollte die E/A-Anforderung nur mit einem Fehlerstatuscode abschließen, wenn eine der folgenden Bedingungen auftritt:

  • Der SPB-Controller kann das Zielgerät nicht auswählen (z. B. ein Zielgerät auf einem I2C-Bus signalisiert einen NACK, wenn der Controller das Adressbyte überträgt).
  • Der SPB-Controllertreiber erhält beim Verarbeiten des Sequenzvorgangs einen Fehlerstatus von einem Aufruf an einen WDF- oder WDM-Dienst.

Um eine EvtSpbControllerIoSequence Rückruffunktion zu registrieren, rufen Sie die SpbDeviceInitialize-Methode auf.

Beispiele

Um eine EvtSpbControllerIoSequence 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 EvtSpbControllerIoSequence Rückruffunktion zu definieren, die MyEvtSpbControllerIoSequenceheißt, verwenden Sie den EVT_SPB_CONTROLLER_SEQUENCE Funktionstyp, wie in diesem Codebeispiel gezeigt:

EVT_SPB_CONTROLLER_SEQUENCE  MyEvtSpbControllerIoSequence;

Implementieren Sie dann die Rückruffunktion wie folgt:

_Use_decl_annotations_
VOID
  MyEvtSpbControllerIoSequence(
    WDFDEVICE Controller,
    SPBTARGET Target,
    SPBREQUEST Request,
    ULONG TransferCount
    )
{ ... }

Der EVT_SPB_CONTROLLER_SEQUENCE Funktionstyp wird in der Headerdatei "Spbcx.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_SPB_CONTROLLER_SEQUENCE 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- Wird ab Windows 8 unterstützt.
Zielplattform- Desktop
Header- spbcx.h
IRQL- Wird bei IRQL <= DISPATCH_LEVEL aufgerufen.

Siehe auch