Communityコーディング&開発github.com

モバイルGPUプロファイリング(MaliおよびAdrenoハードウェアカウンター)

電話のGPUがハードウェアカウンターから実際に行っていることを読み取り、修正が実際の限界をターゲットにできるようにするコーディングスキル。Arm Mali(Arm Performance Studio経由)とQualcomm Adreno(Snapdragon Profiler / Android GPU Inspector経由)をサポート。

モバイルGPUプロファイリング(MaliおよびAdrenoハードウェアカウンター) とは?

このスキルは、モバイルGPU(Arm MaliおよびQualcomm Adreno)のハードウェアカウンターに直接アクセスすることで、パフォーマンスのボトルネックを正確に特定します。fps、メモリ、温度といった外部測定しか行わない`mobile-3d-rendering`スキルとは異なり、このスキルは「GPUが本当に限界なのか」「もしそうなら、ピクセル、頂点、テクスチャ、帯域幅、シェーダー演算のうちどれが原因か」という根本的な問いに答えます。各原因には異なる修正方法が必要であり、推測に頼ると日数を浪費します。 主な機能は3つあります。(1) `mali-capture`コマンドによるMaliカウンターの取得と分析、(2) `malioc_batch.py`を用いたシェーダーコストのオフライン評価、(3) 分析レポートの自動生成です。各指標(フラグメント負荷、ジオメトリ負荷、帯域幅など)のしきい値と、そこから導かれる具体的な修正方法(シャドウマップの削減、テクスチャ圧縮、シェーダーの最適化など)が詳細にドキュメント化されています。 このスキルは、CLIスクリプト群と詳細なリファレンスドキュメントで構成されており、adb経由でデバイスに接続して動作します。Godot、Unity、three.js、Bevyなどのエンジンで動作し、デバッグ可能なビルドが必要です。最終的には`device_probe.py`で実際のfpsや温度を再測定し、カウンターの改善が現実のパフォーマンス向上に結びついていることを確認します。

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

Installed? Explore more コーディング&開発 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

モバイルGPUプロファイリング(MaliおよびAdrenoハードウェアカウンター) は何をしますか?

mobile-3d-renderingは外部から測定します:fps、メモリ、温度、エンジンカウンター。 このスキルはGPUを開き、そのハードウェアカウンターを読み取ります。それは次の問いに答えます:GPUが本当に限界なのか、もしそうなら、それはピクセル、頂点、テクスチャ、帯域幅、それともシェーダー演算のどれか? それぞれに異なる修正が必要なため、推測は日数の無駄になります。

いつ使うか(最初のステップではなく、エスカレーション時):

  • mobile-3d-renderingのトリアージで、fpsが目標を下回っているがドローコール数は予算内、またはドローとトライアングルを減らしてもfpsが変わらない場合;
  • ハイエンド効果(法線マップ、MSAA 4x、ブルームハロー、より多くの光源)がリファレンス端末の予算に収まるか判断する場合;
  • どのシェーダーやマテリアルが高コストかを見つける場合;
  • 明らかな原因がない発熱(帯域幅がここに現れます);
  • 一方のベンダーでのGPU側の異常。

常に最後に、デバイス上でmobile-3d-rendering/scripts/device_probe.pyを使って再測定します(fps、p95、メモリ傾き、温度)。カウンターが説明し、プローブが確認します。

0. GPUを検出し、パスを選択する

S=~/.claude/skills/mobile-gpu-profiling/scripts
python3 $S/gpu_profile.py detect          # ベンダー、GPU、ドライバー、Androidバージョン、画面サイズ
GPUカウンター取得シェーダーコストフレームキャプチャ
Arm Mali / Immortalisgpu_profile.py mali-capture(Streamline、ヘッドレス)malioc_batch.py(Mali Offline Compiler)Frame Advisor、RenderDoc for Arm GPUs
Qualcomm AdrenoSnapdragon Profiler Realtime/Trace(GUI)、またはサポートされているAndroid 11+デバイスではAGIAdrenoオフラインコンパイラ(利用可能な場合)またはSDPシェーダー統計Snapdragon Profiler Snapshot、AGIフレームプロファイラ
その他(PowerVR、Xclipse)ベンダーツール/ AGI;gpu_profile.py gpu-busy—RenderDoc / AGI

各ツールのインストールノート:references/arm-performance-studio.md、references/adreno.md。 アプリはデバッグ可能なビルドである必要があります(Godot:デバッグエクスポート;Unity:Development Build;android:debuggable="true")。

