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

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

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

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

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

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

Чтобы определить, поддерживает ли текущая система платформу гипервизора Windows в Arm64, вызовите WHvGetCapability с помощью WHvCapabilityCodeFeatures и проверьте бит Arm64Support возвращаемого значения WHV_CAPABILITY_FEATURES.

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

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

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

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

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

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

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

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

Сброс и миграция секций

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

Функция	Description
WHvResetPartition	Сбрасывает секцию в исходное состояние.
WHvStartPartitionMigration	Начинает перенос секции на исходном узле.
WHvAcceptPartitionMigration	Принимает перенос секции на конечном узле.
WHvCompletePartitionMigration	Завершает миграцию секций на исходном узле.
WHvCancelPartitionMigration	Прерывает миграцию секций на исходном узле.

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

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

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

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

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

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

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

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

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

Функция	Description
WHvCreateVirtualProcessor	Эта функция создает в секции новый виртуальный процессор. Индекс виртуального процессора используется для задания идентификатора APIC процессора.
WHvCreateVirtualProcessor2	Создает новый виртуальный процессор в секции с необязательными свойствами времени создания.
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 структуре.
Регистрация перехвата	Сведения о выходе Arm64, вызванном перехваченным доступом к системе, предоставляются в WHV_REGISTER_CONTEXT структуре.
Сброс Arm64	Сведения о выходе Arm64, вызванном запросом сброса виртуального процессора, предоставляются в WHV_ARM64_RESET_CONTEXT структуре.

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

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

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

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

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

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

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

Функция	Description
WHvRequestInterrupt	Запрашивает виртуальное прерывание.
WHvGetInterruptTargetVpSet	Разрешает назначение прерывания набору целевых виртуальных процессоров.
WHvGetVirtualProcessorInterruptControllerState	Возвращает состояние контроллера прерывания виртуального процессора. Устаревшие; используйте WHvGetVirtualProcessorState.
WHvGetVirtualProcessorInterruptControllerState2	Возвращает состояние контроллера прерывания виртуального процессора в стандартном формате внешнего состояния. Устаревшие; используйте WHvGetVirtualProcessorState.
WHvSetVirtualProcessorInterruptControllerState	Задает состояние контроллера прерывания виртуального процессора. Не рекомендуется; используйте WHvSetVirtualProcessorState.
WHvSetVirtualProcessorInterruptControllerState2	Задает состояние контроллера прерывания виртуального процессора в стандартном формате внешнего состояния. Не рекомендуется; используйте WHvSetVirtualProcessorState.

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

Помимо отдельных регистров, сохраненное состояние виртуального процессора можно запрашивать и задавать по категориям, а результаты ЦПID, которые могут быть запрошены виртуальным процессором.

Функция	Description
WHvGetVirtualProcessorState	Извлекает категорию сохраненного состояния из виртуального процессора.
WHvSetVirtualProcessorState	Задает категорию сохраненного состояния на виртуальном процессоре.
WHvGetVirtualProcessorCpuidOutput	Возвращает результат ЦПИД, который будет наблюдаться для заданного конечного листа.

Контроллер искусственных прерываний (SynIC)

Эти функции предоставляют события и сообщения контроллера искусственных прерываний (SynIC) виртуальному процессору.

Функция	Description
WHvSignalVirtualProcessorSynicEvent	Сигнализирует о флаге события контроллера искусственных прерываний на виртуальном процессоре.
WHvPostVirtualProcessorSynicMessage	Отправляет сообщение контроллера искусственных прерываний виртуальному процессору.

Счетчики

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

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

Дверные звонки

Doorbell позволяет стеку виртуализации получать уведомления через объект события Windows, когда гость записывает указанное значение в указанный физический адрес гостя.

Замечание

Функции doorbell устарели. Вместо этого используйте порт уведомлений типа WHvNotificationPortTypeDoorbell (см. порты уведомлений).

Дополнительные сведения о типах данных doorbell: Doorbell Data Types

