WHvCreateTrigger

创建一个触发器对象，该对象在发出主机事件信号时将预配置的中断或事件传送到分区。

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

参数

Partition

分区对象的句柄。

Parameters

指定要传递到分区的触发器的类型和操作。 该TriggerType成员选择使用哪个联合成员： WHvTriggerTypeInterrupt （仅 x64）使用Interrupt、WHvTriggerTypeSynicEvent使用SynicEvent和使用WHvTriggerTypeDeviceInterruptDeviceInterrupt。 有关每个成员的完整定义，请参阅 触发器数据类型 。

TriggerHandle

接收新创建的触发器对象的句柄。 使用此句柄 WHvUpdateTriggerParameters 来重定触发器的重定向，并删除 WHvDeleteTrigger 触发器。

EventHandle

接收 Win32 事件句柄。 调用方通过向此事件发出信号来激活触发器，例如， SetEvent 该事件会导致配置的操作 Parameters 传递到分区。 调用方拥有此句柄，并且必须在不再需要该句柄时释放它 CloseHandle 。

返回值

如果函数成功，则返回值为 S_OK.

如果所选触发器类型的参数Parameters无效，则函数返回E_INVALIDARG。 WHvTriggerTypeDeviceInterrupt对于触发器，返回HRESULT_FROM_WIN32(ERROR_HV_INVALID_DEVICE_ID)无效LogicalDeviceId。

Remarks

该 WHvCreateTrigger 函数创建一个分区范围内的对象，该对象将主机事件绑定到预配置的来宾目标操作。 创建触发器后，主机会发出返回 EventHandle 的信号（例如，从 I/O 完成例程或其他线程）将配置的中断或事件传送到分区，而无需在每个传递时进行单独的 API 调用或超集。 这使得触发器非常适合数据路径方案，例如虚拟 NIC 接收队列、存储完成环和通道信号。

选择 TriggerType 在发出事件信号时传递的操作的成员 Parameters ：

• WHvTriggerTypeInterrupt （仅 x64）注入结构描述的 WHV_INTERRUPT_CONTROL 虚拟中断，效果与预武装相同 WHvRequestInterrupt，以便每次发出事件信号时都可以重新传送它。
• WHvTriggerTypeSynicEvent 在虚拟处理器、虚拟信任级别和结构命名的 WHV_SYNIC_EVENT_PARAMETERS SINT 上设置合成中断控制器 （SynIC） 事件标志。 TargetVtl 必须是 VTL 0。
• WHvTriggerTypeDeviceInterrupt为使用LogicalDeviceIdMsiAddress和MsiData命名的逻辑设备断言设备（MSI）中断。 在发出触发器信号之前，逻辑设备必须已存在于分区中，并且映射的中断（例如通过 WHvMapVpciDeviceInterrupt ）。

传递是异步的。 在交付完成之前到达的多个信号可能会合并到单个交付中。 来宾必须准备好清空触发器在每个传递上表示的队列或环。

WHvTriggerTypeInterrupt Interrupt且成员WHV_TRIGGER_PARAMETERS仅在 x64 上可用。 在 Arm64 上，仅 WHvTriggerTypeSynicEvent 可用且 WHvTriggerTypeDeviceInterrupt 可用。

触发器和事件句柄具有独立的生存期。 删除触发器 WHvDeleteTrigger 不会失效 EventHandle;调用方仍必须将其 CloseHandle关闭。 不会在实时迁移中保留触发器。

要求

另见

• WHvUpdateTriggerParameters
• WHvDeleteTrigger
• 触发器数据类型
• WHvRequestInterrupt
• WHvMapVpciDeviceInterrupt
• Windows虚拟机监控程序平台 API 定义