Fonction LocateXStateFeature (winbase.h)

Article
03/08/2023

Récupère un pointeur vers l’état du processeur pour une fonctionnalité XState dans une structure CONTEXT.

La définition des bits de fonctionnalité XState est spécifique au fournisseur de processeur. Pour plus d’informations sur une fonctionnalité particulière, consultez les manuels de référence du processeur appropriés.

Syntaxe

PVOID LocateXStateFeature(
  [in]            PCONTEXT Context,
  [in]            DWORD    FeatureId,
  [out, optional] PDWORD   Length
);

Paramètres

[in] Context

Pointeur vers une structure CONTEXT contenant l’état à récupérer ou à définir. Ce CONTEXTE doit avoir été initialisé avec InitializeContext avec l’indicateur CONTEXT_XSTATE défini dans le paramètre ContextFlags .

[in] FeatureId

Numéro de la fonctionnalité à localiser dans la structure CONTEXT .

[out, optional] Length

Pointeur vers une variable qui reçoit la longueur de la zone de fonctionnalité en octets. Le contenu de cette variable n’est pas défini si cette fonction retourne NULL.

Valeur retournée

Si la fonctionnalité spécifiée est prise en charge par le système et que la structure CONTEXT spécifiée a été initialisée avec l’indicateur CONTEXT_XSTATE , cette fonction retourne un pointeur vers la zone de fonctionnalité pour la fonctionnalité spécifiée. Le contenu et la disposition de cette zone sont spécifiques au processeur.

Si l’indicateur CONTEXT_XSTATE n’est pas défini dans la structure CONTEXT ou si le FeatureID n’est pas pris en charge par le système, la valeur de retour est NULL. Aucune information supplémentaire sur l’erreur n’est disponible.

Remarques

La fonction LocateXStateFeature doit être utilisée pour rechercher une fonctionnalité XState individuelle au sein d’une structure CONTEXT extensible. Les fonctionnalités ne sont pas nécessairement contiguës en mémoire et les applications ne doivent pas supposer que le décalage entre deux fonctionnalités consécutives restera constant à l’avenir.

Le paramètre FeatureID de la fonction correspond à un bit dans le masque de fonctionnalité. Par exemple, FeatureId 2 correspond à un FeatureMask de 4 dans SetXStateFeaturesMask. Les valeurs featureID de 0 et 1 correspondent respectivement à l’état du FPU X87 et à l’état SSE.

Si vous définissez XState sur un thread via les API SetThreadContext ou Wow64SetThreadContext , vous devez également appeler SetXStateFeaturesMask sur la structure CONTEXT avec la valeur de masque de la fonctionnalité renseignée pour marquer la fonctionnalité comme active.

Windows 7 avec SP1 et Windows Server 2008 R2 avec SP1 : L’API AVX est d’abord implémentée sur Windows 7 avec SP1 et Windows Server 2008 R2 avec SP1 . Étant donné qu’il n’existe pas de KIT de développement logiciel (SDK) pour SP1, cela signifie qu’il n’y a pas d’en-têtes et de fichiers de bibliothèque disponibles à utiliser. Dans ce cas, un appelant doit déclarer les fonctions nécessaires à partir de cette documentation et obtenir des pointeurs vers celles-ci à l’aide de GetModuleHandle sur « Kernel32.dll », puis effectuer des appels à GetProcAddress. Pour plus d’informations, consultez Utilisation du contexte XState .

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 7 avec SP1 [applications de bureau \| Applications UWP]
Serveur minimal pris en charge	Windows Server 2008 R2 avec SP1 [applications de bureau \| Applications UWP]
Plateforme cible	Windows
En-tête	winbase.h (inclure Windows.h)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll