WHvCreateTrigger

ホスト イベントが通知されたときに、事前に構成された割り込みまたはイベントをパーティションに配信するトリガー オブジェクトを作成します。

構文

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

パーティション オブジェクトへのハンドル。

Parameters

トリガーの種類と、パーティションに配信するアクションを指定します。 TriggerTypeメンバーは、使用する共用体のメンバーを選択します。WHvTriggerTypeInterrupt (x64 のみ) はInterruptを使用し、WHvTriggerTypeSynicEventはSynicEventを使用し、WHvTriggerTypeDeviceInterruptはDeviceInterruptを使用します。 各メンバーの完全な定義については、「 データ型のトリガー」 を参照してください。

TriggerHandle

新しく作成されたトリガー オブジェクトへのハンドルを受け取ります。 このハンドルを WHvUpdateTriggerParameters と共に使用してトリガーを再ターゲットし、 WHvDeleteTrigger で削除します。

EventHandle

Win32 イベント ハンドルを受け取ります。 呼び出し元は、 SetEvent など、このイベントを通知することによってトリガーをアクティブ化します。これにより、 Parameters で構成されたアクションがパーティションに配信されます。 呼び出し元はこのハンドルを所有し、不要になったら CloseHandle で解放する必要があります。

戻り値

関数が成功した場合、戻り値は S_OK。

Parameters内のパラメーターが選択したトリガーの種類に対して有効でない場合、この関数はE_INVALIDARGを返します。 WHvTriggerTypeDeviceInterrupt トリガーの場合、無効なLogicalDeviceIdはHRESULT_FROM_WIN32(ERROR_HV_INVALID_DEVICE_ID)を返します。

Remarks

WHvCreateTrigger関数は、ホスト イベントを構成済みのゲスト ターゲット アクションにバインドするパーティション スコープ オブジェクトを作成します。 トリガーが作成されると、ホストは、返された EventHandle (I/O 完了ルーチンや別のスレッドなど) に通知し、構成された割り込みまたはイベントを、配信ごとに個別の API 呼び出しやハイパーコールを行わずにパーティションに配信します。 これにより、トリガーは、仮想 NIC 受信キュー、ストレージ完了リング、チャネル シグナリングなどのデータ パス シナリオに適しています。

ParametersのTriggerType メンバーは、イベントが通知されたときに配信されるアクションを選択します。

• WHvTriggerTypeInterrupt (x64 のみ) WHV_INTERRUPT_CONTROL 構造体によって記述された仮想割り込みを挿入します。 WHvRequestInterruptと同じ効果ですが、イベントが通知されるたびに再配信できるように事前に準備されています。
• WHvTriggerTypeSynicEvent は、仮想プロセッサ、仮想信頼レベル、および WHV_SYNIC_EVENT_PARAMETERS 構造体によって指定された SINT に合成割り込みコントローラー (SynIC) イベント フラグを設定します。 TargetVtl VTL 0 である必要があります。
• WHvTriggerTypeDeviceInterruptは、MsiAddressとMsiDataを使用して、LogicalDeviceIdによって指定された論理デバイスのデバイス (MSI) 割り込みをアサートします。 論理デバイスは既にパーティションに存在し、割り込みは、トリガーが通知される前に、 WHvMapVpciDeviceInterrupt を通じてマップされている必要があります。

配信は非同期です。 配信が完了する前に到着する複数のシグナルは、1 つの配信に結合される可能性があります。 ゲストは、各配信でトリガーが表すキューまたはリングをドレインするように準備する必要があります。

WHvTriggerTypeInterrupt WHV_TRIGGER_PARAMETERSのInterruptメンバーは x64 でのみ使用できます。 Arm64 では、 WHvTriggerTypeSynicEvent と WHvTriggerTypeDeviceInterrupt のみを使用できます。

トリガーとイベント ハンドルには、独立した有効期間があります。 WHvDeleteTriggerを使用してトリガーを削除しても、EventHandleは無効になりません。呼び出し元は、CloseHandleを使用してトリガーを閉じる必要があります。 ライブ マイグレーションではトリガーは保持されません。

Requirements

こちらも参照ください

• WHvUpdateTriggerParameters
• WHvDeleteTrigger
• データ型のトリガー
• WHvRequestInterrupt
• WHvMapVpciDeviceInterrupt
• Windows Hypervisor Platform API Definitions