このページの目的

Vitis HLS に Vitis Vision Library を導入し、サンプルデザインを実行するまでのセットアップについて解説していきます。

実は、セットアップ方法については以下の公式ページ

で説明がなされています・・・が、この説明の通りに作業をしてもほとんどの場合何らかのエラーが発生し、まともに動かないはずです。
そこで、本ページでは導入の流れと起こりうるエラーと解決法について特に力を入れて解説していきたいと思います。

なお、この記事は大学の研究室内wikiに投稿したドキュメントを移植したものです。
したがって、Xilinx Vitis HLS のライセンス取得等についてはこの記事の対象外です。

使用バージョン

各アプリケーションのバージョンは以下の表の通りになっているものとします。なお、「*」の付いているものについては、この後詳しく解説します。

アプリケーション	バージョン
Operating system	Ubuntu 20.04.3 LTS
gcc/g++-9	9.3.0
gcc/g++-7*	7.5.0
cmake*	3.21.2
Vitis HLS	2021.1
Vitis Vision Library	2021.1
OpenCV	4.4.0

Vitis Vision Libraryとは?

Vitis Vision Library という言葉は、Xilinx 社が提供してる Vitis Libraries の vision フォルダを指しています。

私は画像処理系を研究している学生なので Vitis Vision Library のみを取り上げますが、 Vitis Libraries では数学・統計・線形代数・画像処理などの複雑な処理を伴うIPを作るためのライブラリが提供されており、FPGAで何かしたいと思う方の役に立つはずです。

なお、 Vitis Vision Library はデバッグ環境に OpenCV を用いる関係上、 Vitis HLS と OpenCV 間でいろいろな不具合が起こる可能性があり、導入が難しい理由となっています。

インストール編

0. 知っておいてほしい "which" コマンドの話

whichコマンドとは、「コマンドのフルパス」を調べるためのコマンドです。

実は、Vivado / Vitis / VitisHLS のインストール時に <installation path>/Xilinx/Vitis/2021.1/settings64.sh を実行したことによって環境変数が書き換わっており、 cmake コマンドなどは実行時のパスが変更されている可能性があります。

したがって、"which" コマンドを利用して、「自分は /usr/local/bin/cmake と /Xilinx/Vitis/2021.1/tps/lnx64/cmake-3.3.2/bin/cmake のどちらのcmakeを使っているのか」を意識して作業してください！

なお、PATHを変更することでコマンドの探索順番を変更し、cmakeコマンドが /usr/local/bin/cmake を指すようにできるはずです。

1. 複数バージョンのgcc/g++を使い分けられるようにする

理由
Vitis HLS は Ubuntu に標準搭載されているgcc/g++-9でビルドしたOpenCVを使うことができないから¹

方法
How to switch between multiple GCC and G++ compiler versions on Ubuntu 20.04 LTS Focal Fossa を参考に、update-alternatives コマンドで gcc/g++-7 と gcc/g++-9 を使い分けられるようにしてください。

2. cmakeのバージョンを上げる

理由
Ubuntu に標準搭載されている cmake-3.1? では OpenCV をビルドすることができないから

方法
How to upgrade cmake in Ubuntu を参考に、cmake のバージョンを上げてください。

なお、apt remove する際は 0. 知っておいてほしいwhichコマンドの話に注意して、/usr/bin (もしくは /usr/local/bin)の cmake を消すようにしてください。

3. OpenCVをインストールする

方法
docs.opencv.org の Build core modules と Install セクションを実行して OpenCV をビルド・インストールします。

注意点

Vitis Vision Library 2021.1 では動作確認が Opencv 4.4.0 までされています。したがって、'''Build core modules''' 中のコマンド列を以下の様に変更してください。

インストールのためのコマンド列

## Install minimal prerequisites (Ubuntu 18.04 as reference)
sudo apt update && sudo apt install -y cmake g++ wget unzip

## Download and unpack sources
# wget -O opencv.zip https://github.com/opencv/opencv/archive/master.zip
wget -O opencv.zip https://github.com/opencv/opencv/archive/refs/tags/4.4.0.zip
unzip opencv.zip

## Create build directory
mkdir -p build && cd build

## Configure
cmake  ../opencv-master

## Build
cmake --build .

ビルド・インストールの際は、1. 複数バージョンのgcc/g++を使い分けられるようにするを参考にして、gcc-7を使って ビルドしてください。また、cmake は 2. cmakeのバージョンを上げるでインストールした /usr/local/bin/cmake の方の cmake を使ってください。

Vitis Vision Library のインストールに失敗する原因の大部分は、OpenCVをビルドする gcc のバージョン違いによるものです。

