HvMapSparseGpaPages function

The HvMapSparseGpaPages function maps a range of guest physical address (GPA) pages within the caller's GPA space to pages within the target partition's GPA space.

Syntax

C++


HV_STATUS  HvMapSparseGpaPages(
  _In_     HV_PARTITION_ID TargetPartitionId,
  _In_     HV_MAP_GPA_FLAGS MapFlags,
  _Inout_  PUINT32 PagePairCount,
  _In_     PCHV_GPA_MAPPING PageList
);

Parameters

TargetPartitionId [in]: An HV_PARTITION_ID value that identifies the target partition for which HvMapSparseGpaPages maps page ranges. HV_PARTITION_ID is defined as an unsigned 64-bit (UINT64) value.
MapFlags [in]: A valid bitwise OR combination of HV_MAP_GPA_FLAGS values that specify the access rights that are associated with the mapping. Valid access rights flags are HV_MAP_GPA_READABLE (0x00000001), HV_MAP_GPA_WRITABLE (0x00000002), and HV_MAP_GPA_EXECUTABLE (0x00000004). For information about valid combinations, see Page Access Rights.
PagePairCount [in, out]: A pointer to a variable that contains the number of pairs of physical page numbers to map. HvMapSparseGpaPages specifies the actual number of pairs of physical pages that it mapped.
PageList [in]: A pointer to an array of HV_GPA_MAPPING structures for the pairs of physical page numbers that HvMapSparseGpaPages maps. Each element of the array is a pair of GPA pages that consists of a GPA page within the target GPA space and a source GPA page within the caller's GPA space.

Return value

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

Return code	Description
HV_STATUS_SUCCESS	HvMapSparseGpaPages successfully mapped a range of GPA pages from source to target.
HV_STATUS_ACCESS_DENIED	The caller is not the parent of the specified target partition (unless both the caller and the target partition are the root partition). The target partition is the root partition and one of the following is true: The target GPA base is not equal to the first source GPA in the list. The source GPA list does not consist of contiguous and incrementing pages. The target GPA range references an inaccessible GPA page.
HV_STATUS_INVALID_PARTITION_ID	The specified target partition identifier is invalid.
HV_STATUS_INVALID_PARAMETER	One of the following invalid parameter conditions exists: A target GPA page lies outside the GPA space of the target partition. A reserved or invalid bit within the MapFlags parameter is set. An invalid combination of access rights is specified. A source GPA page lies outside the GPA space of the caller's partition.
HV_STATUS_OPERATION_DENIED	One of the following conditions exists: A source GPA page is unmapped. A source GPA page has been deposited into a partition's memory pool and is inaccessible.
HV_STATUS_INVALID_PARTITION_STATE	The specified partition is not in the active state.
HV_STATUS_INSUFFICIENT_MEMORY	The number of pages in the partition's memory pool is insufficient to perform the operation.
HV_STATUS_OBJECT_IN_USE	An attempt was made to change the mapping of one or more pages that are being used for a purpose that is incompatible with the change and is not permitted.

Remarks

The HvMapSparseGpaPages function is a rep call. The caller passes a valid value to the PagePairCount parameter in a call to HvMapSparseGpaPages as the rep count. For more information about hypercall inputs, see Hypercall Inputs.

The mapping, if successful, supersedes any previous mapping to the affected GPA pages. Likewise, the specified access rights (readable, writeable, and executable) supersede any previously-installed access rights on the GPA pages.

If an existing mapping is superseded and the pages are used for another purpose that cannot allow the mapping to be changed, HvMapSparseGpaPages 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

The GPA pages within the caller's partition must be mapped and not deposited into any partition's memory pool.

A parent partition is allowed to map its GPA pages into a child's GPA space multiple times. It is also allowed to map its GPA pages into the GPA space of multiple children. This multiple mapping allows the parent partition to create shared areas between itself and one or more of its children.

The root partition is special in that it can call HvMapSparseGpaPages on itself. However, it can modify only the access rights to its GPA pages. It cannot create arbitrary mappings within its own GPA space. Its GPA map is defined by the hypervisor at boot time and at the time system physical address (SPA) RAM ranges are added or removed. Root GPA pages are identity-mapped to SPA pages. Although the root partition can modify the access rights to its own GPA mappings, it cannot establish non-identity mappings.

For best performance on x64-based systems, callers should attempt to map at least 2 MB of consecutive GPA pages and ensure that these pages have the same alignment relative to a 2-MB boundary. This mapping will potentially enable the hypervisor to use large-page mappings and in turn reduce the pressure on physical TLBs. Note that this mapping is not required to be done in a single call, and in fact cannot be done in a single call due to the size constraints on the input parameter list.

HvMapSparseGpaPages has the following restrictions:

The partition that TargetPartitionId specifies must be in the active state.
The caller must either be the parent of the partition that is specified by TargetPartitionId or the root partition that specifies its own partition identifier.

Native Interface

HvMapSparseGpaPages [rep]
	Call Code = 0x006e
Input Parameter Header
0	TargetPartitionId (8 bytes)
8	MapFlags (4 bytes) Padding (4 bytes)
Input List Element
0	PagePair (16 bytes)

Requirements