WHvAdviseGpaRange

Предоставляет указания гипервизору о резервной памяти одного или нескольких диапазонов физических адресов гостя.

Синтаксис

// 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 адресов, к которому применяется совет. Для кодов рекомендаций WHvAdviseGpaRangeCodePinWHvAdviseGpaRangeCodeUnpin каждый диапазон должен быть выровнен по страницам.

GpaRangesCount

Указывает количество записей в массиве, на которые указывает GpaRanges. Это значение должно быть больше нуля.

Advice

Указывает совет, применяемый к диапазонам, в качестве WHV_ADVISE_GPA_RANGE_CODE значения.

AdviceBuffer

Указывает указатель на буфер, содержащий параметры совета. Макет буфера определяется Advice. Для WHvAdviseGpaRangeCodePopulateэтого буфер является структурой WHV_ADVISE_GPA_RANGE_POPULATE .

AdviceBufferSizeInBytes

Указывает размер буфера в байтах, на который указывает.AdviceBuffer

Возвращаемое значение

Если функция выполнена успешно, возвращается S_OKзначение.

Функция возвращает E_INVALIDARG , если Advice не является определенным WHV_ADVISE_GPA_RANGE_CODE значением, или если параметры в буфере советов недопустимы для указанного Advice.

Remarks

Функция WHvAdviseGpaRange позволяет стеку виртуализации сообщить гипервизору о предполагаемом использовании памяти, поддерживающей набор диапазонов гостевых физических адресов, чтобы гипервизор смог оптимизировать фиксацию и доступ к ней.

Параметр Advice выбирает операцию:

  • WHvAdviseGpaRangeCodePopulate фиксирует резервную память для указанных диапазонов перед доступом виртуального процессора, сбой страниц в соответствии AccessType со структурой WHV_ADVISE_GPA_RANGE_POPULATE . Флаг Prefetch запрашивает упреждающую обработку страниц и AvoidHardFaults запрашивает флаг, что операция не принимает ошибки жесткой страницы. Диапазоны, предоставленные для операции заполнения, не должны быть выровнены по страницам.
  • WHvAdviseGpaRangeCodePin закрепляет резервную память для указанных диапазонов, чтобы она оставалась резидентной.
  • WHvAdviseGpaRangeCodeUnpin освобождает пин-код, установленный ранее с WHvAdviseGpaRangeCodePinпомощью .

Для операций с закреплением и открепления требуется, чтобы каждый диапазон GpaRanges был выровнен по страницам.

Требования

Requirement Ценность
Минимальный поддерживаемый Windows Windows 10 версии 20H2 (x64); Windows 11 версии 24H2, сборка 26100.3915 (Arm64)
Header WinHvPlatform.h
Библиотека WinHvPlatform.lib
DLL WinHvPlatform.dll
Architecture x64, Arm64

См. также

  • Last updated on