Vitis™ アプリケーションアクセラレーション開発フローチュートリアル

Vitis 入門チュートリアル¶

バージョン: Vitis 2021.2

パート 4: エンベデッドプロセッサアプリケーションのビルドおよび実行¶

このチュートリアルの 4 番目のパートでは、Vitis フローでサポートされる 3 つのビルドターゲットを使用して、vector-add の例をコンパイルして実行します。フロー全体の説明は、エンベデッドプロセッサアプリケーションアクセラレーション開発フローを参照してください。次のフローの図もここに含まれています。イメージから、Arm プロセッサ用にホストアプリケーションを構築するための G++ クロスコンパイルと、ザイリンクスデバイスバイナリ (xclbin) を構築するための Vitis コンパイラ (v++) を確認できます。この演習で、これらの手順を学びます。

ソフトウェアエミュレーション - カーネルコードは、エンベデッドプロセッサのエミュレーション環境 (QEMU) バージョン上で実行されるようにコンパイルされます。ソフトウェアエミュレーションターゲットを使用すると、ビルドと実行を短時間で反復して、アルゴリズムをすばやく段階的に改良できます。このターゲットは、構文エラーを特定し、アプリケーションと共に実行されるカーネルコードをソースレベルでデバッグし、システムの動作を検証するのに便利です。詳細は、ソフトウェアエミュレーションを参照してください。
ハードウェアエミュレーション - カーネルコードがハードウェアモデル (RTL) にコンパイルされ、Video ロジックシミュレータで実行されます。ホストアプリケーションは、エンベデッドプロセッサのエミュレーション環境 (QEMU) バージョン上で実行されます。ビルドおよび実行ループにかかる時間は長くなりますが、詳細でサイクル精度のカーネルアクティビティが表示されます。このターゲットは、FPGA に配置するロジックの機能をテストして、初期パフォーマンス見積もりを取得する場合に便利です。詳細は、ハードウェアエミュレーションを参照してください。
ハードウェア - カーネルコードがハードウェアモデル (RTL) にコンパイルされ、FPGA にインプリメントされて、実際の FPGA で実行されるバイナリが生成されます。エンベデッドプロセッサプラットフォームでは、ホストアプリケーション、xclbin、必須のサポートファイルが SD カード (たとえば) の書き込まれ、それがシステムのブートと設定に使用されます。詳細は、アプリケーションハードウェアビルドの実行を参照してください。

ZCU102 Zynq MPSoC エンベデッドプロセッサプラットフォームでのビルドと実行¶

環境の設定¶

重要: このチュートリアルを実行するには、Vitis 2021.1 以降が必要です。

注記: 次の手順は、bash シェルで実行していることを前提としています。

Vitis を実行する環境を設定するには、次のスクリプトを実行します。

source <VITIS_install_path>/settings64.sh
source <XRT_install_path>/setup.sh
unset LD_LIBRARY_PATH

次の環境変数が、インストールされている ZCU102 プラットフォーム、rootfs、および sysroot ディレクトリを指定するように設定されていることを確認します。

export PLATFORM_REPO_PATHS=<path to the ZCU102 platform install dir>
export ROOTFS=<path to the ZYNQMP common image directory, containing rootfs>

クロスコンパイラの SDK を正しく起動するには、SDK のソースを抽出したディレクトリで environment-setup-aarch64-xilinx-linux スクリプトを実行します。

source <path to the SDK>/environment-setup-aarch64-xilinx-linux

注記: ZYNQMP 共通イメージファイルは、Vitis エンベデッドプラットフォームページからダウンロードできます。このファイルには、ザイリンクス Zynq MPSoC デバイスの sysroot、rootfs、およびブートイメージが含まれます。

ソフトウェアエミュレーションをターゲットに指定¶

ソフトウェアエミュレーション用に構築するには、ターゲットのビルドディレクトリを設定するための次のコマンドを入力します。

cd <Path to the cloned repo>/Getting_Started/Vitis/example/zcu102
mkdir sw_emu
cp xrt.ini sw_emu
cp run_sw_emu.sh sw_emu
cd sw_emu

ターゲットのビルドディレクトリに移動したあと、ホストアプリケーションおよびデバイスバイナリを構築するために次のコマンドを入力します。

