Inter-Partition Communication Data Types

The hypervisor defines the following data types for inter-partition communication.

Synthetic Interrupt Sources

The SynIC supports 16 synthetic interrupt sources.

#define HV_SYNIC_SINT_COUNT  16

typedef UINT32 HV_SYNIC_SINT_INDEX;

SynIC Message Types

SynIC messages encode the message type as a 32-bit number from the HV_MESSAGE_TYPE enumeration.

The following constant can mask out all message types that are reserved for use by the hypervisor.

#define HV_MESSAGE_TYPE_HYPERVISOR_MASK  0x80000000

Any message type that has the high bit set is reserved for use by the hypervisor. Guests cannot send guest-initiated messages with a hypervisor message type.

For a complete list of messages that the hypervisor sends, see HV_MESSAGE_TYPE.

SynIC Message Flags

The MessagePending bit-field flag from the HV_MESSAGE_FLAGS union indicates whether there are any messages pending in the message queue of the synthetic interrupt source. If messages are pending, the guest must perform an end-of-message (EOM) operation after the guest empties the message slot. This operation allows for opportunistic writes to the EOM MSR (only when required). Note that the hypervisor might set this flag upon message delivery or at any time afterwards. After the guest empties the message slot, the guest should test this flag. If the flag is set, there are one or more pending messages and the guest should perform an EOM.

SynIC Message Format

SynIC messages are fixed in size and composed of a message header, which includes the message type and information about where the message originated, followed by the payload. The HV_MESSAGE structure shows the structure of SynIC messages. The HV_MESSAGE_HEADER structure shows the structure of message headers. Messages that are sent in response to a call to the HvPostMessage hypercall function contain the port identifier (ID). Intercept messages contain the partition ID of the partition whose virtual processor generated the intercept. Timer intercepts do not have an origination ID (that is, the specified ID is zero).

The following constants indicate information about a message:

#define HV_MESSAGE_SIZE  256
#define HV_MESSAGE_MAX_PAYLOAD_BYTE_COUNT 240
#define HV_MESSAGE_MAX_PAYLOAD_QWORD_COUNT 30

For more information about the messages that are sent by the hypervisor, see Hypervisor Message Formats.

SynIC Event Flags

SynIC event flags (HV_SYNIC_EVENT_FLAGS) are fixed-size bitwise arrays. They are numbered such that the first byte of the array contains flags 0 through 7 (0 being the least significant bit) and the second byte of the array contains flags 8 through 15 (8 being the least significant bit), and so on.

#define HV_EVENT_FLAGS_COUNT  (256 * 8)
#define HV_EVENT_FLAGS_BYTE_COUNT  256

Hypervisor Ports

Destination ports are identified by 32-bit HV_PORT_ID values. The high 8 bits of the ID are reserved and must be zero. All port IDs are unique within a partition.

The hypervisor supports message ports, event ports, and monitor ports. These port types are specified with the values of the HV_PORT_TYPE enumeration. A guest can use message ports in a call to the HvPostMessage hypercall function and event ports in a call to the HvSignalEvent hypercall function. A guest can also use monitor ports in a call to HvSignalEvent. These monitor ports are used with monitor pages that the hypervisor monitors and notifies the guest about.

When a guest calls the HvCreatePort hypercall function to create a port, the guest specifies information about the port in a HV_PORT_INFO structure.

Port Properties

Port properties provide a generic way to set or obtain certain characteristics of a port. Properties are identified by a 32-bit code from the HV_PORT_PROPERTY_CODE enumeration. The associated property value is 64 bits in size.

typedef UINT64 HV_PORT_PROPERTY;
typedef HV_PORT_PROPERTY *PHV_PORT_PROPERTY;

Hypervisor Connections

Connections are identified by 32-bit HV_CONNECTION_ID values. The high 8 bits are reserved and must be zero. All connection identifiers are unique within a partition.

The hypervisor does not ascribe special meaning to any connection identifiers.

Hypervisor Connection Information

A guest uses the HV_CONNECTION_INFO structure to specify information about a connection when the guest calls the HvConnectPort hypercall function to create a connection to a port.

Monitored Notification Trigger Group

The monitored notification triggers group is described by the HV_MONITOR_TRIGGER_GROUP union and defines 32 triggers per group. The 32 triggers are represented by two related arrays of bits: pending and armed. Setting a trigger bit to 1 in the pending array indicates to the hypervisor that the related notification should eventually generate a signal event. The corresponding bit in the armed array should be set to 0 whenever the matching pending bit is modified. The armed bit is used to ensure that a notification is deferred by at least the latency that is specified for the notification. Both of these bits must be updated atomically.

Monitored Notification Parameters

Each monitored notification trigger has a set of associated notification parameters that the hypervisor passes as inputs when the hypervisor makes an implicit call to the HvSignalEvent hypercall function. These notification parameters are defined by the HV_MONITOR_PARAMETER structure.

Monitored Notification Page

Monitored notifications are defined in a monitored notification facility (MNF) overlay page, which supports four sets of monitored notification trigger groups. Each individual 32-bit group can be enabled independently by using the HV_MONITOR_PAGE structure. The HV_MONITOR_TRIGGER_STATE union specifies the state of each monitored notification trigger group.

Send comments about this topic to Microsoft

Build date: 11/16/2013