IOCTL_VPCI_INVALIDATE_BLOCK IOCTL (vpci.h)

Artikel
03/01/2024

Der Treiber für eine virtuelle PCI-Express-Funktion (PCIe) gibt die IOCTL_VPCI_INVALIDATE_BLOCK IOCTL-Anforderung aus, um über Änderungen an Daten in einem oder mehreren VF-Konfigurationsblöcken 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 Daten, die zuvor aus den angegebenen VF-Konfigurationsblöcken gelesen wurden, ungültig wurden. Daher sollte der Treiber seinen Cache aktualisieren, indem er die Konfigurationsblockdaten erneut liest.

Der Treiber gibt diese IOCTL an den nächstniedrigen Treiber im Treiberstapel aus.

Hinweis Diese IOCTL-Anforderung wird vom Treiber eines PCIe VF auf einem Gerät ausgegeben, das die Single-Root-I/O-Virtualisierungsschnittstelle (SINGLE Root I/O Virtualization, 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-Stapelspeicherortstruktur

Ausstellen der IOCTL-Anforderung

Ergebnisse der IOCTL-Anforderungsabschluss

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 wird Status zur entsprechenden Fehlerbedingung als NTSTATUS-Code verwendet.

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

Hinweise

Vorbereiten einer E/A-Anforderungspaketstruktur

Der Treiber muss zunächst ein E/A-Anforderungspaket (IRP) zuordnen oder wiederverwenden. Sie können die IoBuildDeviceIoControlRequest-Routine verwenden, um eine IOCTL-IRP speziell zuzuordnen. Sie können auch allgemeine IRP-Erstellungs- und Initialisierungsroutinen wie IoAllocateIrp, IoReuseIrp oder IoInitializeIrp verwenden. Weitere Informationen zur IRP-Zuordnung finden Sie unter Erstellen von IRPs für Lower-Level-Treiber.

Der Treiber muss dann die Member 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 dieser Member auf NULL festgelegt werden. Weitere Informationen finden Sie unter Erstellen von IOCTL-Anforderungen in Treibern.
UserIosb	Die Adresse einer vom Aufrufer zugeordneten IO_STATUS_BLOCK-Struktur . Diese Struktur wird vom unteren Treiber aktualisiert, um die endgültige status der E/A-Anforderung anzugeben.

Vorbereiten einer E/A-Stapelspeicherortstruktur

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

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

IO_STACK_LOCATION Mitglied	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.
I-Parameter. DeviceIoControl. InputBufferLength	Die Größe der VPCI_INVALIDATE_BLOCK_OUTPUT-Struktur in Bytes.
Parameter. DeviceIoControl. OutputBufferLength	Die Größe des vom Aufrufer zugewiesenen Puffers in Bytes, der die zu lesenden Konfigurationsdaten enthält. Hinweis Dieser Wert muss mit dem Wert des BytesRequested-Elements der VPCI_INVALIDATE_BLOCK_OUTPUT-Struktur identisch sein.

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ächstniedrigen Treiber im Treiberstapel weiterzureichen. Der Treiber legt die Parameter von IoCallDriver fest, wie in der folgenden Tabelle beschrieben.

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

Ergebnisse der IOCTL-Anforderungsabschluss

Wenn die IOCTL_VPCI_INVALIDATE_BLOCK IOCTL-Anforderung abgeschlossen ist, werden die Elemente der vom Aufrufer zugeordneten IO_STATUS_BLOCK-Struktur 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 Daten in einem oder mehreren VF-Konfigurationsblöcken geändert (ungültig) hat.

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

Ein VF-Konfigurationsblock wird für die Backchannelkommunikation 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 untergeordneten Hyper-V-Partition ausgeführt.
Der PF-Treiber, der im Verwaltungsbetriebssystem ausgeführt wird.
Dieses Betriebssystem wird innerhalb der übergeordneten Hyper-V-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 verarbeiten.

Im Gastbetriebssystem gibt NDIS eine IOCTL_VPCI_INVALIDATE_BLOCK-Anforderung aus.
Im Verwaltungsbetriebssystem werden die folgenden Schritte ausgeführt:
1. Der PF-Miniporttreiber ruft die NdisMInvalidateConfigBlock-Funktion auf, um NDIS zu benachrichtigen, dass SICH DIE VF-Konfigurationsdaten geändert haben und nicht mehr gültig sind. Der Treiber legt den BlockMask-Parameter auf eine ULONGLONGLONG-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, haben sich die Daten im entsprechenden VF-Konfigurationsblock geändert.
2. NDIS signalisiert dem Virtualisierungsstapel, der im Verwaltungsbetriebssystem ausgeführt wird, die Änderung der VF-Konfigurationsblockdaten. Der Virtualisierungsstapel speichert die BlockMask-Parameterdaten zwischen.
  Hinweis Jedes Mal, wenn der PF-Miniporttreiber NdisMInvalidateConfigBlock aufruft, verwendet der Virtualisierungsstapel ODERdie BlockMask-Parameterdaten mit dem aktuellen Wert im Cache.
3. Der Virtualisierungsstapel benachrichtigt den virtuellen PCI-Treiber (VPCI), der im Gastbetriebssystem ausgeführt wird, über die Ungültigkeit von VF-Konfigurationsdaten. Der Virtualisierungsstapel sendet die zwischengespeicherten BlockMask-Parameterdaten an den VPCI-Treiber.
Im Gastbetriebssystem werden die folgenden Schritte ausgeführt:
1. Der VPCI-Treiber 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 VPCI-Treiber schließt die IOCTL_VPCI_INVALIDATE_BLOCK Anforderung erfolgreich ab. In diesem Fall gibt NDIS eine Objektbezeichneranforderung (Object Identifier, OID) 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 zum Verarbeiten von aufeinanderfolgenden Benachrichtigungen über Änderungen an VF-Konfigurationsdaten.
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 seiner Konfigurationsdaten werden vom unabhängigen Hardwareanbieter (Independent Hardware Vendor, IHV) des Geräts definiert. Die Konfigurationsdaten werden nur von den Treibern der PF und VF verwendet.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Unterstützt in Windows Server 2012 und höheren Versionen von Windows.
Kopfzeile	vpci.h (einschließlich Wdm.h)
IRQL	DISPATCH_LEVEL