Kopfzeile pcivirt.h

2025-05-10

Referenzhandbuch für die Verwendung von Schnittstellen, die verwendet werden, um VFs für eine virtuelle Maschine verfügbar zu machen.

Geräte, die der PCI Express Single-Root I/O Virtualization (SR-IOV) -Spezifikation entsprechen, können mehrere Schnittstellen zum Gerät bereitstellen. Diese Schnittstellen, die als virtuelle Funktionen (VFs) bezeichnet werden, sind unabhängig und werden über die anfängliche Geräteschnittstelle bereitgestellt, die als Physical Function (PF) bezeichnet wird. Beispielsweise kann eine Ethernet-Netzwerkkarte, die SR-IOV unterstützt, so konzipiert werden, dass sie über einen Switch mit einem physischen Ethernet-Port (der mit dem physischen Kabel verbunden ist) und vielen virtuellen Ethernet-Ports verfügt.

Der Konfigurationsraum des PF ermöglicht es dem PF-Treiber, die PCI-Ressourcen des VF zu verwalten, einschließlich des speicherabgebildeten I/O-Raums und der nachrichtensignalisierten Interrupts. Da VFs eine Teilmenge eines vollständigen Geräts sind, kann es kostengünstiger sein, sie in Hardware verfügbar zu machen als eine herkömmliche Funktion in einem Multifunktionspaket. Dies ermöglicht es dem Gerätehersteller, mehr Schnittstellen zu erstellen und alle gemeinsam genutzten Ressourcen zentral zu verwalten.

Wenn Windows direkt auf der Computerhardware ausgeführt wird, nehmen die Gerätetreiber an Vorgängen im Zusammenhang mit Plug & Play, Energieverwaltung, Interruptverwaltung und anderen Aufgaben teil. Ein vertrauenswürdiger Windows-Bustreiber und Hardware Abstraction Layer (HAL) übernehmen die eigene Buskonfiguration und konfigurieren den gesamten Bus. Der Treiber wird innerhalb derselben Berechtigungsstufe ausgeführt, und im Kernelmodus gibt es keine Vertrauensgrenzen.

Wenn Windows auf einem virtuellen Computer (VM) ausgeführt wird, gelten diese Annahmen nicht. VFs können unter die Kontrolle einer nicht privilegierten VM gestellt werden. Die Sicherheit der Hardware muss jedoch überprüft werden, damit die Sicherheit oder Leistung des Systems nicht beeinträchtigt wird.

Wenn ein Treiber, der auf dem VF ausgeführt wird, einen Konfigurationsbereich mit Lese- oder Schreibzugriff anfordert, wird die Anforderung vom Virtualisierungsstack empfangen und an den PF-Treiber des SR-IOV Geräts gesendet. Es liegt in der Verantwortung des PF-Fahrers, auf diese Anfragen zu antworten und Details für den VF bereitzustellen. Der PF-Treiber kann gelegentlich erfordern, dass eine Lese- oder Schreibanforderung für die Konfiguration an die Hardware weitergegeben wird.

Der Stapel verwendet eine E/A-MMU, um den Datenverkehr von den verschiedenen Schnittstellen zu unterscheiden, die vom Gerät verfügbar gemacht werden, und erzwingt die Richtlinie, auf welche Bereiche des Arbeitsspeichers ein Gerät zugreifen kann und welche ihn unterbrechen können.

Das Diagramm zeigt die PCI-Virtualisierung.

Hardwareanforderungen

Das System, das für SR-IOV Gerätezuweisung verwendet werden soll, muss die Anforderungen für SR-IOV Netzwerk und direkte Gerätezuweisung erfüllen. Das System muss über eine IOMMU verfügen, diese IOMMU muss so konfiguriert sein, dass die Steuerung der Geräte an das Betriebssystem übergeben wird, und PCIe ACS (Access Control Services) muss aktiviert und für die Verwendung durch das Betriebssystem konfiguriert sein. Schließlich darf das betreffende Gerät keine zeilenbasierten Interrupts verwenden und darf keine ATS (Address Translation Services) benötigen.

