Intel® VTune™ Amplifierを使ってFPGAを解析するチュートリアル

皆さんは、Intel® VTune™ Amplifier(以下 VTune™)でFPGAの解析をしてますか？
実はVTune™はすでに利用するだけ(Community Forum Support)であれば、無償で利用することができます。
また、FPGAについてもまだプレビューの段階ですが利用することができます。
意外と知られていないこの機能の実行までをスクリーンショットを交えながら説明したいと思います。
  
使った環境に関しては、下記の通りです。
FPGAとしては、Intel® FPGA PACを利用していますが、既存のFPGA開発キットでも同様に利用可能です。

テスト環境

+ OS : Ubuntu18.04  
+ Acceleartion Stack : 1.2.1 PV (本記事ではここの部分のインストールは割愛)
+ FPGA : Intel® Programmable Acceleration Card with Intel® Arria® 10 GX FPGA (Intel® PAC with Intel® Arria® 10 GX FPGA)
+ AOCL Version : 20.3.0.158
+ VTune™ Version : 2020 Update 3

## VTune™のインストール
まずは、VTune™のインストール・ダウンロードを行います。[ダウンロードページ][LINK_VTune_Download]にアクセスします。

![vtune-download.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/698105/4c2c4761-f651-572d-c283-4b8da948eb64.png)

"Download"のボタンを押すと、名前やメールアドレス、会社名、国、職種について聞かれるので、これらを入力してSubmitします。入力が終わると、次のような選択画面になるので、Intel® VTune™ Profiler for Linux*とバージョンを選択すると、vtune_profiler_XXXX_updateX.tar.gz(XXXXはバージョン, update)と書かれたボタンが出てきます。
今回は執筆時最新版、*2020 Update 3* を利用しました。

![vtune-select.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/698105/7b9cc22b-fca0-f597-ce5f-7bf89784a5b8.png)

このダウンロード・ファイルをFPGAを実行するサーバーに転送します。
ここからはコマンドラインで作業します。tar解凍して、解凍後のディレクトリーに入ります。

```
$ tar zxf vtune_profiler_2020.tar.gz
$ ls
vtune_profiler_2020.tar.gz  vtune_profiler_2020_update3
$ cd vtune_profiler_2020_update3; ls
install_GUI.sh  install.sh  license.txt  pset  PUBLIC_KEY.PUB  rpm  silent.cfg  support.txt
```

ここにある、install.shを実行します。ドライバー等もインストールするので、基本的にはsudoないしはsuperuser権限で実行します。

```
$ sudo ./install.sh
```

ライセンス規約等に合意した後、パッケージの確認が行われた後にデフォルトのインストール設定が出てきます。
もしインストール・ディレクトリーなど、設定をカスタムするときはここで変更してください。
今回は特に必要ないので、そのまま"Enter" でインストールしました。  
問題なく終了すれば、Sampling driver boot script installed successfullyと表示され、Press "Enter" key to continueと出てくるので、Enterを入力して次に進みます。
最後にガイドが出てくるので、必ず読みましょう。環境変数などの設定をしてくれるスクリプトへのPathが書いてあります。
私の場合はこれでbashなので、以下でした。

```
 $ source /opt/intel/vtune_profiler/vtune-vars.sh
```

その他細かい部分は下記ドキュメントをご参照ください。
[Intel® VTune™ Profiler Installation Guide - Linux* Host][LINK_VTune_Installation_Guide_Linux]

## OpenCL™ コンパイラーの準備
最近のpenCL™コンパイラーはBSP(Board Support Package)の[後方互換性をサポートしています][LINK_Backward_Compatible]。そのため、OpenCL™コンパイラーとしては最新バージョンを利用することが可能です。2020年11月執筆現在、最新バージョンは*v20.3*だったので、それを利用しました。

後方互換を利用する時は、OpenCL™コンパイラーのみをインストールしますが、インストール手順が少し複雑なので説明します。
まずは[ここ][LINK_Quartus_Download] にアクセスします。
※ Intel® FPGA SDK for OpenCL™ではなく、Quartus Prime Pro Editionと書かれているのが正しいです。

![quartus-select.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/698105/307a9f3d-921f-fc84-9af6-eddaae516470.png)

Individual Filesの中から、Intel FPGA SDK for OpenCL™ Pro Editionを探してダウンロードします。
こうすることで、OpenCL™コンパイラーのみをダウンロードすることができます。
ファイルのダウンロードにはインテル®のアカウントが必要になりますので、登録/サインインした後にダウンロードします。
ダウンロードができたら、実行権限を付与してインストールします。

```
$ chmod +x ./AOCLProSetup-20.3.0.158-linux.run
$ sudo ./AOCLProSetup-20.3.0.158-linux.run
```

