HvTranslateVirtualAddress function

The HvTranslateVirtualAddress function attempts to translate a specified guest virtual address (GVA) page number into a guest physical address (GPA) page number.

Syntax

HV_STATUS  HvTranslateVirtualAddress(
  _In_   HV_PARTITION_ID PartitionId,
  _In_   HV_VP_INDEX VpIndex,
  _In_   HV_TRANSLATE_GVA_CONTROL_FLAGS ControlFlags,
  _In_   HV_GVA_PAGE_NUMBER GvaPage,
  _Out_  PHV_TRANSLATE_GVA_RESULT TranslationResult,
  _Out_  PHV_GPA_PAGE_NUMBER GpaPage
);

Parameters

PartitionId [in]

An HV_PARTITION_ID value that identifies the partition on which HvTranslateVirtualAddress translates a GVA page number to a GPA page number. HV_PARTITION_ID is defined as an unsigned 64-bit (UINT64) value.

VpIndex [in]

An HV_VP_INDEX value that specifies the index of the virtual processor that HvTranslateVirtualAddress translates GVA to GPA page numbers. HV_VP_INDEX is defined as an unsigned 32-bit (UINT32) value.

ControlFlags [in]

A valid bitwise OR combination of HV_TRANSLATE_GVA_CONTROL_FLAGS values that specify a set of flag bits that modify the translation. HV_TRANSLATE_GVA_CONTROL_FLAGS is defined as an unsigned 64-bit (UINT64) value.

GvaPage [in]

An HV_GVA_PAGE_NUMBER value that specifies the GVA page number to translate.

TranslationResult [out]

A pointer to an HV_TRANSLATE_GVA_RESULT union in which HvTranslateVirtualAddress stores the results of the translation including the result code and flags.

GpaPage [out]

A pointer to an HV_GPA_PAGE_NUMBER variable that HvTranslateVirtualAddress fills with the translated GPA (if the result code that TranslationResult points to is HvTranslateGvaSuccess) or the address of a GPA access failure (if the result code is HvTranslateGvaGpaUnmapped, HvTranslateGvaGpaNoReadAccess, HvTranslateGvaGpaNoWriteAccess, or HvTranslateGvaGpaIllegalOverlayAccess). For other result codes, the value that GpaPage points to is invalid. HV_GPA_PAGE_NUMBER is defined as an unsigned 64-bit (UINT64) value.

Return value

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

Remarks

The translation determines the current modes and state of the specified virtual processor as well as the guest page tables.

The caller must set HV_TRANSLATE_GVA_CONTROL_FLAGS values in the ControlFlags parameter to specify whether the intended access is to read (HV_TRANSLATE_GVA_VALIDATE_READ (0x0001)), write (HV_TRANSLATE_GVA_VALIDATE_WRITE (0x0002)), or execute (HV_TRANSLATE_GVA_VALIDATE_EXECUTE (0x0004)). The caller can also use a bitwise OR on valid combinations of these access types and can use the following HV_TRANSLATE_GVA_CONTROL_FLAGS values as translation options:

HV_TRANSLATE_GVA_PRIVILEGE_EXEMPT (0x0008)

Indicates that the access should be performed as though the processor was running at a privilege level zero rather than the current privilege level.

HV_TRANSLATE_GVA_SET_PAGE_TABLE_BITS (0x0010)

Indicates that HvTranslateVirtualAddress should set the dirty and accessed bits within the guest's page tables if appropriate for the access type. The dirty bit will only be set if HV_TRANSLATE_GVA_VALIDATE_WRITE is also specified. If the caller has requested that accessed and dirty bits be set as part of the table walk, these bits are set as the walk occurs. If a walk is terminated, the accessed and dirty bits that were already set are not restored to their previous values.

HV_TRANSLATE_GVA_TLB_FLUSH_INHIBIT (0x0020)

