HvMapGpaPages function

The HvMapGpaPages function maps one or more guest physical address (GPA) pages within the caller's GPA space to pages within the target partition's GPA space.

Syntax

C++


HV_STATUS  HvMapGpaPages(
  _In_     HV_PARTITION_ID TargetPartitionId,
  _In_     HV_GPA_PAGE_NUMBER TargetGpaBase,
  _In_     HV_MAP_GPA_FLAGS MapFlags,
  _Inout_  PUINT32 PageCount,
  _In_     PCHV_GPA_PAGE_NUMBER SourceGpaPageList
);

Parameters

TargetPartitionId [in]: An HV_PARTITION_ID value that identifies the target partition for which HvMapGpaPages 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 to which HvMapGpaPages maps. HV_GPA_PAGE_NUMBER 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.
PageCount [in, out]: A pointer to a variable that contains the number of GPA pages to map. HvMapGpaPages specifies the actual number of pages that it mapped.
SourceGpaPageList [in]: A pointer to an array of HV_GPA_PAGE_NUMBER variables for the GPA pages that HvMapGpaPages maps to pages within the GPA space of the target partition that the PartitionId parameter specifies.

Return value

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

Return code	Description
HV_STATUS_SUCCESS	HvMapGpaPages successfully mapped GPA pages within the caller's GPA space to pages within the target partition's GPA space.
HV_STATUS_ACCESS_DENIED	The caller is not the parent of the specified target partition (unless the caller and the target partition are both 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 HvMapGpaPages function is a rep call. The caller passes a valid value to the PageCount parameter in a call to HvMapGpaPages 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, HvMapGpaPages 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 HvMapGpaPages 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 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.

HvMapGpaPages 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

HvMapGpaPages [rep]
	Call Code = 0x004B
Input Parameter Header
0	TargetPartitionId (8 bytes)
8	TargetGpaBase (8 bytes)
16	MapFlags (4 bytes) Padding (4 bytes)
Input List Element
0	SourceGpaPageList (8 bytes)

Requirements