sudoはディレクトリー・パスによっては必須ではありません。今回は、*/opt/intelFPGA_pro/20.3*を指定しました。
インストール完了後にディレクトリーを見てみると、確かにhld(OpenCL™コンパイラー)関連のディレクトリーしかできていません。

```
$ ls /opt/intelFPGA_pro/20.3/
hld  licenses  logs  uninstall
```

Pathの設定はIASについているinit_env.shから*INTELFPGAOCLSDKROOT*の変更と
*QUARTUS_ROOTDIR_OVERIDE*の環境変数を追加したカスタムスクリプト(custom_init_env.sh)を用意するのがおすすめです。

```
export INTELFPGAOCLSDKROOT="/opt/intelFPGA_pro/20.3/hld" #24-25行目付近の記述を変更
export QUARTUS_ROOTDIR_OVERIDE=$QUARTUS_HOME #最終行に追加
```

これでOpenCL™の後方互換機能を利用することができます。

## FPGAのコンパイルと実行

PATHの設定ができたら、aocというOpenCL™コンパイラー用のコマンドを使ってコンパイルします。
今回は/opt/intelFPGA_pro/20.3/hld/examples_aoc の下にあるvector_addを元に説明します。
まずは作業用ディレクトリーにファイルをコピーします。

```
$ cp -r $INTELFPGAOCLSDKROOT/examples_aoc/vector_add $INTELFPGAOCLSDKROOT/examples_aoc/common ./
```
VTune™を使う時には、["-profile"オプションを追加してコンパイルします。][LINK_VTune_Option]

```
$ cd vector_add
$ aoc -profile device/vector_add.cl -o bin/vector_add.aocx
```

続いて、Intel® FPGA PACではSecurity Featureが導入されていますので、[必要に応じて署名を行います][LINK_IntelPAC_OpenCL]。(FPGA開発キットを利用している場合にはこの手順は不要です。)
Root Entry Hashを導入していない場合には以下のようなコマンドで実行可能です。

```
$ AOCL_BOARD_PACKAGE_ROOT/linux64/libexec/sign_aocx.sh -H openssl_manager \
-i vector_add.aocx -r NULL -k NULL -o unsigned_vector_add.aocx
```

※ 途中で2回、鍵なしで生成するかどうか確認されるので、どちらも"Y"を入力します。
ここで生成された、unsigned_vector_add.aocxというファイルが実際に書き込み可能なファイルになりますので、書き込んでみます。

```
$ aocl program acl0 unsigned_vector_add.aocx
aocl program: Running program from /opt/inteldevstack/a10_gx_pac_ias_1_2_1_pv/opencl/opencl_bsp/linux64/libexec
Program succeed.
```

"Program succeed"が出れば成功です。
この時点ですでにアプリケーションは実行可能なので、必要に応じてホスト・アプリケーションのコンパイルと実行も行ってみてください。

```
$ make
$ cd bin;./host
```

## VTune™による解析
VTune™を使った解析には現在大きく分けて2つのパターンがあります。  

1. FPGAのカーネルレベル  
    FPGA内(=カーネルコード)の最適化をする場合に利用
2. システム(OpenCL™ API)レベル  
    システムレベル(=ホストコード)の最適化をする場合に利用
    
両者は少しずつ使い方が異なりますので、それぞれ説明します。
開発フローとしては、1. にてFPGA最適化をした後に、2. をホスト側を含めたアプリケーション全体の最適化を行うのが理想的です。

### FPGAのカーネルレベルでの解析
カーネルレベルのより詳細な解析を行いたい場合は、先にアプリケーションを実行しておくことでFPGAのプロファイルをとります。具体的には、

```
$ mkdir exec; cd exec
$ cp ../host ../vector_add.aocx ./
$ aocl profile -x vector_add.aocx ./host
```

と実行すると、profile.jsonおよびprofile.monという解析用のファイルが出力されます。
ディレクトリーを作る理由としては、後にVTune™側でディレクトリーごとImportして解析するので、そのままだとIntel® Quartus®のプロジェクトなど不要なものも入ってしまうので、それを除外するためです。
面倒に感じれば、そのまま実行でも問題ありません。

```
$ ls
host  profile.json  profile.mon  vector_add.aocx
```

実行ができたら、VTune™を起動します。

```
$ sudo su
# vtune-gui #custom_init_env.shおよびvtune-vars.shを実行した後
```

VTune™を実行する際は、Root Userで実行するのがおすすめです。
初回起動時はWorking Directoryを尋ねられるので、任意のディレクトリーを指定し、その後Create a Projectでプロジェクトを作成してください。  
プロジェクト作成後は上部にあるアイコンの中から"Import Result"というのを選択します。(下画像参照)
選択すると、画像のような画面が出てくるはずです。


