IOCTL_VPCI_WRITE_BLOCK IOCTL (vpci.h)

Artikel
02/29/2024

Der Treiber für eine virtuelle PCI Express-Funktion (PCIe) gibt einen IOCTL_VPCI_WRITE_BLOCK E/A-Kontrollcode (IOCTL) aus, um Daten in einen VF-Konfigurationsblock zu schreiben. 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_WRITE_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
Parameters.DeviceIoControl.IoControlCode	IOCTL_VPCI_WRITE_BLOCK
Parameters.DeviceIoControl.Type3InputBuffer	Ein Zeiger auf eine VPCI_WRITE_BLOCK_INPUT-Struktur . Der Treiber formatiert diese Struktur mit den Parametern für die IOCTL_VPCI_WRITE_BLOCK E/A-Anforderung.
IParameters.DeviceIoControl.InputBufferLength	Die Größe der VPCI_WRITE_BLOCK_INPUT-Struktur in Bytes.
Parameters.DeviceIoControl.OutputBufferLength	Null

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 I/O-Anforderungspaketstruktur (IRP).

Ergebnisse der IOCTL-Anforderungsabschluss

Wenn die IOCTL_VPCI_WRITE_BLOCK IOCTL-Anforderung abgeschlossen ist, wird der Status-Member der IO_STATUS_BLOCK-Struktur des Aufrufers 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-Routine 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-Routine 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	Das Parameters.DeviceIoControl.InputBufferLength-Element wurde auf einen Wert festgelegt, der kleiner als die Größe der VPCI_WRITE_BLOCK_INPUT-Struktur in Bytes ist.

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

Wenn die IOCTL_VPCI_WRITE_BLOCK IOCTL ausgestellt wird, wird der Treiber der physischen PCIe-Funktion (PF) benachrichtigt, die Daten in den angegebenen VF-Konfigurationsblock zu schreiben.

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. Der PF-Treiber ordnet jedem VF einen Konfigurationsblock innerhalb nicht verwendeter Blöcke des PCI-Konfigurationsraums des Geräts zu.

Sobald der VF-Konfigurationsblock zugeordnet ist, können VF-Konfigurationsdaten geschützt 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_WRITE_BLOCK IOCTL bietet eine asynchrone Alternative zur WriteVfConfigBlock-Routine .

Anforderungen

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