KeSaveExtendedProcessorState function (wdm.h)

The KeSaveExtendedProcessorState routine saves extended processor state information.

Syntax

NTSTATUS KeSaveExtendedProcessorState(
  [in]  ULONG64      Mask,
  [out] PXSTATE_SAVE XStateSave
);

Parameters

[in] Mask

A 64-bit feature mask. The bits in this mask identify the extended processor feature states to save. If a mask bit is one, the routine saves the state of the feature that is identified by this bit. If a mask bit is zero, the state for the corresponding feature is not saved. This mask must not identify extended processor features that the operating system has not enabled. To obtain a mask of the enabled features, call the RtlGetEnabledExtendedFeatures routine.

A caller can set this parameter to the bitwise OR of one or more of the following XSTATE_MASK_XXX flag bits:

[out] XStateSave

A pointer to a caller-allocated buffer into which the routine writes an XSTATE_SAVE structure. This structure contains the saved state information for the extended processor features indicated by the Mask parameter. The buffer must be large enough to contain this structure.

Return value

KeSaveExtendedProcessorState returns STATUS_SUCCESS if the call is successful. Possible error return values include the following:

Remarks

On x86-based processors that support the XSAVE and XRSTOR instructions, these instructions provide a flexible mechanism to save and restore extended processor state information. KeSaveExtendedProcessorState uses these instructions if they are available.

To restore the extended processor state that was saved by KeSaveExtendedProcessorState, call the KeRestoreExtendedProcessorState routine.

The Mask parameter specifies the extended processor features whose state is to be saved. A KeRestoreExtendedProcessorState call restores only the extended processor state that was saved by the KeSaveExtendedProcessorState call that saved the state.

Kernel-mode code must save the state of an extended processor feature before it uses that feature, and it must restore the state before it exits.

Interrupt service routines (ISRs) run under severe time constraints that typically prevent them from using extended processor features. However, an ISR can schedule a deferred procedure call (DPC) that uses one or more extended processor features. The DPC routine must save and restore the state of the extended features to preserve the context of the interrupted program in whose process address space the routine runs.

The KeSaveFloatingPointState and KeRestoreFloatingPointState routines save and restore just the floating-point state (the x87/MMX registers) and the SSE state.

Requirements

See also

KeRestoreExtendedProcessorState

KeRestoreFloatingPointState

KeSaveFloatingPointState

RtlGetEnabledExtendedFeatures

XSTATE_SAVE