oneAPIを試してみる

12/8に、oneAPI、正確にはIntel® oneAPI toolkitsの正式版がリリースされました（若干もって回った書き方をしているのは、oneAPIはあくまでもオープンなスタンダードであって、Intel®がリリースするのはIntel®のoneAPI実装に過ぎないからです。スタンダードとしてのoneAPIはoneapi.comで参照できます）。これまでもBeta版という形で誰でも評価可能になっていましたが、ようやく正式版（Gold版とか呼んでます）となったようです。
oneAPIには、直接コーディングして開発するためのData Parallel C++(以下DPC++）と呼ばれるコンパイラと、APIを呼んで開発を進めていくためのライブラリ群という、２つの大きな構成要素があります。現状FPGAについてはライブラリの拡充が進んでおらず、そのため今のところは、oneAPIをFPGAで使うイコールDPC++を使うということになります。
ここでは、皆さんにoneAPIというかDPC++を触ってもらうべく、その導入部分についてざっと解説したいと思っています（以下、oneAPIとDPC++という言葉が混在しますが、ほぼ同じ意味と思っていただいて大丈夫です。一応ニュアンス等で使い分けてますが）。例によって、公式ドキュメント等が英語で読みづらかったり、あまり分かりやすいものにはなっていないので…

現状、DPC++を触るには、以下の２つの方法があります。

1, Intel® DevCloud for oneAPIを使う
2, Intel® oneAPI Toolkitsをインストールして使う

以下のような方は、１のDevCloudを使うのがお勧めです。

・実機を持っていない
・クラウド環境で触りたい
・軽く評価したい
・評価の際、必要なデータはインテルのクラウドにアップロードしても構わない

是非、以下のURLからSign Inして試してみてください。最近はアカウントが即時発行されるようです。私も何度かこのサービスを使って、お客様向けのoneAPIのトレーニングを行ったりしています。Jupyter Notebookでも使えるので、とても便利です。
https://devcloud.intel.com/oneapi/

さて、本稿での本題は後者の、実際にIntel® oneAPI toolkitsをインストールして試してみるというほうになります。
現時点で、oneAPIに対応しているFPGAボードはIntel® PAC with Intel® Arria®10 GX FPGAとIntel® FPGA PAC D5005の２品種になります。これは、oneAPIはPACカード向けということではありませんで、Arria®10及びStratix®10搭載ボードであれば動作する可能性があります。詳しくはボードベンダーにお問い合わせください。
今回は、私が普段使っているIntel® PAC with Intel® Arria®10 GX FPGAのためのoneAPI環境を作りたいと思います。この時点（PACカードを選んだ時点）で、残念ながら？OSは現状自動的にUbuntu 18.04に限定されますので、注意してください。

# その前に

最近、oneAPIとOpenCLどちらを使うのが良いの？と質問されることが多くなってきました。Intel® FPGAで高位合成を使う場合、以下の３つのフローが考えられます。

1, Intel® HLS Compilerを使ってIPを生成し、それ以外はRTLで開発。SW側は開発者任せ
2, Intel® FPGA SDK for OpenCLで開発 
3, DPC++で開発

一番開発の柔軟性が高い（ただしその分工数もかかる）のが1、一番開発が楽なのが3になるかと思います。2は、ホスト側のコントロールをDPC++より柔軟に行えますので、1と３の中間のような位置づけになりますかね。大分3寄りではありますが。
ですので、回答としては、状況に応じて使い分けていただければ良いかなという、曖昧感漂うものになります。
ただ、これから高位合成を試す方は、間違いなくDPC++から入るのが良いのではないでしょうか。また、既にOpenCLを使っている開発者の方も、ホストコードで細かいバッファの管理・制御なんてやってないよという場合は、個人的にはoneAPIへの移行をお勧めします。


# Intel® oneAPI Base Toolkitsのインストール

ではまず、Base Toolkitをインストールしていきましょう。
どこから入っていただいても良いのですが（oneapi downloadとかでググれば多分たどり着けます）、一応トップページ的なところから行ってみます。まずはこちらに。

https://software.intel.com/content/www/us/en/develop/tools/oneapi.html

こんなページに飛びます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/95821/0b39777e-a658-a1ed-1627-f7a445d2a234.png)

