2019.2 Vitis(TM) チュートリアルやってみた

はじめに

去る 2019/11/01 (JST)、待ちに待った Vitis™ がリリースされました。10 月頭の Xilinx Developer Forum 2019 でアナウンスされてから早一ヶ月 (PR)、心待ちにされていた方も多いのではないでしょうか。本記事では、その Vitis のインストールから、サンプルファイルのコンパイル・リンク・エミュレーション・実行までを行うチュートリアル（Vitis Execution Model から Building the Accelerated Application – Essential Concepts まで）をやってみたので共有します。チュートリアルは GitHub の Vitis Getting Started からアクセス可能です。以下、Vitis について簡単に紹介し、その後インストールについて、最後にチュートリアルについて書きます。ちなみに、このチュートリアルでは、IDE を開くことはなく全てコマンドラインの操作で Vitis を利用していきます。Vitis Getting Started の傍らに本稿が開かれ、チュートリアル理解・実践の助けになることを期待します。

Vitis について

Vitis とは、Xilinx 社 が提供する統合ソフトウェアプラットフォームです。詳しいことはここを見たほうが早く正確に理解できるので参照いただきたいのですが、今まで色々あった開発環境が 1 つに統合されたように感じます。後々出てきますが、SDAccel と同じ機能もところどころ見受けられます。

開発環境以外でのセールスポイントは、十分に最適化されたライブラリ（Vitis アクセラレーションライブラリ）が多数用意されていることではないでしょうか。これらのライブラリが、仕様の検討から実装・運用までの時間短縮や高い性能を実現させてくれると謳われています。

インストール

ではさっそくインストールしていきましょう。インストールが既に完了している方は、チュートリアル実践まで飛ばしてください。

XRT

Alveo U200 の Getting Started の 1. Download the Xilinx Runtime 右にあるリンクからインストーラをダウンロードして、.rpm なり .deb をインストールしてください。これは、Alveo 導入時に既にインストールされた方もいらっしゃると思います。XRT は Alveo U200/U250/U50 どのページからでも同じものがインストールできます。Alveo U200 を選んだことに特別な理由はありません。

既にインストール済みの方はこの作業は不要です。ただし、インストールした XRT の版数によっては、あとに出てくるエミュレーションで SEGV したり、Vitis の起動でコケる時があるので注意してください。後述の原因でうまくいかないときは XRT を再インストールすると改善すると思います。

Platform

Alveo U200, Alveo U250, Alveo U50 のうち使用するカードに対応した Development Target Platform をインストールします。XRT インストールのときと同様に、Getting Started の 2., 3. Download the Development Target Platform 右にあるリンクからインストーラをダウンロードしてそれぞれインストールします。また、XRT と同じくこれも Alveo 導入時に既にインストールされた方もいらっしゃると思います。

Vitis

最後に Vitis をインストールします。上と同様に Getting Started の 4. Download the Vitis Design Environment 右のリンク先のページへ飛んでから Vitis (SW Developer) ではなく Vivado (HW Developer) にある Xilinx Unified Installer 2019.2 {Windows,Linux} Self Extracting Web Installer をダウンロード、インストールします。このインストーラで、Vivado だけでなく Vitis もインストールできます。今までの Vivado と同じようにインストールを進めていき、インストール対象を選択する画面で Vitis を選びます。

これで Vivado も Vitis もインストールされるようになります。参考までに、我々の環境では以下のディスク容量が必要になりました。

インストール後のトラブル

ここでは、インストール後に筆者が体験したトラブルとその解決策について紹介します。もし他に同じ現象を体験された方がいて、他により良い解決方法がいましたら是非コメントお願いします。

さて、前節までで Vitis をインストールできました。$ vitis で Vitis が起動できると思います。起動できなかった場合、以下の 2 点を確認してみてください。

• CentOS のバージョンが 7.6 以上である。
  Vitis 起動スクリプトは、起動時に XRT の環境セットアップスクリプト /opt/xilinx/xrt/setup.sh を source します。CentOS のバージョンがサポート対象なのに以下のようなメッセージで Vitis の起動ができないことがあるかもしれません。

$ cat /etc/redhat-release
CentOS Linux release 7.6.1810 (Core)
$ vitis
ERROR: Centos or RHEL release version must be 7.4 or later
****** Xilinx Vitis Development Environment
****** Vitis v2019.2 (64-bit)
  **** SW Build 2700185 on Thu Oct 24 18:46:26 MDT 2019
    ** Copyright 1986-2019 Xilinx, Inc. All Rights Reserved.
