HvDepositMemory function

The HvDepositMemory function deposits memory from the parent partition into a child partition's memory pool.

Syntax


HV_STATUS  HvDepositMemory(
  _In_     HV_PARTITION_ID PartitionId,
  _Inout_  PUINT32 PageCount,
  _In_     PCHV_GPI_PAGE_NUMBER GpaPages
);

Parameters

PartitionId [in]: An HV_PARTITION_ID value that identifies the partition on which to credit the memory pool. HV_PARTITION_ID is defined as an unsigned 64-bit (UINT64) value.
PageCount [in, out]: A pointer to a variable that contains the number of guest physical address (GPA) pages to deposit. HvDepositMemory specifies the actual number of pages that it deposits.
GpaPages [in]: A pointer to an array of HV_GPA_PAGE_NUMBER variables for the GPA pages that HvDepositMemory deposits into 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

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

Return code	Description
HV_STATUS_SUCCESS	HvDepositMemory successfully deposited memory into 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_OPERATION_DENIED	One of the following is true: A specified GPA page is not mapped within the caller's GPA space. A specified GPA page is not read, write, and execute-accessible within the GPA space of the caller. A specified GPA page is readable, writable, or executable within the GPA space of a partition that is not the caller. A specified GPA page has already been deposited into the memory pool of a partition.
HV_STATUS_INVALID_PARTITION_STATE	The specified partition is not in the active or uninitialized state.
HV_STATUS_OBJECT_IN_USE	A specified GPA is being used for another purpose and therefore cannot be deposited.

Remarks

The pages that are specified by GpaPages become exclusively accessible by the hypervisor. The pages must be mapped within the caller's GPA space with read, write, and execute access. If mapped within the GPA space of any other partition, the pages must be inaccessible. If HvDepositMemory returns HV_STATUS_SUCCESS, the pages are no longer accessible to the caller. In addition, future mapping changes to the pages are prohibited until the pages have been successfully withdrawn from the pool (through a call to the HvWithdrawMemory function).

HvDepositMemory fails if a page has already been deposited into a partition's memory pool. If a page is being used for another purpose, an error is returned to indicate that the page is currently in use. Such purposes include:

The page is mapped as an event log buffer.
The page is locked down for I/O operations.

HvDepositMemory has the following restrictions:

The caller must possess the AccessMemoryPool privilege.
The partition that is specified by PartitionId must be in the active or uninitialized state.
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.
The caller must possess read, write, and execute access to the GPAs that are specified by GpaPages.
No other partition can possess read, write, or execute access to the GPAs that are specified by GpaPages.

Native Interface

HvDepositMemory [rep]
	Call Code = 0x0048
Input Parameter Header
0	PartitionId (8 bytes)
Input List Element
0	GpaPage (8 bytes)

Requirements