IOCTL_VPCI_INVALIDATE_BLOCK IOCTL (vpci.h)

Article
02/07/2025

Le pilote d’une fonction virtuelle PCI Express (PCIe) émet la demande IOCTL_VPCI_INVALIDATE_BLOCK IOCTL afin d’être informé des modifications apportées aux données dans un ou plusieurs blocs de configuration VF. Le pilote est informé de ces modifications lorsque le IOCTL est terminé. Une fois averti, le pilote doit supposer que toutes les données lues précédemment à partir des blocs de configuration VF spécifiés ne sont pas valides. Par conséquent, le pilote doit mettre à jour son cache en lisant à nouveau les données du bloc de configuration.

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_INVALIDATE_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
paramètres .DeviceIoControl. IoControlCode	IOCTL_VPCI_INVALIDATE_BLOCK
paramètres .DeviceIoControl.Type3InputBuffer	Pointeur vers une structure VPCI_INVALIDATE_BLOCK_OUTPUT. Le pilote met en forme cette structure avec les paramètres de la requête d’E/S IOCTL_VPCI_INVALIDATE_BLOCK.
IParameters.DeviceIoControl.InputBufferLength	Taille, en octets, de la structure VPCI_INVALIDATE_BLOCK_OUTPUT.
paramètres .DeviceIoControl.OutputBufferLength	Taille, en octets, de la mémoire tampon allouée par l’appelant qui contiendra les données de configuration à lire. Remarque Cette valeur doit être identique à la valeur du membre OctetsRequested de la structure VPCI_INVALIDATE_BLOCK_OUTPUT.

é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 de 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 requête d’E/S.

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

Une fois la requête IOCTL IOCTL_VPCI_INVALIDATE_BLOCK terminée, les membres de la structure IO_STATUS_BLOCK allouée par l’appelant sont définis sur les valeurs du tableau suivant.

Valeur d’état	Valeur
Status	STATUS_SUCCESS
Informations	Zéro

Lorsque le IOCTL_VPCI_INVALIDATE_BLOCK IOCTL est émis et terminé, le pilote VF est averti que le pilote PF a changé (invalidé) données dans un ou plusieurs blocs de configuration VF.

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. Les données 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.

À compter de NDIS 6.30, le pilote miniport VF ne doit pas émettre de requête IOCTL_VPCI_INVALIDATE_BLOCK. Au lieu de cela, les étapes suivantes sont effectuées pour gérer les notifications des données de bloc de configuration VF invalidées.

Dans le système d’exploitation invité, NDIS émet une demande de IOCTL_VPCI_INVALIDATE_BLOCK.
Dans le système d’exploitation de gestion, les étapes suivantes se produisent :
1. Le pilote pf miniport appelle la fonction NdisMInvalidateConfigBlock pour informer NDIS que les données de configuration VF ont changé et qu’elles ne sont plus valides. Le pilote définit le paramètre BlockMask sur un masque de bits ULONGLONG qui spécifie les blocs de configuration VF qui ont changé. Chaque bit dans le masque de bits correspond à un bloc de configuration VF. Si un bit est défini sur un, les données du bloc de configuration VF correspondant ont changé.
2. NDIS signale la pile de virtualisation, qui s’exécute dans le système d’exploitation de gestion, sur la modification des données de bloc de configuration VF. La pile de virtualisation met en cache les données de paramètre BlockMask.
  Remarque Chaque fois que le pilote miniport PF appelle NdisMInvalidateConfigBlock, la pile de virtualisation OUs’agit des données de paramètre BlockMask avec la valeur actuelle dans son cache.
3. La pile de virtualisation notifie le pilote PCI virtuel (VPCI), qui s’exécute dans le système d’exploitation invité, sur l’invalidation des données de configuration VF. La pile de virtualisation envoie les données de paramètre BlockMask mises en cache au pilote VPCI.
Dans le système d’exploitation invité, les étapes suivantes se produisent :
1. Le pilote VPCI enregistre les données de paramètre BlockMask mises en cache dans le membre BlockMask de la structure VPCI_INVALIDATE_BLOCK_OUTPUT associée à la requête IOCTL_VPCI_INVALIDATE_BLOCK.
2. Le pilote VPCI termine correctement la demande de IOCTL_VPCI_INVALIDATE_BLOCK. Dans ce cas, NDIS émet une requête d’identificateur d’objet (OID) de OID_SRIOV_VF_INVALIDATE_CONFIG_BLOCK au pilote miniport VF. Un pointeur vers une structure NDIS_SRIOV_VF_INVALIDATE_CONFIG_BLOCK_INFO est transmis dans la requête OID. Cette structure contient les données de paramètre BlockMask mises en cache.
  NDIS émet également une autre demande de IOCTL_VPCI_INVALIDATE_BLOCK pour gérer les notifications successives des modifications apportées aux données de configuration VF.
3. Lorsque le pilote VF gère la requête OID_SRIOV_VF_INVALIDATE_CONFIG_BLOCK, il lit les données des blocs de configuration VF spécifiés.

Remarque 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.

Exigences

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