IOCTL_VPCI_READ_BLOCK IOCTL (vpci.h)

Article
02/26/2024

Le pilote d’une fonction virtuelle (VF) PCI Express (PCIe) émet une IOCTL_VPCI_READ_BLOCK

Code de contrôle d’E/S (IOCTL) pour lire les données d’un bloc de configuration VF. Le pilote émet ce IOCTL au pilote inférieur suivant dans la pile de pilotes.

Note Cette demande IOCTL est émise par le pilote d’une instance VF PCIe sur un appareil qui prend en charge l’interface de virtualisation d’E/S racine unique (SR-IOV).

Lorsque le pilote émet le IOCTL_VPCI_READ_BLOCK IOCTL, il doit suivre les étapes suivantes :

Préparation d’une structure de paquets de demande d’E/S

Préparation d’une structure d’emplacement de pile d’E/S

Émission de la demande IOCTL

Résultats de l’achèvement de la requête IOCTL

Pour plus d’informations sur l’émission d’IOCTL entre des pilotes en mode noyau, consultez Création de demandes IOCTL dans les pilotes.

Code principal

IRP_MJ_DEVICE_CONTROL

Bloc d’état

Irp-IoStatus.Status> est défini sur STATUS_SUCCESS si la demande réussit.

Sinon, état à la condition d’erreur appropriée en tant que code NTSTATUS.

Pour plus d’informations, consultez [XREF-LINK :NTSTATUS Values].

Remarques

Préparation d’une structure de paquets de demande d’E/S

Le pilote doit d’abord allouer ou réutiliser un paquet de requête d’E/S (IRP). Vous pouvez utiliser la fonction IoBuildDeviceIoControlRequest pour allouer spécifiquement un IRP IOCTL. Vous pouvez également utiliser des fonctions de création et d’initialisation IRP à usage général, telles que IoAllocateIrp, IoReuseIrp ou IoInitializeIrp. Pour plus d’informations sur l’allocation IRP, consultez Création de runtimes d’intégration pour les pilotes Lower-Level.

Le pilote doit ensuite définir les membres de la structure IRP comme décrit dans le tableau suivant.

Membre IRP	Valeur
UserBuffer	Adresse de la mémoire tampon allouée à l’appelant qui contiendra les données de configuration à lire.
UserEvent	Adresse de l’objet d’événement initialisé dans l’appel à la fonction KeInitializeEvent . Note Si l’exécution asynchrone de la requête IOCTL n’est pas requise, ce membre doit être défini sur NULL. Pour plus d’informations, consultez Création de demandes IOCTL dans les pilotes.
UserIosb	Adresse d’une structure de IO_STATUS_BLOCK allouée par l’appelant. Cette structure est mise à jour par le pilote inférieur pour indiquer la status finale de la demande d’E/S.

Préparation d’une structure d’emplacement de pile d’E/S

Le pilote appelle la fonction IoGetNextIrpStackLocation pour accéder à l’emplacement de la pile d’E/S du pilote inférieur. Cette fonction retourne un pointeur vers une structure IO_STACK_LOCATION qui contient les paramètres de l’emplacement de la pile d’E/S.

Le pilote doit ensuite définir les membres dans la structure IO_STACK_LOCATION comme décrit dans le tableau suivant.

IO_STACK_LOCATION membre	Valeur
MajorFunction	IRP_MJ_INTERNAL_DEVICE_CONTROL
Parameters.DeviceIoControl.IoControlCode	IOCTL_VPCI_READ_BLOCK
Parameters.DeviceIoControl.Type3InputBuffer	Pointeur vers une structure VPCI_READ_BLOCK_INPUT . Le pilote met en forme cette structure avec les paramètres de la demande d’E /S IOCTL_VPCI_READ_BLOCK.
IParameters.DeviceIoControl.InputBufferLength	Taille, en octets, de la structure VPCI_READ_BLOCK_INPUT .
Parameters.DeviceIoControl.OutputBufferLength	Taille, en octets, de la mémoire tampon allouée à l’appelant qui contiendra les données de configuration à lire. Note Cette valeur doit être identique à la valeur du membre BytesRequested de la structure VPCI_READ_BLOCK_INPUT .

Émission de la demande IOCTL

Pour émettre cette requête IOCTL, le pilote appelle la fonction IoCallDriver pour transmettre la demande au pilote inférieur suivant dans la pile de pilotes. Le pilote définit les paramètres d’IoCallDriver comme décrit dans le tableau suivant.

Paramètre IoCallDriver	Valeur
DeviceObject	Objet de périphérique du pilote inférieur.
Irp	Adresse de l’IRP précédemment allouée et initialisée. Pour plus d’informations, consultez Préparation d’une structure de paquets de demandes d’E/S (IRP).

Résultats de l’achèvement de la requête IOCTL

Une fois la requête IOCTL IOCTL_VPCI_READ_BLOCK terminée, le membre Status de la structure de IO_STATUS_BLOCK allouée à l’appelant est défini sur l’une des valeurs du tableau suivant.

Valeur d’état	Description
STATUS_SUCCESS	L’IOCTL s’est terminé avec succès.
STATUS_PENDING	L’IOCTL n’a pas terminé. Le pilote doit appeler la fonction KeWaitForSingleObject pour placer le thread actuel dans un état d’attente. Le pilote définit le paramètre Object sur l’adresse d’un objet d’événement initialisé dans l’appel à la fonction KeInitializeEvent . L’événement est signalé lorsque la demande IOCTL est terminée. Une fois l’événement signalé, le thread reprend l’exécution.
STATUS_BUFFER_TOO_SMALL	Le membre Parameters.DeviceIoControl.InputBufferLength ou le membre Parameters.DeviceIoControl.OutputBufferLength a été défini sur une valeur inférieure à la taille de mémoire tampon requise.

Si la demande s’est terminée correctement, le membre Information de la structure IO_STATUS_BLOCK est défini sur le nombre d’octets qui ont été lus. Sinon, le membre Information est défini sur zéro.

Lorsque le IOCTL_VPCI_READ_BLOCK IOCTL est émis, le pilote de la fonction physique PCIe (PF) est averti de retourner les données du bloc de configuration VF spécifié.

Note Le système d’exploitation réserve et gère les ressources nécessaires à la réussite de ce IOCTL.

Un bloc de configuration VF est utilisé pour la communication backchannel entre les pilotes du PF PCIe et une VF sur un appareil qui prend en charge l’interface SR-IOV. Les données d’un bloc de configuration VF peuvent être échangées entre les pilotes suivants :

Pilote VF, qui s’exécute dans le système d’exploitation invité. Ce système d’exploitation s’exécute dans une partition enfant Hyper-V.
Pilote PF, qui s’exécute dans le système d’exploitation de gestion.
Ce système d’exploitation s’exécute dans la partition parente Hyper-V.

L’utilisation du bloc de configuration VF et le format de ses données de configuration sont définis par le fournisseur de matériel indépendant (IHV) de l’appareil. Les données de configuration sont utilisées uniquement par les pilotes pf et VF.

Note Le IOCTL_VPCI_READ_BLOCK IOCTL offre une alternative asynchrone à la fonction ReadVfConfigBlock .

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Pris en charge dans Windows Server 2012 et versions ultérieures de Windows.
En-tête	vpci.h (inclure Wdm.h)
IRQL	DISPATCH_LEVEL