WHvCreateTrigger

Cria um objeto trigger que entrega uma interrupção ou evento pré-configurado a uma partição quando um evento host é sinalizado.

Sintaxe

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

Handle para o objeto de partição.

Parameters

Especifica o tipo de gatilho e a ação a entregar à partição. O TriggerType membro seleciona qual membro da união é usado: WHvTriggerTypeInterrupt (apenas x64) usa Interrupt, WHvTriggerTypeSynicEvent usa SynicEvent, e WHvTriggerTypeDeviceInterrupt usa DeviceInterrupt. Consulte Trigger Data Types para a definição completa de cada membro.

TriggerHandle

Recebe o handle do objeto trigger recém-criado. Usa este handle com WHvUpdateTriggerParameters para redirecionar o trigger e com WHvDeleteTrigger para o apagar.

EventHandle

Recebe um handle de evento Win32. O chamador ativa o disparador sinalizando este evento — por exemplo, com SetEvent — que faz com que a ação configurada em Parameters seja entregue à partição. O chamador detém esta alavanca e deve libertá-la CloseHandle quando já não for necessária.

Valor de retorno

Se a função tiver sucesso, o valor de retorno é S_OK.

A função retorna E_INVALIDARG se os parâmetros em Parameters não forem válidos para o tipo de trigger selecionado. Para um WHvTriggerTypeDeviceInterrupt gatilho, um inválido LogicalDeviceId devolve HRESULT_FROM_WIN32(ERROR_HV_INVALID_DEVICE_ID).

Remarks

A WHvCreateTrigger função cria um objeto com escopo de partição que associa um evento host a uma ação de alvo de convidados pré-configurada. Após a criação do trigger, o host sinaliza ao retornado EventHandle — por exemplo, de uma rotina de conclusão de I/O ou outro thread — para entregar a interrupção ou evento configurado à partição sem fazer uma chamada API separada ou hypercall em cada entrega. Isto torna os gatilhos bem adequados a cenários de caminho de dados, como filas virtuais de receção de NIC, anéis de conclusão de armazenamento e sinalização de canal.

O TriggerType membro de Parameters seleciona a ação que é executada quando o evento é sinalizado:

• WHvTriggerTypeInterrupt (apenas x64) injeta uma interrupção virtual descrita pela WHV_INTERRUPT_CONTROL estrutura — o mesmo efeito que WHvRequestInterrupt, mas pré-armada para que possa ser reentregue cada vez que o evento é sinalizado.
• WHvTriggerTypeSynicEvent define uma flag de evento de controlador de interrupção sintético (SynIC) no processador virtual, no nível de confiança virtual e no SINT nomeados pela WHV_SYNIC_EVENT_PARAMETERS estrutura. TargetVtl deve ser VTL 0.
• WHvTriggerTypeDeviceInterrupt afirma uma interrupção de dispositivo (MSI) para o dispositivo lógico nomeado por LogicalDeviceId, usando MsiAddress e MsiData. O dispositivo lógico deve já estar presente na partição e a interrupção mapeada — por exemplo, através WHvMapVpciDeviceInterrupt — antes de o disparo ser sinalizado.

A entrega é assíncrona. Múltiplos sinais que chegam antes de uma entrega ser concluída podem convergir numa única entrega. O convidado deve estar preparado para esgotar a fila ou anel que o gatilho representa em cada entrega.

WHvTriggerTypeInterrupt e o Interrupt membro de WHV_TRIGGER_PARAMETERS estão disponíveis apenas em x64. No Arm64, apenas WHvTriggerTypeSynicEvent e WHvTriggerTypeDeviceInterrupt estão disponíveis.

O gatilho e o handle do evento têm vidas independentes. Eliminar o gatilho com WHvDeleteTrigger não invalida EventHandle; o chamador deve ainda assim fechá-lo com CloseHandle. Os gatilhos não são preservados durante a migração viva.

Requirements

Ver também

• WHvUpdateTriggerParameters
• WHvDeleteTrigger
• Tipos de Dados de Gatilho
• WHvRequestInterrupt
• WHvMapVpciDeviceInterrupt
• Windows Definições da API da Plataforma de Hipervisores