À partir du 27 mars 2025, nous vous recommandons d'utiliser android-latest-release au lieu de aosp-main pour créer et contribuer à AOSP. Pour en savoir plus, consultez la section Modifications apportées à AOSP.

Cette page a été traduite par l'API Cloud Translation.

Utiliser ftrace
Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

ftrace est un outil de débogage permettant de comprendre ce qui se passe dans le kernel Linux. Les sections suivantes décrivent les fonctionnalités de base de ftrace, l'utilisation de ftrace avec atrace (qui capture les événements du noyau) et la ftrace dynamique.

Pour en savoir plus sur les fonctionnalités avancées de ftrace qui ne sont pas disponibles dans systrace, consultez la documentation ftrace sur <kernel tree>/Documentation/trace/ftrace.txt.

Capturer des événements du kernel avec atrace

atrace (frameworks/native/cmds/atrace) utilise ftrace pour capturer les événements du noyau. À son tour, systrace.py (ou run_systrace.py dans les versions ultérieures de Catapult) utilise adb pour exécuter atrace sur l'appareil. atrace effectue les opérations suivantes:

Configure le traçage en mode utilisateur en définissant une propriété (debug.atrace.tags.enableflags).
Active la fonctionnalité ftrace souhaitée en écrivant dans les nœuds sysfs ftrace appropriés. Toutefois, comme ftrace est compatible avec davantage de fonctionnalités, vous pouvez définir vous-même certains nœuds sysfs, puis utiliser atrace.

À l'exception du traçage au démarrage, utilisez atrace pour définir la propriété sur la valeur appropriée. La propriété est un masque de bits, et il n'existe aucun moyen efficace de déterminer les valeurs correctes, si ce n'est en examinant l'en-tête approprié (qui peut changer entre les versions d'Android).

Activer les événements ftrace

Les nœuds sysfs ftrace se trouvent dans /sys/kernel/tracing et les événements de suivi sont divisés en catégories dans /sys/kernel/tracing/events.

Pour activer les événements par catégorie, utilisez:

echo 1 > /sys/kernel/tracing/events/irq/enable

Pour activer les événements par événement, utilisez:

echo 1 > /sys/kernel/tracing/events/sched/sched_wakeup/enable

Si des événements supplémentaires ont été activés en écrivant dans des nœuds sysfs, ils ne seront pas réinitialisés par atrace. Un modèle courant pour la mise en service d'un appareil Qualcomm consiste à activer les tracepoints kgsl (GPU) et mdss (pipeline d'affichage), puis à utiliser atrace ou systrace:

adb shell "echo 1 > /sys/kernel/tracing/events/mdss/enable"
adb shell "echo 1 > /sys/kernel/tracing/events/kgsl/enable"
./systrace.py sched freq idle am wm gfx view binder_driver irq workq ss sync -t 10 -b 96000 -o full_trace.html