Weitere Informationen finden Sie hier:

So ermitteln Sie, ob ein System die Gerätezuweisung unterstützt und ob ein bestimmtes PCI-Gerät für die Gerätezuweisung geeignet ist:

Skript für die Zuweisung diskreter Geräte

GUID_DEVINTERFACE_VIRTUALIZABLE_DEVICE handelt sich um eine Geräteklassenschnittstelle, die von Treibern für SR-IOV Geräte bereitgestellt wird. Diese GUID bietet eine Möglichkeit, alle Gerätestapel abzufragen, die die verschiedenen Funktionstabellen verfügbar machen, die zum Verwalten der virtualisierungsbezogenen Features des Geräts verwendet werden. Nachdem der Treiber die GUID registriert hat, werden einzelne Funktionen durch Senden von IRP_MN_QUERY_INTERFACE ermittelt. Der Fahrer muss auf diese Anfrage mit GUID_SRIOV_DEVICE_INTERFACE_STANDARD antworten. Die Fahrer müssen auch IOCTL_SRIOV_NOTIFICATION und IOCTL_SRIOV_EVENT_COMPLETE bewältigen.

Ein Treiber für ein SR_IOV Gerät, das auf einer privilegierten VM ausgeführt wird, ist das Hostbetriebssystem. Er besitzt Plug-and-Play und Energieverwaltung für einen gesamten Computer und macht PCI Express SR-IOV Virtual Functions in nicht privilegierten VMs verfügbar, muss die GUID_SRIOV_DEVICE_INTERFACE_STANDARD bereitstellen (definiert im Header Pcivirt.h). Bei diesem Treiber kann es sich um einen PCI Express SR-IOV Physical Function (PF)-Treiber handeln, der das FDO erstellt, oder es kann sich um einen niedrigeren Filter auf diesem Geräteknoten handeln, wenn das FDO von einem Porttreiber verwaltet wird.

Die Geräteschnittstelle wird benötigt, damit der Treiber auf den Konfigurationsraum der VFs zugreifen kann.

Führen Sie in der EVT_WDF_DRIVER_DEVICE_ADD Implementierung des PF-Treibers die folgenden Aufgaben aus:

Rufen Sie nach dem Aufrufen von WdfDeviceCreate zum Erstellen des Funktionsgeräteobjekts (Function Device Object, FDO) WdfDeviceCreateDeviceInterface auf, um GUID_DEVINTERFACE_VIRTUALIZABLE_DEVICE zu registrieren. Auf diese Weise kann der Virtualisierungsstack ein Gerätehandle für das SR-IOV Gerät abrufen.
Legen Sie die GUID_SRIOV_DEVICE_INTERFACE_STANDARD frei.
- Initialisieren Sie eine SRIOV_DEVICE_INTERFACE_STANDARD Struktur, und legen Sie Member auf Funktionszeiger der Callback-Funktionen fest, die vom PF-Treiber implementiert werden.
- Konfigurieren Sie die Struktur, indem Sie WDF_QUERY_INTERFACE_CONFIG_INIT aufrufen.
- Registrieren Sie die Schnittstelle beim FDO, indem Sie WdfDeviceAddQueryInterface aufrufen.

// Make the device visible as an assignable device.
//
status = WdfDeviceCreateDeviceInterface(
    fdo,
    &GUID_DEVINTERFACE_VIRTUALIZABLE_DEVICE,
    NULL);
if (!NT_SUCCESS(status))
{
    TraceEvents(TRACE_LEVEL_ERROR, DBG_INIT,
                "Failed to create interface: %!STATUS!",
                status);
    goto Cleanup;
}

