Определения API платформы гипервизора Windows

Этот API доступен начиная с обновления Windows за апрель 2018 г.

На следующей схеме представлен общий обзор архитектуры сторонних производителей.

В следующем разделе содержатся определения API платформы гипервизора Windows, предоставляемые с помощью WinHvPlatform.h. WinHvPlatform.dll (расположенный в папке System32) экспортирует набор функций API Windows в стиле C, возвращающих коды ошибок HRESULT. Заголовки публикуются с помощью пакета Пакета SDK для Windows .

Возможности платформы

Функция	Description
WHvGetCapability	Возможности платформы — это универсальный способ запроса свойств и возможностей гипервизора, реализации API и аппаратной платформы, на которую работает приложение. API платформы использует эти возможности для публикации доступности расширенных функциональных возможностей API, а также набора функций, поддерживаемых процессором в текущей системе.

Создание, настройка и удаление секций

Функция	Description
WHvCreatePartition	Создание секции создает новый объект секции. Дополнительные свойства секции хранятся в объекте секции и применяются при создании секции в гипервизоре.
WHvSetupPartition	Настройка секции приводит к созданию фактической секции в гипервизоре. Перед выполнением любой другой операции в секции необходимо настроить секцию, за исключением настройки начальных свойств секции.
WHvDeletePartition	Удаление секции удаляет объект секции и освобождает весь ресурс, который использовался секцией.

Свойства секции

Свойства секции предоставляют механизм запроса вызывающим абонентам и настройке характеристик секции. При запросе свойства возвращается текущее значение этого свойства, которое предоставляет значение по умолчанию, определяемое реализацией гипервизора и API, если свойство не было ранее изменено вызывающим элементом. 

Доступность функций, которые можно настроить с помощью свойств секции, зависит от возможностей гипервизора, реализации API и физического процессора в системе. Приложение должно проверить соответствующую возможность перед попыткой настроить свойство.

Некоторые свойства (например, свойства, которые настраивают функции процессора, доступные для секции), можно изменять только во время создания секции и перед выполнением виртуального процессора в секции. Попытка изменить эти свойства после запуска секции приводит к сбою операции.

Дополнительные сведения о свойствах секции: Типы данных свойств секции

Функция	Description
WHvGetPartitionProperty	При запросе свойства возвращается текущее значение этого свойства, которое предоставляет значение по умолчанию, определяемое реализацией гипервизора и API, если свойство не было ранее изменено вызывающим элементом.
WHvSetPartitionProperty	Эти функции задают конфигурации свойств секции.

Управление памятью виртуальной машины

Физическое адресное пространство секции виртуальной машины (пространство GPA) заполняется с помощью памяти, выделенной в процессе пользовательского режима стека виртуализации. Т. е. стек виртуализации выделяет необходимую память с помощью стандартных функций управления памятью в Windows (например, VirtualAlloc) или сопоставляет файл с его процессом и использует адреса для сопоставления этой памяти с пространством GPA секции.

Функция	Description
WHvMapGpaRange	Создание сопоставления для диапазона в пространстве GPA секции задает регион в процессе вызывающего объекта в качестве резервной памяти для этого диапазона. Операция заменяет все предыдущие сопоставления для указанных страниц GPA.
WHvUnmapGpaRange	Отмена сопоставления ранее сопоставленного диапазона GPA делает диапазон памяти недоступным для секции. Любой дополнительный доступ виртуального процессора к диапазону приведет к выходу из памяти.
WHvTranslateGva	Преобразование виртуального адреса, используемого виртуальным процессором в секции, позволяет стеку виртуализации эмулировать инструкцию процессора для операции ввода-вывода, используя результаты перевода для чтения и записи операндов памяти инструкции в пространстве GPA секции.
WHvQueryGpaRangeDirtyBitmap	Запрос диапазона пространства GPA, чтобы определить, какие страницы были изменены гостем с момента последнего запроса диапазона.

Выполнение виртуального процессора

Виртуальные процессоры виртуальной машины выполняются с помощью нового встроенного планировщика гипервизора. Чтобы запустить виртуальный процессор, поток в процессе стека виртуализации выдает блокирующий вызов для выполнения виртуального процессора в гипервизоре, вызов возвращается из-за операции виртуального процессора, требующего обработки в стеке виртуализации или из-за запроса стека виртуализации.  

Поток, обрабатывающий виртуальный процессор, выполняет следующие основные операции:

1. Создайте виртуальный процессор в разделе.
2. Настройте состояние виртуального процессора, которое включает внедрение ожидающих прерываний и событий в процессор.
3. Запустите виртуальный процессор.
4. При возвращении от запуска виртуального процессора запросите состояние процессора и обработайте операцию, из-за которой процессор перестал работать.
5. Если виртуальный процессор по-прежнему активен, вернитесь к шагу 2, чтобы продолжить запуск процессора.
6. Удалите виртуальный процессор в разделе.  

Состояние виртуального процессора включает аппаратные регистры и любые прерывания стека виртуализации, которые хотят внедрить в виртуальный процессор.

