CommunityCodierung & Entwicklunggithub.com

Mobil-GPU-Profiling

Coding-Skill. Liest die Hardware-Zähler des Mobil-GPUs aus, um Engpässe präzise zu identifizieren und zu beheben. Unterstützt Arm Mali (via Arm Performance Studio) und Qualcomm Adreno (via Snapdragon Profiler / Android GPU Inspector).

Was ist Mobil-GPU-Profiling?

Dieses Skill für KI-Agenten (z. B. Claude Code, Cursor) ermöglicht das detaillierte Profiling mobiler GPUs durch Auslesen von Hardware-Zählern. Es identifiziert präzise, ob die GPU der Engpass ist und ob dieser durch Pixel, Vertices, Texturen, Bandbreite oder Shader-Mathematik verursacht wird – im Gegensatz zu externen Metriken (FPS, Speicher, Temperatur), die nur Symptome zeigen. Das Skill unterstützt Arm Mali/Immortalis (via Arm Performance Studio: Streamline Headless Capture, Performance Advisor, Mali Offline Compiler, Frame Advisor, RenderDoc for Arm) und Qualcomm Adreno (via Snapdragon Profiler / Android GPU Inspector). Es liefert Skripte, um Mali-Zähler über adb zu erfassen und auszuwerten, sowie eine detaillierte Referenz zur Übersetzung von Zählern in Optimierungsmaßnahmen. Entwickler können damit zielgerichtet Engpässe beheben – z. B. Fragment-Shader vereinfachen, Overhead reduzieren oder Texturkompression verbessern – und die Ergebnisse mit device_probe.py verifizieren.

Funktioniert mit✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/P0r0ro/mobile-gpu-profiling-skill/tree/HEAD/mobile-gpu-profiling

Installed? Explore more Codierung & Entwicklung skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Mobil-GPU-Profiling (Mali- und Adreno-Hardwarezähler)

mobile-3d-rendering misst von außen: FPS, Speicher, Temperatur und Engine-Zähler. Dieses Skill öffnet die GPU und liest ihre Hardware-Zähler aus. Es beantwortet: Ist die GPU wirklich der Engpass, und wenn ja, liegt es an Pixeln, Vertices, Texturen, Bandbreite oder Shader-Mathematik? Jeder Fall erfordert eine andere Lösung – Raten kostet Tage.

Wann einsetzen (Eskalation, nicht erster Schritt):

  • mobile-3d-rendering-Triage zeigt FPS unter Ziel bei akzeptablen Draw-Counts, oder FPS ändert sich nicht beim Reduzieren von Draws und Dreiecken;
  • Entscheidung, ob ein High-End-Effekt (Normal Maps, MSAA 4x, Bloom-Halo, mehr Lichter) auf dem Referenzgerät ins Budget passt;
  • Finden, welcher Shader oder welches Material teuer ist;
  • Hitze ohne offensichtliche Ursache (Bandbreite zeigt sich hier);
  • GPU-seitige Besonderheiten bei einem Anbieter.

Abschließend immer mit mobile-3d-rendering/scripts/device_probe.py auf dem Gerät nachmessen (FPS, p95, Speicheranstieg, Temperatur). Zähler erklären; die Sonde bestätigt.

0. GPU erkennen und Pfad wählen

S=~/.claude/skills/mobile-gpu-profiling/scripts
python3 $S/gpu_profile.py detect          # Anbieter, GPU, Treiber, Android-Version, Bildschirmgröße
GPUZähler-AufnahmeShader-KostenFrame-Erfassung
Arm Mali / Immortalisgpu_profile.py mali-capture (Streamline, headless)malioc_batch.py (Mali Offline Compiler)Frame Advisor, RenderDoc for Arm GPUs
Qualcomm AdrenoSnapdragon Profiler Echtzeit/Trace (GUI), oder AGI auf Android 11+-GerätenAdreno Offline Compiler (falls verfügbar) oder SDP Shader-StatistikenSnapdragon Profiler Snapshot, AGI Frame Profiler
andere (PowerVR, Xclipse)Hersteller-Tool / AGI; gpu_profile.py gpu-busy—RenderDoc / AGI

Installationshinweise für jedes Tool: references/arm-performance-studio.md, references/adreno.md. Die App muss ein debugfähiger Build sein (Godot: Debug-Export; Unity: Development Build; android:debuggable="true").

1. Mali: Zähler erfassen und auswerten

python3 $S/gpu_profile.py mali-capture -p <paket> -s 30 -o gpu-profil-<name>
#   Erster Lauf erstellt eine Zählerkonfiguration aus der Arm-Vorlage für diese GPU (zwischengespeichert in ~/.cache/mobile-gpu-profiling)
#   Das Skript startet die App; spielen Sie die zu messende Szene ab (Worst-Case: Menschenmengen, Kampf, Nacht)
python3 $S/gpu_profile.py mali-analyze gpu-profil-<name>/capture.apc --fps 60   # später erneut lesen