$CXX -Wall -g -std=c++11 ../../src/host.cpp -o ./app.exe -I/usr/include/xrt -lOpenCL -lpthread -lrt -lstdc++
v++ -c -t sw_emu --config ../../src/zcu102.cfg -k vadd -I../../src ../../src/vadd.cpp -o ./vadd.xo 
v++ -l -t sw_emu --config ../../src/zcu102.cfg ./vadd.xo -o ./vadd.xclbin
v++ -p -t sw_emu --config ../../src/zcu102.cfg ./vadd.xclbin --package.out_dir ./package --package.rootfs ${ROOTFS}/rootfs.ext4 --package.sd_file ${ROOTFS}/Image --package.sd_file ./xrt.ini --package.sd_file ./app.exe --package.sd_file ./vadd.xclbin --package.sd_file ./run_sw_emu.sh

次に、これら 4 つのコマンドを簡単に説明します。

$CXX は、Arm クロスコンパイラを使用してホストアプリケーションをコンパイルします。この変数には、クロスコンパイルに関連したフルコンパイラ実行ファイルプラスフラグが含まれ、SDK 環境設定スクリプトを実行するときに設定されます。詳細は、ホストプログラムのビルドを参照してください。
v++ -c は、vector-add アクセラレータのソースコードをコンパイルされたカーネルオブジェクト (.xo ファイル) にコンパイルします。詳細は、Vitis コンパイラでのカーネルのコンパイルを参照してください。
v++ -l は、コンパイルされたカーネルをターゲットプラットフォームにリンクし、FPGA バイナリ (.xclbin ファイル) を生成します。詳細は、カーネルのリンクを参照してください。
v++ -p は、ホスト実行ファイル、rootfs、FPGA バイナリ、およびその他のいくつかのファイルをパッケージ化し、ブータブルイメージを生成します。詳細は、エンベデッドプラットフォームのパッケージを参照してください。

データセンターアクセラレータカード用のビルドとエンベデッドプラットフォーム用の構築との間には 2 つの重要な違いがあります。

1 つは v++ --package コマンドの使用です。これはエンベデッドプロセッサプラットフォームフローに必須のステップで、データセンターフローではオプションで実行する場合がほとんどです。データセンターアプリケーションは X86 環境で実行され、ディスクから xclbin が読み込まれます。ところが、エンベデッドプロセッサプラットフォームフローの場合、普通はプロセッサを SD カードからブートする必要があるので、--package オプションにより、ファイルが収集されて、SD カードが生成されます。
もう 1 つは emconfigutil コマンドの使用です。このコマンドは、ハードウェアプラットフォームのエミュレーションバージョンを構築するために、データセンターフローで使用されます。ところが、エンベデッドプラットフォームフローでは、エミュレーションの実行で説明しているエミュレーション環境をエンベデッドプロセッサで使用する必要があります。このフローでは、エミュレーションプラットフォームではなく、launch_emulation スクリプトを使用します。

v++ コマンドの -t オプションは、ビルドターゲットを指定します。ここでは、ソフトウェアエミュレーション用に構築しているため、sw_emu に設定されています。

また、--config オプションを使用すると、追加オプションを含むコンフィギュレーションファイルの名前を指定できます。ここでは、このコンフィギュレーションファイルを使用して、ターゲットプラットフォームの名前と特定のメモリバンクのカーネル引数のマップを指定します。

save-temps=1
debug=1

# Enable profiling of data ports
[profile]
data=all:all:all

ソフトウェアエミュレーションのビルドは迅速で、1 ～ 2 分以上かかることはありません。ビルドプロセスが完了したら、次のようにソフトウェアエミュレーションを開始できます。

./package/launch_sw_emu.sh -forward-port 1440 22

このコマンドは、ソフトウェアエミュレーションを起動し、Xilinx Quick Emulation (QEMU) 環境を起動して、ブートシーケンスを開始します。詳細は、launch_emulator ユーティリティを参照にしてください。

重要: QEMU 環境からファイルを取り出すためには、エンベデッドプロセッサプラットフォームでのエミュレーションの実行で説明されている方法で、-forward-port オプションを使用する必要があります。

Linux の起動が完了したら、QEMU 環境内で次のコマンドを入力してサンプルプログラムを実行します。

cd /media/sd-mmcblk0p1
export XILINX_XRT=/usr
export XCL_EMULATION_MODE=sw_emu
./app.exe

実行が正常に完了したことを示す次のメッセージが表示されます。

INFO: Found Xilinx Platform
INFO: Loading 'vadd.xclbin'
TEST PASSED

