DXGK_SPB_INTERFACE struttura (dispmprt.h)

  • Articolo

La struttura DXGK_SPB_INTERFACE contiene puntatori alle funzioni nell'interfaccia SPB (Simple Peripheral Bus) che un modello wdDM (Windows Display Driver Model) 1.2 e versioni successive può chiamare per controllare e modificare le risorse SPB.

Sintassi

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;

Members

Size

Dimensione, in byte, della struttura.

Version

Numero di versione dell'interfaccia SPB. Le costanti del numero di versione sono definite in Dispmprt.h (ad esempio, DXGK_SPB_INTERFACE_VERSION_1).

Context

Puntatore a un contesto fornito dal driver miniport visualizzato.

InterfaceReference

Puntatore a una funzione di riferimento dell'interfaccia implementata dal driver miniport visualizzato.

InterfaceDereference

Puntatore a una funzione di dereferenza dell'interfaccia implementata dal driver miniport visualizzato.

OpenSpbResource

Apre una risorsa SPB (Simple Peripheral Bus). Tutti i parametri di input vengono forniti dal driver miniport visualizzato.

Parametro OpenSpbResource Descrizione
DeviceHandle Handle che rappresenta una scheda di visualizzazione. Il driver miniport visualizzato in precedenza ha ottenuto questo handle nel membro DeviceHandle della struttura DXGKRNL_INTERFACE passata alla funzione DxgkDdiStartDevice .
SpbReourceId ID risorsa dell'hub risorse SPB.
SpbResourceSubName Puntatore facoltativo al nome secondario della risorsa SPB Unicode.
DesiredAccess Valore ACCESS_MASK che determina l'accesso richiesto alla risorsa SPB. Per altre informazioni, vedere il parametro DesiredAccess della funzione ZwCreateFile .
ShareAccess Tipo di accesso di condivisione per il file. Per altre informazioni, vedere il parametro ShareAccess di ZwCreateFile.
OpenOptions Opzioni da applicare quando si apre la risorsa SPB. Per altre informazioni, vedere il parametro CreateOptions di ZwCreateFile.
SpbResource Puntatore a un buffer utilizzato per restituire l'handle alla risorsa SPB.

CloseSpbResource

Chiude una risorsa SPB. Tutti i parametri di input vengono forniti dal driver miniport visualizzato.

La chiusura di un handle di oggetti aperto causa la non validità dell'handle. Il sistema decrementa anche il numero di handle per l'oggetto e verifica se l'oggetto può essere eliminato. Il sistema non elimina effettivamente l'oggetto finché non vengono chiusi tutti gli handle dell'oggetto e non rimangono puntatori a riferimento.

Il driver deve chiamare CloseSpbResource per chiudere ogni handle aperto con OpenSpbResource non appena l'handle non è più necessario.

I chiamanti di CloseSpbResource non devono presupporre che questa funzione attenda automaticamente il completamento di tutte le operazioni di I/O prima della restituzione.

Parametro CloseSpbResource Descrizione
DeviceHandle Handle che rappresenta una scheda di visualizzazione. Il driver miniport visualizzato in precedenza ha ottenuto questo handle nel membro DeviceHandle della struttura DXGKRNL_INTERFACE passata alla funzione DxgkDdiStartDevice .
SpbResource Puntatore a una risorsa SPB aperta dal driver miniport visualizzato usando la funzione OpenSpbResource .

ReadSpbResource

Legge i dati da una risorsa SPB aperta. Tutti i parametri di input vengono forniti dal driver miniport visualizzato.

Se la chiamata a OpenSpbResource imposta uno dei flag OpenOptionsFILE_SYNCHRONOUS_IO_ALERT o FILE_SYNCHRONOUS_IO_NONALERT (definito in Wdm.h), gestione I/O mantiene la posizione del file corrente. In tal caso, il chiamante readSpbResource può specificare che l'offset di posizione del file corrente viene usato anziché un valore ByteOffset esplicito. Questa specifica può essere effettuata usando uno dei metodi seguenti:

  • Specificare un puntatore a un valore LARGE_INTEGER con il membro HighPart impostato su -1 e il membro LowPart impostato sul valore definito dal sistema FILE_USE_FILE_POINTER_POSITION (definito in Wdm.h).
  • Passare un puntatore NULL per ByteOffset.

ReadSpbResource aggiorna la posizione del file corrente aggiungendo il numero di byte letti al termine dell'operazione di lettura, se usa la posizione del file corrente gestita da Gestione I/O.

