IOCTL_VPCI_INVALIDATE_BLOCK IOCTL (kgi.h)

Artikel
02/07/2025

Der Treiber für eine virtuelle PCI Express(PCIe)-Funktion (VF) gibt die IOCTL_VPCI_INVALIDATE_BLOCK IOCTL-Anforderung aus, um über Änderungen an Daten in mindestens einem VF-Konfigurationsblock benachrichtigt zu werden. Der Treiber wird über diese Änderungen benachrichtigt, wenn die IOCTL abgeschlossen ist. Nach der Benachrichtigung sollte der Treiber davon ausgehen, dass alle zuvor aus den angegebenen VF-Konfigurationsblöcken gelesenen Daten ungültig wurden. Daher sollte der Treiber den Cache aktualisieren, indem die Konfigurationsblockdaten erneut gelesen werden.

Der Treiber gibt diesen IOCTL auf den nächsten niedrigeren Treiber im Treiberstapel aus.

Hinweis Diese IOCTL-Anforderung wird vom Treiber eines PCIe VF auf einem Gerät ausgestellt, das die einzelne I/O-Virtualisierungsschnittstelle (SR-IOV) unterstützt.

Wenn der Treiber die IOCTL_VPCI_INVALIDATE_BLOCK IOCTL ausgibt, muss der Treiber die folgenden Schritte ausführen:

Vorbereiten einer E/A-Anforderungspaketstruktur

Vorbereiten einer E/A-Stapelpositionsstruktur

Ausstellen der IOCTL-Anforderung

IOCTL-Anforderungsabschlussergebnisse

Weitere Informationen zum Ausstellen von IOCTLs zwischen Kernelmodustreibern finden Sie unter Erstellen von IOCTL-Anforderungen in Treibern.

Hauptcode

IRP_MJ_DEVICE_CONTROL

Statusblock

Irp->IoStatus.Status wird auf STATUS_SUCCESS festgelegt, wenn die Anforderung erfolgreich ist.

Andernfalls ist status to the appropriate error condition as a NTSTATUS code.

Weitere Informationen finden Sie unter [XREF-LINK:NTSTATUS Values].

Bemerkungen

Vorbereiten einer E/A-Anforderungspaketstruktur

Der Treiber muss zuerst ein E/A-Anforderungspaket (IRP-) zuweisen oder wiederverwenden. Sie können die IoBuildDeviceIoControlRequest Routine verwenden, um eine IOCTL-IRP speziell zuzuweisen. Sie können auch allgemeine IRP-Erstellungs- und Initialisierungsroutinen wie IoAllocateIrp, IoReuseIrpoder IoInitializeIrpverwenden. Weitere Informationen zur IRP-Zuweisung finden Sie unter Creating IRPs for Lower-Level Drivers.

Der Treiber muss dann die Elemente der IRP- Struktur festlegen, wie in der folgenden Tabelle beschrieben.

IRP Mitglied	Wert
UserBuffer-	NULL-
UserEvent-	Die Adresse des Ereignisobjekts, das im Aufruf der KeInitializeEvent Routine initialisiert wurde. Hinweis Wenn der asynchrone Abschluss der IOCTL-Anforderung nicht erforderlich ist, sollte dieses Element auf NULL-festgelegt werden. Weitere Informationen finden Sie unter Erstellen von IOCTL-Anforderungen in Treibern.
UserIosb-	Die Adresse einer vom Anrufer zugewiesenen IO_STATUS_BLOCK Struktur. Diese Struktur wird vom unteren Treiber aktualisiert, um den endgültigen Status der E/A-Anforderung anzugeben.

Vorbereiten einer E/A-Stapelpositionsstruktur

Der Treiber ruft die IoGetNextIrpStackLocation Routine auf, um auf die I/O-Position des niedrigeren Treibers zuzugreifen. Diese Funktion gibt einen Zeiger auf eine IO_STACK_LOCATION Struktur zurück, die die Parameter für die E/A-Stapelposition enthält.

Der Treiber muss dann die Elemente in der IO_STACK_LOCATION Struktur festlegen, wie in der folgenden Tabelle beschrieben.

mitglied IO_STACK_LOCATION	Wert
MajorFunction-	IRP_MJ_INTERNAL_DEVICE_CONTROL
Parameter.DeviceIoControl.IoControlCode-	IOCTL_VPCI_INVALIDATE_BLOCK
Parameter.DeviceIoControl.Type3InputBuffer-	Ein Zeiger auf eine VPCI_INVALIDATE_BLOCK_OUTPUT Struktur. Der Treiber formatiert diese Struktur mit den Parametern für die IOCTL_VPCI_INVALIDATE_BLOCK E/A-Anforderung.
IchParameter.DeviceIoControl.InputBufferLength-	Die Größe der VPCI_INVALIDATE_BLOCK_OUTPUT Struktur in Byte.
Parameter.DeviceIoControl.OutputBufferLength-	Die Größe des vom Aufrufer zugewiesenen Puffers in Bytes, der die zu lesenden Konfigurationsdaten enthält. Note This value must be the same as the value of the BytesRequested member of the VPCI_INVALIDATE_BLOCK_OUTPUT structure.

Ausstellen der IOCTL-Anforderung

Um diese IOCTL-Anforderung ausstellen zu können, ruft der Treiber die IoCallDriver Routine auf, um die Anforderung an den nächsten niedrigeren Treiber im Treiberstapel zu übergeben. Der Treiber legt die Parameter IoCallDriver fest, wie in der folgenden Tabelle beschrieben.

