DXGK_SPB_INTERFACE-Struktur (dispmprt.h)

Artikel
08/07/2023

Die DXGK_SPB_INTERFACE-Struktur enthält Zeiger auf Funktionen in der SPB-Schnittstelle (Simple Peripheral Bus), die ein Windows Display Driver Model (WDDM) 1.2 und höher-Displayporttreiber aufrufen kann, um SPB-Ressourcen zu untersuchen und zu ändern.

Syntax

typedef struct _DXGK_SPB_INTERFACE {
  USHORT                 Size;
  USHORT                 Version;
  PVOID                  Context;
  PINTERFACE_REFERENCE   InterfaceReference;
  PINTERFACE_DEREFERENCE InterfaceDereference;
  NTSTATUS(HANDLE DeviceHandle,LARGE_INTEGER SpbReourceId,UNICODE_STRING *SpbResourceSubName,ACCESS_MASK DesiredAccess,ULONG ShareAccess,ULONG OpenOptions,VOID **SpbResource)              * )(OpenSpbResource;
  NTSTATUS()(HANDLE DeviceHandle,VOID *SpbResource)              * CloseSpbResource;
  NTSTATUS(ANDLE DeviceHandle,VOID *SpbResource,ULONG Length,VOID *Buffer,LARGE_INTEGER *ByteOffset,HANDLE EventHandle,IO_STATUS_BLOCK *IoStatusBlock)              * )(HReadSpbResource;
  NTSTATUS(ANDLE DeviceHandle,VOID *SpbResource,ULONG Length,VOID *Buffer,LARGE_INTEGER *ByteOffset,HANDLE EventHandle,IO_STATUS_BLOCK *IoStatusBlock)              * )(HWriteSpbResource;
  NTSTATUS(ANDLE DeviceHandle,VOID *SpbResource,ULONG IoControlCode,ULONG InBufferSize,VOID *InputBuffer,ULONG OutBufferSize,VOID *OutputBuffer,HANDLE EventHandle,IO_STATUS_BLOCK *IoStatusBlock)              * )(HSpbResourceIoControl;
} DXGK_SPB_INTERFACE, *PDXGK_SPB_INTERFACE;

Member

Size

Die Größe (in Bytes) dieser Struktur.

Version

Die Versionsnummer der SPB-Schnittstelle. Versionsnummernkonstanten werden in Dispmprt.h definiert (z. B. DXGK_SPB_INTERFACE_VERSION_1).

Context

Ein Zeiger auf einen Kontext, der vom Anzeigeminiporttreiber bereitgestellt wird.

InterfaceReference

Ein Zeiger auf eine Schnittstellenverweisfunktion, die vom Anzeigeminiporttreiber implementiert wird.

InterfaceDereference

Ein Zeiger auf eine Schnittstellendereferenzierungsfunktion, die vom Anzeigeminiporttreiber implementiert wird.

OpenSpbResource

Öffnet eine SPB-Ressource (Simple Peripheral Bus). Alle Eingabeparameter werden vom Anzeigeminiporttreiber bereitgestellt.

OpenSpbResource-Parameter	BESCHREIBUNG
DeviceHandle	Ziehpunkt, der einen Grafikkarte darstellt. Der Anzeige-Miniporttreiber hat dieses Handle zuvor im DeviceHandle-Member der DXGKRNL_INTERFACE-Struktur abgerufen, die an die DxgkDdiStartDevice-Funktion übergeben wurde.
SpbReourceId	Die Ressourcen-ID des SPB-Ressourcenhubs.
SpbResourceSubName	Optionaler Zeiger auf den Unicode SPB-Ressourcenunternamen.
DesiredAccess	Ein ACCESS_MASK Wert, der den angeforderten Zugriff auf die SPB-Ressource bestimmt. Weitere Informationen finden Sie im DesiredAccess-Parameter der ZwCreateFile-Funktion .
ShareAccess	Typ des Freigabezugriffs für die Datei. Weitere Informationen finden Sie im ShareAccess-Parameter von ZwCreateFile.
OpenOptions	Die Optionen, die beim Öffnen der SPB-Ressource angewendet werden sollen. Weitere Informationen finden Sie im CreateOptions-Parameter von ZwCreateFile.
SpbResource	Ein Zeiger auf einen Puffer, der verwendet wird, um das Handle an die SPB-Ressource zurückzugeben.

CloseSpbResource

Schließt eine SPB-Ressource. Alle Eingabeparameter werden vom Anzeigeminiporttreiber bereitgestellt.

