xrt.ini ファイル - 2020.1 Japanese

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

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

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

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

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

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

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

#Start of Debug group 
[Debug] 
timeline_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}
ert_polling [true|false] アクセラレーション プラットフォームで実行される計算ユニット (CU) を妨害するメカニズムとしてポーリングを使用するように指定します。デフォルト値は false で、ポーリングではなく、プラットフォームに既存の割り込み信号が使用されます。
exclusive_cu_context [true|false] ホスト アプリケーションが OpenCL に CU の内容のみ取得するよう命令できるようになるので、下位レベルの AXI 読み出し/書き込みを標準カーネルおよびフリーランニング カーネルに使用できるようになります。
polling_throttle <value> ert_polling がイネーブルの場合に、ランタイム ライブラリがデバイス ステータスをポーリングする時間間隔をマイクロ秒で指定します。デフォルト値は 0 です。
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 グループ
キー 有効な値 説明
app_debug [true|false] GDB を使用したデバッグで xprint および xstatus コマンドをイネーブルにします。
  • true: イネーブル。
  • false: ディスエーブル。これがデフォルト値です。
continuous_trace [on|off] アプリケーション実行中にデバイスのトレース データを続けてオフロードできます。トレース ファイルがディスクに続けて書き込まれるので、クラッシュがあったときに、アプリケーションのデバッグに使用可能なトレース データもあります。
注記: これは、Vitis コンパイラの一般オプション で説明される --trace_memory オプションで指定されたメモリ タイプに書き込まれます。これにより結果が改善されるのは、トレース メモリが FIFO に指定されない場合です。
continuous_trace_interval_ms <int> トレース バッファーを読み出す間隔をミリ秒で指定します。この機能は、トレース データが FIFO に取り込まれる際に、ディスクへのデータのダンプ レートを増やして、バッファーのオーバーフローやデータ損失が発生しないようにする場合に使用すると便利です。デフォルトの間隔は 1 ms です。
data_transfer_trace=<arg> [coarse|fine|off] デバイス レベルの AXI 転送トレースをイネーブルにします。
  • coarse: CU の転送アクティビティを最初の転送の初めから最後の転送の終わり (計算ユニットの転送終了前) まで表示します。
  • fine: すべての AXI レベルのバースト データ転送を表示します。
  • off: ランタイム中のデバイス レベルのトレースの読み出しおよびレポートをオフにします。これがデフォルト値です。
device_profile [true|false] デバイス プロファイリングをイネーブルまたはディスエーブルにします。
  • true: イネーブル。
  • false: ディスエーブル。これがデフォルト値です。
lop_trace [true|false] オーバーヘッドの少ないプロファイリングをイネーブルまたはディスエーブルにします。ホスト側のデータのみを含む省略された timeline_trace が生成されるので、デバイス側のプロファイリングのオーバーヘッドがなくなり、パフォーマンスへの影響がかなり減ります。
  • true: イネーブル。
  • false: ディスエーブル。これがデフォルト値です。
注記: lop_trace=trueprofile=true の場合に指定しても、オーバヘッドの少ないプロファイリングは実行されません。また、lop_trace を使用する際には、Vitis コンパイラの一般オプション に説明するような --profile_kernel オプションを使用してコンパイルまたはリンクする必要はありません。
power_profile [true|false] デバイスの消費電力プロファイリングをイネーブルまたはディスエーブルにします。
  • true: イネーブル。
  • false: ディスエーブル。これがデフォルト値です。

イネーブルの場合、アプリケーションのランタイム中にアクセラレータ カードから消費電力データが取り込まれます。消費電力プロファイルでは、カードの各レールの平均、最小、最大消費電力がレポートされます。記録されたデータは、Vitis アナライザーで表示できます。

profile [true|false] OpenCL コードのプロファイリングをイネーブルまたはディスエーブルにします。
  • true: イネーブル。
  • false: ディスエーブル。これがデフォルト値です。

このオプションを true にすると、基本プロファイル モニタリングがイネーブルになります。追加のオプションを指定しない場合、これによりホスト ランタイムのログ プロファイル サマリがイネーブルになります。false にすると、プロファイル モニタリングは実行されません。

stall_trace=<arg> [dataflow|memory|pipe|all|off] タイムライン トレースで収集してレポートするストールのタイプを指定します。デフォルトは off です。
注記: ストール トレースをイネーブルにすると、トレース バッファーがフルになることが多くなり、タイムライン トレースが完了せずに破損する可能性があります。これを回避するには、stall_trace=off を設定します。
  • off: ストール トレース情報の収集をオフにします。
  • all: すべてのストール トレース情報を記録します。
  • dataflow: カーネル ストリーム間 (例: データフロー ブロック間のフル FIFO への書き込み)。
  • memory: 外部メモリ ストール (例: DDR からの AXI4 読み出し)。
  • pipe: OpenCL カーネルのカーネル間パイプ (例: カーネル間のフル パイプへの書き込み)。
timeline_trace [true|false] プロファイル タイムライン トレースをイネーブルまたはディスエーブルにします。
  • true: イネーブル。
  • false: ディスエーブル。これがデフォルト値です。

このオプションは、タイムライン トレースのデータ収集をイネーブルにしますが、カーネルにアクセラレーション モニターおよび AXI パフォーマンス モニター IP を追加しない場合は、タイムラインにホスト情報のみが表示されます。計算ユニットの開始および終了時間をタイムラインに表示するには、最低でも CU を --profile_kernel exec を使用してビルトする必要があります (Vitis コンパイラ コマンド を参照)。

trace_buffer_size <value{K|M|G}> トレース データの収集に割り当てるメモリのサイズを指定します。十分なトレース データを収集できるように設定します。割り当てるメモリの量 (64K、200M、1G など) を指定します。
注記: このバッファー サイズは、Vitis コンパイラの一般オプション に説明するように、--trace_memory オプションと関連します。
表 3. Emulation グループ
キー 有効な値 説明
aliveness_message_interval 整数 メッセージを出力する時間間隔を秒で指定します。デフォルトは 300 です。
debug_mode [off|batch|gui|gdb] エミュレーション中の波形の保存および表示方法を指定します。
  • off: シミュレータの波形 GUI を起動せず、wdb ファイルを保存しません。これがデフォルト値です。
  • batch: シミュレータの波形 GUI は起動せず、wdb ファイルを保存します。
  • gui: シミュレータの波形 GUI を起動し、wdb ファイルを保存します。
  • gdb: gdb を使用してカーネルをデバッグするため、シミュレータを gdb モードで起動します。このモードでは波形がサポートされないので、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 タイムアウトをイネーブルにしておく必要があります。