このページの真ん中へんにこんなところがありますので、「Get Your Toolkit」のところをクリックします。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/95821/c58a0902-a2f2-5b77-fc27-a2297ec21d77.png)

そうすると、こんなページに飛びます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/95821/52954581-8195-b6a4-f5c1-1c63d4515396.png)

このページの下のほうに、Base Toolkitのダウンロードボタンがありますので、ここをクリック。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/95821/9888b752-909e-e253-bf34-861f8610959d.png)

これで、ようやくダウンロードページにたどり着きます。DistributionとInstallerのタイプは幾つかあるんですが、とりあえずここではお勧めらしいWeb & LocalとOnlineというのを選んでみました。これら３つの項目を左側で選択して、ダウンロードボタンをクリックします。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/95821/7750b222-64ed-99d7-d01b-9756b1257f0e.png)

この原稿を書いている時点では、l_BaseKit_p_2021.1.0.2659.shというファイルがダウンロードされました。時期によっては、バージョンを示す数字が異なるものがダウンロードされると思います。
早速、これを実行しましょう。

```
$ sudo sh ./l_BaseKit_p_2021.1.0.2659.sh
```

こんなウィンドウが立ち上がりますので、Continueをクリックします。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/95821/82f9ba04-8788-80a5-c953-aa21527fdb8f.png)

次にこんなウィンドウが表示されます。ここでは、全部入りの「Recommended」のままで、Continueボタンを押してインストールを開始してみます。「I accept the term of the license agreement」のチェックを押すのを忘れずに。ちなみに、Custom Installationを選択すると、インストールするアプリケーションを選択できます。実際、FPGAでは使えないツールが幾つかありますので、FPGAしか使わない場合はこちらで細かく選ぶのも手です。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/95821/78a25392-e1d9-6c62-30e1-c59ed3a22424.png)

Continueを押すと、私の環境ではこのようなWarningが表示されました。私はとりあえずはFPGAしか使わないし、Xeon®サーバを使っていてIntel®のGPUは搭載されていないので、ここは無視して次に進みました。GPU内蔵CPUを使っている方は、GPUに必要なSWもインストールしておくと面白いかも知れません。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/95821/0215e409-afe1-1607-e162-e73eeb0e1ba2.png)

次に、Eclipseに関するウィンドウが表示されます。私はEclipseで開発する気はないのでSkipを選択しました。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/95821/78180bcd-6194-d782-2990-c6b64f5949bd.png)

最後に、いつものImprovement Programのウィンドウが表示されます。こちらは、好きなほうを選択してください。よろしければ「I consent」のほうを選択していただけるとありがたいです。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/95821/8069acc3-ab07-b50d-f6e5-a85604b8dc4d.png)

これでようやくインストールが開始されますが、筆者の環境ではかなり長い時間以下の画面のままでした。我慢して待ってみてください。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/95821/3adf22f7-f969-9f9b-7fc0-c0f7f817f304.png)

すると、以下の進捗の画面に移行します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/95821/01d62d86-dddf-888d-f1cb-9c1b4cd96b03.png)

終了すると、以下の画面になります。「Get Started Guide」ボタンをクリックすると、ブラウザにGet Started Guideドキュメントが表示されます。適宜読んでみてください。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/95821/10a2a40e-267c-b01c-535b-e7bba3412eb8.png)

「Go to Installed Products」ボタンをクリックすると、以下の表示になります。ここは特に表示の必要はないので、一つ前のウィンドウでXボタンを押してウィンドウを閉じてしまって大丈夫です。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/95821/eeaf9224-abb9-8e20-3b8f-77869f101537.png)

/opt/intel/oneapiというディレクトリに全てインストールされたはずです。
試しに、以下を実行して環境設定をしてみてください。筆者の環境での実行例を挙げておきます。

