HvReadGpa function

The HvReadGpa function attempts to read from a range of bytes within the specified guest physical address (GPA) page.

Syntax

HV_STATUS  HvReadGpa(
  _In_   HV_PARTITION_ID PartitionId,
  _In_   HV_VP_INDEX VpIndex,
  _In_   HV_GPA BaseGpa,
  _In_   UINT32 ByteCount,
  _In_   HV_ACCESS_GPA_CONTROL_FLAGS ControlFlags,
  _Out_  PNV_ACCESS_GPA_RESULT AccessResult,
  PVOID DataBuffer
);

Parameters

PartitionId [in]

An HV_PARTITION_ID value that identifies the partition on which HvReadGpa reads from a GPA page. 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 on which HvReadGpa reads from a GPA page. HV_VP_INDEX is defined as an unsigned 32-bit (UINT32) value.

BaseGpa [in]

An HV_GPA value that specifies the first guest physical address to be accessed. HV_GPA is defined as an unsigned 64-bit (UINT64) value.

ByteCount [in]

The number of bytes to access (1 through 16, inclusive).

ControlFlags [in]

An HV_ACCESS_GPA_CONTROL_FLAGS union that specifies a valid bitwise OR combination of flag bits that modify the behavior of the access.

AccessResult [out]

A pointer to an HV_ACCESS_GPA_RESULT union in which HvReadGpa stores the results of the access.

DataBuffer

[out]

A pointer to a buffer that HvReadGpa fills with the data that was read. For the native interface, DataLow contains bytes 1-8 and DataHigh contains bytes 9-16.

If the caller specifies a byte count in the ByteCount parameter that is smaller than 16 bytes, HvReadGpa fills the remaining bytes in the output data with zeroed bytes.

Return value

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

Remarks

The range of bytes that HvReadGpa reads from cannot cross a page boundary. HvReadGpa can read up to 16 bytes of data. A byte count of zero is invalid.

The hypervisor performs the access according to the current GPA mapping. If the specified GPA references an overlay page, the access is directed to the overlay page and not the page that is potentially mapped to the specified GPA. This is also true of memory-mapped I/O (MMIO) ranges that the hypervisor manages (namely, the APIC page). In other words, the access is performed as though the virtual processor itself performed the access.

HvReadGpa uses the appropriate combination of 32-bit, 16-bit, and 8-bit reads to access data in an aligned manner. HvReadGpa performs the data access in ascending address order.

Accesses to overlay pages perform the side effects normally associated with the access.

HvReadGpa does not guarantee atomicity of the access. Another virtual processor might be attempting to modify the specified GPA range. Unless the other virtual processor uses atomic accesses, HvReadGpa might return partially-modified data.

If HvReadGpa returns HV_STATUS_SUCCESS, the AccessResult parameter is valid. The caller must consult the value in the ResultCode member of the HV_ACCESS_GPA_RESULT union to determine whether an error was detected when the specified GPA page was accessed. An error can occur for one of the following reasons:

• The GPA is unmapped. In this case, HvReadGpa returns HvAccessGpaUnmapped in the ResultCode member of the HV_ACCESS_GPA_RESULT union to which the AccessResult parameter points.

• The GPA mapping's access rights indicate that the page is not readable. In this case, HvReadGpa returns HvAccessGpaReadIntercept in ResultCode.

• The access targets an overlay page that does not allow reads. In this case, HvReadGpa returns HvAccessGpaWriteIntercept in ResultCode.

HvReadGpa 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_ACCESS_GPA_CONTROL_FLAGS

HV_ACCESS_GPA_RESULT

Send comments about this topic to Microsoft

Build date: 11/16/2013