DXGK_SPB_INTERFACE structure (dispmprt.h)

Article
08/07/2023

La structure DXGK_SPB_INTERFACE contient des pointeurs vers des fonctions de l’interface SPB (Simple Peripheral Bus) qu’un pilote de miniport Windows Display Driver Model (WDDM) 1.2 et ultérieur peut appeler pour inspecter et modifier les ressources SPB.

Syntaxe

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;

Membres

Size

Taille, en octets, de cette structure.

Version

Numéro de version de l’interface SPB. Les constantes de numéro de version sont définies dans Dispmprt.h (par exemple, DXGK_SPB_INTERFACE_VERSION_1).

Context

Pointeur vers un contexte fourni par le pilote de miniport d’affichage.

InterfaceReference

Pointeur vers une fonction de référence d’interface implémentée par le pilote de miniport d’affichage.

InterfaceDereference

Pointeur vers une fonction de déréférencement d’interface implémentée par le pilote de miniport d’affichage.

OpenSpbResource

Ouvre une ressource SPB (Simple Peripheral Bus). Tous les paramètres d’entrée sont fournis par le pilote de miniport d’affichage.

Paramètre OpenSpbResource	Description
DeviceHandle	Handle qui représente un adaptateur d’affichage. Le pilote de miniport d’affichage a précédemment obtenu ce handle dans le membre DeviceHandle de la structure DXGKRNL_INTERFACE qui a été passée à la fonction DxgkDdiStartDevice .
SpbReourceId	ID de ressource du hub de ressources SPB.
SpbResourceSubName	Pointeur facultatif vers le sous-nom de ressource Unicode SPB.
DesiredAccess	Valeur ACCESS_MASK qui détermine l’accès demandé à la ressource SPB. Pour plus d’informations, consultez le paramètre DesiredAccess de la fonction ZwCreateFile .
ShareAccess	Type d’accès au partage pour le fichier. Pour plus d’informations, consultez le paramètre ShareAccess de ZwCreateFile.
OpenOptions	Options à appliquer lors de l’ouverture de la ressource SPB. Pour plus d’informations, consultez le paramètre CreateOptions de ZwCreateFile.
SpbResource	Pointeur vers une mémoire tampon utilisée pour retourner le handle à la ressource SPB.

CloseSpbResource

Ferme une ressource SPB. Tous les paramètres d’entrée sont fournis par le pilote de miniport d’affichage.

La fermeture d’un handle d’objet ouvert rend ce handle non valide. Le système décrémente également le nombre de handles pour l’objet et vérifie si l’objet peut être supprimé. Le système ne supprime pas réellement l’objet tant que tous les handles de l’objet ne sont pas fermés et qu’aucun pointeur référencé ne reste.

Le pilote doit appeler CloseSpbResource pour fermer chaque handle qu’il a ouvert avec OpenSpbResource dès que le handle n’est plus nécessaire.

Les appelants de CloseSpbResource ne doivent pas supposer que cette fonction attend automatiquement que toutes les E/S se terminent avant de revenir.

CloseSpbResource, paramètre	Description
DeviceHandle	Handle qui représente un adaptateur d’affichage. Le pilote de miniport d’affichage a précédemment obtenu ce handle dans le membre DeviceHandle de la structure DXGKRNL_INTERFACE qui a été passée à la fonction DxgkDdiStartDevice .
SpbResource	Pointeur vers une ressource SPB que le pilote de miniport d’affichage a ouverte à l’aide de la fonction OpenSpbResource .

ReadSpbResource

Lit les données d’une ressource SPB ouverte. Tous les paramètres d’entrée sont fournis par le pilote de miniport d’affichage.

Si l’appel à OpenSpbResource définit l’un des indicateurs OpenOptionsFILE_SYNCHRONOUS_IO_ALERT ou FILE_SYNCHRONOUS_IO_NONALERT (défini dans Wdm.h), le Gestionnaire d’E/S conserve la position du fichier actuel. Dans ce cas, l’appelant de ReadSpbResource peut spécifier que le décalage de position de fichier actuel doit être utilisé au lieu d’une valeur ByteOffset explicite. Cette spécification peut être effectuée à l’aide de l’une des méthodes suivantes :

Spécifiez un pointeur vers une valeur LARGE_INTEGER avec le membre HighPart défini sur -1 et le membre LowPart défini sur la valeur définie par le système FILE_USE_FILE_POINTER_POSITION (défini dans Wdm.h).
Passez un pointeur NULL pour ByteOffset.

ReadSpbResource met à jour la position du fichier actuel en ajoutant le nombre d’octets lus lorsqu’il termine l’opération de lecture, s’il utilise la position de fichier actuelle gérée par le Gestionnaire d’E/S.

