HvFlushVirtualAddressList function

The HvFlushVirtualAddressList function invalidates portions of the virtual TLB that belong to a specified address space.

Syntax

HV_STATUS  HvFlushVirtualAddressList(
  _In_     HV_ADDRESS_SPACE_ID AddressSpace,
  _In_     HV_FLUSH_FLAGS Flags,
  _In_     UINT64 ProcessorMask,
  _Inout_  PUINT32 GvaCount,
  _In_     PCH_GVA GvaRangeList
);

Parameters

AddressSpace [in]

An HV_ADDRESS_SPACE_ID value that identifies the address space to flush (that is, a CR3 value). HV_ADDRESS_SPACE_ID is defined as an unsigned 64-bit (UINT64) value.

Flags [in]

A valid bitwise OR combination of HV_FLUSH_FLAGS values that specify a set of flag bits that modify the operation of the flush. HV_FLUSH_FLAGS is defined as an unsigned 32-bit (UINT32) value. For more information about flush flags, see Virtual MMU Data Types.

ProcessorMask [in]

A processor mask that indicates which processors should be affected by the flush operation.

GvaCount [in, out]

A pointer to a variable that contains the number of guest virtual address (GVA) ranges to flush. HvFlushVirtualAddressList specifies the actual number of GVA ranges that it flushed.

GvaRangeList [in]

A pointer to an array of HV_GVA variables for the GVA ranges that HvFlushVirtualAddressList should flush. HV_GVA is defined as an unsigned 64-bit (UINT64) value.

Return value

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

Remarks

The HvFlushVirtualAddressSpace virtual TLB invalidation operation acts on one or more processors.

If the guest has information about which processors might need to be flushed, it can specify a processor mask in the ProcessorMask parameter. Each bit in the mask corresponds to a virtual processor index. For example, a mask of 0x0000000000000051 indicates that the hypervisor should flush only the TLB of virtual processors 0, 4, and 6.

The following flags can be used to modify the behavior of the flush:

• HV_FLUSH_ALL_PROCESSORS (0x00000001) indicates that the operation should apply to all virtual processors within the partition. If this flag is set, the ProcessorMask parameter is ignored.

• HV_FLUSH_ALL_VIRTUAL_ADDRESS_SPACES (0x00000002) indicates that the operation should apply to all virtual address spaces. If this flag is set, the AddressSpace parameter is ignored.

• HV_FLUSH_NON_GLOBAL_MAPPINGS_ONLY (0x00000004) does not make sense for HvFlushVirtualAddressList and is treated as an invalid option.

All other flags are reserved and must be set to zero.

HvFlushVirtualAddressList takes a list of GVA ranges. Each range has a base GVA. Because flushes are performed with page granularity, the bottom 12 bits of the GVA can be used to define a range length. These bits encode the number of additional pages (beyond the initial page) within the range. This allows each entry to encode a range of 1 to 4096 pages.

A GVA that falls within a large-page mapping (2 MB or 4 MB) will cause the entire large page to be flushed from the virtual TLB.

HvFlushVirtualAddressList guarantees that by the time control returns back to the caller, the observable effects of all flushes on the specified virtual processors have occurred.

Invalid GVAs (those that specify addresses beyond the end of the partition's GVA space) are ignored.

If a target virtual processor's TLB requires flushing and that virtual processor currently inhibits TLB flushes, the caller's virtual processor is suspended. When TLB flushes are no longer inhibited, the virtual processor is unsuspended and the hypercall will be reissued. For more information about TLB flush inhibit, see Restrictions on TLB Flushes.

Native Interface

Requirements

Send comments about this topic to Microsoft

Build date: 11/16/2013