IOCTL_VPCI_WRITE_BLOCK IOCTL (vpci.h)

Article
08/08/2023

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

Note Cette demande IOCTL est émise par le pilote d’une 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_WRITE_BLOCK IOCTL, il doit suivre les étapes suivantes :

Préparation d’une structure de paquets de demandes 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 demande IOCTL

Pour plus d’informations sur l’émission de 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> a la valeur STATUS_SUCCESS si la demande réussit.

Sinon, indiquez 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 demandes d’E/S

Le pilote doit d’abord allouer ou réutiliser un paquet de demande 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 IRP à usage général, telles que IoAllocateIrp, IoReuseIrp ou IoInitializeIrp. Pour plus d’informations sur l’allocation IRP, consultez Création d’IRP 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	NULL
UserEvent	Adresse de l’objet d’événement initialisé dans l’appel à la routine KeInitializeEvent . Note Si l’exécution asynchrone de la demande 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 à 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 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 de 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_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 demande 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

Émission de 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 d’IoCallDriver comme décrit dans le tableau suivant.

Paramètre IoCallDriver	Valeur
DeviceObject	Objet d’appareil 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 demande IOCTL

Une fois la requête IOCTL IOCTL_VPCI_WRITE_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	Le IOCTL s’est terminé avec succès.
STATUS_PENDING	Le IOCTL n’a pas terminé. Le pilote doit appeler la routine 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 qui a été 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 correctement, le membre Information de la structure IO_STATUS_BLOCK est défini sur le nombre d’octets écrits. Sinon, 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é.

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. Le pilote PF alloue un bloc de configuration pour chaque VF dans les 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 de la VF.

Note Le IOCTL_VPCI_WRITE_BLOCK IOCTL offre une alternative asynchrone à la routine WriteVfConfigBlock .

Configuration requise

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