Es schreibt report.md + metrics.json. Lesen Sie das Ergebnis oben, dann die Zahlen:

MetrikGesund auf einem Mittelklasse-GerätWenn nicht
gpu_util< 75–80 % bei Ziel-FPS (thermische Reserve)> 85 %: GPU-limitiert, nächste Zeilen lesen. < 60 % bei niedrigen FPS: CPU-limitiert, also CPU profilieren
fragment_queue_util vs non_fragment_queue_util / tiler_util—Welcher nahe 100 % ist, ist der Engpass: Fragment = Kosten pro Pixel; Non-Fragment/Tiler = Vertices, Dreiecke, Schattenwerfer
fragments_per_screen_pixel< 2,0 (alle Durchläufe)Overdraw, Schattenkarten, zusätzliche Render-Durchläufe (siehe render_passes_per_frame)
alu_instr_per_fragment< 20–30 auf BifrostSchwere Fragment-Shader → §2
tex_compressed_share / tex_mipmapped_sharehoch für SzenentexturenUnkomprimierte/ohne Mipmap-Texturen verschwenden Bandbreite und Cache (Schattenkarten und Renderziele sind nie komprimiert, also prüfen, welche Texturen dominieren)
late_zs_test_share< 10 %Discard/Alpha-Test oder Shader-Tiefenschreibungen deaktivieren Early-Z
early_zs_kill_rate, fpk_occluding_sharehoch ist gutUndurchsichtige Objekte vorne-nach-hinten sortieren; Discard auf großen Flächen vermeiden
bandwidth_mb_per_frame< ~30–40 MB bei 60 FPS auf Geräten von 2018–2020Renderziele, unkomprimierte Texturen, MSAA-Auflösungen → Hitze
facing_culled_share~40–50 % für geschlossene NetzeZweiseitige Materialien verdoppeln Vertex-Arbeit
fp16_varying_sharehochMediump-Varyings halbieren Interpolationskosten

Die vollständige Zähler-zu-Lösung-Referenz mit Formeln finden Sie in references/mali-counters.md.

Frame-Marker: Der Frame-weise HTML-Bericht des Performance Advisor benötigt Framegrenzen von der Arm-Ebene. Arm unterstützt Android 11+. Auf Android 10 (getestet auf Galaxy Note 9) funktionieren die Zähler, aber die Frames der Ebene erreichten nie gatord, daher fällt das Skript auf sekündliche Zähler × die von SurfaceFlinger während der Aufnahme gemessenen FPS zurück.

2. Den teuren Shader finden (jede Engine, Mali-Kostenmodell)