```
$ source /opt/intel/oneapi/setvars.sh
:: initializing oneAPI environment ...
   BASH version = 4.4.20(1)-release
:: intelfpgadpcpp -- latest
:: compiler -- latest
:: dpl -- latest
:: debugger -- latest
:: advisor -- latest
:: dpcpp-ct -- latest
:: ippcp -- latest
:: vtune -- latest
:: dev-utilities -- latest
:: mkl -- latest
:: mpi -- latest
:: ccl -- latest
:: tbb -- latest
:: intelpython -- latest
:: vpl -- latest
:: dnnl -- latest
:: ipp -- latest
:: dal -- latest
:: oneAPI environment initialized ::
```
これでBase Toolkitのインストールは完了しました。次にFPGAのAdd-onをインストールします。


# Intel® FPGA Add-on for oneAPI Base Toolkitのインストール

さて、Betaのころと比べて、FPGAのAdd-onダウンロードはちょっと分かりにくくなっているように感じます（ですので、後ほどサイトが修正されたりするかもしれません）。先ほどのダウンロードの画面に戻って、Installer TypeをLocalに変更します。Base Toolkitもこれでインストールしても良いのですが…
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/95821/acbebf67-2851-96e7-8b56-8960000b7b3a.png)

Localを選択すると、下のほうにFPGA Add-onの項目が見つかるはずです。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/95821/77f10617-550c-5d63-25b4-96aea23bba7b.png)

「Intel® FPGA Add-on for oneAPI Base Toolkit」のところをクリックすると、以下のように展開されます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/95821/d8ade72a-cb9c-9e90-0c55-940a9deed79a.png)

下のほうに行くと、ようやくダウンロードリンクが見つかりますので、環境にあったものをダウンロードします。私の環境ではPACカードを使いますので、一番上の「Get it now」ボタンをクリックします。18GBもあります。恐ろしいですね。これは、Quartus®本体やデバイスファイル等の巨大ファイルがDPC++でのコンパイルにも必要なためです。ちなみに、PACカード以外の場合は、下の３つのうちのどれかを使うことになります。例えば私がどこかのベンダーのStratix®10 FPGAが搭載されたボードにoneAPI環境を移植する立場でしたら、おそらく一番下のQuartus® 20.3対応のファイルをダウンロードすることになると思います。

2021/1/30追記：
少なくとも私の環境では、ダウンロードのリンクをクリックしてもなぜか無反応な状況になっています。この場合は、ダウンロードのボタンのところで右クリック→別タブで開く等すると、なんとか先に進めるようです。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/95821/c2511832-f768-6e5d-b27d-6a863bcf9f6e.png)

License Agreementの画面に飛びますので、チェックボックスをクリックして先に進めます。おそらくこの前後でintel.comへのログインを要求されると思いますので、アカウントが必要です。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/95821/243c68dd-70ad-1793-5262-f07e90123b12.png)

これで、ブラウザ上でダウンロードが始まります。筆者の環境ではｘ時間かかりました（怖くて書けない）。FPGAの開発には忍耐が必要です。FPGAの開発には忍耐が必要です。大切なことなので2回(以下略
ちなみに、intel-fpga-addon-for-oneapi-base-kit-for-a10gx-s10sx-linux.zipというファイルがダウンロードされますが、Beta版のころと同じファイル名なので注意してください。

さて、早速解凍します。

```
$ unzip intel-fpga-addon-for-oneapi-base-kit-for-a10gx-s10sx-linux.zip
```

移動して、setup.shを実行。

```
$ cd intel-fpga-addon-for-oneapi-base-kit-for-a10gx-s10sx-linux/l_intel_fpga_dpcpp-a10gx-s10sx-2021.1.1/
$ sudo ./setup.sh
```

License Agreementが表示されるので、確認しつつスペースキーを連打し、一番下（100%のところ）まで移動します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/95821/b42fd3c0-7724-45ac-d737-fae2a6809699.png)

下まで来るとこのような表示になるので、y+リターン。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/95821/29b69864-a9ca-7d77-9de7-f9f60691889e.png)

インストールのPATHを聞かれます。デフォルトがお勧めなので、ここでは何も入力せずにリターン。

```
Enter the oneAPI root path [default: /opt/intel/oneapi/]:
```

以下を聞かれるので、当然Yesということで、何も入力せずにリターン。ネットワーク環境なしでインストールする場合は、後でマニュアルで色々やる必要があり面倒くさいです。

```
Do you wish to install prerequisites? Note: Installing will require administrative access (sudo) and network access. (Y/n):
```

