ビジョンライブラリをVitis HLSにインクルードする方法(1)

本記事の概要
OpenCVの環境構築
次回の記事のリンク
参考：開発環境
参考にさせていただいたサイト

本記事の概要

概要

Windows環境において、Vitis HLSにVitisビジョンライブラリと、テストベンチ検証用のOpenCVをインクルードする方法について解説。画像処理関数を高位合成する環境を構築する。
本記事では、OpenCVの環境構築までを解説する。

Vitisビジョンライブラリは、Xilinx社が提供しているVitisライブラリのうち、画像処理に特化したライブラリを指します。
Vitisライブラリは、Open Sourceのライブラリで、線形代数やソルバー、画像処理など、各機能に特化したAPI関数が含まれる開発ツールです。このツールを使って、ソフトウェアで記述したプログラムをFPGAのロジックに合成して、処理を高速化(アクセラレーション)することが可能です。

Vitis ライブラリ

Vitis ソフトウェアプラットフォームには、既存のアプリケーションにわずかなコード変更を加えるだけですぐに高速化を実現できる、最適化されたオープンソースライブラリが多数含まれています。アルゴリズムをゼロから再実装する必要がなく、当社の適応性に優れた演算機能を活用できます。

Vitisライブラリは、必要とする抽象度によって異なる3種類のディレクトリが含まれます。本記事で対象とするのは、Vitis Library Primitives (L1)です。

Vitis Libraryに含まれる3種のディレクトリ

Vitis Library Primitives (L1)：最も基本的(低レイヤー)なビルディングブロックで、Vitis HLSで、C/C++の記述をVivadoにインポートするIPに高位合成(HLS)するのに使用できます。
Vitis Library Kernels (L2)：Vitis上で直接呼び出せるように必要なインタフェースがすでに用意された最適化済みの関数。ホストコードが必要でVitisでビルドすれば使用できます。
Vitis Library API (L3)：ホストアプリケーションで直接呼び出し可能なAPI。プリコンパイル済み。

参照元：https://www.xilinx.com/support/documentation/university/Vitis-Workshops/2019_2/vitis_accelerated_libraries.pdf

ビジョンライブラリにおけるVitis Library Primitives (L1)をVitis HLSで使用する場合、OpenCVのライブラリを別に準備することが必要です。
高位合成のみであればビジョンライブラリのみをインクルードすればよいのですが、高位合成対象の関数をテストベンチで検証するためにはOpenCVライブラリを別にインクルードしておくことが必要です。
※テストベンチでOpenCVの関数を呼び出さずに検証することもできるので、OpenCVライブラリのインクルードは必須ではありません。ただし、ビジョンライブラリのexampleは OpenCVライブラリの関数を呼び出しているのでインクルードしておくことを推奨します。

実際に、ビジョンライブラリから高位合成する方法は以下の記事をご覧ください。

Vitis HLSにOpenCVライブラリをインクルードして環境を構築するのはひと手間かかります。
私も何度かエラーが発生するなか、やっとテストベンチシミュレーションと高位合成を行うことができました。
そこで、本記事ではVitis Vision Libraryの高位合成の環境・OpenCVのテストベンチ環境を、Windows10のVitis HLSに構築する方法を解説したいと思います。

本記事の対象読者：以下の状況に直面している方

すでにVitis HLSの開発環境は構築済みで、Vitisビジョンライブラリを新たに追加したい
OpenCVのインクルードでエラーが発生している

Xilinxが公開する以下のページを参考にしています。このページ通りに進めれば、ビジョンライブラリとOpenCVを使えるようになるのですが、私が詰まったところを含め、説明を追加していきたいと思います。

https://support.xilinx.com/s/article/75727?language=ja

OpenCVの環境構築

まず、Vitis HLSにインクルードするためのOpenCVのライブラリ・ファイルをMinGW(Minimalist GNU for Windows)でリビルドします。
OpenCVのリビルドはVisual Studioでも可能ですが、私の環境ではVitis HLSでCリンクエラーが発生し、うまくライブラリ・ファイルをリンクできませんでした。そこで、Visual StudioではなくMinGWを使用しています。

まず、前準備としてOpenCVのライブラリ・ファイルのリビルドを行うツールのインストールを行い、OpenCVのソースファイルのダウンロード、そしてリビルドを行います。

おすすめ書籍

ソースコードをコンパイルしてから、OpenCVのようなライブラリファイル(lib, dll)をリンクし、実行ファイルを作成する流れについては、以下の書籍がおすすめです。よく知っている人にとっても、改めてソースコードからCPUが実行可能な機械語で記述された実行可能ファイルまでを作成する一連の処理を整理するのに有用です。私は第2版を持っていますが、2021年に発売された第3版ではPythonでの機械学習の章が追加されているので改めて買いなおそうかと思っているところです。

プログラムはなぜ動くのか第３版　知っておきたいプログラミングの基礎知識

created by Rinker