Функция	Description
WHvRegisterPartitionDoorbellEvent	Регистрирует событие, которое будет сигнализировать, когда гость записывает в указанный физический адрес гостя. Устаревшие; используйте WHvCreateNotificationPort.
WHvUnregisterPartitionDoorbellEvent	Отменяет регистрацию ранее зарегистрированного события секции doorbell. Не рекомендуется; используйте WHvDeleteNotificationPort.

Триггеры

Триггер предоставляет предварительно настроенное прерывание или событие в секцию при сигнале объекта события узла.

Дополнительные сведения о типах данных триггера: Триггер типов данных

Функция	Description
WHvCreateTrigger	Создает объект триггера, который предоставляет предварительно настроенное прерывание или событие в секцию при сигнале события узла.
WHvUpdateTriggerParameters	Обновляет параметры существующего объекта триггера.
WHvDeleteTrigger	Удаляет объект триггера из раздела.

Порты уведомлений

Порт уведомлений сигнализирует объекту события Windows, когда секция создает соответствующее событие.

Дополнительные сведения о типах данных порта уведомлений: типы данных порта уведомлений

Функция	Description
WHvCreateNotificationPort	Создает порт уведомлений, который сигнализирует объекту события Windows при создании соответствующего события.
WHvSetNotificationPortProperty	Задает свойство на существующем порту уведомлений.
WHvDeleteNotificationPort	Удаляет порт уведомлений.

Виртуальные устройства PCI (VPCI)

Платформа гипервизора Windows может назначать физическое устройство PCI секции как виртуальное устройство PCI (VPCI). Эти функции выделяют резервные ресурсы, создают и удаляют устройства VPCI, запрашивают их свойства и уведомления, сопоставляют диапазоны MMIO, управляют состоянием питания и получают доступ к их регистрам.

Дополнительные сведения о типах данных VPCI: Виртуальные типы данных PCI

Функция	Description
WHvAllocateVpciResource	Выделяет ресурс виртуального PCI (VPCI) для резервного копирования виртуального устройства.
WHvCreateVpciDevice	Создает виртуальное устройство PCI (VPCI) и назначает ресурсы секции.
WHvDeleteVpciDevice	Уничтожает виртуальное устройство PCI (VPCI) и освобождает свои ресурсы.
WHvGetVpciDeviceProperty	Извлекает свойство виртуального устройства PCI (VPCI).
WHvGetVpciDeviceNotification	Извлекает следующее ожидающее уведомление для виртуального устройства PCI (VPCI).
WHvMapVpciDeviceMmioRanges	Сопоставляет диапазоны MMIO виртуального устройства PCI (VPCI) с процессом вызывающего объекта.
WHvUnmapVpciDeviceMmioRanges	Распакует диапазоны MMIO виртуального устройства PCI (VPCI) из процесса вызывающего объекта.
WHvSetVpciDevicePowerState	Изменяет состояние питания виртуального устройства PCI (VPCI).
WHvReadVpciDeviceRegister	Считывает пространство конфигурации или регистр MMIO виртуального устройства PCI (VPCI).
WHvWriteVpciDeviceRegister	Записывает пространство конфигурации или регистр MMIO виртуального устройства PCI (VPCI).

Прерывания виртуальных устройств PCI (VPCI)

Эти функции сопоставляют, распакуйте, перенацеливаете, запрашиваете и запрашивает MSI и MSI-X прерывания назначенных виртуальных PCI-устройств.

Функция	Description
WHvMapVpciDeviceInterrupt	Сопоставляет MSI или MSI-X прерывание для назначенного виртуального PCI-устройства и возвращает адрес MSI и данные для программирования на устройство.
WHvUnmapVpciDeviceInterrupt	Удаляет ранее сопоставленное прерывание для назначенного виртуального устройства PCI.
WHvRetargetVpciDeviceInterrupt	Изменяет целевой вектор и набор процессора для ранее сопоставленного прерывания назначенного виртуального устройства PCI.
WHvRequestVpciDeviceInterrupt	Предоставляет логическое прерывание в секцию, которая владеет назначенным виртуальным устройством PCI.
WHvGetVpciDeviceInterruptTarget	Запрашивает текущий вектор и набор процессора сопоставленного прерывания для назначенного виртуального устройства PCI.