1. Mali:カウンターの取得と読み取り

python3 $S/gpu_profile.py mali-capture -p <package> -s 30 -o gpu-profile-<name>
#   初回実行時、そのGPU用のArmテンプレートからカウンター設定をビルドします(~/.cache/mobile-gpu-profilingにキャッシュ)
#   スクリプトがアプリを起動します。測定したいシーンを再生します(最悪ケース:群衆、戦闘、夜)
python3 $S/gpu_profile.py mali-analyze gpu-profile-<name>/capture.apc --fps 60   # 後で再読み込み

report.md + metrics.jsonを書き出します。先頭の判定結果を読み、次に数値を確認します。

メトリックミッドレンジ端末での健全な値そうでない場合
gpu_util目標fpsで< 75–80%(熱的な余裕)> 85%:GPUバウンド、次の行を読む。 < 60%かつ低fps:CPUバウンド、CPUをプロファイリング
fragment_queue_util vs non_fragment_queue_util / tiler_util—100%に近い方が限界:フラグメント = ピクセル単位のコスト;非フラグメント/タイラー = 頂点、トライアングル、シャドウキャスター
fragments_per_screen_pixel< 2.0(すべてのパス)オーバードロー、シャドウマップ、追加レンダーパス(render_passes_per_frameを参照)
alu_instr_per_fragmentBifrostで< 20–30重いフラグメントシェーダー → §2
tex_compressed_share / tex_mipmapped_shareシーンテクスチャで高い圧縮なし/ミップマップなしのテクスチャは帯域幅とキャッシュを浪費(シャドウマップとレンダーターゲットは決して圧縮されないので、どのテクスチャが支配的か確認)
late_zs_test_share< 10%discard/アルファテスト、またはシェーダー深度書き込み、アーリーZを無効化
early_zs_kill_rate、fpk_occluding_share高いほど良い不透明オブジェクトを前面から背面にソート;大きなサーフェスでのdiscardを避ける
bandwidth_mb_per_frame2018–2020年の端末で60fps時< ~30–40 MBレンダーターゲット、圧縮なしテクスチャ、MSAA解決 → 発熱
facing_culled_share閉じたメッシュで~40–50%両面マテリアルが頂点作業を倍増
fp16_varying_share高いmediump ベアリングが補間コストを半減

数式付きの完全なカウンターから修正へのリファレンスは、references/mali-counters.mdにあります。

フレームマーカー:Performance Advisorのフレーム別HTMLレポートには、Armのレイヤーからのフレーム境界が必要です。ArmはAndroid 11+をサポートしています。Android 10(Galaxy Note 9でテスト済み)ではカウンターは動作しますが、レイヤーのフレームがgatordに届かなかったため、スクリプトはキャプチャ中にSurfaceFlingerから測定したfpsで1秒あたりのカウンターにフォールバックします。

2. 高コストなシェーダーを見つける(任意のエンジン、Maliコストモデル)

