連続トレースの取り込み - 2023.2 日本語

Vitis ツールでは、アプリケーション実行中に連続するトレース データを記録できます。アプリケーションは非常に長い時間実行できるので、かなりの量のトレース データが取り込まれることになり、トレース データに使用するメモリ リソースが十分ない場合は特に、トレース データが不完全になるような問題が発生する可能性があります。連続トレースを使用すると、アプリケーションの実行中、または完了前にアプリケーションがクラッシュした場合に、トレースの解析を実行できます。

トレース データを連続して取り込めるので、アプリケーションの実行中に、[Timeline Trace] レポートを Vitis アナライザー ツールでダイナミックに更新できます。これらのレポートが Vitis アナライザーに読み込まれると、ディスク上で現在のレポートが変更されていることを示すハイパーリンクが表示されます。新しいデータを読み込む必要がある場合や、アプリケーションの実行時に更新されたレポートを表示してトレース データを生成する Reload や Auto-Reload オプションがバナーに表示されます。

連続トレースは、デフォルトではイネーブルにはなっていません。また、FPGA のメモリ リソースは無制限にはありません。このため、アプリケーションが大きなトレース データを生成する場合は、データを格納するための循環バッファーを使用できます。循環バッファーでは、書き込み、ホストへのオフロード、再利用が可能です。連続トレースで循環バッファーをイネーブルにすると、必要なメモリ リソースがさらに少なくなるので、デバイス上の使用可能なリソースを節約できます。ただし、連続トレース/循環バッファーを使用してアプリケーションを実行すると、複数のデバイス トレース ファイルが生成されることがあります。

ここでは、メモリ リソースを循環バッファーとして使用することを推奨する例をいくつか示します。

xrt.ini で連続トレースがイネーブルになると、循環バッファーのインプリメンテーションが自動的にオンになります。連続トレースをイネーブルにするには、フローに次の設定が必要です。

• xrt.ini ファイルでは continuous_trace は TRUE に設定します。
• v++ リンク オプションの --profile.trace_memory は DDR または HBM に設定します。

オプションで次を設定できます。

• xrt.ini ファイルで trace_buffer_size を使用したトレース バッファーのサイズ。デフォルトは 1 MB です。
• xrt.ini ファイルで trace_buffer_offload_interval_ms を使用してデバイスからトレース バッファーがオフロードされる間隔。デフォルトは 10 ms です。
• trace_file_dump_interval_s 設定でファイルがダンプされる間隔。デフォルトは 3 秒です。

[XRT] WARNING: Unable to use circular buffer for continuous trace offload. Please increase trace buffer size and/or reduce continuous
trace interval. Minimum required offload rate (bytes per second) : 104857600 Requested offload rate : 819200

[Debug]
opencl_trace=true
device_trace=fine
stall_trace=all
continuous_trace=true
// The following are optional and needed only in rare circumstances

trace_buffer_size=20M
trace_buffer_offload_interval_ms=10
trace_file_dump_interval_s=2

次は、これらの設定の結果です。

• opencl_trace: ホスト関連の OpenCL API トレースの生成をイネーブルにします。opencl_trace.csv ファイルが作成されます。
• device_trace: プロファイル サマリとトレースに追加されるカーネル アクティビティのコレクションをイネーブルにします。device_trace_0.csv ファイルがデバイス番号 0 で作成されます。
• stall_trace: 計算ユニットへのストールのハードウェア生成をイネーブルにします。
• continuous_trace: トレース用のファイルの連続ダンプとホストへのデバイス データの連続読み出しをイネーブルにします。
• trace_buffer_size: トレース データ キャプチャに使用するメモリ容量を指定します。
• trace_buffer_offload_interval_ms: デバイスからホストへのデバイス データの読み出しをミリ秒単位で制御します。
• trace_file_dump_interval_s: トレース ファイルのダンプ間隔を秒単位で制御します。

この結果、上記の xrt.ini ファイルを使用したアプリケーション実行で、xrt.run_summary だけでなく、複数の CSV ファイルが生成されます。Vitis アナライザーは生成された run_summary ファイルのみを必要とし、関連する CSV ファイルを使用してプロファイル サマリとタイムライン トレースを表示します。

次は、トレース データ ダンプ用にアプリケーションを設定する際の推奨事項です。

1. デフォルトでは、トレース キャプチャに使用されるメモリは、プラットフォーム上の最初のメモリ リソースで、platforminfo ユーティリティ を使用すると決定できます。ほとんどのプラットフォームでは、これは DDR または HBM のいずれかです。トレース データ用に予約されているメモリ容量は、xrt.ini ファイル内の trace_buffer_size オプションで決まります。デフォルトは 1 MB です。
   注記: --profile.trace_memory オプションを使用すると、FIFO の使用と割り当てサイズを指定することもできます。
2. それでも最大トレースをダンプできない場合は、data_transfer_trace=coarse に stall_trace=off または stall_trace=on を使用してストール トレースをディスエーブルにします。
3. アプリケーションでトレース バッファーのサイズを大きくする必要がある場合は、trace_buffer_offload_interval_ms=10 および trace_file_dump_interval_s=5 をデフォルト設定にして continuous_trace=true を設定し、循環バッファーをイネーブルにします。理想的には、次の場合に連続トレース機能を使用する必要があります。
   • 最小限のトレースしか生成されない長時間実行デザイン
   • .csv デバッグ用のファイルが残っていると、デバッグ アプリケーションがクラッシュします。
4. それでもアプリケーション実行で最大トレースをダンプできない場合は、trace_buffer_size をさらに増加します。
5. アプリケーションでホストが維持できないほどの大量のトレース データがまだ作成される場合は、より小さいサイズの trace_file_dump_interval を使用します。これにより、指定された間隔と同じ間隔で複数のファイルが作成されます。
6. 連続トレースでは、xrt.run_summary ファイルだけでなく、アプリケーション実行で複数のトレース ファイルが生成されます。Vitis アナライザーは生成された run_summary ファイルのみを必要とし、生成された関連する CSV ファイルを使用して、プロファイル サマリとタイムライン トレースを表示し、より良い経験を提供します。