AI エンジングラフアプリケーションのシミュレーション

この章では、AI エンジンアプリケーションをさまざまな抽象度、精度、速度でシミュレーションできる各種実行ターゲットについて説明します。SystemC シミュレーション (AI エンジン System C シミュレータ参照) では、AI エンジンアレイのタイミングとリソースは正確にモデル化されますが、NoC、DDR、PL、および PS に関してはトランザクションレベルの AT (Approximately Timed) SystemC モデルが使用されます。これにより、AI エンジンアプリケーションの性能解析を適度な時間と精度で実行できます。

最も高速なのは、x86 論理シミュレータ (x86simulator) で説明する x86 論理シミュレータ (x86simulator) ですが、タイミング、リソース、性能の情報は得られません。このシミュレーションはアプリケーションの機能をテストするためのもので、デザインの開発初期のイテレーションで使用します。

Vitis ツールフローを使用したアプリケーションの統合および Vitis IDE の使用に示すように、GUI 環境から Vitis™ コンパイラでシステムレベルプロジェクトをビルドし、シミュレータを実行します。また、コマンドラインまたはスクリプトでオプションを指定して実行することもできます。

AI エンジン System C シミュレータ

Versal™ ACAP AI エンジン System C シミュレータ (aiesimulator) には、AI エンジンアレイに加え、グローバルメモリ (DDR メモリ) およびネットワークオンチップ (NoC) のモデリングが含まれています。System C シミュレーションターゲットを使用してアプリケーションをコンパイルすると、AI エンジン System C シミュレータを次のように起動できます。

aiesimulator –-pkg-dir=./Work

重要: AI エンジンシミュレータを使用するには、Vitis ツール環境の設定に説明されている設定が必要です。

AI エンジンコンパイラにより、さまざまなコンフィギュレーションファイルとバイナリファイルが --pkg-dir オプションを使用して指定した Work ディレクトリ (AI エンジングラフアプリケーションのコンパイルを参照) に生成されます。グラフは、main アプリケーションとして記述された制御スレッドにより初期化、実行、および終了されます。AI エンジンコンパイラは、PS IP ラッパーが直接シミュレータに読み込まれるように制御スレッドをコンパイルします。

デフォルトでは、graph.run() オプションによりグラフが無限に実行されるよう指定されます。AI エンジンコンパイラでは、データフローグラフを永続的な While ループで実行するコードが生成されるため、シミュレーションも永続的に実行されます。デバッグ用に終了するプログラムを作成するには、グラフコードで graph.run(<number_of_iterations>) を使用して反復回数を指定します。反復回数は、正の整数で指定します。

AI エンジンシミュレータコマンドは、まずコンパイラで生成された Work/config/scsim_config.json ファイルで指定されているようにシミュレータを設定します。これには、PL IP ブロックとその接続の読み込み、I/O データファイルドライバーの設定、および NoC とグローバルメモリ (DDR メモリ) 接続の設定が含まれます。その後、指定の PS アプリケーションを実行し、シミュレータを終了します。

AI エンジンシミュレータには、カーネルコードの printfs をイネーブルにしてコンソールに表示されるようにし、プロファイル情報を生成する --profile オプションがあります。また、--dump-vcd <filename> オプションを使用すると、シミュレーション中に VCD (Value Change Dump) が生成されます。指定のクロックサイクル数後にシミュレーションを終了するには、--simulation-cycle-timeout <number-of-cycles> を使用できます。

重要: クロックサイクル数または graph.run() を使用して実行回数を指定しない場合、シミュレーションは無限に実行されます。シミュレーションをしゅうりょうするには、Ctrl+c キーを 2 回押します。

ヒント: 同じデザインでシミュレーション実行間のサイクル数に違いがあることがわかります。これは、シミュレータがすべての未処理のトランザクション (DMA など) が完了するのを数秒待つからです。この待機時間中に、シミュレータプロセスの時間は経過しますが、OS によりコンテキストスイッチされることがあるので、各実行の合計サイクル数は異なります。各実行の合計サイクル数が同じになるようにするには、AI エンジンシミュレータの --simulation-cycle-timeout オプションを使用してシミュレータを停止するサイクルを指定します。これにより、プロファイルレポートに表示される各実行の合計サイクル数が同じになります。

シミュレータのオプション

