EVT_SPB_CONTROLLER_SEQUENCE Rückruffunktion (spbcx.h)

  • Artikel

Die EvtSpbControllerIoSequence-Ereignisrückruffunktion eines SPB-Controllertreibers führt eine Sequenz 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

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

[in] Request

Das SPBREQUEST-Handle für die E/A-Anforderung. Ihr SPB-Controllertreiber muss diese Anforderung entweder durch Ausführen des angeforderten Vorgangs oder durch Zurückgeben eines Fehlers status abschließen. Weitere Informationen finden Sie unter Hinweise.

[in] TransferCount

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

Rückgabewert

Keine

Bemerkungen

SpbCx verwaltet die E/A-Warteschlange für den SPB-Controller. SpbCx ruft die EvtSpbControllerIoSequence-Rückruffunktion des SPB-Controllertreibers 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-Parameters ist ein Handle, das diese Anforderung kapselt.

Ein EvtSpbControllerIoSequence-Rückruf gibt keinen status Wert zurück. Stattdessen gibt der SPB-Controllertreiber die status des Sequenzvorgangs im Abschluss status für die E/A-Anforderung an.

Ein EvtSpbControllerIoSequence-Rückruf ist asynchron. Das heißt, die Rückruffunktion sollte den angeforderten Sequenzvorgang (oder den ersten Teil der Sequenz) initiieren und dann zurückgeben, ohne auf den Abschluss des Vorgangs zu warten. Später setzt der SPB-Controllertreiber die Verarbeitung der Anforderung fort oder schließt sie während der Unterbrechungs-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 bestimmen. 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 Steuerelementparameter 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 Für den gesamten Sequenzvorgang ausgewählte Zielgerät beibehalten. Wenn das Ziel von einer Device-Select-Zeile ausgewählt wird, kann die Zeile vom Beginn der ersten Übertragung in der Sequenz bis zum Ende der letzten Übertragung kontinuierlich bestätigt werden. Diese Zeile kann bereits beim Sperrvorgang am Anfang der Sequenz bestätigt werden und 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 Verzögerung aufweist, sollte der Treiber zuerst die Adresse übertragen oder die Geräteauswahlleitung des Zielgeräts bestätigen und dann für die angegebene Zeit verzögern, 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 während einer Übertragung in einer Sequenz einen NACK signalisiert, beendet der SPB-Controller die Sequenz. (Das heißt, der Controller versucht die fehlerhafte Übertragung nicht erneut und versucht nicht, die verbleibenden Übertragungen in der Sequenz durchzuführen.) In diesem Fall sollte der SPB-Controllertreiber den Abschluss status der E/A-Anforderung auf STATUS_SUCCESS festlegen, das Feld Information im E/A-status-Block auf die Anzahl der tatsächlich übertragenen Bytes festlegen (die bei der Übertragung verloren gegangenen Daten, die die NACK empfangen haben), und die Anforderung abschließen.

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

  • Der SPB-Controller kann das Zielgerät nicht auswählen (z. B. signalisiert ein Zielgerät auf einemI2C-Bus ein NACK, wenn der Controller das Adressbyte überträgt).
  • Der SPB-Controllertreiber erhält einen Fehler status von einem Aufruf eines WDF- oder WDM-Diensts während der Verarbeitung des Sequenzvorgangs.

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

Beispiele

Um eine EvtSpbControllerIoSequence-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 EvtSpbControllerIoSequence-Rückruffunktion mit dem Namen MyEvtSpbControllerIoSequencezu definieren, verwenden Sie den Funktionstyp EVT_SPB_CONTROLLER_SEQUENCE, wie in diesem Codebeispiel gezeigt:

EVT_SPB_CONTROLLER_SEQUENCE  MyEvtSpbControllerIoSequence;

Implementieren Sie dann Ihre Rückruffunktion wie folgt:

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

Der EVT_SPB_CONTROLLER_SEQUENCE Funktionstyp ist in der Spbcx.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_SPB_CONTROLLER_SEQUENCE 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) Unterstützt ab Windows 8.
Zielplattform Desktop
Kopfzeile spbcx.h
IRQL Wird unter IRQL <= DISPATCH_LEVEL aufgerufen.

Weitere Informationen