Launching Vitis with command ... &

こんな時は以下のことをチェックしてみてください。具体的にはスクリプトの以下の部分です。

$ grep -n '/opt/xilinx/xrt/setup.sh' `which vitis`
98:  if [ -e "/opt/xilinx/xrt/setup.sh" ] ; then
99:    . "/opt/xilinx/xrt/setup.sh"

このスクリプトの中身を追いかけてみると、以下のような記述がありました。これが今回 Vitis 起動失敗の原因なようです。（XRT の版数がいくつのものかを確認し忘れました。）

$ grep -C3 'ERROR: Centos' /opt/xilinx/xrt/setup.sh

if [[ $OSDIST == "centos" ]] || [[ $OSDIST == "redhat"* ]]; then
    if [[ $OSREL != "7.4"* ]] &&  [[ $OSREL != "7.5"* ]]; then
        echo "ERROR: Centos or RHEL release version must be 7.4 or later"
        return 1
    fi
fi

XRT を再インストールすると、起動スクリプトが以下のように変更されてうまく起動できるようになります。

$ grep -C3 'ERROR: Centos' /opt/xilinx/xrt/setup.sh

if [[ $OSDIST == "centos" ]] || [[ $OSDIST == "redhat"* ]]; then
    if (( $OSREL < 704 )); then
        echo "ERROR: Centos or RHEL release version must be 7.4 or later"
        return 1
    fi
fi

• Vitis を root 権限でインストールした。
  JVM が code=13 でエラー終了する場合、Vitis を root 権限でインストールしたことが原因かもしれません。root でインストールした場合は、インストール後に /opt/Xilinx/Vitis/2019.2/tps/lnx64/jre9.0.4 以下にユーザ読み取り＋実行権限を与えるなどの操作が必要になります。これとは別のエラーですが、フォーラムにも同じような現象で困っている人がいました。（2019/11/13 追記）AR に sudo でインストールした場合の対策が記載されました。 https://www.xilinx.com/support/answers/73047.html ）

チュートリアル実践

話をチュートリアルに戻しましょう。ここまでで Vitis が無事起動したとして、チュートリアルを始めたいと思います。

Programming and Execution Model

まずは Vitis Getting Started から Programming and Execution Model へ移動します。早く Vitis に触りたい気持ちを抑えつつ Introduction を読みます。

FPGA を利用したシステムのソフトウェア・ハードウェア開発に携わったことのある人なら理解しやすい内容かと思います。続いて、Alveo カード上へのアプリケーション実装に必要なもののインストールです。Next steps 以下の Read more… へ進みましょう。

Setting up the Alveo Data Center Accelerator Cards and Vitis Core Development Kit

次は Alveo Getting Started です。ここでは Vitis というより Alveo のセットアップについて書かれています。

README.md 中段の Quick Take Video は Alveo のインストールから検証の実施方法まで一通り触れられている 12 分半ほどの動画です。動画は一部古くなっている部分（Alveo Landing Page の見た目が異なる、Develop Shell が Develop Target Platform に変わっている）もありますが、ほとんどは今も使える情報です。

続いて、いよいよ Vitis に触れていきます。Next steps 以下の Essential Concepts for Building and Running the Accelerated Application へ進みましょう。

Building the Accelerated Application – Essential Concepts

ここから Vitis に本格的に触っていきます。ところで、本節 Pathway3 は、さらに 4 つの小節に分かれています。

1. Building an Application: Learn how to build an application’s host program and the hardware kernel.

2. Running Software and Hardware Emulation: Run hardware and software emulation on an application.

3. Generating Profile and Trace Reports: Learn how to generate profiling reports to better understand the performance of the application.

4. Executing in Hardware: Finally, execute an application on the Alveo Data Center accelerator card.

https://github.com/Xilinx/Vitis-Tutorials/tree/master/docs/Pathway3#next-steps

以降、それぞれの節に分けて実践していきます。1. ~ 3. と 4. の途中までは Alveo を持っていなくてもできるのでとりあえず Vitis に触ってみたい方も試せると思います。

Building an Application

ここでは、ホスト側のアプリケーションとハードウェアカーネルの開発方法について学びます。

• 準備
  • チュートリアルで使うファイルは以下で入手できます。
    • $ git clone https://github.com/Xilinx/Vitis-Tutorials
  • reference-filesディレクトリのある Pathway3 ディレクトリへ移動します。
    • $ cd Vitis-Tutorials/docs/Pathway3
  • Vitis を使うための設定を行います。
    • $ source <VITIS_install_path>/settings64.sh
  • XRT を使うための設定を行います。
    • $ source <XRT_install_path>/setup.sh

