IOCTL_VPCI_READ_BLOCK IOCTL (vpci.h)

Artikel
08/08/2023

Der Treiber für eine virtuelle PCI-Express-Funktion (PCIe) gibt eine IOCTL_VPCI_READ_BLOCK

E/A-Steuerungscode (IOCTL) zum Lesen von Daten aus einem VF-Konfigurationsblock. 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_READ_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-Funktion verwenden, um eine IOCTL-IRP speziell zuzuordnen. Sie können auch allgemeine IRP-Erstellungs- und Initialisierungsfunktionen 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	Die Adresse des vom Aufrufer zugewiesenen Puffers, der die zu lesenden Konfigurationsdaten enthält.
UserEvent	Die Adresse des Ereignisobjekts, das im Aufruf der KeInitializeEvent-Funktion 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-Funktion 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
Parameters.DeviceIoControl.IoControlCode	IOCTL_VPCI_READ_BLOCK
Parameters.DeviceIoControl.Type3InputBuffer	Ein Zeiger auf eine VPCI_READ_BLOCK_INPUT-Struktur . Der Treiber formatiert diese Struktur mit den Parametern für die IOCTL_VPCI_READ_BLOCK E/A-Anforderung.
IParameters.DeviceIoControl.InputBufferLength	Die Größe der VPCI_READ_BLOCK_INPUT-Struktur in Bytes.
Parameters.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_READ_BLOCK_INPUT-Struktur identisch sein.

Ausstellen der IOCTL-Anforderung

Um diese IOCTL-Anforderung ausstellen zu können, ruft der Treiber die IoCallDriver-Funktion 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 I/O-Anforderungspaketstruktur (IRP).

Ergebnisse der IOCTL-Anforderungsabschluss

Wenn die IOCTL_VPCI_READ_BLOCK IOCTL-Anforderung abgeschlossen ist, wird der Status-Member der vom Aufrufer zugeordneten IO_STATUS_BLOCK-Struktur auf einen der Werte in der folgenden Tabelle festgelegt.

Statuswert	BESCHREIBUNG
STATUS_SUCCESS	Die IOCTL wurde erfolgreich abgeschlossen.
STATUS_PENDING	Die IOCTL wurde nicht abgeschlossen. Der Treiber muss die KeWaitForSingleObject-Funktion aufrufen, um den aktuellen Thread in einen Wartezustand zu versetzen. Der Treiber legt den Object-Parameter auf die Adresse eines Ereignisobjekts fest, das im Aufruf der KeInitializeEvent-Funktion initialisiert wurde. Das Ereignis wird signalisiert, wenn die IOCTL-Anforderung abgeschlossen ist. Sobald das Ereignis signalisiert wurde, setzt der Thread die Ausführung fort.
STATUS_BUFFER_TOO_SMALL	Entweder das Parameters.DeviceIoControl.InputBufferLength-Element oder das Parameters.DeviceIoControl.OutputBufferLength-Element wurde auf einen Wert festgelegt, der kleiner als die erforderliche Puffergröße ist.

Wenn die Anforderung erfolgreich abgeschlossen wurde, wird der Information-Member der IO_STATUS_BLOCK-Struktur auf die Anzahl der gelesenen Bytes festgelegt. Andernfalls wird das Information-Element auf 0 (null) festgelegt.

Wenn die IOCTL_VPCI_READ_BLOCK IOCTL ausgestellt wird, wird der Treiber der physischen PCIe-Funktion (PF) benachrichtigt, die Daten aus dem angegebenen VF-Konfigurationsblock zurückzugeben.

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. Daten aus einem VF-Konfigurationsblock 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.

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

Hinweis Die IOCTL_VPCI_READ_BLOCK IOCTL bietet eine asynchrone Alternative zur ReadVfConfigBlock-Funktion .

Anforderungen

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