sudo apt install libopencv-dev などの方法でOpenCVをインストールすることは非推奨です。後に使う /lib フォルダや /include フォルダが生成されない恐れがあります。

4. Vitis Vision Libraryを導入する

方法
Vitis Vision Library の github リポジトリからお好みの場所に clone もしくはダウンロードしてくれば大丈夫です。

補足
シンボリックリンクを張ってしまうと、

リンク元の /vision/L1 を読み込む → リンク先の /vision/L1 を読み込む → 多重定義されてるよ！

というエラーが発生してしまうのでご注意ください。（1敗）

5. libOpenCL.so をインストールする

Vitis Vision Libraryの公式ページで

libOpenCL.so must be installed if not present along with the platform.

と書いてあるので、How to install libOpenCL.so on ubuntu を参考にしてインストールしてください。

6. 環境変数（LD_LIBRARY_PATH）を設定する

Vitis Vision Libraryのgithub で

Open a terminal and update the LD_LIBRARY_PATH to point to OpenCV lib folder.

と書いてあるので、~/.bashrc で環境変数 LD_LIBRARY_PATH を登録してください。

7. 後片付け

以上でインストールは完了です。

cmake のパスを Vitis のインストール時に戻したり、update-alternatives コマンドで gcc/g++ のバージョンを gcc/g++-9 に戻したりして後片付けを行いましょう。

利用編

とりあえず、getting-started-with-hls の Use the following steps to operate the HLS Standalone Mode using GUI: セクションをやってみましょう。

補足

上記の例では dilation プロジェクトを動かしています。
dilation プロジェクトの accel.cpp ファイルは 4. Vitis Vision Libraryを導入するで導入した Vitis Libraries の vision/L1/examples/dilation フォルダ内にある xf_dilation_accel.cpp ファイルのことです。
途中で -std=c++0x と設定する場所がありますが、これではエラーが出ます。-std=c++14 としてください。
ここまでのインストールが成功していれば、上記ページで設定すべきパスの場所はこのようになっているはずです。

パスの名前	場所
<path-to-L1-include-directory>	Vitis Libraries の vision/L1/include
<path-to-opencv-include-folder>	/usr/local/include/opencv4
<path-to-opencv-lib-folder>	/usr/local/lib

Vitis HLS のファイル探査機能 ² の動作原理は非常に謎です。具体的にはソースコード編集時はinclude先のファイルにジャンプできている（つまりinclude先が分かっている）のに、ビルド時に「include元のファイルに到達できません」というエラーがしばしば発生します。これは Vitis HLS のファイル探索と Vitis HLS がビルド時に用いる gcc のファイル探索が別々になっていることが理由だと思います。きちんと -L, -I オプションを設定したり、最悪 Vitis HLS を起動しているディレクトリにファイルを置いたりして、gcc のご機嫌を損ねないようにしましょう。

トラブルシューティング編

ERROR: [HLS 207-812] 'asm/errno.h' file not found: /usr/include/linux/errno.h:1:10

原因
/usr/include/asm が存在していない。

解決策
やや強引ですが、/usr/include/asm -> /usr/include/asm-generic のシンボリックリンクを張ることで解決できます。

/usr/local/lib/libopencv_core.so: undefined reference to `std::__cxx11::basic_stringstream, std::allocator >::basic_stringstream()@GLIBCXX_3.4.26

原因
おそらく、3. OpenCVをインストールするの際にgcc/g++-7 を使っていなかったことが原因です。³

これは、/usr/local/lib/libopencv_core.so のシンボリックリンクを辿っていくと、OpenCV のビルド・インストール時に作成された /usr/local/lib/libopencv_core.so.4.4.0 等のファイルに行きつくことから分かります。

解決策
gcc-7 を使って OpenCV を再ビルド・インストールし、libopencv_core.so のシンボリックリンクを再インストールして作成された libopencv_core.so.4.#.## に張りなおせば解決できます。

/usr/local/lib/libopencv_imgcodecs.so: undefined reference to `std::__cxx11::basic_stringstream, std::allocator >::basic_stringstream()@GLIBCXX_3.4.26

原因と解決策
上と同じです。gcc-7を使って OpenCV をビルド・インストールし、シンボリックリンクを張りなおせば解決します。

Vitis HLS 2021.1は内部でgcc4.6.3とgcc6.2.0を使用しています ↩
インクルード機能とかリンク機能と言ったほうがいいのかもしれません ↩
Vitis HLS が使っているバージョンの gcc にとって未知の命令が現れてしまったという感じなのでしょうか ↩