ソフトウェアは C/C++ で書かれ、FPGA と通信するために OpenCL(TM) の API を用います。それらは g++ でコンパイルされ、XRT の .so とリンクされます。次節で実際にコンパイルしていきます。

Building the Software

ここでは、コンパイルの方法について知ることができます。実際に提示された手順に従ってコンパイルしてみたいと思います。4. Complete Command に実行すべきコマンドが示されています。

実行環境は以下のとおりです。

$ uname -a
Linux `hostname` 5.0.0-32-generic #34~18.04.2-Ubuntu SMP Thu Oct 10 10:36:02 UTC 2019 x86_64 x86_64 x86_64 GNU/Linux
$ g++ --version
g++ (Ubuntu 7.4.0-1ubuntu1~18.04.1) 7.4.0
Copyright (C) 2017 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

以下、実行手順です。環境変数 XILINX_XRT, XILINX_VIVAD は自分の環境に応じて読み替えてください。

1. $ cd Pathway3/reference-files/run
2. $ export XILINX_XRT=/opt/xilinx/xrt/
3. $ export XILINX_VIVADO=/opt/Xilinx/Vivado/2019.2/
4. $ g++ -I$XILINX_XRT/include -I$XILINX_VIVADO/include -Wall -O0 -g -std=c++11 ../src/host.cpp -o 'host' -L$XILINX_XRT/lib -lOpenCL -lpthread -lrt -lstdc++

上記の手順で host というバイナリができました。続いて、ハードウェアのビルドを行います。

Building the Hardware

ここでは、ハードウェア上で走るカーネル（以降、単にカーネル）のビルドについて知ることができます。このカーネルのビルドもソフトウェアと同様にコンパイルとリンクが必要です。カーネルは C/C++, OpenCL C または RTL で記述できます。C/C++, OpenCL C は Vitis コンパイラ v++ でコンパイルされますが、RTL は Xilinx の package_xo ユーティリティでコンパイルされます。これらコンパイルについては、Vitis Environment Reference Materials を参照すれば詳細を知ることができます。カーネルの記述言語が何であれ、Xilinx object file (.xo) が出力されるようです。このチュートリアルでは RTL から .xo のビルドについては触れていないため、本記事でも触れません。

Hardware Compilation

ここには v++ の実行方法などの説明があります。v++ の詳細は Hardware Compilation で確認してください。以下にポイントだけ示します。

• -c オプション（コンパイルを指定）でカーネル (.xo) を生成（$ v++ --help より）
• -k オプションでカーネルに名前をつけられる。
• ソース・ファイルとターゲットプラットフォーム、ビルドターゲットが必須
  • ビルドターゲットは全部で 3 つあり、2 つのエミュレーションターゲット (sw_emu, hw_emu)と 1 つのハードウェアターゲット (hw) から構成される。
  • エミュレーションターゲットはデバッグと検証向け
  • ハードウェアターゲットは FPGA にコンフィグするバイナリを生成

ここで 2 つの変わったものが出てきました。SDAccel に詳しい方はご存知かと思いますが、（私含め）知らない方へ向けて少し説明します 。デバッグ・検証向けターゲットの sw_emu と hw_emu です。ハードウェアターゲットは、何となく分かると思いますので、上のエミュレーションターゲットについてもう少し説明を読みます。以下は 2 つの説明に対するまとめです。

• Software Emulation (sw_emu)
  • ホストコード、カーネルの両方が x86 で走るバイナリにコンパイルされる。
  • ビルド、実行のループを早く回したいときに使用
    • （私見）開発の初期段階に多く用いられそう。
  • カーネルが RTL のときは、カーネルの C モデルがあれば sw_emu 可能
  • C モデルがないときは sw_emu はできない。hw_emu を用いる。
• Hardware Emulation (hw_emu)
  • カーネルはハードウェアモデルにコンパイルされ、ハードウェアシミュレータ上で動作する。
  • ビルド・実行は長時間かかるが、カーネルのサイクル精度の動きを確認できる。
  • カーネルを構成するロジックの機能検証や初期の性能見積もりに使用

開発の対象やフェーズにおいてそれぞれのターゲットを使い分けることが大事なようです。

コンパイル時の長いオプションを避けるために、コンフィグファイル（例 Pathway3/reference-files/run/design.cfg）が使用可能です。v++ の --config オプションで v++ に渡せます。コンフィグファイルのフォーマットについて示した資料は見つからないので、design.cfg の中身を見ていきます。