Das Schließen eines geöffneten Objekthandles führt dazu, dass dieses Handle ungültig wird. Das System verringert auch die Handleanzahl für das Objekt und überprüft, ob das Objekt gelöscht werden kann. Das System löscht das Objekt erst, wenn alle Handles des Objekts geschlossen sind und keine Zeiger, auf die verwiesen wird, verbleiben.

Der Treiber muss CloseSpbResource aufrufen, um jedes Handle zu schließen, das er mit OpenSpbResource geöffnet hat, sobald das Handle nicht mehr benötigt wird.

Aufrufer von CloseSpbResource sollten nicht davon ausgehen, dass diese Funktion vor der Rückgabe automatisch darauf wartet, dass alle E/A-Vorgänge abgeschlossen sind.

CloseSpbResource-Parameter	BESCHREIBUNG
DeviceHandle	Ein Handle, das eine Grafikkarte darstellt. Der Anzeige-Miniporttreiber hat dieses Handle zuvor im DeviceHandle-Member der DXGKRNL_INTERFACE-Struktur abgerufen, die an die DxgkDdiStartDevice-Funktion übergeben wurde.
SpbResource	Ein Zeiger auf eine SPB-Ressource, die der Anzeige-Miniporttreiber mit der OpenSpbResource-Funktion geöffnet hat.

ReadSpbResource

Liest Daten aus einer geöffneten SPB-Ressource. Alle Eingabeparameter werden vom Anzeigeminiporttreiber bereitgestellt.

Wenn der Aufruf von OpenSpbResource eines der OpenOptions-FlagsFILE_SYNCHRONOUS_IO_ALERT oder FILE_SYNCHRONOUS_IO_NONALERT (definiert in Wdm.h) festgelegt hat, behält der E/A-Manager die aktuelle Dateiposition bei. Wenn ja, kann der Aufrufer von ReadSpbResource angeben, dass anstelle eines expliziten ByteOffset-Werts der aktuelle Dateipositionsoffset verwendet wird. Diese Spezifikation kann mit einer der folgenden Methoden erstellt werden:

Geben Sie einen Zeiger auf einen LARGE_INTEGER Wert an, wobei der HighPart-Member auf -1 und der LowPart-Member auf den systemdefinierte Wert FILE_USE_FILE_POINTER_POSITION (definiert in Wdm.h) festgelegt ist.
Übergeben Sie einen NULL-Zeiger für ByteOffset.

ReadSpbResource aktualisiert die aktuelle Dateiposition, indem die Anzahl der beim Abschluss des Lesevorgangs gelesenen Bytes hinzugefügt wird, wenn die aktuelle Dateiposition verwendet wird, die vom E/A-Manager verwaltet wird.

Selbst wenn der E/A-Manager die aktuelle Dateiposition beibehielt, kann der Aufrufer diese Position zurücksetzen, indem er einen expliziten ByteOffset-Wert an ReadSpbResource übergibt. Dadurch wird die aktuelle Dateiposition automatisch in diesen ByteOffset-Wert geändert, der Lesevorgang ausgeführt und dann die Position entsprechend der Anzahl der tatsächlich gelesenen Bytes aktualisiert. Diese Technik bietet dem Aufrufer einen atomischen Such- und Lesedienst.

OpenSpbResource-Parameter	BESCHREIBUNG
DeviceHandle	Ein Handle, das eine Grafikkarte darstellt. Der Anzeige-Miniporttreiber hat dieses Handle zuvor im DeviceHandle-Member der DXGKRNL_INTERFACE-Struktur abgerufen, die an die DxgkDdiStartDevice-Funktion übergeben wurde.
SpbResource	Ein Zeiger auf eine SPB-Ressource, die der Anzeige-Miniporttreiber mit der OpenSpbResource-Funktion geöffnet hat.
Länge	Die Größe des Puffers in Bytes, auf den der Buffer-Parameter verweist.
Buffer	Ein Zeiger auf einen Puffer, der die aus der angegebenen SPB-Ressource gelesenen Daten empfängt.
ByteOffset	Ein optionaler Zeiger auf eine Variable, der den Anfangsbyteoffset in der SPB-Ressource angibt, in der der Lesevorgang beginnt. Wenn versucht wird, über das Ende der Datei hinaus zu lesen, gibt ReadSpbResource einen Fehler zurück.
EventHandle	Ein optionales Handle für ein vom Aufrufer erstelltes Ereignis. Wenn dieser Parameter angegeben wird, wird der Aufrufer in einen Wartezustand versetzt, bis der Lesevorgang abgeschlossen ist und das angegebene Ereignis auf den Signalzustand festgelegt ist. Dieser Parameter kann NULL sein.
IoStatusBlock	Ein Zeiger auf eine IO_STATUS_BLOCK-Struktur, die die endgültige Vervollständigung status und Informationen zum angeforderten Lesevorgang empfängt. Der Information-Member der IO_STATUS_BLOCK-Struktur empfängt die Anzahl der Bytes, die tatsächlich aus der SPB-Ressource gelesen werden.