このセクションでは、AI エンジンシミュレータ (aiesimulator) のすべてのオプションについて説明します。オプションは、ほとんどの場合 pkg-dir を指定するだけで十分です。

表 1. AI エンジンシミュレータのオプション
オプション	説明
-h, --help	このヘルプメッセージを表示して終了します。
--dump-vcd FILE	VCD 波形情報を `FILE` にダンプします。指定したファイル名には自動で .vcd が追加されるため、ファイル拡張子を含めて指定する必要はありません。
--gm-init-file <file>	指定したファイルからグローバルメモリイメージを読み出します。メモリ初期化ファイル (グローバルメモリのシミュレーション参照) がロードされます。
--pkg-dir <PKG_DIR>	パッケージディレクトリを指定します (例: ./Work)。
--profile	シミュレーション中に `printf` トレースメッセージを `stdout` に生成し、プロファイリング統計を収集します。このオプションを指定すると、シミュレータの動作速度がやや低下することがあります。
--simulation-cycle-timeout CYCLES	アプリケーションをロードした後、実行するサイクル数を指定します。ヒント: `--simulation-cycle-timeout` オプションは、指定したタイムアウトサイクル数の後にシミュレーションセッションを終了させる場合に使用します。ただし、デバッグプロセス中にシミュレーションタイムアウトを指定すると、タイムアウトサイクル数に達するとデバッグが終了してしますため、サイクル数には大きな値を指定してください。
--online [-ctf] [-wdb]	`vcdanalyze` を呼び出して VCD データをオンザフライで解析し、オプションで CTF (Common Trace Format) または WDB (Waveform Database) ファイルを出力します。ヒント: `--online` オプションと `--dump-vcd` オプションは同時には指定できません。両方のオプションを指定した場合、`--online` オプションのみが適用されます。
--enable-memory-check	実行時にプログラムメモリとデータメモリの境界アクセスチェックを有効にします。アクセス違反が発生した場合は、[ERROR] メッセージとして報告されます。デフォルトでは、このオプションは無効です。

シミュレーション入力および出力データストリーム

入力/出力ストリームのデフォルトのビット幅は 32 ビットです。このビット幅は、シミュレーション入力ファイルの 1 行あたりのサンプル数を指定します。入力ファイルの各行のサンプルは、期待されるデータ型と PLIO データ幅に基づいて解釈されます。次の表に、各種データ型および対応する PLIO インターフェイス仕様において入力データファイルのサンプルがどのように解釈されるかを示します。

表 2. 各種データ型および PLIO 幅におけるシミュレーション入力データの解釈
データ型	PLIO 32 ビット	PLIO 64 ビット	PLIO 128 ビット
データ型	`PLIO *in0 = new PLIO("DataIn1", adf::plio_32_bits)`	`PLIO *in0 = new PLIO("DataIn1", adf::plio_64_bits)`	`PLIO *in0 = new PLIO("DataIn1", adf::plio_128_bits)`
int8	//1 行につき 4 個の値 6 8 3 2	//1 行につき 8 個の値 6 8 3 2 6 8 3 2	//1 行につき 16 個の値 6 8 3 2 6 8 3 2 6 8 3 2 6 8 3 2
int16	//1 行につき 2 個の値 24 18	//1 行につき 4 個の値 24 18 24 18	//1 行につき 8 個の値 24 18 24 18 24 18 24 18
int32	//1 行につき 1 個の値 2386	//1 行につき 2 個の値 2386 2386	//1 行につき 4 個の値 2386 2386 2386 2386
int64	N/A	45678	//1 行につき 2 個の値 45678 95578
cint16	//1 行につき 1 個の cint 値 (実数、虚数) 1980 485	//1 行につき 2 個の cint 値 1980 45 180 85	//1 行につき 4 個の cint 値 1980 485 180 85 980 48 190 45
cint32	N/A	//1 行につき 1 個の cint 値 (実数、虚数) 1980 485	//1 行につき 2 個の cint 値 1980 45 180 85
float	//1 行につき 1 個の浮動小数点値 893.5689	//1 行につき 2 個の浮動小数点値 893.5689 3459.3452	//1 行につき 4 個の浮動小数点値 893.5689 39.32 459.352 349.345
cfloat	N/A	//1 行につき 1 個の浮動小数点 cfloat 値 (実数、虚数) 893.5689 24156.456	//1 行につき 2 個の浮動小数点 cfloat 値 (実数、虚数) 893.5689 24156.456 93.689 256.46