platform=xilinx_u200_xdma_201830_2
debug=1

[connectivity]
nk=mmult:1:mmult_1

コンフィグファイルに記載できるものは v++ --help で確認できます。上の platform や debug、[connectivity] セクションの nk オプションも見られます。nk オプションについて、上のファイルでは mmult というカーネルは、mmult_1 という CU (Compute Units) を 1 つ持つ、という意味になります。

最後に以下のコマンドでハードウェアのコンパイルを行います。

$ v++ -t sw_emu --config design.cfg -c -k mmult -I'../src' -o'mmult.sw_emu.xilinx_u200_xdma_201830_2.xo' '../src/mmult.cpp'
Option Map File Used: '/opt/Xilinx/Vitis/2019.2/data/vitis/vpp/optMap.xml'

****** v++ v2019.2 (64-bit)
  **** SW Build 2700185 on Thu Oct 24 18:45:48 MDT 2019
    ** Copyright 1986-2019 Xilinx, Inc. All Rights Reserved.

INFO: [v++ 60-1306] Additional information associated with this v++ compile can be found at:
        Reports: /path/to/Vitis-Tutorials/docs/Pathway3/reference-files/run/_x/reports/mmult.sw_emu.xilinx_u200_xdma_201830_2
        Log files: /path/to/Vitis-Tutorials/docs/Pathway3/reference-files/run/_x/logs/mmult.sw_emu.xilinx_u200_xdma_201830_2
Running Dispatch Server on port:33858
INFO: [v++ 60-1548] Creating build summary session with primary output /path/to/Vitis-Tutorials/docs/Pathway3/reference-files/run/mmult.sw_emu.xilinx_u200_xdma_201830_2.xo.compile_summary, at Tue Nov  5 15:32:41 2019
INFO: [v++ 60-1316] Initiating connection to rulecheck server, at Tue Nov  5 15:32:41 2019
Running Rule Check Server on port:35667
INFO: [v++ 60-1315] Creating rulecheck session with output '/path/to/Vitis-Tutorials/docs/Pathway3/reference-files/run/_x/reports/mmult.sw_emu.xilinx_u200_xdma_201830_2/v++_compile_mmult.sw_emu.xilinx_u200_xdma_201830_2_guidance.html', at Tue Nov  5 15:32:42 2019
INFO: [v++ 60-895]   Target platform: /opt/xilinx/platforms/xilinx_u200_xdma_201830_2/xilinx_u200_xdma_201830_2.xpfm
INFO: [v++ 60-1578]   This platform contains Device Support Archive '/opt/xilinx/platforms/xilinx_u200_xdma_201830_2/hw/xilinx_u200_xdma_201830_2.dsa'
INFO: [v++ 60-585] Compiling for software emulation target
INFO: [v++ 60-423]   Target device: xilinx_u200_xdma_201830_2
INFO: [v++ 60-242] Creating kernel: 'mmult'

===>The following messages were generated while  performing high-level synthesis for kernel: mmult Log file: /path/to/Vitis-Tutorials/docs/Pathway3/reference-files/run/_x/mmult.sw_emu.xilinx_u200_xdma_201830_2/mmult/vivado_hls.log :
INFO: [v++ 204-61] Option 'relax_ii_for_timing' is enabled, will increase II to preserve clock frequency constraints.
INFO: [v++ 60-594] Finished kernel compilation
INFO: [v++ 60-586] Created mmult.sw_emu.xilinx_u200_xdma_201830_2.xo
INFO: [v++ 60-791] Total elapsed time: 0h 0m 15s

親切に最後にはかかった時間も出してくれています。これで mmult.sw_emu.xilinx_u200_xdma_201830_2.xo というファイルができました。

Hardware Linking

Building an Application 節の最後は、ハードウェアのリンクです。ハードウェアのリンクという考え方が（私は）ピンとこなかったので簡単に説明してみますと、リンクとは「1 つ以上のカーネルとプラットフォームを結びつける作業、または結びつけることそのもの」を指すようです。ソフトウェアのコンパイルで実行ファイルを作るときのリンクと考え方は似ています。このハードウェアのリンクでは Output binary container (.xclbin) というファイルが出来上がります。

この作業で 1 つ大事なことは、Hardware Compilation で指定したターゲット・プラットフォームと今回のコマンドで指定するターゲット・プラットフォームは一致させる必要がある、ということです。一致させないとリンクのときにエラーストップしてしまいます（後述の実験参照）。