WriteSpbResource

Schreibt Daten in eine geöffnete SPB-Ressource.

Wenn beim Aufruf der OpenSpbResource-Funktion nur das DesiredAccess-FlagFILE_APPEND_DATA festgelegt wird, wird der ByteOffset-Parameter ignoriert. In diesem Fall werden die Daten im Puffer, auf die der Buffer-Parameter für Längenbytes verweist, ab dem aktuellen Ende der Datei geschrieben.

Wenn beim Aufruf von OpenSpbResource eines der CreateOptions-Flags , FILE_SYNCHRONOUS_IO_ALERT oder FILE_SYNCHRONOUS_IO_NONALERT festgelegt wird, behält der E/A-Manager die aktuelle Dateiposition bei. Wenn ja, kann der Aufrufer von WriteSpbResource angeben, dass der aktuelle Dateipositionsoffset anstelle eines expliziten ByteOffset-Werts verwendet wird. Diese Spezifikation kann mit einer der folgenden Methoden erstellt werden:

Geben Sie einen Zeiger auf einen LARGE_INTEGER Wert an, wobei der HighPart-Member auf -1 und der LowPart-Member auf den systemdefinierte Wert FILE_USE_FILE_POINTER_POSITION (definiert in Wdm.h) festgelegt ist.
Übergeben Sie einen NULL-Zeiger für ByteOffset.

WriteSpbResource aktualisiert die aktuelle Dateiposition, indem die Anzahl der geschriebenen Bytes hinzugefügt wird, wenn der Schreibvorgang abgeschlossen wird, wenn die aktuelle Dateiposition verwendet wird, die vom E/A-Manager verwaltet wird.

Selbst wenn der E/A-Manager die aktuelle Dateiposition beibehielt, kann der Aufrufer diese Position zurücksetzen, indem er einen expliziten ByteOffset-Wert an WriteSpbResource übergibt. Dadurch wird die aktuelle Dateiposition automatisch in diesen ByteOffset-Wert geändert, der Schreibvorgang ausgeführt und dann die Position entsprechend der Anzahl der tatsächlich geschriebenen Bytes aktualisiert. Diese Technik bietet dem Aufrufer einen atomischen Such- und Schreibdienst.

Es ist auch möglich, einen Schreibvorgang am aktuellen Ende der Datei zu starten, indem für ByteOffset ein Zeiger auf einen LARGE_INTEGER Wert angegeben wird, wobei HighPart auf -1 und LowPart auf FILE_WRITE_TO_END_OF_FILE festgelegt ist. Dies funktioniert unabhängig davon, ob der E/A-Manager die aktuelle Dateiposition bei behält.

WriteSpbResource-Parameter	BESCHREIBUNG
DeviceHandle	Ein Handle, das eine Grafikkarte darstellt. Der Anzeigeminiporttreiber hat dieses Handle zuvor im DeviceHandle-Member der DXGKRNL_INTERFACE-Struktur abgerufen, die an die DxgkDdiStartDevice-Funktion übergeben wurde.
SpbResource	Ein Zeiger auf eine SPB-Ressource, die der Anzeigeminiporttreiber mit der OpenSpbResource-Funktion geöffnet hat.
Länge	Die Größe des Puffers in Bytes, auf die der Buffer-Parameter verweist.
Buffer	Ein Zeiger auf einen vom Aufrufer zugewiesenen Puffer, der die Daten enthält, die in die angegebene SPB-Ressource geschrieben werden sollen.
ByteOffset	Ein optionaler Zeiger auf eine Variable, der den Anfangsbyteoffset in der SPB-Ressource angibt, in der der Schreibvorgang beginnt. Wenn die Parameter Length und ByteOffset einen Schreibvorgang über die aktuelle Dateiendemarke hinaus angeben, erweitert WriteSpbResource die Datei automatisch und aktualisiert die Markierung zum Ende der Datei. Alle Bytes, die nicht explizit zwischen diesen alten und neuen End-of-File-Markierungen geschrieben werden, werden als Null definiert.
EventHandle	Ein optionales Handle für ein vom Anrufer erstelltes Ereignis. Wenn dieser Parameter angegeben wird, wird der Aufrufer in einen Wartezustand versetzt, bis der Schreibvorgang abgeschlossen ist und das angegebene Ereignis auf den Signalzustand festgelegt ist. Dieser Parameter kann NULL sein.
IoStatusBlock	Ein Zeiger auf eine IO_STATUS_BLOCK-Struktur, die die endgültige Vervollständigung status und Informationen zum angeforderten Schreibvorgang empfängt. Das Information-Element der IO_STATUS_BLOCK-Struktur empfängt die Anzahl der Bytes, die tatsächlich in die SPB-Ressource geschrieben wurden.