//
// Expose SRIOV_DEVICE_INTERFACE_STANDARD
//
RtlZeroMemory(&sriovInterface, sizeof(sriovInterface));
sriovInterface.Size = sizeof(sriovInterface);
sriovInterface.Version = 1;
sriovInterface.Context = deviceContext;
sriovInterface.InterfaceReference = Virtualization_ReferenceInterface;
sriovInterface.InterfaceDereference = Virtualization_DereferenceInterface;
sriovInterface.ReadVfConfig = Virtualization_ReadConfig;
sriovInterface.WriteVfConfig = Virtualization_WriteConfig;
sriovInterface.ReadVfConfigBlock = Virtualization_ReadBlock;
sriovInterface.WriteVfConfigBlock = Virtualization_WriteBlock;
sriovInterface.ResetVf = Virtualization_ResetFunction;
sriovInterface.SetVfPowerState = Virtualization_SetPowerState;
sriovInterface.GetDeviceLocation = Virtualization_GetDeviceLocation;
sriovInterface.GetVendorAndDevice = Virtualization_GetVendorAndDevice;
sriovInterface.QueryProbedBars = Virtualization_QueryProbedBars;
sriovInterface.QueryLuid = Virtualization_QueryLuid;


WDF_QUERY_INTERFACE_CONFIG_INIT(&qiConfig,
                                (PINTERFACE)&sriovInterface,
                                &GUID_SRIOV_DEVICE_INTERFACE_STANDARD,
                                NULL);

status = WdfDeviceAddQueryInterface(fdo, &qiConfig);

if (!NT_SUCCESS(status))
{
    TraceEvents(TRACE_LEVEL_ERROR, DBG_INIT,
                "WdfDeviceAddQueryInterface failed: %!STATUS!\n",
                status);
    goto Cleanup;
}

Behandeln von Plug & Play-Ereignissen

Der Virtualisierungsstapel ist dafür verantwortlich, die entsprechenden Nachrichten an die VM zu senden, auf die Antwort (mit einem Timeout) zu warten und im Falle einer nicht reagierenden VM geeignete Maßnahmen anzuwenden, z. B. ein Veto gegen das PnP-Ereignis einzulegen, oder das Gerät überraschend von der nicht privilegierten VM zu entfernen. PF-Treiber, die GUID_DEVINTERFACE_VIRTUALIZABLE_DEVICE implementieren, müssen auch diese E/A-Steuerungsanforderungen verarbeiten, die es dem Virtualisierungsstapel ermöglichen, auf PnP-Ereignisse zu reagieren.

Der Virtualisierungsstack sendet zunächst IOCTL_SRIOV_ATTACH an das Gerät. Dadurch wird das Gerät benachrichtigt, dass der Virtualisierungsstack über bestimmte PnP-Ereignisse benachrichtigt werden muss.
Dies gilt so lange, bis der Virtualisierungsstack IOCTL_SRIOV_DETACH sendet.
Der Virtualisierungsstack fragt die Geräte zu PnP-Ereignissen ab, indem er IOCTL_SRIOV_NOTIFICATION Anforderungen sendet. Der PF-Treiber kann den Virtualisierungsstapel über ein PnP-Ereignis informieren, indem er die IOCTL_SRIOV_NOTIFICATION Anforderung abschließt.
Der Virtualisierungsstack hebt die Blockierung dieser Ereignisse auf, indem er IOCTL_SRIOV_EVENT_COMPLETE sendet.

pcivirt.h enthält die folgenden Programmierschnittstellen:

IOCTLs