グローバルメモリのシミュレーション

アプリケーションが GMIO 仕様 (GMIO 属性を参照) を使用してグローバルメモリにアクセスする場合、シミュレーションで DDR メモリと DDR メモリを PL および AI エンジンに接続する配線ネットワークをモデル化する必要があります。AI エンジンから DDR メモリへの接続は、DMA データムーバーにより制御されます。DMA データムーバーは AI エンジンアレイインターフェイスに組み込まれており、PS プログラムの GMIO API で制御されます。PL ブロックの AXI4-Stream ポートから DDR メモリへの接続は、ソフト GMIO データムーバーブロックにより制御されます。このブロックは、シミュレーション用に AI エンジンコンパイラにより自動的に生成されます。データムーバーは、PL ブロックからのストリーミングインターフェイスを、GMIO 属性に示す特定の開始アドレス、ブロックサイズ、バーストサイズを持つ NoC 上のメモリマップド AXI4 インターフェイストランザクションに変換します。

グローバルメモリを使用するシミュレーション中、DDR メモリを定義済みのデータで初期化するメモリデータファイルを --gm-init-file オプションを使用して指定できます。テキスト形式のこのファイルは、指定のアドレスから開始する DDR メモリのバイトダンプです。このファイルのフォーマットは、次のとおりです。

<startaddr>:
<byte>
<byte>
…

AI エンジンシミュレータを起動する際にグローバルメモリを初期化するには、次のコマンドを使用します。

aiesimulator –-pkg-dir=./Work -–gm-init-file=dump.txt

シミュレータは、使用された DDR メモリの出力バイトダンプもシミュレーション出力ディレクトリ (デフォルトでは aiesimulator_output) に生成します。出力ファイルはベースアドレス 0x0 から開始し、名前は DDR メモリバンク内の場所に基づいて付けられます (例: DDRMC_SITE_X1Y0.mem)。このファイルを使用してグローバルメモリトランザクションを確認できます。

ハードウェアエミュレーションのシミュレータオプション

AI エンジンシミュレータは、AI エンジングラフアプリケーションのシミュレーションに使用されるオプションをリストするオプションファイルを生成します。このオプションファイルは、AI エンジンシミュレータを実行すると自動的に生成されます。これにより、初期のグラフレベルのシミュレーションからシステムレベルのエミュレーションまで、AI エンジンシミュレータオプションを再利用できます。必要に応じてオプションファイルを手動で編集し、ほかのオプションを指定することもできます。次の表に、aiesimulator_output ディレクトリにある aiesim_options.txt ファイルで指定可能なオプションを示します。このオプションは、aiesimulator コマンドで --dump-vcd オプションを使用した場合にのみ作成されます。このファイルは、システムの実行に説明されているように、launch_hw_emu.sh スクリプトを使用してエミュレーターを起動するときにコマンドラインオプションの一部として指定できます。次にコマンド例を示します。

./launch_hw_emu.sh \
-add-env VITIS_LAUNCH_WAVEFORM_BATCH=1 \
-add-env AIE_COMPILER_WORKDIR=${FULL_PATH}/Work \
-aie-sim-options ${FULL_PATH}/aiesimulator_output/aiesim_options.txt

${FULL_PATH}: ファイルまたはディレクトリへの絶対パスを指定します。

Vivado ロジックシミュレータ GUI を使用してエミュレーションを起動せずに波形データをログに記録するためのアドバンスオプションも追加できます。次にコマンド例を示します。

./launch_hw_emu.sh \
-user-pre-sim-script pre-sim.tcl

pre-sim.tcl には、波形を追加したり、デザイン波形をログに記録する Tcl コマンドが含まれます。例は『Vitis 統合ソフトウェアプラットフォームの資料: アプリケーションアクセラレーション開発』 (UG1393)、Tcl コマンドは『Vivado Design Suite ユーザーガイド: ロジックシミュレーション』 (UG900: 英語版、日本語版) を参照してください。

表 3. ハードウェアエミュレーションオプション
コマンド	引数	説明
`AIE_DUMP_VCD`	<filename>	`AIE_DUMP_VCD` を指定すると、シミュレーションで VCD データが生成され、指定した <filename>.vcd に保存されます。

サードパーティシミュレータの有効化

