HvSavePartitionState function

The HvSavePartitionState function saves part of the state of a partition. HvSavePartitionState can also obtain summary state data for the operating system or a partition.

Syntax

C++


HV_STATUS  HvSavePartitionState(
  _In_   HV_PARTITION_ID PartitionId,
  _In_   HV_SAVE_RESTORE_STATE_FLAGS Flags,
  _Out_  PHV_SAVE_RESTORE_STATE_RESULT SaveState,
  _Out_  PUINT32 SaveDataCount,
  _Out_  PVOID SaveData
);

Parameters

PartitionId [in]

An HV_PARTITION_ID value that identifies the partition that HvSavePartitionState saves the state of or zero if HvSavePartitionState retrieves operating system summary state data. 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 save operation. The caller can use the following values:

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

SaveState [out]

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

SaveDataCount [out]

A pointer to a variable in which HvSavePartitionState stores the number of bytes of data that it saved.

SaveData [out]

A pointer to a buffer that HvSavePartitionState fills with some or all of the requested save state data. HvSavePartitionState returns the size, in bytes, of this data in a variable to which the SaveDataCount parameter points. HvSavePartitionState can return, at most, 4080 bytes, and, as with all hypercalls, the output parameters can never cross a page boundary. A size of zero is valid and does not have any significance.

Return value

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

Return code	Description
HV_STATUS_SUCCESS	HvSavePartitionState successfully saved partition or system state.
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_OPERATION_DENIED	The specified partition has one or more virtual processors that are not explicitly suspended. (This error does not apply when saving summary information.)
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	HvSavePartitionState was not previously called with HV_SAVE_RESTORE_STATE_START flag set in the Flags parameter to initialize the save process.
HV_STATUS_INSUFFICIENT_MEMORY	The number of pages in the memory pool of the caller is insufficient to perform the operation.

Remarks

HvSavePartitionState returns save data in a sequence-sensitive stream. The caller begins the save process by specifying the HV_SAVE_RESTORE_STATE_START flag in the Flags parameter. Subsequent calls should not specify this flag. The process should progress as long as HvSavePartitionState returns HV_STATUS_SUCCESS and the status feedback that the SaveState parameter points to is HvStateIncomplete. The process ends when either HvSavePartitionState returns an error status or HvSavePartitionState returns HV_STATUS_SUCCESS and SaveState points to the HvStateComplete status feedback.

HvSavePartitionState 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.
All virtual processors must be in an explicit suspended state except when saving summary information.

Native Interface

HvSavePartitionState
	Call Code = 0x005E
Input Parameters
0	PartitionId (8 bytes)
8	Flags (4 bytes) Padding (4 bytes)
Output Parameters
0	SaveState (4 bytes) SaveDataCount (4 bytes)
8	SaveData (up to 4080 bytes)

Requirements