Même lorsque le gestionnaire d’E/S conserve la position actuelle du fichier, l’appelant peut réinitialiser cette position en passant une valeur ByteOffset explicite à ReadSpbResource. Cette opération remplace automatiquement la position du fichier actuel par cette valeur ByteOffset , effectue l’opération de lecture, puis met à jour la position en fonction du nombre d’octets réellement lus. Cette technique fournit à l’appelant un service atomique de recherche et de lecture.

Paramètre OpenSpbResource	Description
DeviceHandle	Handle qui représente un adaptateur d’affichage. Le pilote de miniport d’affichage a précédemment obtenu ce handle dans le membre DeviceHandle de la structure DXGKRNL_INTERFACE qui a été passée à la fonction DxgkDdiStartDevice .
SpbResource	Pointeur vers une ressource SPB que le pilote de miniport d’affichage a ouverte à l’aide de la fonction OpenSpbResource .
Durée	Taille, en octets, de la mémoire tampon vers laquelle pointe le paramètre Buffer .
Buffer	Pointeur vers une mémoire tampon qui reçoit les données lues à partir de la ressource SPB spécifiée.
ByteOffset	Pointeur facultatif vers une variable qui spécifie le décalage d’octets de départ dans la ressource SPB où l’opération de lecture va commencer. Si une tentative de lecture est effectuée au-delà de la fin du fichier, ReadSpbResource retourne une erreur.
EventHandle	Handle facultatif pour un événement créé par l’appelant. Si ce paramètre est fourni, l’appelant est placé dans un état d’attente jusqu’à ce que l’opération de lecture soit terminée et que l’événement donné soit défini sur l’état Signaled . Ce paramètre peut être NULL.
IoStatusBlock	Pointeur vers une structure de IO_STATUS_BLOCK qui reçoit le status d’achèvement final et des informations sur l’opération de lecture demandée. Le membre Information de la structure IO_STATUS_BLOCK reçoit le nombre d’octets réellement lus à partir de la ressource SPB.

WriteSpbResource

Écrit des données dans une ressource SPB ouverte.

Si l’appel à la fonction OpenSpbResource définit uniquement l’indicateur DesiredAccessFILE_APPEND_DATA, le paramètre ByteOffset est ignoré. Dans ce cas, les données de la mémoire tampon pointées vers par le paramètre Buffer , pour Length bytes, sont écrites à partir de la fin actuelle du fichier.

Si l’appel à OpenSpbResource définit l’un des indicateurs CreateOptions , FILE_SYNCHRONOUS_IO_ALERT ou FILE_SYNCHRONOUS_IO_NONALERT, le Gestionnaire d’E/S conserve la position actuelle du fichier. Dans ce cas, l’appelant de WriteSpbResource peut spécifier que le décalage de position de fichier actuel doit être utilisé à la place d’une valeur ByteOffset explicite. Cette spécification peut être effectuée à l’aide de l’une des méthodes suivantes :

Spécifiez un pointeur vers une valeur LARGE_INTEGER avec le membre HighPart défini sur -1 et le membre LowPart défini sur la valeur définie par le système FILE_USE_FILE_POINTER_POSITION (défini dans Wdm.h).
Passez un pointeur NULL pour ByteOffset.

WriteSpbResource met à jour la position du fichier actuel en ajoutant le nombre d’octets écrits lorsqu’il termine l’opération d’écriture, s’il utilise la position de fichier actuelle gérée par le Gestionnaire d’E/S.

Même lorsque le gestionnaire d’E/S conserve la position actuelle du fichier, l’appelant peut réinitialiser cette position en passant une valeur ByteOffset explicite à WriteSpbResource. Cela remplace automatiquement la position du fichier actuel par cette valeur ByteOffset , effectue l’opération d’écriture, puis met à jour la position en fonction du nombre d’octets réellement écrits. Cette technique fournit le service de recherche et d’écriture atomique de l’appelant.

Il est également possible de faire démarrer une opération d’écriture à la fin actuelle du fichier en spécifiant pour ByteOffset un pointeur vers une valeur LARGE_INTEGER avec HighPart défini sur -1 et LowPart défini sur FILE_WRITE_TO_END_OF_FILE. Cela fonctionne que le Gestionnaire d’E/S conserve ou non la position actuelle du fichier.