デザインのハードウェアエミュレーションは、Questa Advanced Simulator や Xcelium などのサードパーティシミュレータでも実行できます。これらのシミュレータを有効にするには、Vitis コンフィギュレーションファイル (config.ini または system.cfg) を変更します。

シミュレータ v++ --link の設定

Questa

表 4. Vitis のリンク設定
シミュレータ	`v++ --link` の設定
Questa	`EXPORT simulator=questa` `[advanced] param=hw_emu.simulator=QUESTA [vivado] prop=project.__CURRENT__.compxlib.questa_compiled_library_dir=/path/to/questa/2020.2/lin64/lib/`
Xcelium	`EXPORT simulator=xcelium` `[advanced] param=hw_emu.simulator=XCELIUM [vivado] prop=project.__CURRENT__.simulator.xcelium_install_dir=/path/to/xcelium/bin/ prop=project.__CURRENT__.compxlib.xcelium_compiled_library_dir=/path/to/xcelium/20.03.005/lin64/lib/ prop=fileset.sim_1.xcelium.simulate.runtime=1000us prop=fileset.sim_1.xcelium.elaborate.xmelab.more_options={-timescale 1ns/1ps}`

EXPORT
										simulator=questa

[advanced]
param=hw_emu.simulator=QUESTA
[vivado]
prop=project.__CURRENT__.compxlib.questa_compiled_library_dir=/path/to/questa/2020.2/lin64/lib/

Xcelium

EXPORT
										simulator=xcelium

[advanced]
param=hw_emu.simulator=XCELIUM
[vivado]
prop=project.__CURRENT__.simulator.xcelium_install_dir=/path/to/xcelium/bin/
prop=project.__CURRENT__.compxlib.xcelium_compiled_library_dir=/path/to/xcelium/20.03.005/lin64/lib/
prop=fileset.sim_1.xcelium.simulate.runtime=1000us
prop=fileset.sim_1.xcelium.elaborate.xmelab.more_options={-timescale 1ns/1ps}

上記の変更を加えたら、通常の方法でデザインをビルドした後、スクリプト launch_hw_emu.sh を実行すると新しいシミュレータが使用されます。エミュレーションの詳細は、システムの実行を参照してください。

x86 論理シミュレータ (x86simulator)

注記: x86 シミュレータは、暫定的な機能であり、今後のリリースで改善する予定です。

x86 シミュレーションターゲットを使用してアプリケーションをコンパイルすると、x86 シミュレータを起動できます。
```
x86simulator –-pkg-dir=./Work –-input-dir=<dir> --output-dir=<dir>
```
AI エンジンコンパイラにより x86 ネイティブシミュレーション用にコンパイルされたバイナリが Work ディレクトリ (AI エンジングラフアプリケーションのコンパイルを参照) に生成され、このラッパースクリプトにより自動的に開始します。入力ファイルおよび出力ファイルはコマンドラインで指定されているものが使用され、デフォルトではパスは現在のディレクトリに相対します。次に、x86simulator コマンドのヘルプを示します。
```
$ x86simulator --help
 x86simulator [-h] [--help] [--h] [--pkg-dir=PKGDIR] [--gm-init-file=GM_INIT_FILENAME]
 optional arguments:
 -h,--help  --h show this help message and exit
--pkg-dir=PKG_DIR     Set the package directory. ex: Work
--gm-init-file=GM_INIT_FILENAME  set the gm-init-file image for GMIO
--i, -i ,--input-dir=PATH  Set the input-dir to . by Default
--o, -o ,--output-dir=PATH  Set the input-dir to . by Default
```
シミュレータで生成される出力ファイルは、ゴールデン出力と比較できます (空白の違いは無視)。
```
diff –w <data>/golden.txt <data>/output.txt
```
ランタイムパラメーターを動的にアップデートする必要があるアプリケーションでは、main プログラムからランタイムパラメーターのアップデート/読み出しメカニズムに説明されているアップデート API を使用してアプリケーションを制御できます。
次の例に示すように main アプリケーションを実行する反復回数を指定しない場合、シミュレータは継続的に実行されます。
```
clipgraph.init()
clipgraph.run(3)
clipgraph.end()
```

AI エンジン グラフ アプリケーションのシミュレーション

AI エンジン System C シミュレータ

シミュレータのオプション

シミュレーション入力および出力データ ストリーム

グローバル メモリのシミュレーション

ハードウェア エミュレーションのシミュレータ オプション

サードパーティ シミュレータの有効化