HvRestorePartitionState function

The HvRestorePartitionState function restores partition state that was previously saved by using the HvSavePartitionState function. HvRestorePartitionState can also submit summary state data for a system or partition for compatibility assessment purposes.

Syntax

C++


HV_STATUS  HvRestorePartitionState(
  _In_     HV_PARTITION_ID PartitionId,
  _In_     HV_SAVE_RESTORE_STATE_FLAGS Flags,
  _Inout_  PUINT32 RestoreDataCount,
  _In_     PCVOID RestoreData,
  _Out_    PNV_SAVE_RESTORE_STATE_RESULT RestoreState
);

Parameters

PartitionId [in]

An HV_PARTITION_ID value that identifies the partition that HvRestorePartitionState restores the state of or zero if HvRestorePartitionState presents system summary state data for compatibility assessment purposes. HV_PARTITION_ID is defined as an unsigned 64-bit (UINT64) value.

Flags [in]

A valid bitwise OR combination of HV_SAVE_RESTORE_STATE_FLAGS values that specify information for performing the restore operation. The caller can use the following values:

Value	Meaning
HV_SAVE_RESTORE_STATE_START (0x00000001)	Starts a restore process and should be specified with the first call to HvRestorePartitionState. Subsequent calls should not specify this flag unless the calls are prematurely terminating a restore process. In this case, the calls are used to ensure that all intervening restore context that the hypervisor maintains is released.
HV_SAVE_RESTORE_STATE_SUMMARY (0x00000002)	The restore data is summary data and not complete partition restore data.

RestoreDataCount [in, out]

A pointer to a variable that contains the number of valid bytes that the caller provides in the buffer to which the RestoreData parameter points. HvRestorePartitionState returns the actual number of bytes that the hypervisor processed. This number can range from zero to the value that the caller provided at RestoreDataCount.

RestoreData [in]

A pointer to a buffer that contains some or all of the previously-saved state that HvRestorePartitionState will restore. HvRestorePartitionState can provide, at most, 4080 bytes, and, as with all hypercalls, the input parameters can never cross a page boundary.

RestoreState [out]

A pointer to a HV_SAVE_RESTORE_STATE_RESULT enumeration value that HvRestorePartitionState fills with the status feedback of the overall restore operation.

Return value

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

Return code	Description
HV_STATUS_SUCCESS	HvRestorePartitionState successfully restored partition or system state.
HV_STATUS_ACCESS_DENIED	The caller is not the parent of the specified partition or the caller's partition privilege flag CreatePartitions is cleared.
HV_STATUS_INVALID_PARTITION_ID	The specified partition identifier is invalid.
HV_STATUS_OPERATION_DENIED	The specified partition has one or more virtual processors that are not explicitly suspended.
HV_STATUS_INVALID_PARTITION_STATE	The specified partition is not in the active state.
HV_STATUS_INVALID_PARAMETER	The Flags parameter specifies an unsupported option.
HV_STATUS_INVALID_SAVE_RESTORE_STATE	HvRestorePartitionState was not previously called with HV_SAVE_RESTORE_STATE_START flag set in the Flags parameter to initialize the restoration process.
HV_STATUS_INSUFFICIENT_MEMORY	The number of pages in the memory pool of the caller is insufficient to perform the operation.

Remarks

The caller should call HvRestorePartitionState repeatedly until it presents the entire save stream to the hypervisor.

HvRestorePartitionState has the following restrictions:

The caller must possess the CreatePartitions privilege from the HV_PARTITION_PRIVILEGE_MASK union.
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.
All virtual processors must be in an explicit suspended state.

Native Interface

HvRestorePartitionState
	Call Code = 0x005F
Input Parameters
0	PartitionId (8 bytes)
8	Flags (4 bytes) RestoreDataCount (4 bytes)
16	RestoreData (up to 4080 bytes)
Output Parameters
0	RestoreState (4 bytes) RestoreDataConsumed (4 bytes)

Requirements