上の項 Hardware Compilation でコンフィグファイルについて触れました。その中の [connectivity] セクションの nk オプションはこの段階で効いてくるようです。これで、カーネルが持つ CU インスタンス数を決定します（ このオプションについてはヘルプメッセージやドキュメントを読んでも正確な理解ができていません。訂正すべき点があれば是非コメントお願いします）。

では、コマンドを実行してみます。

$ v++ -t sw_emu --config design.cfg  -l  -o'mmult.sw_emu.xilinx_u200_xdma_201830_2.xclbin' mmult.sw_emu.xilinx_u200_xdma_201830_2.xo

Option Map File Used: '/opt/Xilinx/Vitis/2019.2/data/vitis/vpp/optMap.xml'

****** v++ v2019.2 (64-bit)
  **** SW Build 2700185 on Thu Oct 24 18:45:48 MDT 2019
    ** Copyright 1986-2019 Xilinx, Inc. All Rights Reserved.

INFO: [v++ 60-1306] Additional information associated with this v++ link can be found at:
        Reports: /path/to/Vitis-Tutorials/docs/Pathway3/reference-files/run/_x/reports/link
        Log files: /path/to/Vitis-Tutorials/docs/Pathway3/reference-files/run/_x/logs/link
Running Dispatch Server on port:43181
INFO: [v++ 60-1548] Creating build summary session with primary output /path/to/Vitis-Tutorials/docs/Pathway3/reference-files/run/mmult.sw_emu.xilinx_u200_xdma_201830_2.xclbin.link_summary, at Tue Nov  5 16:01:23 2019
INFO: [v++ 60-1316] Initiating connection to rulecheck server, at Tue Nov  5 16:01:23 2019
Running Rule Check Server on port:37882
INFO: [v++ 60-1315] Creating rulecheck session with output '/path/to/Vitis-Tutorials/docs/Pathway3/reference-files/run/_x/reports/link/v++_link_mmult.sw_emu.xilinx_u200_xdma_201830_2_guidance.html', at Tue Nov  5 16:01:24 2019
INFO: [v++ 60-895]   Target platform: /opt/xilinx/platforms/xilinx_u200_xdma_201830_2/xilinx_u200_xdma_201830_2.xpfm
INFO: [v++ 60-1578]   This platform contains Device Support Archive '/opt/xilinx/platforms/xilinx_u200_xdma_201830_2/hw/xilinx_u200_xdma_201830_2.dsa'
INFO: [v++ 60-629] Linking for software emulation target
INFO: [v++ 60-423]   Target device: xilinx_u200_xdma_201830_2
INFO: [v++ 60-645] kernel flags are '-g -I /path/to/Vitis-Tutorials/docs/Pathway3/reference-files/src -g'
INFO: [v++ 60-586] Created mmult.sw_emu.xilinx_u200_xdma_201830_2.xclbin
INFO: [v++ 60-1307] Run completed. Additional information can be found in:
        Guidance: /path/to/Vitis-Tutorials/docs/Pathway3/reference-files/run/_x/reports/link/v++_link_mmult.sw_emu.xilinx_u200_xdma_201830_2_guidance.html
        Steps Log File: /path/to/Vitis-Tutorials/docs/Pathway3/reference-files/run/_x/logs/link/link.steps.log

INFO: [v++ 60-791] Total elapsed time: 0h 0m 9s

無事リンクが完了しました。

最後にハードウェアのコンパイルからリンクまで、.xclbin ファイルを作るための流れについておさらいします。

1. ハードウェアのコンパイル (v++ -c) → .xo ファイルができあがる。
2. ハードウェアのリンク (v++ -l) → .xclbin ファイルができあがる。
   • このとき、コンパイルで指定したターゲットとプラットフォームは、リンクで指定するターゲット・プラットフォームと一致していなければならない。
     • ホストプログラムは、ターゲット・プラットフォームに無関係

【実験】

以下のようにターゲットをわざと間違えてみます。

すると、以下のようなエラーでコマンド実行開始後すぐにストップします。

ERROR: [v++ 60-1576] Input Object file validation failed: ERROR: [v++ 17-70] Application Exception: The kernel 'mmult' in 'mmult.sw_emu.xilinx_u200_xdma_201830_2.xo' is not valid for the specified target 'hw_emu'. The valid target: sw_emu

ここで勉強がてら、ハードウェアターゲット、プラットフォームをチュートリアルのものから少し変更してみます。

• ターゲット: hw_emu
• プラットフォーム: xilinx_u250_xdma_201830_2

手順は以下のとおりです。

