HvInstallIntercept function

The HvInstallIntercept function enables or disables intercepts that are triggered by the specified child partition's virtual processors.

Syntax

C++


HV_STATUS  HvInstallIntercept(
  _In_  HV_PARTITION_ID PartitionId,
  _In_  HV_INTERCEPT_ACCESS_TYPE_MASK AccessType,
  _In_  PCHV_INTERCEPT_DESCRIPTOR Descriptor
);

Parameters

PartitionId [in]

An HV_PARTITION_ID value that identifies the child partition for which HvInstallIntercept enables or disables intercepts. HV_PARTITION_ID is defined as an unsigned 64-bit (UINT64) value.

AccessType [in]

A valid bitwise OR combination of HV_INTERCEPT_ACCESS_TYPE_MASK values that specify the access types that should be intercepted. HV_INTERCEPT_ACCESS_MASK_NONE (0) indicates that the intercept should be disabled.

Valid access type flags are HV_INTERCEPT_ACCESS_MASK_READ (1), HV_INTERCEPT_ACCESS_MASK_WRITE (2), and HV_INTERCEPT_ACCESS_MASK_EXECUTE (4). Combinations of these access types are permitted depending on the intercept type that is specified in the HV_INTERCEPT_DESCRIPTOR structure to which Descriptor points.

Descriptor [in]

A pointer to a HV_INTERCEPT_DESCRIPTOR structure that describes the intercept type to enable or disable.

Return value

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

Return code	Description
HV_STATUS_SUCCESS	HvInstallIntercept successfully enabled or disabled the specified intercept.
HV_STATUS_ACCESS_DENIED	The caller is not the parent of the specified partition.
HV_STATUS_INVALID_PARTITION_ID	The specified partition identifier is invalid.
HV_STATUS_INVALID_PARAMETER	One of the following invalid parameter conditions exists: The specified intercept type is invalid. The specified access type is not permitted for the intercept type that is specified in the HV_INTERCEPT_DESCRIPTOR structure to which Descriptor points. The intercept parameters are invalid or out of range for the intercept type. The intercept type and parameters are described in the HV_INTERCEPT_DESCRIPTOR structure to which Descriptor points.
HV_STATUS_INVALID_PARTITION_STATE	The specified partition is not in the active state.
HV_STATUS_INSUFFICIENT_MEMORY	The number of pages in the specified partition's memory pool is insufficient to perform the operation.

Remarks

The caller passes the appropriate access type to the AccessType parameter to install an intercept. To clear an intercept, the caller passes access type HV_INTERCEPT_ACCESS_MASK_NONE.

In general, calls to HvInstallIntercept can return the HV_STATUS_INSUFFICIENT_MEMORY error code if the hypervisor has insufficient memory that is required to allocate the requisite internal data structures. However, some intercept types do not require dynamic memory allocation and are guaranteed to never fail with the HV_STATUS_INSUFFICIENT_MEMORY error code. The following table shows the intercept types that can and cannot fail because of insufficient memory.

Intercept Type	Can Fail Due to Insufficient Memory?
I/O port access	No
MSR access	No
CPUID instruction execution	Yes
Exceptions	No

HvInstallIntercept 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

HvInstallIntercept
	Call Code = 0x004D
Input Parameters
0	PartitionId (8 bytes)
8	AccessType (4 bytes) InterceptType (4 bytes)
16	InterceptParameter (8 bytes)

Requirements