Indicates that the TlbFlushInhibit flag in the virtual processor's HvRegisterInterceptSuspend register should be set as a consequence of a successful return. This prevents other virtual processors that are associated with the target partition from flushing the TLB of the specified virtual processor until after the TlbFlushInhibit flag is cleared. For more information about preventing TLB flushes, see Restrictions on TLB Flushes.

If paging is disabled in the virtual processor (that is, CR0.PG is clear), no page tables are consulted and translation success is guaranteed.

If paging is enabled in the virtual processor (that is, CR0.PG is set), a page table walk is performed. HvTranslateVirtualAddress uses the current state of the virtual processor to determine whether to perform a two-level, three-level, or four-level page table walk.

During the page table walk, the following conditions can arise that cause the walk to be terminated:

• A table entry is marked "not present" or the GVA is beyond the range permitted for the paging mode. In this case, HvTranslateVirtualAddress returns HvTranslateGvaPageNotPresent in the ResultCode member of the HV_TRANSLATE_GVA_RESULT structure to which the TranslationResult parameter points.

• A privilege violation is detected that is based on the access type (read, write, execute) or on the current privilege level. In this case, HvTranslateVirtualAddress returns HvTranslateGvaPrivilegeViolation in ResultCode.

• A reserved bit is set within a table entry. In this case, HvTranslateVirtualAddress returns HvTranslateGvaInvalidPageTableFlags in ResultCode.

A page table walk can also be terminated if one of the guest's page table pages cannot be accessed, which can occur in one of the following situations:

• The GPA is unmapped. In this case, HvTranslateVirtualAddress returns HvTranslateGvaGpaUnmapped in the ResultCode member of the HV_TRANSLATE_GVA_RESULT structure to which the TranslationResult parameter points.

• The GPA mapping's access rights indicate that the page is not readable. In this case, HvTranslateVirtualAddress returns HvTranslateGvaGpaNoReadAccess or HvTranslateGvaGpaNoWriteAccess in ResultCode.

• The access targets an overlay page that does not allow reads or writes. In this case, HvTranslateVirtualAddress returns HvTranslateGvaGpaIllegalOverlayAccess in ResultCode.

If HvTranslateVirtualAddress reports any of these GPA access failures, HvTranslateVirtualAddress fills the GpaPage output parameter with the address of the GPA page that it could not access.

If translation succeeds, HvTranslateVirtualAddress returns HvTranslateGvaSuccess in the ResultCode member of the HV_TRANSLATE_GVA_RESULT structure to which the TranslationResult parameter points. In this case, HvTranslateVirtualAddress reports the resulting translation in the GpaPage output parameter and appropriately sets the associated CacheType and OverlayPage members in HV_TRANSLATE_GVA_RESULT. The value in CacheType indicates the effective cache type that is used by the virtual processor to access the translated virtual address. The value in OverlayPage indicates whether the translated GPA accesses an overlay page that the hypervisor owns. Callers can use this information to determine whether memory accesses that are performed by the virtual processor would have accessed a mapped GPA page or an overlay page.

If the caller has requested that accessed and dirty bits be set as part of the table walk, these bits are set as the walk occurs. If a walk is terminated, the accessed and dirty bits that were already set are not restored to their previous values.

The reported cache type considers all of the state of the virtual processor including the current virtual PAT register settings and (if supported by the hypervisor implementation) the value of the MTRR MSRs and CR0.CD.

If HvTranslateVirtualAddress returns HV_STATUS_SUCCESS, the TranslationResult output parameter is valid. The caller must consult the value in the ResultCode member of the HV_TRANSLATE_GVA_RESULT structure to determine whether the GpaPage parameter is valid.

HvTranslateVirtualAddress has the following restrictions:

• The partition that PartitionId specifies must be in the active state.

• The caller must be the parent of the partition that is specified by PartitionId.

Native Interface

Requirements

See also

HV_TRANSLATE_GVA_RESULT

Send comments about this topic to Microsoft

Build date: 11/16/2013