WHvAdviseGpaRange

1 つ以上のゲスト物理アドレス範囲をバッキングするメモリに関するヒントをハイパーバイザーに提供します。

構文

// Structure describing a memory range entry
typedef struct WHV_MEMORY_RANGE_ENTRY {
    UINT64 GuestAddress;
    UINT64 SizeInBytes;
} WHV_MEMORY_RANGE_ENTRY;

// WHvAdviseGpaRange types
typedef enum WHV_ADVISE_GPA_RANGE_CODE
{
    WHvAdviseGpaRangeCodePopulate         = 0x00000000,
    WHvAdviseGpaRangeCodePin              = 0x00000001,
    WHvAdviseGpaRangeCodeUnpin            = 0x00000002,
} WHV_ADVISE_GPA_RANGE_CODE;

typedef union WHV_ADVISE_GPA_RANGE_POPULATE_FLAGS
{
    UINT32 AsUINT32;
    struct
    {
        UINT32 Prefetch:1;
        UINT32 AvoidHardFaults:1;
        UINT32 Reserved:30;
    };
} WHV_ADVISE_GPA_RANGE_POPULATE_FLAGS;

typedef enum WHV_MEMORY_ACCESS_TYPE
{
    WHvMemoryAccessRead    = 0,
    WHvMemoryAccessWrite   = 1,
    WHvMemoryAccessExecute = 2
} WHV_MEMORY_ACCESS_TYPE;

//
// Parameters used by WHvAdviseGpaRangeCodePopulate
//
typedef struct WHV_ADVISE_GPA_RANGE_POPULATE
{
    WHV_ADVISE_GPA_RANGE_POPULATE_FLAGS Flags;
    WHV_MEMORY_ACCESS_TYPE AccessType;
} WHV_ADVISE_GPA_RANGE_POPULATE;

//
// WHvAdviseGpaRange buffer
//
typedef union WHV_ADVISE_GPA_RANGE
{
    WHV_ADVISE_GPA_RANGE_POPULATE Populate;
} WHV_ADVISE_GPA_RANGE;

HRESULT
WINAPI
WHvAdviseGpaRange(
    _In_ WHV_PARTITION_HANDLE Partition,
    _In_reads_(GpaRangesCount) const WHV_MEMORY_RANGE_ENTRY* GpaRanges,
    _In_ UINT32 GpaRangesCount,
    _In_ WHV_ADVISE_GPA_RANGE_CODE Advice,
    _In_reads_bytes_(AdviceBufferSizeInBytes) const VOID* AdviceBuffer,
    _In_ UINT32 AdviceBufferSizeInBytes
    );

Parameters

Partition

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

GpaRanges

WHV_MEMORY_RANGE_ENTRY構造体の配列へのポインターを指定します。各構造体は、アドバイスが適用されるゲストの物理アドレス範囲を記述します。 WHvAdviseGpaRangeCodePinおよびWHvAdviseGpaRangeCodeUnpinアドバイス コードの場合は、各範囲をページアラインする必要があります。

GpaRangesCount

GpaRangesが指す配列内のエントリの数を指定します。 この値は 0 より大きくする必要があります。

Advice

範囲に適用するアドバイスを WHV_ADVISE_GPA_RANGE_CODE 値として指定します。

AdviceBuffer

アドバイスのパラメーターを含むバッファーへのポインターを指定します。 バッファーのレイアウトは、 Adviceによって決まります。 WHvAdviseGpaRangeCodePopulateの場合、バッファーはWHV_ADVISE_GPA_RANGE_POPULATE構造体です。

AdviceBufferSizeInBytes

AdviceBufferが指すバッファーのサイズをバイト単位で指定します。

戻り値

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

この関数は、Adviceが定義されたWHV_ADVISE_GPA_RANGE_CODE値でない場合、またはアドバイス バッファー内のパラメーターが指定されたAdviceに対して有効でない場合に、E_INVALIDARGを返します。

Remarks

WHvAdviseGpaRange関数を使用すると、仮想化スタックは、一連のゲスト物理アドレス範囲をサポートするメモリの使用目的をハイパーバイザーに通知し、ハイパーバイザーがそのメモリのコミットとアクセス方法を最適化できるようにします。

Advice パラメーターは、操作を選択します。

• WHvAdviseGpaRangeCodePopulateは、仮想プロセッサがアクセスする前に、指定された範囲のバッキング メモリをコミットし、WHV_ADVISE_GPA_RANGE_POPULATE構造体のAccessTypeに従ってページをエラーにします。 Prefetch フラグは、ページをプロアクティブに取り込むように要求し、AvoidHardFaults フラグは、操作でハード ページ エラーが発生しないように要求します。 設定操作に指定された範囲をページアラインする必要はありません。
• WHvAdviseGpaRangeCodePin は、指定した範囲のバッキング メモリをピン留めして、常駐状態を維持します。
• WHvAdviseGpaRangeCodeUnpin は、以前に WHvAdviseGpaRangeCodePinで確立されたピンを解放します。

ピン留め操作とピン留め解除操作では、 GpaRanges 内のすべての範囲をページアラインする必要があります。

Requirements

こちらも参照ください

• WHvMapGpaRange
• WHvMapGpaRange2
• WHvReadGpaRange
• WHvWriteGpaRange
• メモリ データ型
• Windows Hypervisor Platform API Definitions