1. design.cfg を platform=xilinx_u200_xdma_201830_2 から platform=xilinx_u250_xdma_201830_2 のように変更
2. コンパイル（ターゲットは hw_emu にする）
   $ v++ -t hw_emu --config design.cfg -c -k mmult -I'../src' -o'mmult.hw_emu.xilinx_u250_xdma_201830_2.xo' '../src/mmult.cpp'
3. リンク （ターゲットは hw_emu にする）
   $ v++ -t hw_emu --config design.cfg -l -o'mmult.hw_emu.xilinx_u250_xdma_201830_2.xclbin' mmult.hw_emu.xilinx_u250_xdma_201830_2.xo
4. レポート (./_x/reports/link/system_estimate_mmult.hw_emu.xilinx_u250_xdma_201830_2.xtxt) を確認。レポートが書かれていると思います。レポートについては次々節 Generating Profile and Trace Reports で触れます。
5. チュートリアルにある vitis_analyzer -open profile_summary.csv についても同様に後述です。ちなみに、デフォルトでは当該ファイルは生成されません。

ターゲットを hw_emu もしくは hw に設定すると、ハードウェアのビルドレポートを確認できるようになります。このレポートはコンパイル時・リンク時に自動的に作られるもので、FPGA のリソース、動作周波数の見積もりを示します。

注意すべき点として、リンク実行の前に $ source <XRT_install_path>/setup.sh されていることを確認してください。xclbinutil が見つからずエラーストップしてしまいます。

ここまで（執筆するのに）時間がかかりましたが、続いては各エミュレーションの実行に移ります。チュートリアル上 Next Steps の Running Software and Hardware Emulation を開きます。

Running Software and Hardware Emulation

ここに従って、エミュレーションを実行してみます。エミュレーションはデバッグや最適化に必須です。前述の通り、Vitis はソフトウェア・ハードウェアエミュレーションの両方を提供してくれます。ここまで読んでいただいた方は、既にエミュレーションターゲットでのビルドを完了させており、また各エミュレーションターゲットについて理解しておられると思います。

このフェーズでは、新たに Emulation Configuration File が必要になります。コンフィグファイル emconfig.json は emconfigutil コマンドが作ってくれます。以下のように -f/--platform オプションでプラットフォームを指定してコンフィグファイルを作ってみます。ここでは、プラットフォームは U250 ではなく U200 で進めます。

$ emconfigutil --platform xilinx_u200_xdma_201830_2

****** configutil v2019.2 (64-bit)
  **** SW Build 2700185 on Thu Oct 24 18:45:48 MDT 2019
    ** Copyright 1986-2019 Xilinx, Inc. All Rights Reserved.

INFO: [ConfigUtil 60-895]   Target platform: /opt/xilinx/platforms/xilinx_u200_xdma_201830_2/xilinx_u200_xdma_201830_2.xpfm
INFO: [ConfigUtil 60-1578]   This platform contains Device Support Archive '/opt/xilinx/platforms/xilinx_u200_xdma_201830_2/hw/xilinx_u200_xdma_201830_2.dsa'
emulation configuration file `emconfig.json` is created in current working directory

これでカレントディレクトリに emconfig.json ができました。

最後に必要な作業がもう一つあります。それは環境変数 XCL_EMULATION_MODE の設定です。開発者が期待するエミュレーションをツールに教えてやるために必要です。以下のように定義してください。

• Software emulation: export XCL_EMULATION_MODE=sw_emu
• Hardware emulation: export XCL_EMULATION_MODE=hw_emu

このチュートリアルでは export XCL_EMULATION_MODE=sw_emu を実行します。環境変数の設定が完了したら、エミュレーションを実行します。LD_LIBRARY_PATH に $XILINX_XRT/lib が含まれていることを確認してから以下のコマンドを実行してください。

$ ./host mmult.sw_emu.xilinx_u200_xdma_201830_2.xclbin
Found Platform
Platform Name: Xilinx
INFO: Reading mmult.sw_emu.xilinx_u200_xdma_201830_2.xclbin
Loading: 'mmult.sw_emu.xilinx_u200_xdma_201830_2.xclbin'
TEST PASSED

TEST PASSED というエミュレーションが成功したことを期待させてくれるメッセージが出力されました。

【エミュレーションで SEGV するとき】
上のエミュレーション実行時に手元の環境で再現性のある SEGV が発生しました。XRT のアップグレード (2018.3 → 2019.2) を試してみると SEGV が消えたので、XRT の版数に感度があるように見えました。もし正確な情報をお持ちの方がいらっしゃいましたら、是非コメントをいただければと思います。