![kernel-level-analysis.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/698105/aba42299-98a0-7d91-5ead-1af9fe4ae2b7.png)

"Import multiple trace files form a directory"のチェックボックスにチェックを入れて、先ほどのprofile.monやprofile.jsonを入ったディレクトリーを指定します。
問題なくインポートされれば、Summary, Bottom-up, Platformのタブが出現し解析結果が表示されます。
  
  ![kernel-level-result.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/698105/7aad77c5-5ced-b780-d6b3-12d71b9ec88e.png)


従来あったOpenCL™ Profilerと同様にこちらでは、実機を用いた場合のカーネル内のメモリアクセスの様子が表示されます。
(わかりやすくするために、イテレーション数Nを増やしてわかりやすくしています。)
画像をみると、ストールが全くおこらずに理想的な動きをしていることがわかります。

### OpenCL™ API(システム)レベルでの解析
続いて、アプリケーション全体の解析のパターンを紹介します。先ほどと同様、VTune™を起動した後、Projectを開きます。

```
$ sudo su
# vtune-gui #custom_init_env.shおよびvtune-vars.shを実行した後
```

"Configure Analysis"のボタンを押します。（上部のアイコンなど)
こちらはCPUをメインに解析するものになりますので、適切にオプションを設定することは可能です。

"FPGA profiling data source"では、"OpenCL Profiling API"を選択してください。
"AOCL Profiler"はoneAPI用のプロファイラーになります。

![api-level-analysis.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/698105/2005bb40-81c1-7fcc-d4af-49fa7ac8e59b.png)

設定を完了したら、下部にある再生ボタンのようなものを押すとアプリケーションの実行、解析が行われます。
実行後は、先ほどと同様にSummary, Bottom-up, Platformの3つが出現します。

![api-level-result.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/698105/89d78b7c-d7e1-a0cf-1e76-ea0e9257c272.png)

  
こちらでは、OpenCL™のCommand Queueの様子がよくわかります。一方で、FPGA内の詳細な動作については得ることができません。
そのため、状況に応じて使い分ける必要があります。


今回はVTune™を利用して、実行してみるまでを紹介しました。
詳しい見方など使い方に関しては、[Intel FPGA SDK for OpenCL Pro Edition: Best Practices Guide][LINK_OpenCL_Best_Practice]
をご覧ください。


## References

+ [Intel® VTune™ Profiler Installation Guide - Linux* Host][LINK_VTune_Installation_Guide_Linux]
+ [Choose & Download Intel® VTune™ Profiler][LINK_VTune_Download]
+ [Download Center for FPGAs][LINK_Quartus_Download]
+ [Intel FPGA SDK for OpenCL Pro Edition: Getting Started Guide][LINK_Backward_Compatible]
+ [Intel® VTune™ Profiler User Guide CPU/FPGA Interaction Analysis (Preview)][LINK_VTune_Option]
+ [OpenCL on Intel Programmable Acceleration Card with Intel Arria 10 GX FPGA Quick Start User Guide][LINK_IntelPAC_OpenCL]
+ [Intel FPGA SDK for OpenCL Pro Edition: Best Practices Guide][LINK_OpenCL_Best_Practice]



[LINK_VTune_Installation_Guide_Linux]: https://software.intel.com/content/www/us/en/develop/documentation/vtune-install-guide-linux/top.html
[LINK_VTune_Download]: https://software.intel.com/content/www/us/en/develop/tools/vtune-profiler/choose-download.html

[LINK_Quartus_Download]: https://fpgasoftware.intel.com/?edition=pro
[LINK_Backward_Compatible]: https://www.intel.com/content/www/us/en/programmable/documentation/mwh1391807309901.html#mjm1541100073442  

[LINK_VTune_Option]: https://software.intel.com/content/www/us/en/develop/documentation/vtune-help/top/analyze-performance/accelerators-group/cpu-fpga-interaction-analysis-preview.html

[LINK_IntelPAC_OpenCL]: https://www.intel.com/content/www/us/en/programmable/documentation/fvf1521490619217.html#cgy1522340402284

[LINK_OpenCL_Best_Practice]: https://www.intel.com/content/www/us/en/programmable/documentation/mwh1391807516407.html


### Notices & Disclaimers

Intel technologies may require enabled hardware, software or service activation.
No product or component can be absolutely secure. 
Your costs and results may vary. 

© Intel Corporation.  Intel, the Intel logo, and other Intel marks are trademarks of Intel Corporation or its subsidiaries.  Other names and brands may be claimed as the property of others. 

The products described may contain design defects or errors known as errata which may cause the product to deviate from published specifications.  Current characterized errata are available on request.​