HvWriteGpa function

The HvWriteGpa function attempts to write to a range of bytes within the specified guest physical address (GPA) page.

Syntax

HV_STATUS  HvWriteGpa(
  _In_   HV_PARTITION_ID PartitionId,
  _In_   HV_VP_INDEX VpIndex,
  _In_   HV_GPA BaseGpa,
  _In_   UINT32 ByteCount,
  _In_   HV_ACCESS_GPA_CONTROL_FLAGS ControlFlags,
  _In_   PCVOID DataBuffer,
  _Out_  PHV_ACCESS_GPA_RESULT AccessResult
);

Parameters

PartitionId [in]

An HV_PARTITION_ID value that identifies the partition on which HvWriteGpa writes to 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 HvWriteGpa writes to 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.

DataBuffer [in]

A pointer to a buffer that contains the data that HvWriteGpa writes to the GPA page. 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, HvWriteGpa ignores the remaining bytes in the input data.

AccessResult [out]

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

Return value

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

Remarks

The range of bytes that HvWriteGpa writes to cannot cross a page boundary. HvWriteGpa can write 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.

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

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

HvWriteGpa does not guarantee atomicity of the access. Another virtual processor might be attempting to read or write the specified GPA range. Unless the other virtual processor uses atomic accesses, the other virtual processor might detect partially-written data by HvWriteGpa.

If HvWriteGpa 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, HvWriteGpa 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 writable. In this case, HvWriteGpa returns HvAccessGpaReadIntercept in ResultCode.

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

HvWriteGpa 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