Paramètre WriteSpbResource	Description
DeviceHandle	Handle qui représente un adaptateur d’affichage. Le pilote miniport d’affichage a précédemment obtenu ce handle dans le membre DeviceHandle de la structure DXGKRNL_INTERFACE qui a été passé à la fonction DxgkDdiStartDevice .
SpbResource	Pointeur vers une ressource SPB ouverte par le pilote miniport d’affichage à l’aide de la fonction OpenSpbResource .
Durée	Taille, en octets, de la mémoire tampon pointée vers le paramètre Buffer .
Buffer	Pointeur vers une mémoire tampon allouée à l’appelant qui contient les données à écrire dans la ressource SPB spécifiée.
ByteOffset	Pointeur facultatif vers une variable qui spécifie le décalage d’octet de début dans la ressource SPB où l’opération d’écriture va commencer. Si les paramètres Length et ByteOffset spécifient une opération d’écriture au-delà de la marque de fin de fichier actuelle, WriteSpbResource étend automatiquement le fichier et met à jour la marque de fin de fichier ; tous les octets qui ne sont pas écrits explicitement entre ces marques de fin de fichier anciennes et nouvelles sont définis comme étant zéro.
EventHandle	Handle facultatif pour un événement créé par l’appelant. Si ce paramètre est fourni, l’appelant est placé dans un état d’attente jusqu’à ce que l’opération d’écriture soit terminée et que l’événement donné soit défini sur l’état Signaled . Ce paramètre peut être NULL.
IoStatusBlock	Pointeur vers une structure de IO_STATUS_BLOCK qui reçoit le status d’achèvement final et des informations sur l’opération d’écriture demandée. Le membre Information de la structure IO_STATUS_BLOCK reçoit le nombre d’octets réellement écrits dans la ressource SPB.

SpbResourceIoControl

Effectue une opération de contrôle d’E/S sur une ressource SPB (Simple Peripheral Bus) ouverte. Tous les paramètres d’entrée sont fournis par le pilote miniport d’affichage.

Si l’appelant a ouvert le fichier pour les E/S asynchrones (sans FILE_SYNCHRONOUS_XXX’option créer/ouvrir), l’événement spécifié, le cas échéant, est défini à l’état Signaled à la fin de l’opération de contrôle de l’appareil. Sinon, l’objet de fichier spécifié par le paramètre DeviceHandle sera défini à l’état Signaled .

Paramètre SpbResourceIoControl	Description
DeviceHandle	Handle qui représente une carte d’affichage. Le pilote miniport d’affichage a précédemment obtenu ce handle dans le membre DeviceHandle de la structure DXGKRNL_INTERFACE qui a été passé à la fonction DxgkDdiStartDevice .
SpbResource	Pointeur vers une ressource SPB ouverte par le pilote miniport d’affichage à l’aide de la fonction OpenSpbResource .
IoControlCode	Code de contrôle d’E/S d’appareil (IOCTL_XXX) qui indique l’opération de contrôle d’E/S d’appareil à effectuer, généralement par le pilote de périphérique sous-jacent. La valeur de ce paramètre détermine le format et la longueur requise des paramètres InputBuffer et OutputBuffer , ainsi que les paires de paramètres suivantes qui sont requises.
InBufferSize	Taille, en octets, de la mémoire tampon pointée vers le paramètre InputBuffer . Cette valeur est ignorée si InputBuffer a la valeur NULL.
InputBuffer	Pointeur vers une mémoire tampon d’entrée allouée à l’appelant qui contient des informations spécifiques à l’appareil à fournir à l’appareil cible. Si le paramètre IoControlCode spécifie une opération qui ne nécessite pas de données d’entrée, ce pointeur peut avoir la valeur NULL.
OutBufferSize	Taille, en octets, de la mémoire tampon pointée vers le paramètre OutputBuffer . Cette valeur est ignorée si OutputBuffer a la valeur NULL.
OutputBuffer	Pointeur vers une mémoire tampon de sortie allouée à l’appelant dans laquelle les informations sont retournées à partir de l’appareil cible. Si le paramètre IoControlCode spécifie une opération qui ne produit pas de données de sortie, ce pointeur peut avoir la valeur NULL.
EventHandle	Handle facultatif pour un événement créé par l’appelant. Si ce paramètre est fourni, l’appelant est placé dans un état d’attente jusqu’à ce que l’opération demandée soit terminée et que l’événement donné soit défini sur l’état Signaled . Ce paramètre peut être NULL.
IoStatusBlock	Pointeur vers une variable qui reçoit l’achèvement final status et des informations sur l’opération de contrôle d’E/S demandée. Pour les appels réussis qui retournent des données, le nombre d’octets écrits dans la mémoire tampon pointée par le paramètre OutputBuffer est retourné dans le membre Information de la structure IO_STATUS_BLOCK .

Remarques

Pour utiliser les fonctions de cette structure, fournissez d’abord les membres Size et Version de la structure DXGK_SPB_INTERFACE . Ensuite, appelez la fonction DxgkCbQueryServices avec le paramètre ServicesType défini sur une valeur de DxgkServicesFirmwareTable et définissez le paramètre Interface sur l’adresse (cast en tant que PINTERFACE) de la structure DXGK_SPB_INTERFACE .

Pour plus d’informations sur l’architecture SPB, consultez Bus périphériques simples et Guide de conception du pilote périphérique SPB**.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 8
Serveur minimal pris en charge	Windows Server 2012
En-tête	dispmprt.h (inclure Dispmprt.h)

Partager via