WHvRegisterPartitionDoorbellEvent

ゲストが指定されたゲスト物理アドレスに書き込むときに通知されるイベントを登録します。

構文

// Guest physical address
typedef UINT64 WHV_GUEST_PHYSICAL_ADDRESS;

typedef struct WHV_DOORBELL_MATCH_DATA
{
    WHV_GUEST_PHYSICAL_ADDRESS GuestAddress;
    UINT64 Value;
    UINT32 Length;
    UINT32 MatchOnValue:1;
    UINT32 MatchOnLength:1;
    UINT32 Reserved:30;
} WHV_DOORBELL_MATCH_DATA;

HRESULT
WINAPI
WHvRegisterPartitionDoorbellEvent(
    _In_ WHV_PARTITION_HANDLE Partition,
    _In_ const WHV_DOORBELL_MATCH_DATA* MatchData,
    _In_ HANDLE EventHandle
    );

Parameters

Partition

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

MatchData

ゲストの物理アドレスと、イベントを通知するためにゲストの書き込みが満たす必要がある省略可能な値と長さの制約を指定します。 フィールド セマンティクスとサポートされている一致モードについては、「 Doorbell データ型 」を参照してください。

EventHandle

CreateEventによって返される、通知するイベントへのハンドルを指定します。 一致する書き込みが発生すると、ハイパーバイザーは、 SetEvent が呼び出されたかのようにイベントを設定します。

戻り値

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

この関数は、一致データの形式が正しくない場合、つまり予約ビットが設定されている場合、MatchOnLengthが設定されているが、Lengthが 1、2、4、または 8 のいずれかでない場合、MatchOnLengthがクリアであるが、Lengthが 0 以外またはMatchOnValue設定されている場合、またはMatchOnValueがクリアであるが、Valueが 0 以外の場合に、E_INVALIDARGを返します。

この関数は、要求された登録が同じGuestAddressで既に登録されているドアベルと競合している場合にERROR_HV_INVALID_PARAMETERを返します。 同じLengthの個別のValueで一致する場合、1 つのゲストの物理アドレスに複数のドアベルを登録できます。 競合は、同じドアベルが既に登録されている場合、新しい登録がそのアドレスにある既存のドアベルとは異なる Length を指定した場合、または新しい登録またはそのアドレスの既存のドアベルが任意の値 (つまり、 MatchOnValue が明確) に一致する場合に発生します。

Remarks

仮想プロセッサが一致する書き込みを実行すると、イベントが通知され、仮想プロセッサはWHvRunVpExitReasonMemoryAccessで終了しません。 ハイパーバイザーは、トリガー書き込みの特定のストア命令のみを認識します。認識できない命令を使用してゲストが書き込みを実行した場合、イベントは通知されず、仮想プロセッサは WHvRunVpExitReasonMemoryAccessで終了します。 サポートされている一連の命令は、Windowsリリース間で変更される可能性があるため、呼び出し元は、指定されたゲスト アドレスに対して仮想プロセッサの終了パスが正しく動作することを確認する必要があります。

一致するゲスト アドレスが以前に WHvMapGpaRange にマップされたページ内にある場合、doorbell を登録すると、登録の有効期間中、そのページのマップが効果的に解除されます。 ページへの一致しない書き込みにより、ページがマップ解除されたかのように、仮想プロセッサが WHvRunVpExitReasonMemoryAccess で終了します。 WHvUnregisterPartitionDoorbellEventが呼び出されると、ページはマップされた状態に戻ります。

登録された書き込みでは、ページ境界にまたがってはいけません。他のアラインメント要件はありません。

イベントは、同じ一致データを持つ WHvUnregisterPartitionDoorbellEvent の呼び出しによって削除され、残りのドアベル イベントは、パーティションが削除されると自動的に登録解除されます。

Requirements

こちらも参照ください

• WHvUnregisterPartitionDoorbellEvent
• Doorbell データ型
• WHvMapGpaRange
• WHvRunVirtualProcessor
• Windows Hypervisor Platform API Definitions