Anche quando gestione I/O mantiene la posizione del file corrente, il chiamante può reimpostare questa posizione passando un valore ByteOffset esplicito a ReadSpbResource. Questa operazione modifica automaticamente la posizione del file corrente in tale valore ByteOffset , esegue l'operazione di lettura e quindi aggiorna la posizione in base al numero di byte effettivamente letti. Questa tecnica fornisce al chiamante il servizio atomico di ricerca e lettura.

Parametro OpenSpbResource Descrizione
DeviceHandle Handle che rappresenta una scheda di visualizzazione. Il driver miniport visualizzato in precedenza ha ottenuto questo handle nel membro DeviceHandle della struttura DXGKRNL_INTERFACE passata alla funzione DxgkDdiStartDevice .
SpbResource Puntatore a una risorsa SPB aperta dal driver miniport visualizzato usando la funzione OpenSpbResource .
Lunghezza Dimensioni, in byte, del buffer a cui fa riferimento il parametro Buffer .
Buffer Puntatore a un buffer che riceve i dati letti dalla risorsa SPB specificata.
ByteOffset Puntatore facoltativo a una variabile che specifica l'offset di byte iniziale nella risorsa SPB in cui verrà avviata l'operazione di lettura. Se viene eseguito un tentativo di lettura oltre la fine del file, ReadSpbResource restituisce un errore.
EventHandle Handle facoltativo per un evento creato dal chiamante. Se questo parametro viene fornito, il chiamante verrà inserito in uno stato di attesa fino al completamento dell'operazione di lettura e l'evento specificato viene impostato sullo stato Signaled . Questo parametro può essere NULL.
IoStatusBlock Puntatore a una struttura IO_STATUS_BLOCK che riceve lo stato di completamento finale e informazioni sull'operazione di lettura richiesta. Il membro Information della struttura IO_STATUS_BLOCK riceve il numero di byte effettivamente letti dalla risorsa SPB.

WriteSpbResource

Scrive i dati in una risorsa SPB aperta.

Se la chiamata alla funzione OpenSpbResource imposta solo il flag DesiredAccessFILE_APPEND_DATA, il parametro ByteOffset viene ignorato. In questo caso, i dati nel buffer puntati dal parametro Buffer , per i byte di lunghezza , vengono scritti a partire dalla fine del file corrente.

Se la chiamata a OpenSpbResource imposta uno dei flag CreateOptions , FILE_SYNCHRONOUS_IO_ALERT o FILE_SYNCHRONOUS_IO_NONALERT, gestione I/O mantiene la posizione del file corrente. In tal caso, il chiamante writeSpbResource può specificare che l'offset di posizione del file corrente viene usato anziché un valore ByteOffset esplicito. Questa specifica può essere effettuata usando uno dei metodi seguenti:

  • Specificare un puntatore a un valore LARGE_INTEGER con il membro HighPart impostato su -1 e il membro LowPart impostato sul valore definito dal sistema FILE_USE_FILE_POINTER_POSITION (definito in Wdm.h).
  • Passare un puntatore NULL per ByteOffset.

WriteSpbResource aggiorna la posizione del file corrente aggiungendo il numero di byte scritti al termine dell'operazione di scrittura, se si usa la posizione corrente del file gestita da Gestione I/O.

Anche quando gestione I/O mantiene la posizione del file corrente, il chiamante può reimpostare questa posizione passando un valore ByteOffset esplicito a WriteSpbResource. Questa operazione modifica automaticamente la posizione del file corrente in tale valore ByteOffset , esegue l'operazione di scrittura e quindi aggiorna la posizione in base al numero di byte effettivamente scritti. Questa tecnica fornisce al chiamante il servizio di ricerca atomica e scrittura.

È anche possibile causare l'avvio di un'operazione di scrittura alla fine corrente del file specificando per ByteOffset un puntatore a un valore LARGE_INTEGER con HighPart impostato su -1 e LowPart impostato su FILE_WRITE_TO_END_OF_FILE. Ciò funziona indipendentemente dal fatto che Gestione I/O mantenga la posizione del file corrente.