# Godot (Compatibility/GLES3): das tatsächlich kompilierte GLSL ES über Mesa auf dem Desktop ausgeben
HEADLESS=1 $S/godot_dump_shaders.sh <godot-projekt> dump/ 20 [res://test_scene.tscn]
python3 $S/malioc_batch.py --core Mali-G72 dump/ --label-src <godot-projekt>/shaders --top 15
  • Die Rangliste zeigt Zyklen pro Pixel (oder pro Vertex) und welche Pipeline sie begrenzt (A Arithmetic, LS Load/Store, V Varying, T Texture). Labels benennen Ihre Shader-Datei; "engine" bedeutet ein integriertes Material.
  • Flags: occ50 bedeutet mehr als 32 Arbeitsregister, daher sind nur die Hälfte der Threads aktiv (Latenz wird schlechter versteckt); SPILL bedeutet Stack-Spilling; lateZS bedeutet Discard; fp16:0% bedeutet keine 16-Bit-Mathematik.
  • Kosten eines Shaders ≈ Zyklen × abgedeckte Pixel. Ein 38-Zyklen-Shader auf Boden und Gebäuden ist wichtiger als ein 60-Zyklen-Shader auf einem kleinen Schild.
  • Unity-, three.js- und Bevy-Shader-Extraktion: references/shader-cost.md.

Das Dump-Skript führt das Spiel gegen eine verworfene Kopie seiner Benutzerdaten aus, sodass Spielstände und Einstellungen unberührt bleiben und der Godot-Shader-Cache keine Kompilierungen versteckt. Besuchen Sie während des Laufs die relevanten Bereiche (oder übergeben Sie eine Testszene). Godot kompiliert Varianten träge.

3. Adreno (Qualcomm)

Snapdragon Profiler verwenden: Echtzeit für Live-Metriken, Trace für eine Zeitleiste, Snapshot für einen Frame mit Draw-weise Statistiken. Dieselben Fragen aus den Metriken lesen: % Shaders Busy, % Time Shading Fragments vs Vertices, Avg Bytes / Fragment, % Texture Fetch Stall, % Texture L1 Miss, ALU / Fragment, % Prims Trivially Rejected, Read/Write Total. Die Metrik-zu-Lösung-Tabelle finden Sie in references/adreno.md.

Auf Android 11+-Geräten, die AGI unterstützt, liefert Android GPU Inspector anbieterneutrale Zähler plus einen Frame-Profiler. Für eine schnelle Auslastungsmessung ohne Tools liest gpu_profile.py gpu-busy -s 30 den Busy-Knoten des Kernels, sofern der Build dies erlaubt.

4. Von Zählern zu Änderungen (dann verifizieren)

  1. Beheben Sie den größten im Bericht genannten Engpass. Immer nur eine Änderung auf einmal.

  2. Typische Zuordnungen:

    EngpassLösungen
    Fragment-limitiertWeniger/kleinere Schattenkarten und kürzere Schattenentfernung, weniger transparentes Overdraw, günstigere Shader auf großen Flächen (Mathematik in den Vertex-Shader verschieben, pro-Pixel-Rauschen/Nebel/Specular auf Niedrig/Mittel entfernen, mediump), komprimierte+Mipmap-Texturen, niedrigere interne Auflösung nur dort, wo nachweislich sicher (Mali-G72 hatte Speicherlecks mit Render-Scaling)
    Geometrie/Tiler-limitiertLOD und Sichtbarkeitsbereiche, weniger Schattenwerfer, Backface-Culling aktiviert, einfacheres Skinning bei Menschenmengen
    Bandbreite/HitzeKomprimierte Texturen, weniger Renderziele/Durchläufe, MSAA statt Post-AA, kein Vollbild-Post
    CPU-limitiert (GPU < 60 % Auslastung)Draw-Calls, Skripte, Animation, Physik (performance-optimization)
  3. Die gleiche Szene erneut aufnehmen und metrics.json vorher/nachher vergleichen (GPU ms pro Frame, Anteil des Engpasses).

  4. Auf dem Gerät mit device_probe.py für mindestens 60 s bestätigen (FPS, p95, Speicheranstieg, Temperatur). Ein Zählergewinn, der das Gerät erhitzt oder Speicher verliert, ist kein Gewinn.

  5. Den Befund in den Projektnotizen festhalten (was war der Engpass, was hat ihn behoben, vorher/nachher-Zahlen).

Hart erkämpfte Regeln (aus echten Aufnahmen)

  • Die Zählerkonfiguration aus der GPU-Vorlage erstellen und standardmäßig nur GPU-Zähler behalten. CPU-PMU-Zähler führten dazu, dass die Capture-Child beim Start auf einem Samsung-Android-10-Kernel abstürzte.
  • Wi-Fi-adb funktioniert, aber die Geräte-ID ist ip:port. Überall übergeben (die Skripte tun das).
  • Eine abgestürzte Aufnahme kann gatord-Agenten im Sandbox-Prozess der App hinterlassen. Sie blockieren die Sockets des nächsten Captures ("Adresse bereits verwendet") und brechen es vorzeitig ab. Das Skript tötet sie per PID (run-as <pkg> pkill funktionierte nicht).
  • Ein Force-Stopp der App direkt vor einer Aufnahme kann sie nach einer Sekunde beenden. Das Skript wartet, bis sich alles beruhigt hat.
  • Streamline-cli -generate-config benötigt -template <name> vor dem Ziel, trotz des -help-Textes.
  • Godot behält einen GLES-Shader-Cache in user://shader_cache, daher kompiliert ein zweiter Desktop-Lauf nichts. Ein frisches XDG_DATA_HOME verwenden (das Dump-Skript tut das).
  • Das Ausführen des echten Spiels auf dem Desktop für Audits schreibt sein Autosave. Das Benutzerdatenverzeichnis isolieren.

Referenzen

DateiLesen, wenn
references/arm-performance-studio.mdStreamline, Performance Advisor, Frame Advisor, RenderDoc for Arm, malioc installieren/verwenden; headless-Pipeline-Details
references/mali-counters.mdWas jede Mali-Metrik bedeutet, Formeln, Schwellenwerte, Bifrost vs Valhall vs 5. Generation
references/adreno.mdSnapdragon Profiler / AGI-Setup und Metrik-zu-Lösung-Tabelle für Adreno
references/shader-cost.mdKompilierte Shader aus Godot/Unity/three.js/Bevy extrahieren und malioc-Ausgabe lesen

Verwandte Skills