後はうまく行くことを祈りつつひたすら待ち。結構時間かかります＆かなりディスク消費します。Quartus®とかインストールしますのでね。

以下の表示になったら終了です。一応ログを見返して、エラーがないか確認してください。

```
-------------------------------------------------------------------------------
- Finished installing Intel(R) FPGA Add-on for oneAPI Base Toolkit for PAC A10 and S10 Board
-------------------------------------------------------------------------------
```

最後に、いくつか必要なコマンドをインストールします。Ubuntuの場合は以下でOKです。

```
$ sudo apt update
$ sudo apt -y install cmake pkg-config build-essential
```

ちなみに、Redhat系の場合は以下になるようです。

```
$ sudo yum update
$ sudo yum -y install cmake pkgconfig
$ sudo yum groupinstall "Development Tools"
```

一応確認として、FPGAでのoneAPI実行の基盤となる、OpenCLコンパイラのPATHが通っているか確認してみます。
まず環境変数の設定をして

```
$ source /opt/intel/oneapi/setvars.sh
:: initializing oneAPI environment ...
   BASH version = 4.4.20(1)-release
:: intelfpgadpcpp -- latest
:: compiler -- latest
:: dpl -- latest
:: debugger -- latest
:: advisor -- latest
:: dpcpp-ct -- latest
:: ippcp -- latest
:: vtune -- latest
:: dev-utilities -- latest
:: mkl -- latest
:: mpi -- latest
:: ccl -- latest
:: tbb -- latest
:: intelpython -- latest
:: vpl -- latest
:: dnnl -- latest
:: ipp -- latest
:: dal -- latest
:: oneAPI environment initialized ::
```

で、aocコマンドがちゃんと入っているか確認します。

```
$ which aoc
/opt/intel/oneapi/compiler/2021.1.1/linux/lib/oclfpga/bin/aoc
```

大丈夫そうですね。


# サンプルプログラムを動かしてみる

さて、それでは早速何か動かしてみましょう。幸い、Intel® oneAPI Base Toolkitの環境では、サンプルプログラムを生成するための専用コマンドが用意されていますので、こちらを使ってみます。

まずは前述と同様、環境変数等の設定を行います。

```
$ source /opt/intel/oneapi/setvars.sh
```

次に、以下のコマンドを実行してください。

```
$ oneapi-cli
```

以下のような画面が表示されますので、「Create a project」を選択します。1キーを押しても良いですし、上下カーソルキーで選択してリターンキーでもOKです。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/95821/01e96f84-87a5-63e1-7351-4092c21ab9f1.png)

このような画面に遷移しますので、「cpp」を選択します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/95821/ba0c4c75-9ad2-220f-11e0-b3231bcdf8ef.png)

ここで、実際のサンプルを選択する画面になります。上下カーソルキーで移動して、好きなサンプルを選択しましょう。プロジェクトのテンプレートなんかも用意されていることが分かると思います。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/95821/aa050057-33e9-b971-693e-7d97170164a6.png)

ここでは、簡単なところで「FPGA Compile」というDPC++のサンプルを選択してみます。リターンキーを押して選択しましょう。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/95821/baecb6d6-9726-d002-0b37-6f2ff6bcb292.png)

以下のようなディレクトリ入力画面に移行します。好きなPATHを入力できますが、ここではそのままリターンキーで行きます。自動的にCreateというボタンに移動しますので、もう一度リターンキーを押します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/95821/f213736c-a823-f450-8f02-ce71cef3b76b.png)

サンプルデザインが生成されました。そのままリターンキーを押して終了します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/95821/81cb50cf-f6ed-7f35-e5ff-2dfff1d78e07.png)

生成されたディレクトリに移動して、中身を見てみましょう。

```
$ cd fpga_compile/
$ ls
CMakeLists.txt  fpga_compile.sln  fpga_compile.vcxproj  License.txt  README.md  sample.json  src
```

cmakeベースのデザインが生成されたことが分かると思います。Visual Studio用のファイルも見えますね。
では早速、まずはFPGAエミュレーションで動かしてみます。

