HvWithdrawMemory function

The HvWithdrawMemory function removes one or more pages from the memory pool of the specified child partition.

Syntax


HV_STATUS  HvWithdrawMemory(
  _In_     HV_PARTITION_ID PartitionId,
  _In_     HV_PROXIMITY_DOMAIN_INFO ProximityDomainInfo,
  _Inout_  PUINT32 PageCount,
  _Out_    PHV_GPA_PAGE_NUMBER GpaPages
);

Parameters

PartitionId [in]: An HV_PARTITION_ID value that identifies the partition from which to remove one or more pages of the partition's memory pool. HV_PARTITION_ID is defined as an unsigned 64-bit (UINT64) value.
ProximityDomainInfo [in]: An HV_PROXIMITY_DOMAIN_INFO structure that specifies the ACPI proximity domain information of the NUMA node from which the pages are to be withdrawn.
PageCount [in, out]: A pointer to a variable that contains the number of guest physical address (GPA) pages to withdraw. HvWithdrawMemory specifies the actual number of pages that it withdrew.
GpaPages [out]: A pointer to an array of HV_GPA_PAGE_NUMBER variables for the GPA pages that HvWithdrawMemory removed from the memory pool of the partition that the PartitionId parameter specifies. HV_GPA_PAGE_NUMBER is defined as an unsigned 64-bit (UINT64) value.

Return value

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

Return code	Description
HV_STATUS_SUCCESS	HvWithdrawMemory successfully withdrew memory from the child partition's memory pool.
HV_STATUS_ACCESS_DENIED	Neither of the following items is true: The caller is the parent of the specified partition, and the caller's partition privilege flag AccessMemoryPool is enabled. The caller is the root partition, and the specified partition is the root partition.
HV_STATUS_INVALID_PARTITION_ID	The specified partition is invalid.
HV_STATUS_INVALID_PARAMETER	The ProximityDomainInfo parameter specifies an invalid flag bit or an invalid domain identifier.
HV_STATUS_NO_RESOURCES	No unused page was available.

Remarks

A page can be withdrawn only if it is not currently in use by the hypervisor. The hypervisor guarantees that the contents of the withdrawn page are zeroed. The GPA for the withdrawn page is the same as the GPA of a page that was previously deposited. If HvWithdrawMemory returns HV_STATUS_SUCCESS, each withdrawn page will have read, write, and execute access.

If a partition is in the uninitialized or finalized state, HvWithdrawMemory will allow withdrawal of all pages within the partition's pool. In other cases, success is not guaranteed--even if a recent call to the HvGetMemoryBalance function indicated the presence of available pages--because the hypervisor might require deposited pages at any time.

HvWithdrawMemory has the following restrictions:

The caller must possess the AccessMemoryPool privilege.
The caller must either be the parent of the partition that is specified by PartitionId or the root partition that specifies its own partition identifier.

Native Interface

HvWithdrawMemory [rep]
	Call Code = 0x0049
Input Parameter Header
0	PartitionId (8 bytes)
8	ProximityDomainInfo (8 bytes)
Output List Element
0	GpaPage (8 bytes)

Requirements