zcu104/sw_emu ディレクトリの中を確認すると、この演習の間に次のファイルのいくつかが作成されているのがわかります。

app.exe: コンパイルされ、リンクされたホストアプリケーション
vadd.xclbin: カーネルおよびターゲットプラットフォームをリンクするデバイスバイナリ
opencl_trace.csv: アプリケーションランタイム中に発生するイベントのレポート
summary.csv: アプリケーションプロファイルのレポート
xrt.ini: ランタイム初期化ファイル
xrt.run_summary: アプリケーションランタイムのイベントのサマリレポート

これらのファイルは、ソフトウェアエミュレーションビルドをターゲットにしているビルドおよび実行プロセスの結果、出力されるファイルです。これらのファイルの一部を、このチュートリアルのパート 5 で詳しく説明します。ファイルをあとで確認するには、QEMU 環境からファイルを取り出して、ローカルコンピューターにコピーする必要があります。その場合は、たとえば、エンベデッドプロセッサプラットフォームでのエミュレーションの実行で説明されているように、scp オプションを使用します。

scp -P 1440 root@127.0.0.1:/media/sd-mmcblk0p1/xrt.run_summary ./xrt.run_summary

Ctrl +A + X を押して QEMU を終了し、bash シェルに戻ります。

ヒント: QEMU 環境を終了できない場合は、kill -9 <qemu_pid> を使用して、ほかのターミナルウィンドウからプロセスを強制終了させます。

ハードウェアエミュレーションをターゲットに指定¶

ハードウェアエミュレーション用に構築するには、ターゲットのビルドディレクトリを設定するための次のコマンドを入力します。

cd <Path to the cloned repo>/Getting_Started/Vitis/example/zcu102
mkdir hw_emu
cp xrt.ini hw_emu
cp run_hw_emu.sh hw_emu
cd hw_emu

ターゲットのビルドディレクトリに移動したあと、ホストアプリケーションおよびデバイスバイナリを構築するために次のコマンドを入力します。

$CXX -Wall -g -std=c++11 ../../src/host.cpp -o app.exe -I/usr/include/xrt -lOpenCL -lpthread -lrt -lstdc++
v++ -c -t hw_emu --config ../../src/zcu102.cfg -k vadd -I../../src ../../src/vadd.cpp -o vadd.xo 
v++ -l -t hw_emu --config ../../src/zcu102.cfg ./vadd.xo -o vadd.xclbin
v++ -p -t hw_emu --config ../../src/zcu102.cfg ./vadd.xclbin --package.out_dir package --package.rootfs ${ROOTFS}/rootfs.ext4 --package.sd_file ${ROOTFS}/Image --package.sd_file xrt.ini --package.sd_file app.exe --package.sd_file vadd.xclbin --package.sd_file run_app.sh

これらのコマンドの簡単な説明は、「ソフトウェアエミュレーションをターゲットに指定」を参照してください。前の手順との唯一の違いは、v++ ターゲット (-t) オプションで、sw_emu から hw_emu に変更されます。その他のオプションはすべて同じままです。

ハードウェアエミュレーションはソフトウェアエミュレーションよりも時間がかかりますが、ハードウェアアクセラレータカードをターゲットにしているときよりは時間はかかりません。ビルドプロセスが完了したら、パッケージステップで生成された起動スクリプトを使用して、ハードウェアエミュレーションを起動できます。

./package/launch_hw_emu.sh

Linux の起動が完了したら、QEMU コマンドプロンプトに次のコマンドを入力してサンプルプログラムを実行します。

cd /media/sd-mmcblk0p1
export XILINX_XRT=/usr
export XCL_EMULATION_MODE=hw_emu
./app.exe

TEST PASSED というメッセージが表示され、実行が正常に完了したことが示されます。

QEMU でアプリケーションを実行すると、実行中にいくつかのレポートファイルが生成されます。ソフトウェアエミュレーションビルドをターゲットにしている実行プロセスの結果、出力されるファイルです。これらのファイルの一部を、このチュートリアルのパート 5 で詳しく説明します。ファイルをあとで確認するには、QEMU 環境からファイルを取り出して、ローカルコンピューターにコピーする必要があります。その場合は、たとえば、エンベデッドプロセッサプラットフォームでのエミュレーションの実行で説明されているように、scp オプションを使用します。

scp -P 1440 root@127.0.0.1:/media/sd-mmcblk0p1/xrt.run_summary ./xrt.run_summary

Ctrl +A + X を押して QEMU を終了し、bash シェルに戻ります。