Функция	Description
WHvCreateVirtualProcessor	Эта функция создает в секции новый виртуальный процессор. Индекс виртуального процессора используется для задания идентификатора APIC процессора.
WHvDeleteVirtualProcessor	Эта функция удаляет виртуальный процессор в секции.
WHvRunVirtualProcessor	Эта функция выполняет виртуальный процессор (т. е. позволяет запускать гостевой код). Вызов этой функции блокирует синхронно, пока виртуальный процессор не выполнил операцию, которая должна обрабатываться стеком виртуализации (например, доступ к памяти в пространстве GPA, который не сопоставлен или недоступен) или стек виртуализации явно запрашивает выход функции (например, для внедрения прерывания виртуального процессора или изменения состояния виртуальной машины).
WHvCancelRunVirtualProcessor	Отмена выполнения виртуального процессора позволяет приложению прерывать вызов для запуска виртуального процессора другим потоком и возвращать элемент управления в этот поток. Стек виртуализации может использовать эту функцию для возврата управления виртуальным процессором обратно в стек виртуализации в случае необходимости изменить состояние виртуальной машины или внедрить событие в процессор.

Выход из контекста

Подробная причина и дополнительные сведения о выходе WHvRunVirtualProcessor функции возвращаются в выходной буфер функции, получающей структуру контекста для выхода. Данные, предоставленные в этом буфере контекста, относятся к отдельной причине выхода, и по простым причинам выхода буфер может быть неиспользуем (RunVpExitLegacyFpError и RunVpExitInvalidVpRegisterValue).

Структуры	Description
Выход из контекстов	Структуры контекста по нескольким причинам выхода используют общие определения для данных, предоставляющих сведения об инструкции процессора, вызвавшей выход и состояние виртуального процессора во время выхода.
Обращение к памяти	Сведения о выходе, вызванном доступом виртуального процессора к расположению памяти, которое не сопоставлено или недоступно, предоставляется структурой WHV_MEMORY_ACCESS_CONTEXT .
Доступ к порту ввода-вывода	Сведения о выходе, вызванном виртуальным процессором, выполняющим инструкцию порта ввода-вывода (IN, OUT, INS и OUTS), предоставляются в WHV_X64_IO_PORT_ACCESS_CONTEXT структуре.
Доступ к MSR	Сведения о выходе, вызванном доступом виртуального процессора к определенному регистру модели (MSR) с помощью инструкций RDMSR или WRMSR, предоставляются в WHV_X64_MSR_ACCESS_CONTEXT структуре.
Доступ К ЦПИД	Сведения о выходе, вызванном виртуальным процессором, выполняющим инструкцию CPUID, предоставляются в WHV_X64_CPUID_ACCESS_CONTEXT структуре.
Исключение виртуального процессора	Сведения об исключении, созданном виртуальным процессором, предоставляются в WHV_VP_EXCEPTION_CONTEXT структуре.
Окно прерываний	Сведения о выходе, вызванном виртуальным процессором, когда состояние прерывания процессора позволит доставке заданного прерывания.
Неподдерживаемый компонент	Выход из неподдерживаемой функции вызван тем, что виртуальный процессор обращается к функции архитектуры, которая неправильно виртуализирована гипервизором.
Отменено выполнение	Сведения о выходе, вызванном системой узлов, предоставляются в WHV_RUN_VP_CANCELLED_CONTEXT структуре.
RDTSC(P)	Сведения о выходе, вызванном виртуальным процессором, выполняющим инструкцию RDTSC(P), предоставляются в WHV_X64_RDTSC_CONTEXT структуре.

Регистрация виртуальных процессов

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

Дополнительные сведения о регистрах см. в статье "Имена и значения регистров виртуальных процессоров"

Функция	Description
WHvGetVirtualProcessorRegisters	Эта функция позволяет запрашивать набор отдельных регистров стеком виртуализации.
WHvGetVirtualProcessorXsaveState	Эта функция позволяет запрашивать состояние XSAVE виртуального процессора.
WHvSetVirtualProcessorRegisters	Эта функция позволяет задать набор отдельных регистров стеком виртуализации.
WHvSetVirtualProcessorXsaveState	Эта функция позволяет задать состояние XSAVE виртуального процессора.

Виртуализация контроллера прерывания

При необходимости платформа гипервизора может эмулировать локальный контроллер прерываний APIC. Для виртуальных машин, где требуется APIC, использование встроенной эмуляции платформы обеспечивает лучшую производительность.

Если эта функция включена, эти функции можно использовать для запроса и задания состояния APIC и запроса виртуальных прерываний.

Функция	Description
WHvGetVirtualProcessorInterruptControllerState	Запрашивает состояние контроллера прерывания виртуального процессора.
WHvRequestInterrupt	Запрашивает прерывание.
WHvSetVirtualProcessorInterruptControllerState	Задает состояние контроллера прерывания виртуального процессора.

Счетчики

Эти функции можно использовать для запроса различных счетчиков платформы гипервизора.

Функция	Description
WHvGetPartitionCounters	Эта функция позволяет запрашивать счетчики для секции.
WHvGetVirtualProcessorCounters	Эта функция позволяет запрашивать счетчики для виртуального процессора.