WHvCreateTrigger

Tworzy obiekt wyzwalacza, który dostarcza wstępnie skonfigurowane przerwanie lub zdarzenie do partycji, gdy zdarzenie hosta jest sygnalizowane.

Składnia

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
    );

Parameters

Partition

Dojście do obiektu partycji.

Parameters

Określa typ wyzwalacza i akcję do dostarczenia do partycji. Składowy TriggerType wybiera, który element członkowski unii jest używany: WHvTriggerTypeInterrupt (tylko x64) używa Interrupt, WHvTriggerTypeSynicEvent używa SynicEvent, i WHvTriggerTypeDeviceInterrupt używa .DeviceInterrupt Zobacz Wyzwalanie typów danych , aby uzyskać pełną definicję każdego elementu członkowskiego.

TriggerHandle

Odbiera uchwyt do nowo utworzonego obiektu wyzwalacza. Użyj tego uchwytu za pomocą WHvUpdateTriggerParameters polecenia , aby ponownie uzyskać wyzwalacz i za pomocą WHvDeleteTrigger polecenia , aby go usunąć.

EventHandle

Odbiera dojście zdarzeń Win32. Obiekt wywołujący aktywuje wyzwalacz, sygnalizując to zdarzenie — na przykład za SetEvent pomocą polecenia — co powoduje dostarczenie skonfigurowanej akcji Parameters do partycji. Obiekt wywołujący jest właścicielem tego uchwytu i musi go zwolnić, CloseHandle gdy nie jest już potrzebny.

Wartość zwracana

Jeśli funkcja powiedzie się, zwracana wartość to S_OK.

Funkcja zwraca E_INVALIDARG wartość , jeśli parametry w Parameters elemecie nie są prawidłowe dla wybranego typu wyzwalacza. W przypadku wyzwalacza nieprawidłowa WHvTriggerTypeDeviceInterruptLogicalDeviceId funkcja zwraca wartość HRESULT_FROM_WIN32(ERROR_HV_INVALID_DEVICE_ID).

Remarks

Funkcja WHvCreateTrigger tworzy obiekt o zakresie partycji, który wiąże zdarzenie hosta ze wstępnie skonfigurowaną akcją określania wartości docelowej gościa. Po utworzeniu wyzwalacza host sygnalizuje zwrócone EventHandle — na przykład z procedury uzupełniania we/wy lub innego wątku — w celu dostarczenia skonfigurowanego przerwania lub zdarzenia do partycji bez konieczności wykonywania oddzielnego wywołania interfejsu API lub funkcji hypercall dla każdego dostarczania. Dzięki temu wyzwalacze są dobrze dopasowane do scenariuszy ścieżki danych, takich jak kolejki odbierane przez wirtualną kartę sieciową, pierścienie uzupełniania magazynu i sygnalizowanie kanału.

Element TriggerType członkowski Parameters wybiera akcję dostarczaną po zasygnalizowanej zdarzeniu:

• WHvTriggerTypeInterrupt (tylko x64) wprowadza wirtualne przerwanie opisane przez WHV_INTERRUPT_CONTROL strukturę — taki sam efekt jak WHvRequestInterrupt, ale wstępnie uzbrojony, aby można było go ponownie dostarczyć za każdym razem, gdy zdarzenie jest sygnalizowane.
• WHvTriggerTypeSynicEvent Ustawia syntetyczną flagę zdarzenia kontrolera przerwań (SynIC) na procesorze wirtualnym, wirtualnym poziomie zaufania i SINT nazwanym WHV_SYNIC_EVENT_PARAMETERS przez strukturę. TargetVtl musi mieć wartość VTL 0.
• WHvTriggerTypeDeviceInterruptpotwierdza przerwanie urządzenia (MSI) dla urządzenia logicznego o nazwie , LogicalDeviceIdprzy użyciu i MsiDataMsiAddress . Urządzenie logiczne musi być już obecne w partycji i zamapowane przerwania — na przykład za pośrednictwem WHvMapVpciDeviceInterrupt — przed zasygnalizowanym wyzwalaczem.

Dostarczanie jest asynchroniczne. Wiele sygnałów, które docierają przed zakończeniem dostawy, może być jedną dostawą. Gość musi być przygotowany do opróżnienia kolejki lub pierścienia reprezentowanego przez wyzwalacz w każdym dostarczaniu.

WHvTriggerTypeInterrupt Interrupt element członkowski WHV_TRIGGER_PARAMETERS programu jest dostępny tylko w wersji x64. Tylko w arm64 WHvTriggerTypeSynicEvent i WHvTriggerTypeDeviceInterrupt są dostępne.

Wyzwalacz i dojście zdarzeń mają niezależne okresy istnienia. Usunięcie wyzwalacza za pomocą WHvDeleteTrigger polecenia nie powoduje unieważnienia EventHandle; obiekt wywołujący musi nadal zamknąć go za pomocą CloseHandlepolecenia . Wyzwalacze nie są zachowywane w ramach migracji na żywo.

Requirements

Zobacz także

• WHvUpdateTriggerParameters
• WHvDeleteTrigger
• Wyzwalanie typów danych
• WHvRequestInterrupt
• WHvMapVpciDeviceInterrupt
• Windows Definicje interfejsu API platformy funkcji Hypervisor