ヒント: QEMU 環境を終了できない場合は、kill -9 <qemu_pid> を使用して、ほかのターミナルウィンドウからプロセスを強制終了させます。

ハードウェアターゲットの指定¶

ハードウェアターゲット用に構築するには、ターゲットのビルドディレクトリを設定するための次のコマンドを入力します。

cd <Path to the cloned repo>/Getting_Started/Vitis/example/zcu102
mkdir hw
cp xrt.ini hw
cp run_hw.sh hw
cd hw

ターゲットのビルドディレクトリに移動したあと、ホストアプリケーションおよびデバイスバイナリを構築するために次のコマンドを入力します。

$CXX -Wall -g -std=c++11 ../../src/host.cpp -o app.exe -I/usr/include/xrt -lOpenCL -lpthread -lrt -lstdc++ -O
v++ -c -t hw --config ../../src/zcu102.cfg -k vadd -I../../src ../../src/vadd.cpp -o vadd.xo 
v++ -l -t hw --config ../../src/zcu102.cfg ./vadd.xo -o vadd.xclbin
v++ -p -t hw --config ../../src/zcu102.cfg ./vadd.xclbin --package.out_dir package --package.rootfs ${ROOTFS}/rootfs.ext4 --package.sd_file ${ROOTFS}/Image --package.sd_file xrt.ini --package.sd_file app.exe --package.sd_file vadd.xclbin --package.sd_file run_app.sh

ハードウェアをターゲットにするには、v++ -t オプションを hw に設定し、emconfigutil ステップはエミュレーションにのみ適用されるため省略されます。その他のオプションはすべて同じままです。

ハードウェアターゲットのビルドには数時間かかることがありますが、正確な所要時間は、ビルドするコンピューターとその負荷によって異なります。

ビルドプロセスが完了したら、sd_card ディレクトリを SD カードにコピーし、プラットフォームに接続して、Linux プロンプトが表示されるまで起動します。この時点で、エンベデッドプロセッサプラットフォームで次のコマンドを入力してアクセラレーションされたアプリケーションを実行します。

cd /media/sd-mmcblk0p1
export XILINX_XRT=/usr
./app.exe

実行が正常に完了したことを示す TEST PASSED という同じメッセージが表示されます。zcu102/hw フォルダーを確認すると、このビルドおよび実行プロセスの間に作成されたファイルを確認できます。これらのファイルの簡単な説明は、「ソフトウェアエミュレーションをターゲットに指定」を参照してください。

お疲れさまでした。これで、ZCU102 カードで初めて Vitis アクセラレーションアプリケーションを実行できました。Vitis ツールをさらに学ぶには、Vitis チュートリアルを進めていってください。また、ホストアプリケーションおよびカーネルコードの例を使用するには、 Vitis_Accel_例を参照してください。

次の手順¶

結果の表示とレポートの解析をクリックしてください。

ライセンス規約

Apache ライセンス、バージョン 2.0 (以下「ライセンス」) に基づいてライセンス付与されています。本ライセンスに準拠しないと、このファイルを使用することはできません。ライセンスのコピーは、http://www.apache.org/licenses/LICENSE-2.0 から入手できます

適切な法律で要求されるか、書面で同意された場合を除き、本ライセンスに基づいて配布されるソフトウェアは、明示的または黙示的を問わず、いかなる種類の保証または条件もなく、「現状のまま」配布されます。ライセンスに基づく権限と制限を管理する特定の言語については、ライセンスを参照してください。

Vitis™ アプリケーション アクセラレーション開発フロー チュートリアル

Vitis 入門チュートリアル¶

パート 4: エンベデッド プロセッサ アプリケーションのビルドおよび実行¶

ZCU102 Zynq MPSoC エンベデッド プロセッサ プラットフォームでのビルドと実行¶

環境の設定¶

ソフトウェア エミュレーションをターゲットに指定¶

ハードウェア エミュレーションをターゲットに指定¶

ハードウェア ターゲットの指定¶

次の手順¶

Vitis™ アプリケーションアクセラレーション開発フローチュートリアル

パート 4: エンベデッドプロセッサアプリケーションのビルドおよび実行¶

ZCU102 Zynq MPSoC エンベデッドプロセッサプラットフォームでのビルドと実行¶

ソフトウェアエミュレーションをターゲットに指定¶

ハードウェアエミュレーションをターゲットに指定¶

ハードウェアターゲットの指定¶