Software Emulation に続いて Hardware Emulation も試してみます。ここに先程たまたま作ったプラットフォーム U250 向けのファイル群がありますのでこれを利用します。

1. コンフィグファイルを作成 emconfigutil --platform xilinx_u250_xdma_201830_2
2. 環境変数 XCL_EMULATION_MODE=hw_emu の設定
3. コマンドを実行

$ ./host mmult.hw_emu.xilinx_u250_xdma_201830_2.xclbin
Found Platform
Platform Name: Xilinx
INFO: Reading mmult.hw_emu.xilinx_u250_xdma_201830_2.xclbin
Loading: 'mmult.hw_emu.xilinx_u250_xdma_201830_2.xclbin'
INFO: [HW-EM 01] Hardware emulation runs simulation underneath. Using a large data set will result in long simulation times. It is recommended that a small dataset is used for faster execution. The flow uses approximate models for DDR memory and interconnect and hence the performance data generated is approximate.
TEST PASSED
INFO::[ Vitis-EM 22 ] [Time elapsed: 0 minute(s) 11 seconds, Emulation time: 0.0686954 ms]
Data transfer between kernel(s) and global memory(s)
mmult_1:m_axi_gmem-DDR[0]          RD = 2.000 KB               WR = 1.000 KB

上の実行結果を見ると、Hardware Emulation は以下のことに注意すべきと教えてくれています。

• ハードウェアエミュレーションは時間がかかるのでより速い実行のために小さめのデータセットを使用することを推奨
• DDR や Interconnect は近似モデルなので性能見積もりも近似値

ここまでで、ハードウェアのビルドからエミュレーション実行までできました。Next Step の Generating Profile and Trace Reports でレポートを確認します。

ちなみに、ここまでのコマンドは全て /path/to/Vitis-Tutorials/docs/Pathway3/reference-files/run/Makefile にまとまっているので、別途ご確認ください。

Generating Profile and Trace Reports

デザインをより理解するために、開発者は以下の 2 つのレポートを生成できます。

1. Profile Summray: 全体の性能に関する詳細を確認
2. Application Timeline: ホストとデバイスのそれぞれのイベントを共通のタイムライン上で視覚的に確認

両レポートはどのビルドターゲットでも作られます。ただし、レポートの粒度はそれぞれのターゲット間で異なるようです。どこまで真剣にエミュレーションするか、が異なるわけですから、当然といえば当然ですね。

このチュートリアルでは、Hardware Emulation を前提として進めます。もちろん、その他のターゲットでも同様にレポートを確認することができます。

Generating Emulation Data

各レポートは、エミュレーションデータ生成時間やディスク使用量の削減のためデフォルトでは生成されないようになっています。それらを生成するためには、xrt.ini ファイルをホストプログラムと同じディレクトリ（ここでは /path/to/Vitis-Tutorials/docs/Pathway3/reference-files/run）に置きます。

まず、xrt.ini を作ります。内容は以下のとおりです。

[Debug]
profile=true
timeline_trace=true
data_transfer = fine

1 行目、[Debug] セクションがあるということは、その他の設定も書かれる予定があることがわかりますね。2 ~ 3 行目は 2 種レポートそれぞれに対応しているように見えます。また最後の行の data_transfer はデータ転送の粒度を示しています。各値のレベルはチュートリアルを確認ください。ここでは fine を選択します。

xrt.ini を作ったら、次に design.cfg を以下のように変更します。

platform=xilinx_u200_xdma_201830_2
debug=1
profile_kernel=data:all:all:all

[connectivity]
nk=mmult:1:mmult_1

profile_kernel=data:all:all:all という行が追加されました。これはハードウェアリンクの段階において、パフォーマンス情報の取得を許すものです。v++ --help には、各値の意味は次のように記載されています。

• data: カーネルのデータ転送と実行のプロファイリングを有効にする。
• 1 つ目の all: 全カーネルのプロファイリングを有効にする。
• 2 つ目の all: 全 CU のプロファイリングを有効にする。
• 3 つ目の all: 全インタフェースのプロファイリングを有効にする。

続いて、新たに作った xrt.ini と design.cfg を用いてハードウェアエミュレーションを実行します。コマンドは Build and Run Hardware Emulation の 1., 2. を参照ください。

エミュレーション完了後、以下の 2 ファイルができていると思います。

• profile_summary.csv
• timeline_trace.csv