# Godot(Compatibility/GLES3):ゲームが実際にコンパイルするGLSL ESを、デスクトップ上のMesa経由でダンプ
HEADLESS=1 $S/godot_dump_shaders.sh <godot_project> dump/ 20 [res://test_scene.tscn]
python3 $S/malioc_batch.py --core Mali-G72 dump/ --label-src <godot_project>/shaders --top 15
  • ランキングは、ピクセル(または頂点)あたりのサイクル数と、それを制限するパイプライン(A演算、LSロード/ストア、Vベアリング、Tテクスチャ)を示します。ラベルはあなたのシェーダーファイルを名前で示します;"engine"はビルトインマテリアルを意味します。
  • フラグ:occ50は32を超えるワークレジスタがあることを意味し、スレッドの半分しか実行中でない(レイテンシがより隠蔽されにくい);SPILLはスタックスピル;lateZSはdiscard;fp16:0%は16ビット演算がないことを意味します。
  • シェーダーのコスト ≈ サイクル数 × カバーするピクセル数。地面と建物をカバーする38サイクルのシェーダーは、小さな看板をカバーする60サイクルのシェーダーよりも重要です。
  • Unity、three.js、Bevyのシェーダー抽出:references/shader-cost.md。

ダンプスクリプトは、ユーザーデータの使い捨てコピーに対してゲームを実行するため、セーブデータや設定は変更されず、Godotのシェーダーキャッシュがコンパイルを隠しません。実行中に関心のあるエリアを訪れてください(またはテストシーンを渡してください)。Godotは遅延してシェーダーバリアントをコンパイルします。

3. Adreno(Qualcomm)

Snapdragon Profilerを使用:Realtimeでライブメトリック、Traceでタイムライン、Snapshotでドロー毎の統計を含む1フレーム。そのメトリックから同じ質問を読み取ります:% Shaders Busy、% Time Shading Fragments vs Vertices、Avg Bytes / Fragment、% Texture Fetch Stall、% Texture L1 Miss、ALU / Fragment、% Prims Trivially Rejected、Read/Write Total。メトリックから修正へのテーブルはreferences/adreno.mdにあります。

Android 11+デバイスでAGIがサポートする場合、Android GPU Inspectorはベンダーニュートラルなカウンターとフレームプロファイラを提供します。ツールなしで簡単な使用率を読み取るには、gpu_profile.py gpu-busy -s 30が、ビルドが許可する場合にカーネルのbusyノードを読み取ります。

4. カウンターから変更へ(そして検証)

  1. レポートが名前を挙げた最大の制限要因を修正します。一度に1つの変更を行います。

  2. 典型的なマッピング:

    制限修正
    フラグメントバウンド少ない/小さいシャドウマップと短いシャドウ距離、透明度のオーバードロー削減、大きなサーフェスでの安いシェーダー(演算を頂点シェーダーに移動、Low/Mediumでピクセル単位のノイズ/フォグ/スペキュラを削除、mediump)、圧縮+ミップマップテクスチャ、安全が証明された場所でのみ内部解像度を下げる(Mali-G72はレンダリングスケーリングでメモリリーク)
    ジオメトリ/タイラーバウンドLODと可視範囲、シャドウキャスターの削減、背面カリングの有効化、群衆のスキニング簡略化
    帯域幅/発熱圧縮テクスチャ、レンダーターゲット/パスの削減、ポストAAの代わりにMSAA、全画面ポストなし
    CPUバウンド(GPU使用率< 60%)ドローコール、スクリプト、アニメーション、物理(performance-optimization)
  3. 同じシーンを再キャプチャし、metrics.jsonの変更前後を比較します(フレームあたりのGPUミリ秒、制限要因の割合)。

  4. デバイス上でdevice_probe.pyを使って少なくとも60秒間確認します(fps、p95、メモリ傾き、温度)。端末を熱くしたりメモリリークを起こすカウンター上の勝利は勝利ではありません。

  5. 発見事項をプロジェクトノートに記録します(何が制限だったか、何が修正したか、変更前後の数値)。

実戦で得たルール(実際のキャプチャから)

  • GPUのテンプレートからカウンター設定を生成し、デフォルトではGPUカウンターのみにします。CPU PMUカウンターは、Samsung Android 10カーネルでキャプチャ子プロセスを起動時に終了させました。
  • Wi-Fi adbは動作しますが、デバイスIDはip:portです。それをすべての場所に渡します(スクリプトはそうします)。
  • クラッシュしたキャプチャは、アプリのサンドボックス内にgatordエージェントを生きたまま残すことがあります。それらは次のキャプチャのソケットをブロックし("Address already in use")、キャプチャを短く切ります。スクリプトはPIDでそれらを強制終了します(run-as <pkg> pkillは効きませんでした)。
  • キャプチャ直前にアプリを強制停止すると、1秒後にキャプチャが終了することがあります。スクリプトは状況が落ち着くのを待ちます。
  • Streamline-cli -generate-configは、-helpテキストに反して、ターゲットの前に-template <name>を必要とします。
  • GodotはGLESシェーダーキャッシュをuser://shader_cacheに保持するため、2回目のデスクトップ実行では何もコンパイルされません。新しいXDG_DATA_HOMEを使用します(ダンプスクリプトはそうします)。
  • 監査のためにデスクトップで実際のゲームを実行すると、オートセーブが書き込まれます。ユーザーデータディレクトリを分離します。

リファレンス

ファイルいつ読むか
references/arm-performance-studio.mdStreamline、Performance Advisor、Frame Advisor、RenderDoc for Arm、maliocのインストール/使用;ヘッドレスパイプラインの詳細
references/mali-counters.md各Maliメトリックの意味、数式、しきい値、Bifrost vs Valhall vs 第5世代
references/adreno.mdSnapdragon Profiler / AGIのセットアップとAdreno向けメトリック-修正テーブル
references/shader-cost.mdGodot/Unity/three.js/Bevyからコンパイル済みシェーダーを取得し、malioc出力を読む方法

関連スキル