HvUnmapGpaPages function

The HvUnmapGpaPages function unmaps one or more guest physical address (GPA) pages from a child partition.

Syntax


HV_STATUS  HvUnmapGpaPages(
  _In_     HV_PARTITION_ID TargetPartitionId,
  _In_     HV_GPA_PAGE_NUMBER TargetGpaBase,
  _Inout_  PUINT32 PageCount
);

Parameters

TargetPartitionId [in]: An HV_PARTITION_ID value that identifies the target partition for which HvUnmapGpaPages modifies the GPA space. HV_PARTITION_ID is defined as an unsigned 64-bit (UINT64) value.
TargetGpaBase [in]: An HV_GPA_PAGE_NUMBER value that specifies the base GPA page number in the GPA space of the target partition that HvUnmapGpaPages unmaps. HV_GPA_PAGE_NUMBER is defined as an unsigned 64-bit (UINT64) value.
PageCount [in, out]: A pointer to a variable that contains the number of GPA pages to unmap. HvUnmapGpaPages specifies the actual number of pages that it unmapped.

Return value

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

Return code	Description
HV_STATUS_SUCCESS	HvUnmapGpaPages successfully unmapped GPA pages from the target partition's GPA space.
HV_STATUS_ACCESS_DENIED	One of the following conditions exists: The caller is not the parent of the specified target partition. The caller is the root partition and attempted to unmap pages from its own GPA space.
HV_STATUS_INVALID_PARTITION_ID	The specified target partition identifier is invalid.
HV_STATUS_INVALID_PARAMETER	A specified GPA page lies outside the GPA space of the specified target partition.
HV_STATUS_INVALID_PARTITION_STATE	The specified partition is not in the active state.
HV_STATUS_OBJECT_IN_USE	An attempt was made to unmap one or more pages that are being used for a purpose that requires them and the unmapping operation is not permitted.

Remarks

The HvUnmapGpaPages function is a rep call despite the fact that its parameters do not include an input or output list. The caller passes a valid value to the PageCount parameter in a call to HvUnmapGpaPages as the rep count. For more information about hypercall inputs, see Hypercall Inputs.

An attempt to unmap an already unmapped page is ignored, and HvUnmapGpaPages returns HV_STATUS_SUCCESS. Pages that have been deposited to pools by using the HvDepositMemory function are inaccessible and cannot be unmapped until they are first withdrawn by using the HvWithdrawMemory function.

If any of the pages are used for another purpose that cannot allow the unmapping to be performed, HvUnmapGpaPages returns the HV_STATUS_OBJECT_IN_USE error to indicate that the pages are currently in use. Such purposes include:

Pages mapped as event log buffers
Pages deposited into memory pools
Pages locked down for I/O operations

Unlike a call to the HvMapGpaPages function, the root partition cannot call HvUnmapGpaPages to act upon itself.

HvUnmapGpaPages has the following restrictions:

The partition that TargetPartitionId specifies must be in the active state.
The caller must be the parent of the partition that is specified by TargetPartitionId.

Native Interface

HvUnmapGpaPages [rep]
	Call Code = 0x004C
Input Parameter Header
0	TargetPartitionId (8 bytes)
8	TargetGpaBase (8 bytes)

Requirements