SpbResourceIoControl

Führt einen E/A-Steuerungsvorgang für eine geöffnete SPB-Ressource (Simple Peripheral Bus) aus. Alle Eingabeparameter werden vom Anzeigeminiporttreiber bereitgestellt.

Wenn der Aufrufer die Datei für asynchrone E/A geöffnet hat (ohne dass FILE_SYNCHRONOUS_XXX Option create/open festgelegt ist), wird das angegebene Ereignis, falls vorhanden, auf den Signalzustand festgelegt, wenn der Gerätesteuerungsvorgang abgeschlossen ist. Andernfalls wird das durch den DeviceHandle-Parameter angegebene Dateiobjekt auf den Signaled-Zustand festgelegt.

SpbResourceIoControl-Parameter	BESCHREIBUNG
DeviceHandle	Ein Handle, das einen Anzeigeadapter darstellt. Der Anzeigeminiporttreiber hat dieses Handle zuvor im DeviceHandle-Member der DXGKRNL_INTERFACE-Struktur abgerufen, die an die DxgkDdiStartDevice-Funktion übergeben wurde.
SpbResource	Ein Zeiger auf eine SPB-Ressource, die der Anzeigeminiporttreiber mit der OpenSpbResource-Funktion geöffnet hat.
Iocontrolcode	Ein Geräte-E/A-Steuercode (IOCTL_XXX), der angibt, auf welchem Geräte-E/A-Steuerungsvorgang ausgeführt werden soll, in der Regel vom zugrunde liegenden Gerätetreiber. Der Wert dieses Parameters bestimmt das Format und die erforderliche Länge der Parameter InputBuffer und OutputBuffer sowie welche der folgenden Parameterpaare erforderlich sind.
InBufferSize	Die Größe des Puffers in Bytes, auf den der InputBuffer-Parameter verweist. Dieser Wert wird ignoriert, wenn InputBufferNULL ist.
Inputbuffer	Ein Zeiger auf einen vom Aufrufer zugewiesenen Eingabepuffer, der gerätespezifische Informationen enthält, die dem Zielgerät zugewiesen werden sollen. Wenn der IoControlCode-Parameter einen Vorgang angibt, der keine Eingabedaten erfordert, kann dieser Zeiger NULL sein.
OutBufferSize	Die Größe des Puffers in Bytes, auf die der OutputBuffer-Parameter verweist. Dieser Wert wird ignoriert, wenn OutputBufferNULL ist.
OutputBuffer	Ein Zeiger auf einen vom Aufrufer zugewiesenen Ausgabepuffer, in dem Informationen vom Zielgerät zurückgegeben werden. Wenn der IoControlCode-Parameter einen Vorgang angibt, der keine Ausgabedaten erzeugt, kann dieser Zeiger NULL sein.
EventHandle	Ein optionales Handle für ein vom Anrufer erstelltes Ereignis. Wenn dieser Parameter angegeben wird, wird der Aufrufer in einen Wartezustand versetzt, bis der angeforderte Vorgang abgeschlossen ist und das angegebene Ereignis auf den Signalzustand festgelegt ist. Dieser Parameter kann NULL sein.
IoStatusBlock	Ein Zeiger auf eine Variable, die die endgültige Vervollständigung status und Informationen zum angeforderten E/A-Steuerungsvorgang empfängt. Bei erfolgreichen Aufrufen, die Daten zurückgeben, wird die Anzahl der Bytes, die in den Puffer geschrieben wurden, auf die der OutputBuffer-Parameter verweist, im Element Information der IO_STATUS_BLOCK-Struktur zurückgegeben.

Hinweise

Um die Funktionen dieser Struktur zu verwenden, geben Sie zuerst die Member Size und Version der DXGK_SPB_INTERFACE-Struktur an. Rufen Sie dann die DxgkCbQueryServices-Funktion auf, wobei der Parameter ServicesType auf einen Wert von DxgkServicesFirmwareTable festgelegt ist, und legen Sie den Parameter Interface auf die Adresse (als PINTERFACE umgewandelt) der DXGK_SPB_INTERFACE-Struktur fest.

Weitere Informationen zur SPB-Architektur finden Sie unter Entwurfshandbuch für einfache Peripheriebusse und SPB-Peripherietreiber**.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 8
Unterstützte Mindestversion (Server)	Windows Server 2012
Kopfzeile	dispmprt.h (include Dispmprt.h)

Freigeben über