WHvRegisterPartitionDoorbellEvent

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

Important

WHvRegisterPartitionDoorbellEvent не рекомендуется к использованию. Вместо этого используйте WHvCreateNotificationPort порт уведомлений типа WHvNotificationPortTypeDoorbell .

Синтаксис

// 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значение.

Функция возвращаетсяE_INVALIDARG, если данные соответствия неправильно сформированы: если заданы зарезервированные биты; если MatchOnLength задано значение, но Length не одно из 1, 2, 4 или 8; если MatchOnLength ясно, но не является ненулевой или MatchOnValue задано; или если MatchOnValue значение ясно, но LengthValue ненулевое значение.

Функция возвращается ERROR_HV_INVALID_PARAMETER , если запрошенная регистрация конфликтует с дверью, уже зарегистрированной в том же случае GuestAddress. Несколько дверей можно зарегистрировать на одном гостевом ValueLengthфизическом адресе, если каждое совпадение совпадает с одинаковым. Конфликт возникает, когда идентичная дверь уже зарегистрирована, когда новая регистрация указывает на другой номер, отличный Length от существующего дверного в этом адресе, или когда новая регистрация или существующую дверь в этом адресе совпадает с любым значением (то есть MatchOnValue ясно).

Remarks

Когда виртуальный процессор выполняет соответствующую запись, событие сигнализируется, и виртуальный процессор не завершает работу с WHvRunVpExitReasonMemoryAccess. Гипервизор распознает только определенные инструкции хранилища для запуска записи; Если гость выполняет запись с помощью нераспознанной инструкции, событие не сигнализируется и виртуальный процессор завершает работу с WHvRunVpExitReasonMemoryAccess. Набор поддерживаемых инструкций может измениться между Windows выпусками, поэтому вызывающие пользователи должны обеспечить правильное поведение пути выхода виртуального процессора для указанного гостевого адреса.

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

Зарегистрированная запись не должна перестраивать границу страницы; Нет других требований к выравниванию.

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

Требования

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

См. также

  • Last updated on