IOCTL_SRIOV_ATTACH Die Anforderung gibt an, dass sich der Virtualisierungsstapel für Plug- und Play-Ereignisse registrieren möchte, die vom SR-IOV Gerät empfangen werden.
IOCTL_SRIOV_DETACH Die Anforderung gibt an, dass der Virtualisierungsstapel die Registrierung für Plug- und Play-Ereignisse aufheben möchte (zuvor über die anforderung IOCTL_SRIOV_ATTACH registriert).
IOCTL_SRIOV_EVENT_COMPLETE Die Anforderung gibt an, dass der Virtualisierungsstapel oder das SR-IOV Gerät eines der ereignisse empfangen hat, die in SRIOV_PF_EVENT aufgeführt sind.
IOCTL_SRIOV_INVALIDATE_BLOCK Die IOCTL_SRIOV_INVALIDATE_BLOCK-Anforderung gibt an, dass der Virtualisierungsstapel den Inhalt des angegebenen Konfigurationsblocks zurücksetzen möchte.
IOCTL_SRIOV_MITIGATED_RANGE_UPDATE Die IOCTL_SRIOV_MITIGATED_RANGE_UPDATE-Anforderung gibt an, dass der Virtualisierungsstapel auf die Entschärfungsbereiche aktualisiert werden möchte.
IOCTL_SRIOV_NOTIFICATION Die Anforderung gibt an, dass der Virtualisierungsstapel benachrichtigt werden möchte, wenn eines der in SRIOV_PF_EVENT aufgeführten Ereignisse auftritt.
IOCTL_SRIOV_PROXY_QUERY_LUID Diese Anforderung stellt den lokalen eindeutigen Bezeichner des SR_IOV Geräts bereit, das die Schnittstelle implementiert.
IOCTL_SRIOV_QUERY_MITIGATED_RANGE_COUNT Die Anforderung bestimmt die Bereiche des speicherzuordnungen E/A-Speicherplatzes, der abgemildert werden muss.
IOCTL_SRIOV_QUERY_MITIGATED_RANGES Die Anforderung bestimmt die spezifischen Bereiche, für die Abschnitte platziert werden müssen.

Rückruffunktionen


READ_WRITE_MITIGATED_REGISTER Liest oder schreibt, um entschärfte Adressräume zu vermeiden.
SRIOV_GET_DEVICE_LOCATION Ruft Informationen zur aktuellen Position des PCI-Geräts auf dem Bus ab, z. B. PCI-Segment, Bus, Gerät und Funktionsnummer.
SRIOV_GET_MMIO_REQUIREMENTS Diese Rückruffunktion wird nicht unterstützt.
SRIOV_GET_RESOURCE_FOR_BAR Ruft die übersetzte Ressource für ein bestimmtes Basisadressregister (BASE Address Register, BAR) ab.
SRIOV_GET_VENDOR_AND_DEVICE_IDS Stellt die Anbieter- und Geräte-ID für einen PCI Express SR-IOV Virtual Function (VF) bereit, der zum Generieren einer generischeren Plug- und Play-ID für den VF verwendet werden soll. Diese IDs können nicht direkt aus dem Konfigurationsbereich des VF gelesen werden.
SRIOV_QUERY_LUID Ruft den lokalen eindeutigen Bezeichner des SR-IOV Geräts ab.
SRIOV_QUERY_LUID_VF Ruft den PCI Express SR-IOV Virtual Function (VF) mit einem eindeutigen Bezeichner ab.
SRIOV_QUERY_PROBED_BARS Fragt die Daten ab, die aus den PF-Basisadressenregistern (PF) gelesen werden, wenn der Wert -1 zuerst in sie geschrieben wurde.
SRIOV_QUERY_PROBED_BARS_2 Fragt die daten ab, die aus den angegebenen PCI Express SR-IOV Virtual Function (VF)-Basisadressenregistern (BARs) gelesen werden, wenn der Wert -1 zuerst in sie geschrieben wurden.
SRIOV_QUERY_VF_LUID Ruft den lokalen eindeutigen Bezeichner des PCI Express SR-IOV Virtual Function (VF) ab.
SRIOV_READ_BLOCK Liest Daten aus dem angegebenen Konfigurationsblock eines PCI Express SR-IOV Virtual Function (VF).
SRIOV_READ_CONFIG Liest Daten aus dem Konfigurationsraum des angegebenen PCI Express SR-IOV Virtual Function (VF).
SRIOV_RESET_FUNCTION Setzt den angegebenen PCI Express SR-IOV Virtual Function (VF) zurück.
SRIOV_SET_POWER_STATE Legt den Leistungsstatus des angegebenen PCI Express SR-IOV Virtual Function (VF) fest.
SRIOV_WRITE_BLOCK Schreibt Daten in den angegebenen Konfigurationsblock eines PCI Express SR-IOV Virtual Function (VF).
SRIOV_WRITE_CONFIG Schreibt Konfigurationsdaten in einen PCI Express SR-IOV Virtual Function (VF).

