xrt.ini ファイル - 2021.1 Japanese

Vitis 統合ソフトウェアプラットフォームの資料: アプリケーションアクセラレーション開発 (UG1393)

Document ID

UG1393

Release Date

2022-03-29

Version

2021.1 Japanese

ザイリンクスランタイム (XRT) ライブラリでは、デバッグ、プロファイリング、ホストアプリケーションおよびカーネルを実行する際に XRT で記録されるメッセージの記録などを制御するためのさまざまなパラメーターが使用されます。これらの制御パラメーターはランタイム初期化ファイル (xrt.ini) で指定され、XRT の起動時の機能を設定します。

コマンドラインを使用している場合は、xrt.ini ファイルを手動で作成し、ホスト実行ファイルと同じディレクトリに保存する必要があります。ランタイムライブラリで、xrt.ini がホスト実行ファイルと同じディレクトリにあるかどうかがチェックされ、起動時にこのファイルを読み込んでランタムが設定されます。

ヒント: Vitis IDE を使用している場合は、xrt.ini は設定に基づいて自動的に作成され、ホスト実行ファイルと同じディレクトリに保存されます。

ランタイム初期化ファイルのフォーマット

xrt.ini ファイルはテキスト形式のファイルで、キーのグループおよびその値が記述されています。セミコロン (;) またはシャープ記号 (#) で始まる行はコメント行です。グループ名、キー、キーの値では、大文字/小文字が区別されます。

次に、タイムライントレース機能をイネーブルにし、ランタイムログメッセージを xrt.ini ビューに表示するよう指定した Console ファイルの例を示します。

#Start of Debug group 
[Debug] 
opencl_trace = true

#Start of Runtime group 
[Runtime] 
runtime_log = console

初期化キーには、次の 3 つのグループがあります。

Runtime
Debug
Emulation

次の表に、サポートされる各グループのすべてのキー、各キーでサポートされる値、およびキーの簡単な説明を示します。

表 1. Runtime グループ
キー	有効な値	説明
`api_checks`	`[true\|false]`	OpenCL API チェックをイネーブルまたはディスエーブルにします。 `true`: イネーブル。これがデフォルト値です。 `false`: ディスエーブル。
`cpu_affinity`	`{N,N,...}`	すべてのランタイムスレッドを指定の CPU に固定します。例: `cpu_affinity = {4,5,6}`
`exclusive_cu_context`	`[true\|false]`	ホストアプリケーションが OpenCL に CU の内容のみ取得するよう命令できるようになるので、下位レベルの AXI 読み出し/書き込みを標準カーネルに使用できるようになります。
`runtime_log`	`[null \| console \| syslog \| <filename>]`	ランタイムのログを出力する場所を指定します。 `null`: ログを出力しない。これがデフォルト値です。 `console`: ログを `stdout` に出力。 `syslog`: ログを Linux システムログに出力。 `<filename>`: ログを指定ファイルに出力。たとえば、runtime_log=my_run.log のように指定します。
`verbosity`	`[0 \| 1 \| 2 \| 3]`	詳細なログメッセージを生成します。デフォルト値は 0 です。

表 2. Debug グループ
キー	有効な値	説明
`aie_profile`	`[true\|false]`	AI エンジンハードウェアパフォーマンスカウンターの実行時設定およびポーリングをイネーブルにします。VCK190 ハードウェア実行でのみ使用できます。 `true`: イネーブル。 `false`: ディスエーブル。これがデフォルト値です。
`aie_profile_core_metrics`	`[heat_map\|stalls\|execution]`	AI エンジンコアパフォーマンスカウンターから読み取られる統計情報の設定を制御します。デフォルトはオフ`heat_map`です。注記: このオプションは、`aie_profile = true` の場合にのみ有効です。
`aie_profile_interval_us`	`<int>`	AI エンジンカウンター値の読み出し間隔をマイクロ秒 (µ s) 単位で制御します。デフォルトの間隔は 1000 µs です。注記: このオプションは、`aie_profile = true` の場合にのみ有効です。
`aie_profile_memory_metrics`	`[dma_locks\|conflicts]`	AI エンジンのメモリパフォーマンスカウンターから読み取られる統計情報の設定を制御します。デフォルトはオフ`dma_locks`です。注記: このオプションは、`aie_profile = true` の場合にのみ有効です。
`aie_trace`	`[true\|false]`	AI エンジンのランタイム設定およびイベントトレースの収集をイネーブルにします。VCK190 ハードウェア実行でのみ使用できます。 `true`: イネーブル。 `false`: ディスエーブル。これがデフォルト値です。
`aie_trace_buffer_size`	`<string>`	AI エンジンイベントトレースに割り当てられたバッファーの合計サイズを制御します。このサイズは、AI エンジンから送信されるさまざまなトレースストリームの数に均等に分割されます。デフォルトは 8M です。注記: このオプションは、`aie_trace = true` の場合にのみ有効です。
`aie_trace_metrics`	`[functions\|functions_partial_stalls\| function_all_stalls\|all]`	指定したレベルのイベントトレースを生成するための AI エンジンレジスタの設定を制御します。注記: このオプションは、`aie_trace = true` の場合にのみ有効です。
`app_debug`	`[true\|false]`	OpenCL アプリケーションのデバッグをイネーブルにします。 `true`: イネーブル。 `false`: ディスエーブル。これがデフォルト値です。
`continuous_trace`	`[true\|false]`	トレース用のファイルの連続ダンプとホストへのデバイスデータの連続読み出しをイネーブルにします。 `true`: イネーブル。 `false`: ディスエーブル。これがデフォルト値です。注記: このオプションは、`data_transfer_trace = off` の場合にのみ有効です。
`data_transfer_trace`	`[off\|fine\|coarse\|accel]`	PL に挿入されたモニターからのデータの収集をイネーブルにして、サマリおよびトレースに追加します。 `accel`: 計算ユニットの開始/停止をトレースします。 `coarse`: 計算ユニットの実行ごとに、すべての読み出し/書き込みをまとめます。 `fine`: すべてを追跡します。 `off`: 実行中のデバイスレベルのトレースの読み出しおよびレポートをオフにします。これがデフォルト値です。
`debug`	`[true\|false]`	ソフトウェアエミュレーションのカーネルデバッグ機能をイネーブルにします。 `true`: イネーブル。 `false`: ディスエーブル。これがデフォルト値です。
`lop_trace`	`[true\|false]`	オーバーヘッドの少ない OpenCL API ホストトレースの生成をイネーブルにします。ほかの OpenCL オプションと組み合わせて使用しないでください。 `true`: イネーブル。 `false`: ディスエーブル。これがデフォルト値です。
`native_xrt_trace`	`[true\|false]`	ネイティブ C/C++ API トレースの生成をイネーブルにします。 `true`: イネーブル。 `false`: ディスエーブル。これがデフォルト値です。
`opencl_device_counter`	`[true\|false]`	生成された OpenCL サマリファイルにハードウェアカウンター情報を追加します。`data_transfer_trace` を指定した場合は必要ありません。 `true`: イネーブル。 `false`: ディスエーブル。これがデフォルト値です。
`opencl_summary`	`[true\|false]`	OpenCL API サマリレポートの生成をイネーブルにします。指定したフラグがこれだけの場合は、ホスト情報のみが含まれます。 `true`: イネーブル。 `false`: ディスエーブル。これがデフォルト値です。
`opencl_trace`	`[true\|false]`	OpenCL API ホストトレースの生成をイネーブルにします。 `true`: イネーブル。 `false`: ディスエーブル。これがデフォルト値です。
`power_profile`	`[true\|false]`	アプリケーションの実行中に消費電力データのポーリングをイネーブルにします。 `true`: イネーブル。 `false`: ディスエーブル。これがデフォルト値です。
`power_profile_interval_ms`	`<int>`	消費電力カウンターの読み出し間隔をミリ秒単位で制御します。デフォルトの間隔は 20 ms です。注記: このオプションは、`power_profile = true` の場合にのみ有効です。
`stall_trace`	`[on\|off]`	計算ユニットのストールのハードウェア生成をイネーブルにします。デフォルトはオフ`off`です。注記: このオプションは、`data_transfer_trace = off` の場合にのみ有効です。
`trace_buffer_offload_interval_ms`	`<int>`	デバイスからホストへのデバイスデータの読み出しをミリ秒 (ms) 単位で制御します。デフォルトは 10 ms です。注記: このオプションは、`data_transfer_trace = off` の場合にのみ有効です。
`trace_buffer_size`	`<string>`	トレースのメモリオフロードを指定して .xclbin が作成された場合、このオプションでトレース用にメモリに割り当てるバッファーのサイズが決定されます。デフォルトは 1M です。注記: このオプションは、`data_transfer_trace = off` の場合にのみ有効です。
`trace_file_dump_interval_s`	`<int>`	トレースファイルのダンプ間隔を秒 (s) 単位で制御します。デフォルトは 5s です。注記: このオプションは、`data_transfer_trace = off` の場合にのみ有効です。
`vitis_ai_profile`	`[true\|false]`	プロファイルサマリおよびその他のファイルは、Vitis AI アプリケーション層から取得されます。 `true`: イネーブル。 `false`: ディスエーブル。これがデフォルト値です。

表 3. Emulation グループ
キー	有効な値	説明
`aliveness_message_interval`	整数	メッセージを出力する時間間隔を秒で指定します。デフォルトは 300 です。
`debug_mode`	`[off\|batch\|gui]`	エミュレーション中の波形の保存および表示方法を指定します。 `off`: シミュレータの波形 GUI を起動せず、wdb ファイルを保存しません。これがデフォルト値です。 `batch`: シミュレータの波形 GUI は起動せず、wdb ファイルを保存します。 `gui`: シミュレータの波形 GUI を起動し、wdb ファイルを保存します。注記: 波形を保存してシミュレータの GUI に表示するには、カーネルをデバッグをイネーブル (`v++ -g`) にしてコンパイルする必要があります。
`print_infos_in_console`	`[true\|false]`	ユーザーコンソールへのエミュレーション情報メッセージの表示を制御します。エミュレーション情報メッセージは、emulation_debug.log というファイルに保存されます。 `true`: ユーザーコンソールに表示します。これがデフォルト値です。 `false`: ユーザーコンソールに出力しません。
`print_warnings_in_console`	`[true\|false]`	ユーザーコンソールへのエミュレーション警告メッセージの表示を制御します。エミュレーション警告メッセージは、emulation_debug.log というファイルに保存されます。 `true`: ユーザーコンソールに表示します。これがデフォルト値です。 `false`: ユーザーコンソールに出力しません。
`print_errors_in_console`	`[true\|false]`	ユーザーコンソールへのエミュレーションエラーメッセージの表示を制御します。エミュレーションエラーメッセージは、emulation_debug.log ファイルに保存されます。 `true`: ユーザーコンソールに表示します。これがデフォルト値です。 `false`: ユーザーコンソールに表示しません。
`user_pre_sim_script`	Tcl ファイルへのパス	1 回目の run では、シミュレーションを GUI モードで実行します。信号を追加し、Tcl コンソールからコマンドをコピーして Tcl スクリプトに保存します。次の run では、バッチモードで Tcl スクリプトを渡します。
`user_post_sim_script`	Tcl ファイルへのパス	シミュレーション後の操作は Tcl ファイルで指定しておいて、このオプションでファイルを指定します。Tcl で指定するコマンドはすべてシミュレーションの終了後に実行されます。
`xtlm_aximm_log`	`[true\|false]`	ランタイム時の XTLM AXI4 メモリマップのトランザクションログをイネーブルにすると、すべてのトランザクションが xsc_report.log ファイルで確認できるようになります。
`xtlm_axis_log`	`[true\|false]`	ランタイムジの XTLM AXI4-Stream トランザクションログをイネーブルにすると、すべてのトランザクションが xsc_report.log ファイルで確認できるようになります。
`timeout_scale`	`na/ms/sec/min`	エミュレーションでの `clPollStream` API のタイムアウトをサポートするためのもので、`clPollStream` API で指定されたタイムアウトの単位を提供します。コードで指定されたタイムアウトの単位は ms なので、エミュレーションには使用できないことがあります。このため、エミュレーションで必要な場合は、`timeout_scale` で ms を別の単位に変更しておきます。重要: エミュレーションでは、タイムアウトはデフォルトではイネーブルになっていません。このオプションを使用するには、`clPollStream` タイムアウトをイネーブルにしておく必要があります。