WHvCreateTrigger

Erstellt ein Triggerobjekt, das eine vorkonfigurierte Unterbrechung oder ein Ereignis an eine Partition übermittelt, wenn ein Hostereignis signalisiert wird.

Syntax

typedef enum WHV_TRIGGER_TYPE
{
#if defined(_AMD64_)
    WHvTriggerTypeInterrupt = 0,
#endif
    WHvTriggerTypeSynicEvent = 1,
    WHvTriggerTypeDeviceInterrupt = 2,
} WHV_TRIGGER_TYPE;

typedef struct WHV_TRIGGER_PARAMETERS
{
    WHV_TRIGGER_TYPE TriggerType;
    UINT32 Reserved;
    union
    {
#if defined(_AMD64_)
        WHV_INTERRUPT_CONTROL Interrupt;
#endif
        WHV_SYNIC_EVENT_PARAMETERS SynicEvent;
        struct
        {
            UINT64 LogicalDeviceId;
            UINT64 MsiAddress;
            UINT32 MsiData;
            UINT32 Reserved;
        } DeviceInterrupt;
    };
} WHV_TRIGGER_PARAMETERS;

typedef PVOID WHV_TRIGGER_HANDLE;

HRESULT
WINAPI
WHvCreateTrigger(
    _In_ WHV_PARTITION_HANDLE Partition,
    _In_ const WHV_TRIGGER_PARAMETERS* Parameters,
    _Out_ WHV_TRIGGER_HANDLE* TriggerHandle,
    _Out_ HANDLE* EventHandle
    );

Parameter

Partition

Behandeln sie das Partitionsobjekt.

Parameters

Gibt den Typ des Triggers und die Aktion an, die an die Partition übergeben werden soll. Das TriggerType Mitglied wählt aus, welches Mitglied der Union verwendet wird: WHvTriggerTypeInterrupt (nur x64) verwendetInterrupt, WHvTriggerTypeSynicEvent verwendet SynicEventund verwendet DeviceInterrupt.WHvTriggerTypeDeviceInterrupt Weitere Informationen finden Sie unter Trigger-Datentypen für die vollständige Definition der einzelnen Member.

TriggerHandle

Empfängt das Handle für das neu erstellte Triggerobjekt. Verwenden Sie dieses Handle, WHvUpdateTriggerParameters um den Trigger neu zuzuweisen und WHvDeleteTrigger ihn zu löschen.

EventHandle

Empfängt ein Win32-Ereignishandle. Der Aufrufer aktiviert den Trigger durch Signalisieren dieses Ereignisses , z. B. mit SetEvent dem, wodurch die konfigurierte Aktion Parameters an die Partition übermittelt wird. Der Aufrufer besitzt dieses Handle und muss es CloseHandle freigeben, wenn es nicht mehr benötigt wird.

Rückgabewert

Wenn die Funktion erfolgreich ist, lautet S_OKder Rückgabewert .

Die Funktion gibt zurück E_INVALIDARG , wenn die Parameter Parameters für den ausgewählten Triggertyp ungültig sind. Für einen WHvTriggerTypeDeviceInterrupt Auslöser gibt eine ungültige LogicalDeviceId Rückgabe zurück HRESULT_FROM_WIN32(ERROR_HV_INVALID_DEVICE_ID).

Remarks

Die WHvCreateTrigger Funktion erstellt ein partitionsbezogenes Objekt, das ein Hostereignis an eine vorkonfigurierte Gastadressierungsaktion bindet. Nachdem der Trigger erstellt wurde, signalisiert der Host die zurückgegebene EventHandle (z. B. von einer E/A-Abschlussroutine oder einem anderen Thread), um den konfigurierten Interrupt oder das Ereignis an die Partition zu übermitteln, ohne bei jeder Übermittlung einen separaten API-Aufruf oder Hypercall durchzuführen. Dies eignet sich gut für Datenpfadszenarien wie virtuelle NIC-Empfangswarteschlangen, Speicherabschlussringe und Kanalsignalisierung.

Das TriggerType Mitglied der Parameters Auswahl der Aktion, die beim Signalsignal des Ereignisses übermittelt wird:

• WHvTriggerTypeInterrupt (x64 nur) fügt einen virtuellen Interrupt ein, der durch die WHV_INTERRUPT_CONTROL Struktur beschrieben wird – derselbe Effekt wie WHvRequestInterrupt, aber vorgewaffnet, sodass er jedes Mal erneut übermittelt werden kann, wenn das Ereignis signalisiert wird.
• WHvTriggerTypeSynicEvent legt ein SynIC-Ereigniskennzeichnung (Synthetischer Interruptcontroller) für den virtuellen Prozessor, die virtuelle Vertrauensstufe und SINT fest, die von der WHV_SYNIC_EVENT_PARAMETERS Struktur benannt wird. TargetVtl muss VTL 0 sein.
• WHvTriggerTypeDeviceInterrupt bestätigt einen Geräteunterbruch (MSI) für das logische Gerät, das durch LogicalDeviceId, using MsiAddress und MsiData. Das logische Gerät muss bereits in der Partition vorhanden sein und der interrupt zugeordnete (z. B. durch WHvMapVpciDeviceInterrupt ) bevor der Trigger signalisiert wird.

Die Übermittlung ist asynchron. Mehrere Signale, die eingehen, bevor eine Lieferung abgeschlossen wird, können zu einer einzigen Lieferung zusammenwachsen. Der Gast muss bereit sein, die Warteschlange oder den Ring abzulassen, die der Trigger für jede Lieferung darstellt.

WHvTriggerTypeInterrupt und das Interrupt Mitglied von WHV_TRIGGER_PARAMETERS sind nur auf x64 verfügbar. Nur auf Arm64 WHvTriggerTypeSynicEvent und WHvTriggerTypeDeviceInterrupt sind verfügbar.

Der Trigger und das Ereignishandle verfügen über unabhängige Lebensdauern. Das Löschen des Triggers mit WHvDeleteTrigger "Ungültig" EventHandlewird nicht ungültig; der Aufrufer muss ihn trotzdem schließen.CloseHandle Trigger werden nicht über die Livemigration hinweg beibehalten.

Anforderungen

Siehe auch

• WHvUpdateTriggerParameters
• WHvDeleteTrigger
• Auslösen von Datentypen
• WHvRequestInterrupt
• WHvMapVpciDeviceInterrupt
• Windows Hypervisor-Plattform-API-Definitionen