```
$ mkdir build
$ cd build
$ cmake ..
-- The C compiler identification is GNU 7.5.0
-- The CXX compiler identification is Clang 12.0.0
-- Check for working C compiler: /usr/bin/cc
-- Check for working C compiler: /usr/bin/cc -- works
-- Detecting C compiler ABI info
-- Detecting C compiler ABI info - done
-- Detecting C compile features
-- Detecting C compile features - done
-- Check for working CXX compiler: /opt/intel/oneapi/compiler/2021.1.1/linux/bin/dpcpp
-- Check for working CXX compiler: /opt/intel/oneapi/compiler/2021.1.1/linux/bin/dpcpp -- works
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
-- Detecting CXX compile features
-- Detecting CXX compile features - done
--      FPGA_BOARD was not specified. Configuring the design to run on the Intel(R) Programmable Acceleration Card (PAC) with Intel Arria(R) 10 GX FPGA. Please refer to the README for information on board selection.
-- Configuring done
-- Generating done
-- Build files have been written to: /home/intel/fpga_compile/build
```

```
$ make fpga_emu
Scanning dependencies of target fpga_compile.fpga_emu
[ 50%] Building CXX object src/CMakeFiles/fpga_compile.fpga_emu.dir/fpga_compile.cpp.o
[100%] Linking CXX executable ../fpga_compile.fpga_emu
[100%] Built target fpga_compile.fpga_emu
Scanning dependencies of target fpga_emu
[100%] Built target fpga_emu
```

```
$ ./fpga_compile.fpga_emu
Running on device: Intel(R) FPGA Emulation Device
PASSED: results are correct
```

make時にfpga_emuを指定することでエミュレーションで動くバイナリが生成されるようになっています。
では、実機でも動かしてみましょう。実機で動くバイナリを生成するには、make fpgaと実行します。

```
$ make fpga
[ 50%] Linking CXX executable ../fpga_compile.fpga
aoc: Compiling for FPGA. This process may take several hours to complete.  Prior to performing this compile, be sure to check the reports to ensure the design will meet your performance targets.  If the reports indicate performance targets are not being met, code edits may be required.  Please refer to the oneAPI FPGA Optimization Guide for information on performance tuning applications for FPGAs.
[100%] Built target fpga_compile.fpga
Scanning dependencies of target fpga
[100%] Built target fpga
```

```
$ ./fpga_compile.fpga
Running on device: pac_a10 : Intel PAC Platform (pac_ed00000)
PASSED: results are correct
```

正常動作しました！

なお、筆者の環境では、もともとBeta版が入っていたのをアンインストールして、それから最新版をインストールしたのですが、最初は正常動作しませんでした。どうも一部にBeta版が残っていたようで、これを下のように消去して再度行うとうまく行きました。

```
$ sudo rm -r /opt/intel/oneapi/intelfpgadpcpp/2021.1-beta09
```

また、場合によっては以下の実行が必要かもしれません（本来は不要のはず）。

```
$ aocl install -f intel_a10gx_pac
```

もしそれでもうまく行かない場合は、一度以下のようにGBSファイルをFPGAにロードしてみてください（本来はこの動作は自動で行われます）。_null_signedとついているGBSをロードするのが重要です。

```
$ fpgaconf ./fpga_compile.prj/build/output_files/afu_import_null_signed.gbs
```

また、OpenCLを使っていただいている開発者の方は、ひょっとすると自動でのFPGAイメージのロードをオフにする設定がされていて、うまく行かない可能性があるかもしれません。その場合は、以下のようにunsetを試してみてください。

```
$ unset CL_CONTEXT_COMPILER_MODE_ALTERA
$ unset CL_CONTEXT_COMPILER_MODE_INTELFPGA
```

是非他のサンプルも色々試してみてください。あ、もちろん、srcディレクトリの中身やMakefileの確認もお忘れなく。サンプルによって、コンパイルや実行の仕方が異なったりしてますので。
ちなみに、個人的にはGZIPのサンプルがお勧めです。力作ですし。

# 最後に

今回この記事を書くにあたって色々ドキュメントを見たのですが、現時点で情報が古いままのものがまだ散見されます。そこは注意して見てみてください。
では良いoneAPIライフを。何かFPGAとGPU両方使う良いネタないですかね。


# 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.