Strukturen


MITIGABLE_DEVICE_INTERFACE Speichert Funktionszeiger auf Rückruffunktionen, die vom PF-Treiber (physical function) für die mitigierbare Geräteschnittstelle implementiert werden.
SRIOV_DEVICE_INTERFACE_STANDARD Speichert Funktionszeiger auf Rückruffunktionen, die vom PF-Treiber (Physical Function) im Gerätestapel für das SR-IOV-Gerät implementiert werden.
SRIOV_DEVICE_INTERFACE_STANDARD_2 Speichert Funktionszeiger auf Rückruffunktionen, die vom PF-Treiber (Physical Function) im Gerätestapel für das SR-IOV-Gerät implementiert werden. Dies ist eine erweiterte Version von SRIOV_DEVICE_INTERFACE_STANDARD.
SRIOV_INVALIDATE_BLOCK Enthält die Konfigurationsblockinformationen. Diese Struktur wird in einer IOCTL_SRIOV_INVALIDATE_BLOCK Anforderung verwendet.
SRIOV_MITIGATED_RANGE_COUNT_INPUT Diese Struktur wird als Eingabepuffer für die IOCTL_SRIOV_QUERY_MITIGATED_RANGE_COUNT Anforderung verwendet, um die Bereiche des speicherzuordnungen E/A-Speicherplatzes zu ermitteln, der abgemildert werden muss.
SRIOV_MITIGATED_RANGE_COUNT_OUTPUT Bei diesen Strukturen handelt es sich um den Ausgabepuffer, der von der IOCTL_SRIOV_QUERY_MITIGATED_RANGE_COUNT-Anforderung empfangen wird, die ein Array von Bereichen mit speicherzuordnungen E/A-Speicherplatz enthält, der abgemildert werden muss.
SRIOV_MITIGATED_RANGE_UPDATE_INPUT Diese Struktur wird als Eingabepuffer für die IOCTL_SRIOV_MITIGATED_RANGE_UPDATE Anforderung verwendet, um die virtuelle Funktion (VF) anzugeben, deren speicherzuordnungen E/A-Speicherplatz abgemildert werden muss.
SRIOV_MITIGATED_RANGE_UPDATE_OUTPUT Diese Strukturen sind der Ausgabepuffer, der von der IOCTL_SRIOV_MITIGATED_RANGE_UPDATE-Anforderung empfangen wird, die die virtuelle Funktion (VF) angibt, deren speicherzuordnunger E/A-Speicherplatz abgemildert wurde.
SRIOV_MITIGATED_RANGES_INPUT Diese Struktur ist der Eingabepuffer in der IOCTL_SRIOV_QUERY_MITIGATED_RANGES Anforderung, um die spezifischen Bereiche abzurufen, auf denen Abschnitte platziert werden müssen.
SRIOV_MITIGATED_RANGES_OUTPUT Diese Struktur ist der Ausgabepuffer, der von der IOCTL_SRIOV_QUERY_MITIGATED_RANGES Anforderung empfangen wird, um die spezifischen Bereiche abzurufen, für die Abschnitte platziert werden müssen.
SRIOV_PNP_EVENT_COMPLETE Speichert den Status für ein Ereignis, das der SR-IOV Physische Funktion (PF)-Treiber für Plug- und Play-Abschluss festgelegt werden soll. Diese Struktur wird im Eingabepuffer der IOCTL_SRIOV_EVENT_COMPLETE Anforderung verwendet.
SRIOV_PROXY_QUERY_LUID_OUTPUT Speichert den lokalen eindeutigen Bezeichner des SR_IOV Geräts, das die Schnittstelle implementiert. Diese Struktur ist der Ausgabepuffer für die IOCTL_SRIOV_PROXY_QUERY_LUID Anforderung.

Enumerationen


SRIOV_PF_EVENT Definiert Ereigniswerte für das SR-IOV Gerät.

Freigeben über