IOCTL_VPCI_WRITE_BLOCK IOCTL (vpci.h)

Article
02/07/2025

Le pilote d’une fonction virtuelle PCI Express (PCIe) émet un code de contrôle d’E/S (IOCTL) IOCTL_VPCI_WRITE_BLOCK afin d’écrire des données dans un bloc de configuration VF. Le pilote émet cette IOCTL au pilote inférieur suivant dans la pile des pilotes.

Remarque Cette demande IOCTL est émise par le pilote d’une machine virtuelle PCIe sur un appareil qui prend en charge la virtualisation d’E/S racine unique (SR-IOV).

Lorsque le pilote émet la IOCTL_VPCI_WRITE_BLOCK IOCTL, le pilote doit suivre les étapes suivantes :

préparation d’une structure de paquets de requête d’E/S

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

émettre la demande IOCTL

résultats de la saisie semi-automatique des demandes IOCTL

Pour plus d’informations sur l’émission de iocTLs entre les pilotes en mode noyau, consultez Création de requêtes 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 [Valeurs XREF-LINK :NTSTATUS].

Remarques

préparation d’une structure de paquets de requête 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 routine IoBuildDeviceIoControlRequest pour allouer spécifiquement un IRP IOCTL. Vous pouvez également utiliser des routines de création et d’initialisation à usage général, telles que IoAllocateIrp, IoReuseIrpou IoInitializeIrp. Pour plus d’informations sur l’allocation IRP, consultez Création d’IRPs pour Lower-Level Pilotes.

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

Membre IRP	Valeur
UserBuffer	NULL
UserEvent	Adresse de l’objet d’événement initialisé dans l’appel à la routine KeInitializeEvent. Remarque Si l’achèvement asynchrone de la requête IOCTL n’est pas obligatoire, ce membre doit être défini sur NULL. Pour plus d’informations, consultez Création de requêtes IOCTL dans les pilotes.
UserIosb	Adresse d’une structure IO_STATUS_BLOCK allouée par l’appelant. Cette structure est mise à jour par le pilote inférieur pour indiquer l’état final de la demande d’E/S.

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

Le pilote appelle la routine 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 :

membre IO_STACK_LOCATION	Valeur
MajorFunction	IRP_MJ_INTERNAL_DEVICE_CONTROL
Parameters.DeviceIoControl.IoControlCode	IOCTL_VPCI_WRITE_BLOCK
Parameters.DeviceIoControl.Type3InputBuffer	Pointeur vers une structure VPCI_WRITE_BLOCK_INPUT. Le pilote met en forme cette structure avec les paramètres de la requête d’E/S IOCTL_VPCI_WRITE_BLOCK.
IParameters.DeviceIoControl.InputBufferLength	Taille, en octets, de la structure VPCI_WRITE_BLOCK_INPUT.
Parameters.DeviceIoControl.OutputBufferLength	Zéro

émettre la demande IOCTL

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

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

résultats de la saisie semi-automatique des demandes IOCTL

Une fois la demande IOCTL IOCTL_VPCI_WRITE_BLOCK terminée, l’état membre de la structure IO_STATUS_BLOCK allouée par l’appelant est défini sur l’une des valeurs du tableau suivant :

Valeur d’état	Description
STATUS_SUCCESS	Le IOCTL s’est terminé avec succès.
STATUS_PENDING	Le IOCTL n’a pas terminé. Le pilote doit appeler la routine KeWaitForSingleObject afin de placer le thread actuel dans un état d’attente. Le pilote définit le paramètre Object sur l’adresse d’un objet événement initialisé dans l’appel à la routine 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 a été défini sur une valeur inférieure à la taille, en octets, de la structure VPCI_WRITE_BLOCK_INPUT.

Si la demande s’est terminée avec succès, le membre Information de la structure IO_STATUS_BLOCK est défini sur le nombre d’octets écrits. Dans le cas contraire, le membre Information est défini sur zéro.

Lorsque le IOCTL_VPCI_WRITE_BLOCK IOCTL est émis, le pilote de la fonction physique PCIe (PF) est averti d’écrire les données dans le bloc de configuration VF spécifié.

Remarque Le système d’exploitation réserve et gère les ressources requises pour la réussite de cette IOCTL.

Un bloc de configuration VF est utilisé pour la communication backchannel entre les pilotes du PCIe PF et un VF sur un appareil qui prend en charge l’interface SR-IOV. Le pilote PF alloue un bloc de configuration pour chaque VF dans des blocs inutilisés de l’espace de configuration PCI de l’appareil.

Dès que le bloc de configuration VF est alloué, les données de configuration VF peuvent être échangées de manière protégée 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 du PF et du VF.

Remarque La IOCTL_VPCI_WRITE_BLOCK IOCTL offre une alternative asynchrone à la routine WriteVfConfigBlock.

Exigences

Exigence	Valeur
client minimum pris en charge	Disponible dans Windows Server 2012 et versions ultérieures de Windows.
d’en-tête	vpci.h (include Wdm.h)
IRQL	DISPATCH_LEVEL