IoCallDriver Parameter	Wert
DeviceObject-	Das Geräteobjekt des unteren Treibers.
Irp-	Die Adresse der IRP-, die zuvor zugewiesen und initialisiert wurde. Weitere Informationen finden Sie unter Vorbereiten einer E/A-Anforderungspaketstruktur.

IOCTL-Anforderungsabschlussergebnisse

Wenn die IOCTL_VPCI_INVALIDATE_BLOCK IOCTL-Anforderung abgeschlossen ist, werden die Mitglieder der IO_STATUS_BLOCK Struktur zugewiesenen Aufrufers auf die Werte in der folgenden Tabelle festgelegt.

Statuswert	Wert
Status-	STATUS_SUCCESS
Information	Null

Wenn die IOCTL_VPCI_INVALIDATE_BLOCK IOCTL ausgestellt und abgeschlossen wird, wird der VF-Treiber benachrichtigt, dass der PF-Treiber (ungültige) Daten in mindestens einem VF-Konfigurationsblock geändert hat.

Hinweis Das Betriebssystem reserviert und verwaltet die Ressourcen, die für den erfolgreichen Abschluss dieses IOCTL erforderlich sind.

Ein VF-Konfigurationsblock wird für die Backchannel-Kommunikation zwischen den Treibern der PCIe PF und einem VF auf einem Gerät verwendet, das die SR-IOV-Schnittstelle unterstützt. VF-Konfigurationsdaten können zwischen den folgenden Treibern ausgetauscht werden:

Der VF-Treiber, der im Gastbetriebssystem ausgeführt wird. Dieses Betriebssystem wird in einer Hyper-V untergeordneten Partition ausgeführt.
Der PF-Treiber, der im Verwaltungsbetriebssystem ausgeführt wird.
Dieses Betriebssystem wird innerhalb der Hyper-V übergeordneten Partition ausgeführt.

Ab NDIS 6.30 sollte der VF-Miniporttreiber keine IOCTL_VPCI_INVALIDATE_BLOCK Anforderung ausgeben. Stattdessen werden die folgenden Schritte ausgeführt, um Benachrichtigungen über ungültige VF-Konfigurationsblockdaten zu behandeln.

Im Gastbetriebssystem gibt NDIS eine IOCTL_VPCI_INVALIDATE_BLOCK Anforderung aus.
Im Verwaltungsbetriebssystem werden die folgenden Schritte ausgeführt:
1. Der PF Miniport-Treiber ruft den NdisMInvalidateConfigBlock Funktion auf, um NDIS zu benachrichtigen, dass die VF-Konfigurationsdaten geändert wurden und nicht mehr gültig sind. Der Treiber legt den BlockMask Parameter auf eine ULONGLONG Bitmaske fest, die angibt, welche VF-Konfigurationsblöcke geändert wurden. Jedes Bit in der Bitmaske entspricht einem VF-Konfigurationsblock. Wenn ein Bit auf eins festgelegt ist, wurden die Daten im entsprechenden VF-Konfigurationsblock geändert.
2. NDIS signalisiert den Virtualisierungsstapel, der im Verwaltungsbetriebssystem ausgeführt wird, über die Änderung der VF-Konfigurationsblockdaten. Der Virtualisierungsstapel speichert die BlockMask Parameterdaten zwischen.
  Note Each time that the PF miniport driver calls NdisMInvalidateConfigBlock, the virtualization stack ORs the BlockMask parameter data with the current value in its cache.
3. Der Virtualisierungsstapel benachrichtigt den virtuellen PCI-Treiber (PCII), der im Gastbetriebssystem ausgeführt wird, über die Ungültigkeit von VF-Konfigurationsdaten. Der Virtualisierungsstapel sendet den zwischengespeicherten BlockMask Parameterdaten an den DRIVERI-Treiber.
Im Gastbetriebssystem werden die folgenden Schritte ausgeführt:
1. Der VORGANGStreiber speichert die zwischengespeicherten BlockMask Parameterdaten im BlockMask Member der VPCI_INVALIDATE_BLOCK_OUTPUT Struktur, die der IOCTL_VPCI_INVALIDATE_BLOCK Anforderung zugeordnet ist.
2. Der VORGANGstreiber KONNTE die IOCTL_VPCI_INVALIDATE_BLOCK Anforderung erfolgreich abschließen. In diesem Fall gibt NDIS eine OID-Anforderung (Object Identifier) von OID_SRIOV_VF_INVALIDATE_CONFIG_BLOCK an den VF-Miniporttreiber aus. Ein Zeiger auf eine NDIS_SRIOV_VF_INVALIDATE_CONFIG_BLOCK_INFO Struktur wird in der OID-Anforderung übergeben. Diese Struktur enthält die zwischengespeicherten BlockMask- Parameterdaten.
  NDIS stellt auch eine weitere IOCTL_VPCI_INVALIDATE_BLOCK Anforderung zur Behandlung aufeinander folgender Benachrichtigungen von Änderungen an VF-Konfigurationsdaten aus.
3. Wenn der VF-Treiber die OID_SRIOV_VF_INVALIDATE_CONFIG_BLOCK Anforderung verarbeitet, liest er Daten aus den angegebenen VF-Konfigurationsblöcken.

Hinweis Die Verwendung des VF-Konfigurationsblocks und das Format der Konfigurationsdaten werden vom unabhängigen Hardwareanbieter (IHV) des Geräts definiert. Die Konfigurationsdaten werden nur von den Treibern der PF und VF verwendet.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Unterstützt in Windows Server 2012 und höheren Versionen von Windows.
Header-	austriai.h (include Wdm.h)
IRQL-	DISPATCH_LEVEL