Export (0) Print
Expand All

LocateXStateFeature function

Retrieves a pointer to the processor state for an XState feature within a CONTEXT structure.

The definition of XState feature bits are processor vendor specific. Please refer to the relevant processor reference manuals for additional information on a particular feature.

Syntax


PVOID WINAPI LocateXStateFeature(
  _In_       PCONTEXT Context,
  _In_       DWORD FeatureId,
  _Out_opt_  PDWORD Length
);

Parameters

Context [in]

A pointer to a CONTEXT structure containing the state to retrieve or set. This CONTEXT should have been initialized with InitializeContext with the CONTEXT_XSTATE flag set in the ContextFlags parameter.

FeatureId [in]

The number of the feature to locate within the CONTEXT structure.

Length [out, optional]

A pointer to a variable which receives the length of the feature area in bytes. The contents of this variable are undefined if this function returns NULL.

Return value

If the specified feature is supported by the system and the specified CONTEXT structure has been initialized with the CONTEXT_XSTATE flag, this function returns a pointer to the feature area for the specified feature. The contents and layout of this area is processor-specific.

If the CONTEXT_XSTATE flag is not set in the CONTEXT structure or the FeatureID is not supported by the system, the return value is NULL. No additional error information is available.

Remarks

The LocateXStateFeature function must be used to find an individual XState feature within an extensible CONTEXT structure. Features are not necessarily contiguous in memory and applications should not assume the offset between two consecutive features will remain constant in the future.

The FeatureID parameter of the function corresponds to a bit within the feature mask. For example, FeatureId 2 corresponds to a FeatureMask of 4 in SetXStateFeaturesMask. FeatureID values of 0 and 1 correspond to X87 FPU state and SSE state, respectively.

If you are setting XState on a thread via the SetThreadContext or Wow64SetThreadContext APIs, you must also call SetXStateFeaturesMask on the CONTEXT structure with the mask value of the filled-in feature to mark the feature as active.

Windows 7 with SP1 and Windows Server 2008 R2 with SP1:  The AVX API is first implemented on Windows 7 with SP1 and Windows Server 2008 R2 with SP1 . Since there is no SDK for SP1, that means there are no available headers and library files to work with. In this situation, a caller must declare the needed functions from this documentation and get pointers to them using GetModuleHandle on "Kernel32.dll", followed by calls to GetProcAddress. See Working with XState Context for details.

Requirements

Minimum supported client

Windows 7 with SP1 [desktop apps | Windows Store apps]

Minimum supported server

Windows Server 2008 R2 with SP1 [desktop apps | Windows Store apps]

Header

WinBase.h (include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll

See also

CONTEXT
Intel AVX
Working with XState Context
SetXStateFeaturesMask
SetThreadContext
Wow64SetThreadContext

 

 

Community Additions

ADD
Show:
© 2014 Microsoft