SpbCx-Objekthandles

  • Artikel

In diesem Thema werden Objekthandles beschrieben, die für die SPB-Frameworkerweiterungsbibliothek (SpbCx) definiert sind.

Darüber hinaus verwendet serCx2 DDI zwei der generischen Objekthandletypen WDFDEVICE und WDFREQUEST, die vom Kernel-Mode Driver Framework (KMDF) definiert werden. Weitere Informationen zu Frameworkhandletypen finden Sie unter Zusammenfassung von Frameworkobjekten.

In diesem Thema werden die folgenden Objekthandles beschrieben:

Header: Spbcx.h

SPBREQUEST-Objekthandle

Ein SPBREQUEST-Objekthandle stellt eine E/A-Anforderung dar, die an ein Zielgerät auf dem Bus ausgegeben wird.

DECLARE_HANDLE(SPBREQUEST)

Die SPBREQUEST-Objektklasse wird von der WDFREQUEST-Objektklasse abgeleitet, die eine E/A-Anforderung darstellt, die vom E/A-Manager verteilt wird. Daher akzeptieren WdfRequestXxx-Methoden , die WDFREQUEST-Handle-Werte als Parameter verwenden , SPBREQUEST-Handle-Werte als gültige Parameterwerte. Weitere Informationen zu diesen Methoden finden Sie unter Framework Request Objects.

Einige SpbCx-Methoden und Rückruffunktionen erfordern jedoch speziell SPBREQUEST-Handles als Parameter. Für einen solchen Parameter ist das Ersetzen eines WDFREQUEST-Handles , das nicht auch ein SPBREQUEST-Handle ist, ein Fehler.

Die SpbRequestGetTransferParameters-Methode verwendet beispielsweise ein SPBREQUEST-Handle als Parameter. Für diesen Parameter ist ein WDFREQUEST-Handle , das nicht auch ein SPBREQUEST-Handle ist, ein Fehler. Der Grund für diese Anforderung ist, dass ein SPBREQUEST-Objekt zusätzliche SPB-spezifische Zustandsinformationen speichern muss, um E/A-Übertragungssequenzen zu unterstützen. Die WDFREQUEST-Basisobjektklasse bietet diese Unterstützung nicht.

Während der Geräteinitialisierung kann Ihr SPB-Controllertreiber einem SPBREQUEST-Handle einen Anforderungskontext zuweisen, indem die SpbControllerSetRequestAttributes-Methode aufgerufen wird.

SPBTARGET-Objekthandle

Ein SPBTARGET-Objekthandle identifiziert eine logische Verbindung zwischen einem Client (Peripherietreiber) und einem adressierbaren Port oder Peripheriegerät auf dem Bus.

DECLARE_HANDLE(SPBTARGET)

Für einen I2C-Bus entspricht ein SPBTARGET-Handle einer bestimmten Geräteadresse.
Für einen SPI-Bus entspricht ein SPBTARGET-Handle einer Geräteauswahllinie.

In der Regel ist ein SPBTARGET-Objekt vom Anfang des EvtSpbTargetConnect-Ereignisrückrufs bis zum Ende des entsprechenden EvtSpbTargetDisconnect-Ereignisrückrufs vorhanden. Die Lebensdauer des SPBTARGET-Objekts kann jedoch über den zweiten Rückruf hinausgehen, wenn der SPB-Controllertreiber einen zusätzlichen Verweis auf das SPBTARGET-Objekt akzeptiert, um zu verhindern, dass das Objekt während der Verarbeitung einer E/A-Anforderung für das Ziel unerwartet verschwindet.

Der SPB-Controllertreiber führt alle hardwarespezifischen Vorgänge für ein SPB-Controllergerät aus. Wenn ein Client eine IRP_MJ_CREATE Anforderung zum Öffnen einer Verbindung mit einem Ziel auf dem Bus sendet, übergibt die SPB-Frameworkerweiterung (SpbCx), die die E/A-Warteschlange für den Controllertreiber verwaltet, diese Anforderung an den SPB-Controllertreiber, indem die Rückruffunktion EvtSpbTargetConnect dieses Treibers aufgerufen wird. Dieser Target-Parameter dieser Funktion ist ein SPBTARGET-Handle . Die Funktion kann dieses Handle verwenden, um verbindungsspezifische Ressourceninformationen (z. B. die Geräteadresse) aus dem PnP-Manager abzurufen. Wenn der Client eine IRP_MJ_CLOSE Anforderung zum Schließen der Verbindung sendet, übergibt SpbCx diese Anforderung an die EvtSpbTargetDisconnect-Rückruffunktion des SPB-Controllertreibers, die diese Ressourcen freigibt.

Exclusive-Mode Zugriff

Clients verfügen über den exklusiven Modus für den Zugriff auf Zielgeräte. Nur ein Client kann gleichzeitig über eine Verbindung mit einem bestimmten Zielgerät verfügen. SpbCx stellt sicher, dass nur ein SPBTARGET-Handle für eine Zielgeräteadresse auf dem Bus vorhanden ist. Diese Einschränkung ist erforderlich, da SpbCx die Verschachtelung von E/A-Anforderungen, die von mindestens zwei Clients an ein Zielgerät gesendet werden, nicht unterstützt. Wenn ein Zielgerät In der Lage sein muss, Anforderungen von mehreren Clients zu empfangen, benötigt dieses Gerät einen MUX-Treiber – getrennt vom Controllertreiber –, der die angeforderten Vorgänge ordnungsgemäß ineinandergreifen kann.

Interoperabilität mit KMDF

Die serCx2-Treiberunterstützungsmethoden und SpbCx-Ereignisrückruffunktionen , die von SpbCx definiert werden, verwenden SPBTARGET-Handles , um offene Verbindungen mit Zielgeräten auf dem Bus darzustellen. Ein Controllertreiber muss jedoch in der Regel KMDF-Methoden aufrufen, die WDFFILEOBJECT-Handles anstelle von SPBTARGET-Handles erfordern, um Zielgeräte festzulegen.

Ein SPBTARGET-Objekt ähnelt einem WDFFILEOBJECT-Objekt. Ein SPBTARGET-Objekt enthält jedoch zusätzliche SPB-spezifische Informationen. Beispielsweise verfolgt das SPBTARGET-Objekt für das Zielgerät während der Verarbeitung einer IOCTL_SPB_EXECUTE_SEQUENCE E/A-Steuerelementanforderung den Zustand der Übertragungen in der E/A-Übertragungssequenz nach.

Um das WDFFILEOBJECT-Handle für ein Ziel abzurufen, ruft der SPB-Controllertreiber die SpbTargetGetFileObject-Methode auf. Diese Methode akzeptiert als Eingabeparameter ein SPBTARGET-Handle für ein geöffnetes Zielgerät und gibt das entsprechende WDFFILEOBJECT-Handle an dieses Ziel zurück.

In Übereinstimmung mit KMDF-Konventionen kann der SPB-Controllertreiber einen eigenen Kontext an das SPBTARGET-Objekt für ein Zielgerät anfügen, und dieser Kontext kann zugehörige Rückruffunktionen EvtCleanupCallback und EvtDestroyCallback enthalten. Der SPB-Controllertreiber verwendet diesen Kontext, um Informationen nachzuverfolgen, die für den Controllertreiber und das Zielgerät spezifisch sind. Darüber hinaus kann dieser Treiber untergeordnete Objekte des SPBTARGET-Objekts erstellen, z. B. Timer, DPCs oder bei Bedarf E/A-Anforderungen und E/A-Warteschlangen.