XBOX Hang Investigation Tool (XHIT) - XBOX Game Development Documentation

XBOX Hang Investigation Tool (XHIT) sert à l’analyse hors ligne des vidages de blocages GPU sur les appareils de la famille XBOX One. Hang Investigation for XBOX (HIX) sert à l’analyse hors ligne des vidages de blocages GPU sur les consoles XBOX Series X|S. Si le GPU de la console se bloque, un vidage de débogage est écrit dans un fichier .xhit. Ce fichier est stocké sur la console, sur le lecteur xd:\. Par défaut, les fichiers de vidage sont nommés d’après la date et l’heure en temps universel coordonné (heure de Greenwich). En voici un exemple.

gpuhang-2014-05-13-22-11-33.xhit
gpuhang-2014-05-13-22-16-44.xhit
gpuhang-2014-05-13-22-34-05.xhit  

Pour plus de clarté, vous pouvez renommer ces fichiers. Pour analyser le vidage, exécutez XHIT depuis la fenêtre d’invite de commandes XBOX One, comme suit.

Colonne 1
`xhit [/?] [/help] [/index] [/disasm] [/fulldisasm] [/detailed] [filename]`

Option	Description
/?	Affiche l’aide de l’outil.
/help	Affiche l’aide de l’outil.
/index	Affiche l’index du fichier.
/disasm	Désassemble toutes les mémoires tampons de commandes.
/fulldisasm	Désassemble toutes les mémoires tampons de commandes, y compris tous les champs des paquets et des registres.
/detailed	Affiche des détails supplémentaires.
filename	Spécifie l’emplacement (sur le PC local) du fichier .xhit qui contient le vidage de blocage GPU à analyser. Le chemin est entièrement spécifié comme un chemin local à la console. En voici un exemple. `d:\gpuhang-2014-05-13-22-11-33.xhit`

Remarques

XHIT affiche la même sortie que l’analyse des plantages GPU effectuée à l’exécution par le pilote graphique Direct3D au moment du plantage. Pour désactiver l’écriture du fichier de vidage, voir ID3D12Device::SetHangCallbacksX. La valeur retournée par le rappel détermine le paramètre : 1 indique qu’un fichier de vidage doit être écrit, et 0 qu’aucun fichier de vidage ne doit être écrit. L’analyse du blocage se compose de plusieurs sections, décrites ci-dessous.

Débogage des blocages de fences

Si un interblocage de fence GPU ou un autre blocage de synchronisation est détecté, des informations spécifiques sur le blocage sont affichées, comme dans l’exemple suivant.

The Title command processor Micro-Engine (ME) was waiting in an infinite loop for a memory location to
change value. The location is 0x01c0000400, and the wait was until the 64-bit value
at that location was >= the reference value (0xfffffffffffffffe)
AND the mask (0xffffffffffffffff).
The current value at that memory location is 0x386.
This could be caused by a fence deadlock, memory corruption, usage of the
InsertWaitOnMemory/Wait64BitValueX/Wait32BitValueX APIs, or a driver bug.

The fence memory location 0x01c0000400 corresponds to the ID3D12Fence object
(0x000001D6BBB14290 "Frame Progress Fence").

Le premier paragraphe décrit le blocage lui-même : dans ce cas, le ME du processeur de commandes GPU est bloqué dans une boucle infinie, en attendant que la valeur située à une adresse graphique (0x1c0000400) soit supérieure ou égale à une valeur de référence. Le deuxième paragraphe identifie ce que représente cette adresse graphique. Dans ce cas, cette adresse appartient à un objet ID3D12Fence, et cette fence porte un nom, “Frame Progress Fence”. Elle possède aussi un pointeur d’objet d’API associé. Grâce à ces informations contextuelles, il devrait être plus facile de trouver et de corriger le problème dans le code du titre. Tous les objets de synchronisation graphique, y compris les objets ID3D12Fence et les adresses brutes de mémoire graphique utilisées pour une synchronisation personnalisée, peuvent recevoir un nom afin de faciliter le débogage des blocages de fences avec XHIT. Pour nommer un objet ID3D12Fence, utilisez la méthode de la classe de base ID3D12Object::SetName. Pour nommer une adresse mémoire utilisée avec une synchronisation personnalisée (par exemple, ID3D12GraphicsCommandList::Wait64BitValueX), utilisez l’API ID3D12Device::RegisterCustomFenceLocationX.

Résumé de l’état des registres GPU

La liste des blocs GPU bloqués figure dans la section de résumé de l’état des registres GPU. Elle est principalement destinée aux scénarios de débogage avancés. De nombreux types de blocages détectables à partir des registres sont résumés plus loin, dans la section de résumé de haut niveau.

Pile d’événements PIX

Les mémoires tampons de commandes GPU sont analysées à proximité de la position actuelle du pointeur de lecture (RPTR) du processeur de commandes GPU. Les mémoires tampons de commandes sont analysées à la recherche d’événements PIX et d’appels de dessin. L’arborescence des événements est affichée, avec une flèche pointant vers l’endroit où le GPU s’est arrêté. Les listes de commandes différées (aussi appelées IB2) sont analysées, de même que les commandes immédiates (IB1) du contexte immédiat graphique.

Les événements PIX doivent être insérés manuellement par le titre à l’aide d’appels à PIXBeginEvent et PIXEndEvent. Les événements PIX ne sont pas présents dans les builds commerciales de Direct3D. Pour plus de renseignements, consultez la référence de l’API PIX3.

Résumé du blocage

L’analyse du blocage se termine par des descriptions en langage clair des problèmes détectés lors de l’analyse du blocage GPU, y compris des pistes d’investigation à approfondir.

Documentation de référence de l’API

Pix3 (contenu de l’API)

Voir aussi

HIX Outils PIX

​Remarques

​Débogage des blocages de fences

​Résumé de l’état des registres GPU

​Pile d’événements PIX

​Résumé du blocage

​Documentation de référence de l’API

​Voir aussi

Remarques

Débogage des blocages de fences

Résumé de l’état des registres GPU

Pile d’événements PIX

Résumé du blocage

Documentation de référence de l’API

Voir aussi