Parametro WriteSpbResource Descrizione
DeviceHandle Handle che rappresenta una scheda di visualizzazione. Il driver miniport di visualizzazione ottenuto in precedenza questo handle nel membro DeviceHandle della struttura DXGKRNL_INTERFACE passata alla funzione DxgkDdiStartDevice .
SpbResource Puntatore a una risorsa SPB aperta dal driver miniport visualizzato usando la funzione OpenSpbResource .
Lunghezza Dimensione, in byte, del buffer a cui punta il parametro Buffer .
Buffer Puntatore a un buffer allocato dal chiamante che contiene i dati da scrivere nella risorsa SPB specificata.
ByteOffset Puntatore facoltativo a una variabile che specifica l'offset dei byte iniziale nella risorsa SPB in cui inizierà l'operazione di scrittura. Se i parametri Length e ByteOffset specificano un'operazione di scrittura oltre il contrassegno di fine file corrente, WriteSpbResource estende automaticamente il file e aggiorna il contrassegno di fine file; tutti i byte che non vengono scritti in modo esplicito tra tali contrassegni precedenti e nuovi contrassegni di fine file sono definiti come zero.
EventHandle Handle facoltativo per un evento creato dal chiamante. Se questo parametro viene specificato, il chiamante verrà inserito in uno stato di attesa fino al completamento dell'operazione di scrittura e l'evento specificato viene impostato sullo stato Segnalato . Questo parametro può essere NULL.
IoStatusBlock Puntatore a una struttura IO_STATUS_BLOCK che riceve lo stato di completamento finale e informazioni sull'operazione di scrittura richiesta. Il membro Information della struttura IO_STATUS_BLOCK riceve il numero di byte effettivamente scritti nella risorsa SPB.

SpbResourceIoControl

Esegue un'operazione di controllo di I/O su una risorsa SPB (Simple Peripheral Bus) aperta. Tutti i parametri di input vengono forniti dal driver miniport di visualizzazione.

Se il chiamante ha aperto il file per operazioni di I/O asincrone (con nessuna FILE_SYNCHRONOUS_XXX set di opzioni create/open), l'evento specificato, se presente, verrà impostato sullo stato Segnalato al termine dell'operazione di controllo del dispositivo. In caso contrario, l'oggetto file specificato dal parametro DeviceHandle verrà impostato sullo stato Signaled .

Parametro SpbResourceIoControl Descrizione
DeviceHandle Handle che rappresenta una scheda di visualizzazione. Il driver miniport di visualizzazione ottenuto in precedenza questo handle nel membro DeviceHandle della struttura DXGKRNL_INTERFACE passata alla funzione DxgkDdiStartDevice .
SpbResource Puntatore a una risorsa SPB aperta dal driver miniport visualizzato usando la funzione OpenSpbResource .
IoControlCode Codice di controllo di I/O del dispositivo (IOCTL_XXX) che indica l'operazione di controllo di I/O del dispositivo da eseguire, in genere dal driver di dispositivo sottostante. Il valore di questo parametro determina il formato e la lunghezza richiesta dei parametri InputBuffer e OutputBuffer , nonché quali delle coppie di parametri seguenti sono necessarie.
InBufferSize Dimensione, in byte, del buffer a cui punta il parametro InputBuffer . Questo valore viene ignorato se InputBuffer è NULL.
Inputbuffer Puntatore a un buffer di input allocato dal chiamante che contiene informazioni specifiche del dispositivo da assegnare al dispositivo di destinazione. Se il parametro IoControlCode specifica un'operazione che non richiede dati di input, questo puntatore può essere NULL.
OutBufferSize Dimensioni, in byte, del buffer a cui punta il parametro OutputBuffer . Questo valore viene ignorato se OutputBuffer è NULL.
OutputBuffer Puntatore a un buffer di output allocato dal chiamante in cui le informazioni vengono restituite dal dispositivo di destinazione. Se il parametro IoControlCode specifica un'operazione che non produce dati di output, questo puntatore può essere NULL.
EventHandle Handle facoltativo per un evento creato dal chiamante. Se questo parametro viene specificato, il chiamante verrà inserito in uno stato di attesa fino al completamento dell'operazione richiesta e l'evento specificato viene impostato sullo stato Segnalato . Questo parametro può essere NULL.
IoStatusBlock Puntatore a una variabile che riceve lo stato di completamento finale e informazioni sull'operazione di controllo di I/O richiesta. Per le chiamate riuscite che restituiscono dati, il numero di byte scritti nel buffer a cui punta il parametro OutputBuffer viene restituito nel membro Information della struttura IO_STATUS_BLOCK .

Commenti

Per usare le funzioni di questa struttura, specificare innanzitutto i membri Size e Version della struttura DXGK_SPB_INTERFACE . Chiamare quindi la funzione DxgkCbQueryServices con il parametro ServicesType impostato su un valore dxgkServicesFirmwareTable e impostare il parametro Interface sull'indirizzo (cast come PINTERFACE) della struttura DXGK_SPB_INTERFACE .

Per altre informazioni sull'architettura SPB, vedere Simple Peripheral Buses and SPB Peripheral Driver Design Guide**.

Requisiti

Requisito Valore
Client minimo supportato Windows 8
Server minimo supportato Windows Server 2012
Intestazione dispmprt.h (include Dispmprt.h)