profile_summary.csv は次のコマンドで確認できます。$ vitis_analyzer -open ./profile_summary.csv これで GUI が立ち上がります。このレポートは、カーネルの実行時間やホスト・デバイス間のデータ転送についての情報を示しています。また Run Guidance ページでは、データ転送やカーネルの実行が設定された閾値を越えているかを教えてくれます。この閾値を越えたものに対しては、Vitis は改善方法を提示してくれます。

これだけ言われてもなんのことかさっぱりだと思うので 1 つ例を示します。例えば、以下のような結果が得られたとします。

図中のハイライトされた行は、この閾値を満たさず Warning が出ています。HOST_WRITE_TRANSFER_SIZE の行で Warning が出ていることから、ホストからデバイスへのデータ転送サイズが何やら良くないと言われてそうです。この行の一番右の Resolusion 列を見ると解決法が提示されます。試しに here の部分をクリックしてみると、以下のようにパフォーマンス改善のための Tip が表示されます。

以上のように、profile_summary.csv からは、パフォーマンス改善の足がかりになる情報を得ることができます。性能改善が必要なときは、ひとまずここにある改善すべき項目を一通り潰していく、ということがセオリーになるのかもしれません。

一方、timeline_trace.csv は次のコマンドで確認できます。$ vitis_analyzer -open ./timeline_trace.csv 同じく GUI が立ち上がり、カーネルの実行時間やデータ転送などを時間軸に沿って確認できます。こちらは RTL 設計者には馴染み深い？ILA の波形と同じような操作でタイムラインを追うことができます。

clFinish の部分を拡大してみると、DDR の読み書きの様子などが見て取れます。

Execute in Hardware

いよいよクライマックス、ハードウェア上での実行です。ハードウェア実行では、ホストコードはホストマシンで動作し、カーネルコードは Alveo Data Center accelerator 上で動作します。

早速ビルドしていきます。まず環境変数 XCL_EMULATION_MODE を unset XCL_EMULATION_MODE します。

あとはエミュレーションのときと同じようなコマンドを実行するだけです。今回はターゲットを U50 (xilinx_u50_xdma_201920_1) にして $ make build TARGET=hw PLATFORM=xilinx_u50_xdma_201920_1 しました。ビルドは、さすがにハードウェアをビルドしているだけあってエミュレーションとは比較にならないくらいの時間がかかります。標準出力を見ると、見慣れた Vivado のメッセージが見られ、配置配線を行っている様子がわかります。今回は 1 時間ほどで終了しました。

INFO: [v++ 60-791] Total elapsed time: 1h 15m 30s

以下のように、ハードウェアの実行も完了しました。もしカードが見つからないなどでうまく完了できなかった場合は、UG1370 などを参考に Flash のアップデートや Validation を試してみてください。

$ make run TARGET=hw PLATFORM=xilinx_u50_xdma_201920_1
emconfigutil --platform xilinx_u50_xdma_201920_1

****** configutil v2019.2 (64-bit)
  **** SW Build 2700185 on Thu Oct 24 18:45:48 MDT 2019
    ** Copyright 1986-2019 Xilinx, Inc. All Rights Reserved.

INFO: [ConfigUtil 60-895]   Target platform: /opt/xilinx/platforms/xilinx_u50_xdma_201920_1/xilinx_u50_xdma_201920_1.xpfm
INFO: [ConfigUtil 60-1578]   This platform contains Device Support Archive '/opt/xilinx/platforms/xilinx_u50_xdma_201920_1/hw/xilinx_u50_xdma_201920_1.dsa'
emulation configuration file `emconfig.json` is created in current working directory
./host mmult.hw.xilinx_u50_xdma_201920_1.xclbin
Found Platform
Platform Name: Xilinx
INFO: Reading mmult.hw.xilinx_u50_xdma_201920_1.xclbin
Loading: 'mmult.hw.xilinx_u50_xdma_201920_1.xclbin'
TEST PASSED

終わりに

本稿では 2019/11/01 (JST) にリリースされた Vitis のインストールから GitHub 上のチュートリアル Building the Accelerated Application – Essential Concepts までを実践しました。ここで紹介したものの後には Your First Program, Optimizing Accelerated FPGA Applications — Based on Vitis Environment Methodology の 2 つのチュートリアルがあります。チュートリアル以外にも、Vitis には RTL カーネルの取り込みや Vitis Libraries など多数の機能が存在します。それらについても試してみて、Vitis 力を高めていきたいと思います。

このサイトはスパムを低減するために Akismet を使っています。コメントデータの処理方法の詳細はこちらをご覧ください。