HvCreatePort function

The HvCreatePort function allocates a port object and a set of sixteen message buffers to store queued pending messages.

Syntax

C++


HV_STATUS  HvCreatePort(
  _In_  HV_PARTITION_ID PortPartition,
  _In_  HV_PORT_ID PortId,
  _In_  HV_PARTITION_ID ConnectionPartition,
  _In_  PCHV_PORT_INFO PortInfo
);

Parameters

PortPartition [in]

An HV_PARTITION_ID value that identifies the partition that is to receive messages or events through the port that HvCreatePort creates. HV_PARTITION_ID is defined as an unsigned 64-bit (UINT64) value.

PortId [in]

An HV_PORT_ID value that identifies the port to create. The port identifier must be unique among all port identifiers for the partition that PortPartition specifies. The port identifier is used to refer to the port. The port identifier is also used to identify the source of a message when it arrives.

ConnectionPartition [in]

An HV_PARTITION_ID value that identifies the partition that is allowed to send messages or events through the port that PortId identifies.

PortInfo [in]

A pointer to a HV_PORT_INFO structure that describes the port to create.

If the PortType member of HV_PORT_INFO is set to HvPortTypeMessage, the following table shows other members of HV_PORT_INFO for the native interface.

1st 8-byte	TargetSint (4 bytes)	TargetVp (4 bytes)
2nd 8-byte	PortType (4 bytes) = HvPortTypeMessage	Padding (4 bytes)
3rd 8-byte	RsvdZ (8 bytes)

If the PortType member of HV_PORT_INFO is set to HvPortTypeEvent, the following table shows other members of HV_PORT_INFO for the native interface.

1st 8-byte

TargetSint (4 bytes)

TargetVp (4 bytes)

2nd 8-byte

PortType (4 bytes) = HvPortTypeEvent

Padding (4 bytes)

3rd 8-byte

BaseFlagNumber
(2 bytes)

FlagCount
(2 bytes)

RsvdZ (4 bytes)

Return value

HvCreatePort returns one of the following values. In addition to these values, HvCreatePort can also return one of the values that are specified in Common Hypercall Status Codes.

Return code	Description
HV_STATUS_SUCCESS	HvCreatePort successfully created a port.
HV_STATUS_ACCESS_DENIED	Neither of the following is true: The caller is the parent of the specified partition. The caller is the specified partition, and the partition has the CreatePort partition privilege.
HV_STATUS_INVALID_PARTITION_ID	One of the following invalid partition conditions exists: The specified port-partition identifier is invalid. The specified connection-partition identifier is invalid. The connection and port partition identifiers reference the same partition.
HV_STATUS_INVALID_PORT_ID	One of the following invalid port conditions exists: The specified port identifier is already in use. The reserved portion (high 8 bits) of the PortId are nonzero.
HV_STATUS_INVALID_VP_INDEX	The specified virtual processor index does not reference a valid VP and is not HV_ANY_VP.
HV_STATUS_INVALID_PARAMETER	One of the following invalid parameter conditions exists: The specified interrupt source index is not in the range 1 through 15 inclusive. The specified port type is invalid. For event ports, the specified base flag number plus the flag count is greater than or equal to HV_EVENT_FLAGS_COUNT. For event ports, the specified flag count is zero. The reserved fields of the PortInfo parameter are not set to zero.
HV_STATUS_INVALID_PARTITION_STATE	The specified port or connection partition is not in the active state.
HV_STATUS_INSUFFICIENT_MEMORY	The number of pages in the memory pool of the caller is insufficient to perform the operation.
HV_STATUS_NO_RESOURCES	A required system resource is unavailable or an implementation limit has been reached.

Remarks

HvCreatePort allocates the memory for the port object and the message buffers from the memory pool of the partition that the PortPartition parameter identifies.

The port identifier that the PortId parameter specifies must be unique among all ports that are associated with the receive partition (that is, the partition that the PortPartition parameter specifies).

The caller must specify a partition in the ConnectionPartition parameter to prevent other partitions from maliciously connecting to the newly-created port. Only connections from the specified partition will be allowed.

HvCreatePort has the following restrictions:

The caller must possess the CreatePort privilege.
The partitions that are specified by PortPartition and ConnectionPartition must be in the active state.
The caller must be the parent of the partition that is specified by PortPartition, or the caller must possess the CreatePort privilege and specify its own partition identifier.

Native Interface

HvCreatePort
	Call Code = 0x0057
Input Parameters
0	PortPartition (8 bytes)
8	PortId (4 bytes) Padding (4 bytes)
16	ConnectionPartition (8 bytes)
24	PortTypeInfo (24 bytes)
32
40

Requirements