同シリーズの「コンピュータはなぜ動くのか」と一緒に読んで全体的な知識を広く浅くつけた後なら、より詳しいパターソン＆ヘネシーの教科書「コンピュータの構成と設計」が読みやすくなり、理解も深まると思います(…といいつつ、パターソン＆ヘネシーの教科書はまだまだ私も勉強中)

コンピュータはなぜ動くのか　知っておきたいハードウエア＆ソフトウエアの基礎知識

created by Rinker

コンピュータの構成と設計　MIPS Edition　第6版　上

created by Rinker

※パターソン＆ヘネシーも2021年11月に新版が発売されたとのことです

前準備

インストールするツールは、次の2つです。すでにインストールしてあれば、それぞれ省略可能です。

事前にインストールするアプリケーション

MinGW-w64：Windows(64bit版)上で使えるGCC(GNU Compiler Collection)環境。ソースコードからビルドを実行するために使用。
CMake：Makefileを自動生成するビルド支援ツール。Makefileとは、コンパイルしたいソースファイルやファイル間の依存関係などの管理ルールを記述したファイル。

今回インストールするCMakeとMinGWの位置づけは次の図の通りです。

MinGW-w64のダウンロード＆インストール

MinGW-w64のインストーラのダウンロード

MinGW-w64のインストーラを次のリンク先からダウンロードします。

MinGW-w64

GCC for Windows 64 & 32 bits

リンク先で、左上の[Downloads]をクリックします。

ダウンロード可能なインストーラがあります。
今回はWindows向けのインストーラ[MingW-W64-builds]をダウンロードします。

リンクをクリックすると、ダウンロードできるサイトを選択できます、今回はSourceforgeを選択しました。

次の画像のようなページに遷移し、ダウンロードが始まるので、しばらく待ちましょう。

MinGW-w64のインストール

ダウンロードできたら、インストーラを起動します。[Next]をクリックします。

64bit版のWindowsを使用しているので、Architectureは[x86_64]を選択します。[i686]のままでは、リンクエラーが発生します。
それ以外の項目はデフォルトのままで問題ありません。

インストール先を選択します。特に変更なくデフォルトのままで問題ありません。

インストールが始まるので少し待ちます。すぐにインストールは完了すると思います。
[Finish]を押してインストールを完了しましょう。

最後に、コマンドラインでMinGWを実行できるように環境変数を定義しましょう。
左下の検索窓で[システム環境変数]と検索し、[システム環境変数の編集]を選択します。

システムのプロパティというウィンドウが立ち上がるので、右下の[環境変数]を選択します。

環境変数の編集を行います。システム環境変数のPathを選択して[編集]をクリックします。

環境変数の編集というウィンドウが立ち上がったら、[新規]を選択し、新しく以下のpathを追加します。

C:\Program Files\mingw-w64\x86_64-8.1.0-posix-seh-rt_v6-rev0\mingw64\bin

ここに追加するpathは先ほどインストールしたMinGW-w64のインストールディレクトリのうち、gccやg++などの実行ファイルが格納されたディレクトリです。
次の画面のようにコマンドプロンプト上でgccとmingw32-makeを起動することができるようになれば、成功です。

CMakeのインストール

次に、CMakeインストーラを次のリンク先からダウンロードします。

CMake - Upgrade Your Software Build System

CMake is a powerful and comprehensive solution for managing the software build process. CMake is the de-facto standard for building C++ code, with over 2 millio...

リンク先で、右上の[Download]をクリックします。

いくつかあるインストーラのうち、最新の64bit版のインストーラWindows x64 Installerを選択します。

しばらく待つとダウンロードが始まるので、完了するまで待ちましょう。

CMakeのインストール

ダウンロードが完了したら、インストーラを起動します。[Next]をクリックします。

利用許諾を読み同意出来たら、チェックを入れ[Next]をクリックします。

[Add CMake to the system Path for all users]にチェックを入れました。このチェックを入れることによって、コマンドプロンプトからCMakeを起動できるようになります。
ただし、今回、CMake-GUIを起動するので、PathにCMakeを追加しなくても([Do not add CMake to the system PATH]を選択)、問題ありません。
選択できたら、[Next]をクリックします。

インストールディレクトリを選択し、[Next]をクリックします。

[Install]をクリックします。

インストールが始まりますのでしばらく待ちます。完了したら、[Finish]をクリックします。

[Add CMake to the system Path for all users] を選択し、PathにCMakeを追加したので、次のようにコマンドプロンプトからCMakeを起動できるようになります。

以上で、前準備は完了です。

OpenCVのダウンロード

では、引き続きOpenCVのソースコードをダウンロードします。
次のOpenCVのページから、ソースコードをダウンロードします。

Home

OpenCV provides a real-time optimized Computer Vision library, tools, and hardware. It also supports model execution for Machine Learning (ML) and Artificial In...

リンク先で、右上の[Library]をクリックし、[Releases]を選択します。