Vous pouvez également utiliser ftrace sans atrace ni systrace, ce qui est utile lorsque vous souhaitez des traces réservées au noyau (ou si vous avez pris le temps d'écrire manuellement la propriété de traçage en mode utilisateur). Pour exécuter uniquement ftrace:

Définissez la taille de la mémoire tampon sur une valeur suffisamment importante pour votre trace:
```
echo 96000 > /sys/kernel/tracing/buffer_size_kb
```

Activez le traçage:

echo 1 > /sys/kernel/tracing/tracing_on

Exécutez votre test, puis désactivez le traçage:
```
echo 0 > /sys/kernel/tracing/tracing_on
```

Videz la trace:

cat /sys/kernel/tracing/trace > /data/local/tmp/trace_output

trace_output fournit la trace sous forme de texte. Pour le visualiser à l'aide de Catapult, récupérez le dépôt Catapult sur GitHub et exécutez trace2html:

catapult/tracing/bin/trace2html ~/path/to/trace_file

Par défaut, trace_file.html est écrit dans le même répertoire.

Mettre en corrélation des événements

Il est souvent utile d'examiner simultanément la visualisation Catapult et le journal ftrace. Par exemple, certains événements ftrace (en particulier ceux spécifiques au fournisseur) ne sont pas visualisés par Catapult. Toutefois, les codes temporels de Catapult sont relatifs au premier événement de la trace ou à un code temporel spécifique extrait par atrace, tandis que les codes temporels bruts de ftrace sont basés sur une source d'horloge absolue particulière dans le noyau Linux.

Pour trouver un événement ftrace donné à partir d'un événement Catapult:

Ouvrez le journal ftrace brut. Les traces des versions récentes de systrace sont compressées par défaut :
- Si vous avez capturé votre trace système avec --no-compress, elle se trouve dans le fichier HTML, dans la section commençant par BEGIN TRACE.
- Dans le cas contraire, exécutez html2trace à partir de l'arborescence Catapult (tracing/bin/html2trace) pour décompresser la trace.
Recherchez l'horodatage relatif dans la visualisation Catapult.
Recherchez une ligne au début de la trace contenant tracing_mark_sync. Exemple :
```
<5134>-5134  (-----) [003] ...1    68.104349: tracing_mark_write: trace_event_clock_sync: parent_ts=68.104286
```
Si cette ligne n'existe pas (ou si vous avez utilisé ftrace sans atrace), les temps seront relatifs au premier événement du journal ftrace.
1. Ajoutez le code temporel relatif (en millisecondes) à la valeur dans parent_ts (en secondes).
2. Recherchez le nouveau code temporel.

Ces étapes devraient vous placer à proximité de l'événement (ou du moins très près de celui-ci).

Utiliser ftrace dynamique

Lorsque systrace et ftrace standard sont insuffisants, il existe un dernier recours: le ftrace dynamique. La ftrace dynamique implique la réécriture du code du noyau après le démarrage. Par conséquent, elle n'est pas disponible dans les noyaux de production pour des raisons de sécurité. Toutefois, chaque bug de performances difficile en 2015 et 2016 a finalement été identifié à l'aide de ftrace dynamique. Il est particulièrement efficace pour déboguer les veilles ininterruptibles, car vous pouvez obtenir une trace de pile dans le noyau chaque fois que vous appuyez sur la fonction déclenchant la veille ininterruptible. Vous pouvez également déboguer des sections avec les interruptions et les préemptions désactivées, ce qui peut être très utile pour prouver les problèmes.

Pour activer ftrace dynamique, modifiez le fichier defconfig de votre kernel:

Supprimez CONFIG_STRICT_MEMORY_RWX (s'il est présent). Si vous utilisez la version 3.18 ou ultérieure et arm64, elle n'est pas disponible.
Ajoutez les éléments suivants: CONFIG_DYNAMIC_FTRACE=y, CONFIG_FUNCTION_TRACER=y, CONFIG_IRQSOFF_TRACER=y, CONFIG_FUNCTION_PROFILER=y et CONFIG_PREEMPT_TRACER=y.
Recompilez et démarrez le nouveau noyau.
Exécutez la commande suivante pour rechercher les traceurs disponibles:
```
cat /sys/kernel/tracing/available_tracers
```
Vérifiez que la commande renvoie function, irqsoff, preemptoff et preemptirqsoff.

Exécutez la commande suivante pour vous assurer que ftrace dynamique fonctionne:

cat /sys/kernel/tracing/available_filter_functions | grep <a function you care about>

Une fois ces étapes effectuées, vous disposez de ftrace dynamique, du profileur de fonction, du profileur irqsoff et du profileur preemptoff. Nous recommandons vivement de lire la documentation ftrace sur ces sujets avant de les utiliser, car ils sont puissants, mais complexes. irqsoff et preemptoff sont principalement utiles pour confirmer que les pilotes peuvent laisser les interruptions ou la préemption désactivées trop longtemps.

Le profileur de fonction est la meilleure option pour les problèmes de performances et est souvent utilisé pour déterminer où une fonction est appelée.

Affichage du problème: photo HDR et viseur rotatif

Dans ce cas, l'utilisation d'un Pixel XL pour prendre une photo HDR+, puis la rotation immédiate du viseur provoquait un à-coup à chaque fois. Nous avons utilisé le profileur de fonction pour déboguer le problème en moins d'une heure. Pour suivre l'exemple, téléchargez le fichier ZIP des traces (qui inclut également d'autres traces mentionnées dans cette section), décompressez-le et ouvrez le fichier trace_30898724.html dans votre navigateur.

La trace montre plusieurs threads du processus cameraserver bloqués en mode veille ininterruptible sur ion_client_destroy. Il s'agit d'une fonction coûteuse, mais elle ne doit être appelée que très rarement, car les clients ion doivent englober de nombreuses allocations. Au départ, le code Hexagon de Halide était mis en cause, ce qui était effectivement l'un des coupables (il créait un nouveau client pour chaque allocation d'ions et le détruisait lorsque l'allocation était libérée, ce qui était beaucoup trop coûteux). Le passage à un seul client ion pour toutes les allocations Hexagon a amélioré la situation, mais le problème de saccade n'a pas été résolu.

À ce stade, nous devons savoir qui appelle ion_client_destroy. Il est donc temps d'utiliser le profileur de fonction:

Comme les fonctions sont parfois renommées par le compilateur, vérifiez que ion_client_destroy est présent à l'aide de:
```
cat /sys/kernel/tracing/available_filter_functions | grep ion_client_destroy
```
Après avoir vérifié qu'il est bien présent, utilisez-le comme filtre ftrace:
```
echo ion_client_destroy > /sys/kernel/tracing/set_ftrace_filter
```

Activez le profileur de fonction:

echo function > /sys/kernel/tracing/current_tracer

Activez les traces de pile chaque fois qu'une fonction de filtre est appelée:
```
echo func_stack_trace > /sys/kernel/tracing/trace_options
```

Augmentez la taille de la mémoire tampon:

echo 64000 > /sys/kernel/tracing/buffer_size_kb

Activez le traçage:
```
echo 1 > /sys/kernel/tracing/trace_on
```

Exécutez le test et obtenez la trace:

cat /sys/kernel/tracing/trace > /data/local/tmp/trace

Affichez la trace pour voir de nombreuses traces de pile:

    cameraserver-643   [003] ...1    94.192991: ion_client_destroy <-ion_release
    cameraserver-643   [003] ...1    94.192997: <stack trace>
 => ftrace_ops_no_ops
 => ftrace_graph_call
 => ion_client_destroy
 => ion_release
 => __fput
 => ____fput
 => task_work_run
 => do_notify_resume
 => work_pending

Après examen du pilote ion, nous pouvons voir que ion_client_destroy est bombardé de spam par une fonction d'espace utilisateur qui ferme un fd sur /dev/ion, et non par un pilote de kernel aléatoire. En recherchant \"/dev/ion\" dans le code source Android, nous trouvons plusieurs pilotes de fournisseurs qui font la même chose que le pilote Hexagon et ouvrent/ferment /dev/ion (créent et détruisent un nouveau client ion) chaque fois qu'ils ont besoin d'une nouvelle allocation d'ion. En les modifiant pour utiliser un seul client ion pendant toute la durée de vie du processus, le bug a été corrigé.

Si les données du profileur de fonction ne sont pas assez spécifiques, vous pouvez combiner les points de trace ftrace avec le profileur de fonction. Les événements ftrace peuvent être activés exactement de la même manière que d'habitude, et ils seront entrelacés avec votre trace. Cela est très utile si un sommeil long et ininterruptible se produit occasionnellement dans une fonction spécifique que vous souhaitez déboguer: définissez le filtre ftrace sur la fonction souhaitée, activez les points de trace et effectuez une trace. Vous pouvez analyser la trace obtenue avec trace2html, rechercher l'événement souhaité, puis obtenir les traces de pile à proximité dans la trace brute.

Utiliser lockstat

Parfois, ftrace ne suffit pas et vous devez vraiment déboguer ce qui semble être un conflit de verrouillage du kernel. Il existe une autre option de kernel à essayer : CONFIG_LOCK_STAT. Il s'agit d'une solution de dernier recours, car il est extrêmement difficile de la faire fonctionner sur des appareils Android, car elle gonfle la taille du noyau au-delà de ce que la plupart des appareils peuvent gérer.

Toutefois, lockstat utilise l'infrastructure de verrouillage de débogage, qui est utile pour de nombreuses autres applications. Toute personne travaillant sur la mise en service de l'appareil doit trouver un moyen de faire fonctionner cette option sur chaque appareil, car il y aura un moment où vous penserez : "Si seulement je pouvais activer LOCK_STAT, je pourrais confirmer ou infirmer que c'est le problème en cinq minutes au lieu de cinq jours."

Problème d'affichage: blocage dans SCHED_FIFO lorsque les cœurs sont à charge maximale avec un autre paramètre que SCHED_FIFO

Dans ce problème, le thread SCHED_FIFO s'est bloqué lorsque tous les cœurs étaient à charge maximale avec des threads autres que SCHED_FIFO. Nous avons obtenu des traces montrant une contention de verrouillage importante sur un fd dans les applications de RV, mais nous n'avons pas pu identifier facilement le fd utilisé. Pour suivre l'exemple, téléchargez le fichier ZIP des traces (qui inclut également d'autres traces mentionnées dans cette section), décompressez-le et ouvrez le fichier trace_30905547.html dans votre navigateur.

Nous avons émis l'hypothèse que ftrace était la source du conflit de verrouillage, lorsqu'un thread de faible priorité commençait à écrire dans le canal ftrace, puis était préempté avant de pouvoir libérer le verrouillage. Il s'agit du pire scénario, qui a été exacerbé par un mélange de threads à priorité extrêmement faible écrivant sur le repère ftrace, ainsi que par certains threads de priorité plus élevée tournant sur les processeurs pour simuler un appareil complètement chargé.

Comme nous ne pouvions pas utiliser ftrace pour le débogage, nous avons fait fonctionner LOCK_STAT, puis désactivé tout autre traçage de l'application. Les résultats ont montré que la contention de verrouillage provenait en fait de ftrace, car aucune contention ne s'est affichée dans la trace de verrouillage lorsque ftrace n'était pas en cours d'exécution.

Si vous pouvez démarrer un noyau avec l'option de configuration, le traçage des verrouillages est semblable à ftrace:

Activez le traçage:
```
echo 1 > /proc/sys/kernel/lock_stat
```
Exécutez votre test.
Pour désactiver le traçage:
```
echo 0 > /proc/sys/kernel/lock_stat
```

Videz votre trace:

cat /proc/lock_stat > /data/local/tmp/lock_stat

Pour obtenir de l'aide pour interpréter le résultat, consultez la documentation de lockstat sur <kernel>/Documentation/locking/lockstat.txt.

Utiliser des tracepoints de fournisseur

Utilisez d'abord les tracepoints en amont, mais vous devrez parfois utiliser des tracepoints du fournisseur:

  { "gfx",        "Graphics",         ATRACE_TAG_GRAPHICS, {
        { OPT,      "events/mdss/enable" },
        { OPT,      "events/sde/enable" },
        { OPT,      "events/mali_systrace/enable" },
    } },

Les points de trace sont extensibles par le service HAL, ce qui vous permet d'ajouter des points/catégories de trace spécifiques à l'appareil. Les points de trace sont intégrés à Perfetto, atrace/systrace et à l'application de traçage système sur l'appareil.

Les API permettant d'implémenter des tracepoints/catégories sont les suivantes:

listCategories()génère (vec<TracingCategory> categories);
enableCategories(vec<string> categories) génère (Status status);
disableAllCategories() génère (Status status);

Pour en savoir plus, consultez la définition de HAL et l'implémentation par défaut dans AOSP:

Utiliser ftrace Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.