Vitis 2021.1以降は、動作確認がOpenCV4.4.0までなされています。そこで、今回はOpenCV4.4.0のWindows版を選択し、ダウンロードします。いくつかバージョンがあるので、スクロールして OpenCV4.4.0のWindowsを選択します。

クリックすると、ダウンロードが始まります。

インストーラを開くと、ソースコードの展開先ディレクトリを選択することができます。
適切なフォルダ(OPENCV_ROOT)を選択し、[Extract]をクリックします。私の場合はディレクトリ( OPENCV_ROOT = C:\opencv_hls )に展開しました

指定したディレクトリ( OPENCV_ROOT )に次のようにソースコードとビルド済みのファイルが格納されます。
ビルド済みのファイル([build]フォルダ)はVisual Studio向けにビルドされているので、今回は使用しません。

OpenCVのリビルド

次に、OpenCVのソースコードを用いて、MinGW向けに新しくライブラリファイルをビルドしていきます。

CMakeでMakefileを作成

前準備でインストールしたCMakeを使ってMakefileを作成します。
Makefileはソースコードをビルドするために必要な情報をまとめたファイルと思えば問題ありません。

GUIを使って視覚的に設定ができるCMake-GUIを立ち上げます。
GUIが立ち上がったら、ソースコードの格納元のディレクトリとビルドした後のライブラリファイルを格納する格納先のディレクトリ(新たに作成)を、それぞれ図のように指定します。
格納先のディレクトリ名は[build_mingw]としました。

Pathの指定

Where is the source code: OPENCV_ROOT \sources
Where to build the binaries: OPENCV_ROOT \buid_mingw (新規作成)

OPENCV_ROOT = C:\opencv_hls

本記事では、OpenCVをビルドしたパスを次のように、 OPENCV_BUILD_PATH と表記します：
OPENCV_BUILD_PATH = OPENCV_ROOT \buid_mingw

ディレクトリの指定が完了したら、[Configure]をクリックします。
すると、ビルドの際に用いるコンパイラの種類を選択できるので、[MinGW Makefiles]を選択し、[Finish]をクリックします。

Configureが終わると、未解決の項目が赤網掛けで表示されるはずです。
ここからMakefileに記述するビルドの設定を行います。

私はOPENCV_ENABLE_ALLOCATOR_STATSのチェックのみ外し、それ以外はデフォルトのままにしました。

OPENCV_ENABLE_ALLOCATOR_STATSのチェックを入れたままだとどうなる？

チェックを入れたままだと、ビルドのときに次のエラーが発生します。

gcc: error: long: No such file or directory
C:\PROGRA~1\MINGW-~1\X86_64~1.0-P\mingw64\bin\windres.exe: preprocessing failed.
make[2]: *** [modules/core/CMakeFiles/opencv_core.dir/vs_version.rc.obj] エラー 1
make[1]: *** [modules/core/CMakeFiles/opencv_core.dir/all] エラー 2
make: *** [all] エラー 2

以下の記事に解説されているように、 OPENCV_ENABLE_ALLOCATOR_STATS のチェックを外せばエラーを回避できます。

https://answers.opencv.org/question/228737/gcc-error-long-no-such-file-or-directory/

CMakeの設定が完了したら、もう一度[Configure]をクリックすれば、赤網掛けが消えるはずです。消えていない項目があれば、設定を見直してください。
すべて消えていれば、[Generate]をクリックし、Makefileを生成します。

Generateも完了すれば、以上でCMakeでの操作は完了です。

ビルドを実行

では、Makefileを用いて、実際にOpenCVのソースコードをビルドしていきましょう。
コマンドプロンプトを起動し、cdコマンドでMakefileを生成したディレクトリ( OPENCV_BUILD_PATH )に移動します。そして、mingw32-make installでビルドを行います。
最後に追加したinstallというオプションは、ビルドしたライブラリファイルとソースコードのincludeファイルをinstallというディレクトリにまとめるためです。

例えば、私の場合は

$ cd C:\opencv_hls\opencv\build_mingw
$ mingw32-make install

ビルドまで長時間(1時間程度)かかりますので、ゆっくりと待ちましょう。
100%まで達成するとビルドが完了です。installオプションを追加していると、この後にinstallディレクトリへの移動が一気に行われます。

最後に、作成したOpenCVのライブラリファイルをシステム環境変数に追加しましょう。
ビルドファイルのinstallディレクトリの中に次の画像のように作成したダイナミックリンクライブラリ(dll)が格納されているはずです。このダイナミックリンクライブラリのpath( OPENCV_BUILD_PATH \install\x64\mingw\bin )を追加します。

例えば、私の場合、 OPENCV_BUILD_PATH = C:\opencv_hls\buid_mingw と指定したので、ダイナミックリンクライブラリのパスはC:\opencv_hls\opencv\build_mingw\install\x64\mingw\binです。

このpathをMinGWのときと同様に、システム環境変数に追加します。