FPGA開発用のWindows版oneAPI IP Authoring Flow環境を構築してみる

はじめに

こんにちは。

今回は私が不慣れな（なので、内容におかしなところが含まれる可能性があります。是非指摘お願いします…）Windows環境用に、oneAPIを使ったFPGA用IP生成・シミュレーション環境（IP Authoring Flowと呼びます）を構築するためのガイドを書きたいと思います。

なぜIP Authoring Flowに限った環境を構築するかというと、現時点でFull Stack Flowと呼ばれている通常のoneAPIの使い方をサポートしているWindows対応FPGAボードはありませんし、今後出てくる可能性も低そうなためです。このあたり、実はニーズ沢山あったりするんでしょうかね？？

Microsoft Visual Studioのインストール

まずVisual Studio 2022をダウンロード・インストールします。これ、インストールの順番が重要で、最初にVS2022のインストールをするのが良いです。
ダウンロードはこちらから。どのEditionでもOKのようです。筆者は自宅の趣味マシンで試しているので、Community Editionにしてみました。

ダウンロードしたらインストールを開始しますが、必要なのは「C++によるデスクトップ開発（Desktop development with C++）」というやつなので、これにチェックを入れます。他は不要なので適当に。

その後、インストールをクリックし、インストール開始（上のキャプチャ画面はインストール後に撮ったので、インストールというボタンが無いですが…）

再起動が求められたら再起動します。

Microsoft Visual Studio Codeのインストール

次。おすすめのIDEはVS Codeになってますので、こちらも入れましょう（必須ではないですし、VS2022でももちろん開発できます）。
ダウンロードはこちらから。

インストールは特に選択肢がないので簡単です。VS Codeがお勧めなのはoneAPI用のExtensionがあるのが理由の一つですが、これは後で触れます。

oneAPI Base Toolkitのインストール

次にoneAPI Base Toolkitのインストールです。今回はFPGA用なので、Base ToolkitだけでOKです。
ダウンロードはこちらから。

筆者はOffline Installerを選択しました。

ダウンロードしたら、ダブルクリックでインストール開始。今回はRecommended Installationで行きます。

Continueボタンを押して続行。

筆者はこの環境でGPU使う気がないので次に行きます。

先にVisual Studio 2022を入れておかないと、ここでVSを見つけてくれなくて色々苦労しそうです。次をクリック。

ここはお好きなほうを選択いただいて、Install開始。

インストールが開始されます。

終わったらFinishをクリック。

FPGAエミュレーション

この段階で、oneAPI Base Toolkitインストールの確認がてら、FPGAエミュレーションが動作するか確認します。
VS Codeを起動して、左側のExtensionをクリック。oneapiで検索します。

とりあえず必要なのは、上の画像では一番上に出ているCode Sample Browserですが、私は全部入りのExtension Packというのを入れました。

左側にoneAPIというアイコンができているのがわかります。そこをクリック。
oneapi-cliをダウンロードするか聞かれたので、Yesで。

定番のFPGA Compileというサンプルで試しましょう。Createボタン（フォルダのマークに＋がついてるやつ）をクリックしてサンプル生成。

今回はIP Authoring Flowをやる上で一番の基本になるpart2_dpcpp_functor_usmというサンプルを試します。ソース等々見ておきます。
ここでは、C++ Extension入れませんかとか色々言われたので、筆者は全部入れちゃいました。

ありがたいことに？、適宜Configure your development environmentのポップアップが出るので、default environmentで設定してもらいます。これで、oneAPIの設定を行うバッチファイル（setvars.bat）が流れるようです。

setvars.batはoneAPI環境構築のために都度実行が必要なものです。以下のように手動で流してもOKのはず。ここでは、上記のように既に自動で流してくれているため、もういいよと言われています。

> & 'C:\Program Files (x86)\Intel\oneAPI\setvars.bat'
:: WARNING: setvars.bat has already been run. Skipping re-execution.
   To force a re-execution of setvars.bat, use the '--force' option.
   Using '--force' can result in excessive use of your environment variables.

では、実際にコンパイル・実行してみます。Terminal->New Terminal等でターミナルを開いて、part2_dpcpp_functor_usmフォルダに移動、buildディレクトリを作ってcmakeを実行します。ターミナルをあまり使わないでコマンドパレットを使って行っていくやり方もあるようですが、私はLinux環境慣れしていることもあり、こっちのほうが好きです。

> mkdir build
> cd build
> cmake -G "NMake Makefiles" ..

これでMakefileができていることを確認してください（ちなみに、Linux環境ではcmake実行の際-G "NMake Makefiles"というオプションは不要です）。あとは引き続きターミナル内でnmakeでFPGAエミュレーション用のバイナリを生成。

> nmake fpga_emu

Microsoft(R) Program Maintenance Utility Version 14.36.32537.0
Copyright (C) Microsoft Corporation.  All rights reserved.

[ 50%] Building CXX object src/CMakeFiles/vector_add.fpga_emu.dir/vector_add.cpp.obj
Intel(R) oneAPI DPC++/C++ Compiler for applications running on Intel(R) 64, Version 2023.1.0 Build 20230320
Copyright (C) 1985-2023 Intel Corporation. All rights reserved.

[100%] Linking CXX executable ..\vector_add.fpga_emu.exe
Intel(R) oneAPI DPC++/C++ Compiler for applications running on Intel(R) 64, Version 2023.1.0 Build 20230320
Copyright (C) 1985-2023 Intel Corporation. All rights reserved.

icx-cl: warning: unknown argument ignored in clang-cl: '-lkernel32' [-Wunknown-argument]
icx-cl: warning: unknown argument ignored in clang-cl: '-luser32' [-Wunknown-argument]
icx-cl: warning: unknown argument ignored in clang-cl: '-lgdi32' [-Wunknown-argument]
icx-cl: warning: unknown argument ignored in clang-cl: '-lwinspool' [-Wunknown-argument]
icx-cl: warning: unknown argument ignored in clang-cl: '-lshell32' [-Wunknown-argument]
icx-cl: warning: unknown argument ignored in clang-cl: '-lole32' [-Wunknown-argument]
icx-cl: warning: unknown argument ignored in clang-cl: '-loleaut32' [-Wunknown-argument]
icx-cl: warning: unknown argument ignored in clang-cl: '-luuid' [-Wunknown-argument]
icx-cl: warning: unknown argument ignored in clang-cl: '-lcomdlg32' [-Wunknown-argument]
icx-cl: warning: unknown argument ignored in clang-cl: '-ladvapi32' [-Wunknown-argument]
[100%] Built target vector_add.fpga_emu
[100%] Built target fpga_emu

沢山Warningが出ていますが、ここでは無視して大丈夫です。
実行してPASSEDと表示されることを確認します。

> .\vector_add.fpga_emu.exe
Running on device: Intel(R) FPGA Emulation Device
add two vectors of size 256
PASSED

インテル® Quartus® Prime 開発ソフトウェアのインストール

次にインテル® Quartus® Prime 開発ソフトウェアをインストールします。今回は最新のインテル® Agilex™ 7 FPGAを対象にしたいので、有償のPro Editionを選択します（後述のとおり、対象デバイスによっては無償のライト・エディションも使えるようです）。ちなみに、Emulation及びSimulationについてはインテル® Quartus® Prime 開発ソフトウェアのインストールは不要なんですが、SimulationにはQuestaが必要なので、一緒にインストールしてしまいます（ですので、HW生成のコンパイルはしないよということであれば、QuestaのみのインストールでOKのはず）。
ダウンロードはこちらから。

今回インストールしたoneAPI Base Toolkitはバージョンが2023.1です。こちらを見ると、

対応しているインテル® Quartus® Prime 開発ソフトウェアは20.1から22.4とのことなので、22.4をインストールすることにします。こちらから直接ダウンロードできるかも。

ちなみに、原稿執筆時点では最新バージョンは23.2です。まもなく出てくる次のバージョンのoneAPI Base Toolkitでは新しいバージョンまでサポートされると思います。
色々なダウンロード方法がありますが、全部入りのtarファイルは巨大なので、筆者は通常Individual FilesタブからIntel® Quartus® Softwareのところ全てと、必要なデバイスファイル（今回はAgilex7のものを使います）のみをダウンロードすることが多いです。
今回はIP Authoring Flow用の環境なので、Questa®は必須です。

筆者がダウンロードしたファイルは以下です。

> dir *22.4*
(snip)
Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
-a----        2023/07/13     22:59    10693861717 agilex-22.4.0.94.qdz
-a----        2023/07/13     21:50     3356001448 QuartusProSetup-22.4.0.94-windows.exe
-a----        2023/07/13     23:20    12888423816 quartus_part2-22.4.0.94-windows.qdz
-a----        2023/07/13     21:24      601087328 QuestaSetup-22.4.0.94-windows.exe
-a----        2023/07/13     23:31    21936342545 questa_part2-22.4.0.94-windows.qdz

QuartusProSetup-22.4.0.94-windows.exeをダブルクリックしてインストールします。
筆者は以下のようにインストールしました。ライセンスを持っているので、QuestaはStarter EditionではなくIntel FPGA Editionのほうを選択しています。

インストールが終わったら、quartus\bin64ディレクトリを環境変数のPathのところに追加しておきます。Questaのパスは自動で追加してくれているようです。なぜなんでしょう。

また、LM_LICENSE_FILEでライセンスファイルを指定します。

以上でインストールは終了なので、VS Codeで新しいターミナルを開いて、以下を実行しPATHが通っているか確認します。

> vlog -version
Questa Intel FPGA Edition-64 vlog 2022.1 Compiler 2022.01 Jan 29 2022
> quartus_sh --version
Quartus Prime Shell
Version 22.4.0 Build 94 12/07/2022 SC Pro Edition
Copyright (C) 2022  Intel Corporation. All rights reserved.

出来ればライセンスファイルが正しく設定されているかも確認したいところです。
Questaについては、vsimを実行して正しくvsimのGUIが起動しエラーがでなければOKです。
Quartusについては、GUIを起動して、Tools->License Setupで、ライセンスが表示されているかを確認します。問題ありそうならここで再度ライセンスを設定します。

FPGAシミュレーション

では、実際にシミュレーション用のバイナリを作るためのコンパイルしてみましょう。またWarningが沢山出ますが、無視。cmake_minimum_requiredを設定すれば消せるようですが。

> nmake fpga_sim

Microsoft(R) Program Maintenance Utility Version 14.36.32537.0

Intel(R) oneAPI DPC++/C++ Compiler for applications running on Intel(R) 64, Version 2023.1.0 Build 20230320
Copyright (C) 1985-2023 Intel Corporation. All rights reserved.

Intel(R) oneAPI DPC++/C++ Compiler for applications running on Intel(R) 64, Version 2023.1.0 Build 20230320
Copyright (C) 1985-2023 Intel Corporation. All rights reserved.

icx-cl: warning: unknown argument ignored in clang-cl: '-lkernel32' [-Wunknown-argument]
icx-cl: warning: unknown argument ignored in clang-cl: '-luser32' [-Wunknown-argument]
icx-cl: warning: unknown argument ignored in clang-cl: '-lgdi32' [-Wunknown-argument]
icx-cl: warning: unknown argument ignored in clang-cl: '-lwinspool' [-Wunknown-argument]
icx-cl: warning: unknown argument ignored in clang-cl: '-lshell32' [-Wunknown-argument]
icx-cl: warning: unknown argument ignored in clang-cl: '-lole32' [-Wunknown-argument]
icx-cl: warning: unknown argument ignored in clang-cl: '-loleaut32' [-Wunknown-argument]
icx-cl: warning: unknown argument ignored in clang-cl: '-luuid' [-Wunknown-argument]
icx-cl: warning: unknown argument ignored in clang-cl: '-lcomdlg32' [-Wunknown-argument]
icx-cl: warning: unknown argument ignored in clang-cl: '-ladvapi32' [-Wunknown-argument]
warning: -reuse-exe file 'C:/Users/Takemura/oneapi/fpga_compile/Tutorials/GettingStarted/fpga_compile/part2_dpcpp_functor_usm/build/vector_add.fpga_sim' not found; ignored
aoc: Compiling for Simulator.
aoc: Simulation generation done!
LINK : 前回のインクリメンタル リンクで ..\vector_add.fpga_sim.exe が見つからなかったか、ビルドされませんでした。フル リンクを行います。
[100%] Built target vector_add.fpga_sim
[100%] Built target fpga_sim

初回のコンパイルでは、「LINK : 前回のインクリメンタル リンクで ..\vector_add.fpga_sim.exe が見つからなかったか、ビルドされませんでした。フル リンクを行います。」とかいうメッセージが出ます。これは、-reuse-exeというオプションを付けていることも関係しています。
では早速、Simulationを動かしてみます。先ほどEmulationを動かしたbuildというディレクトリに移動して作業します。

> $env:CL_CONTEXT_MPSIM_DEVICE_INTELFPGA=1
> .\vector_add.fpga_sim.exe
Running on device: SimulatorDevice : Multi-process Simulator (aclmsim0)
add two vectors of size 256
PASSED
> $env:CL_CONTEXT_MPSIM_DEVICE_INTELFPGA=$null      

エミュレーションの時と全く同じ出力になるのがポイントですね。diffで簡単にOK/NG確認ができます。

CL_CONTEXT_MPSIM_DEVICE_INTELFPGAという環境変数が登場していますが、これを設定すると、Simulation用のDeviceが追加されるのがミソです。

> sycl-ls                                           
[opencl:acc:0] Intel(R) FPGA Emulation Platform for OpenCL(TM), Intel(R) FPGA Emulation Device 1.2 [2023.15.3.0.20_160000]
[opencl:cpu:1] Intel(R) OpenCL, Intel(R) Core(TM) i7-7700K CPU @ 4.20GHz 3.0 [2023.15.3.0.20_160000]
> $env:CL_CONTEXT_MPSIM_DEVICE_INTELFPGA=1
> sycl-ls
[opencl:acc:0] Intel(R) FPGA Emulation Platform for OpenCL(TM), Intel(R) FPGA Emulation Device 1.2 [2023.15.3.0.20_160000]
[opencl:cpu:1] Intel(R) OpenCL, Intel(R) Core(TM) i7-7700K CPU @ 4.20GHz 3.0 [2023.15.3.0.20_160000]
[opencl:acc:2] Intel(R) FPGA SDK for OpenCL(TM), SimulatorDevice : Multi-process Simulator (aclmsim0) 1.0 [2023.1]        

Simulationが終了すると波形ファイルができているはずです。波形も見てみます。

> .\vector_add.fpga_sim.prj\view_waveforms.cmd

以下でもOKです。

> vsim .\vector_add.fpga_sim.prj\vsim.wlf

Questaのウィンドウが起動します。

あとは、適宜波形を見ていってください。

CmakeLists.txtを見ていただくと分かりますが、デフォルトではFPGA_DEVICEがAgilexになっています。ここまでは特にcmake実行時に何も指定しなかったのでそのままAgilexが指定されます。FPGA_DEVICEにデバイス名またはOPNが指定される＝IP Authoring Flowで実行される、ということになります。ちなみに、Full Stack Flowで動かすためには、ここでoneAPI ASP名を指定する必要があります。

一応実機用コンパイル

最後にQuartusをすべて回すコンパイルを試してみます。
Full Stack Flowの場合は、これでFPGAボードを使って実行可能な環境が生成されますが、IP Authoring Flowにおいては正確なHW情報（リソース使用量や動作周波数）が取れる程度の意味しかありません。

> nmake fpga

Microsoft(R) Program Maintenance Utility Version 14.36.32537.0
Copyright (C) Microsoft Corporation.  All rights reserved.

[ 50%] Building CXX object src/CMakeFiles/vector_add.fpga.dir/vector_add.cpp.obj
Intel(R) oneAPI DPC++/C++ Compiler for applications running on Intel(R) 64, Version 2023.1.0 Build 20230320
Copyright (C) 1985-2023 Intel Corporation. All rights reserved.

[100%] Linking CXX executable ..\vector_add.fpga.exe
Intel(R) oneAPI DPC++/C++ Compiler for applications running on Intel(R) 64, Version 2023.1.0 Build 20230320
Copyright (C) 1985-2023 Intel Corporation. All rights reserved.

icx-cl: warning: unknown argument ignored in clang-cl: '-lkernel32' [-Wunknown-argument]
icx-cl: warning: unknown argument ignored in clang-cl: '-luser32' [-Wunknown-argument]
icx-cl: warning: unknown argument ignored in clang-cl: '-lgdi32' [-Wunknown-argument]
icx-cl: warning: unknown argument ignored in clang-cl: '-lshell32' [-Wunknown-argument]
icx-cl: warning: unknown argument ignored in clang-cl: '-lole32' [-Wunknown-argument]
icx-cl: warning: unknown argument ignored in clang-cl: '-loleaut32' [-Wunknown-argument]
icx-cl: warning: unknown argument ignored in clang-cl: '-luuid' [-Wunknown-argument]
icx-cl: warning: unknown argument ignored in clang-cl: '-lcomdlg32' [-Wunknown-argument]
icx-cl: warning: unknown argument ignored in clang-cl: '-ladvapi32' [-Wunknown-argument]
warning: -reuse-exe file 'C:/Users/Takemura/oneapi/fpga_compile/Tutorials/GettingStarted/fpga_compile/part2_dpcpp_functor_usm/build/vector_add.fpga' not found; 
ignored
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 vector_add.fpga
[100%] Built target fpga

もちろん実行は出来ません。逆に言えば、Full Stack Flow用の環境を用意すれば、IPの動作確認は実FPGAで行うことが可能です。

> .\vector_add.fpga.exe
Caught a SYCL host exception:
No device of requested type available. Please check https://software.intel.com/content/www/us/en/develop/articles/intel-oneapi-dpcpp-system-requirements.html -1 (PI_ERROR_DEVICE_NOT_FOUND)

インテル® Quartus® Prime 開発ソフトウェア　ライト・エディションを使う

ドキュメントによると、oneAPI IP Authoring Flowは現時点でCycloneVには対応しているようです。

ですので、インテル® Quartus® Prime 開発ソフトウェア　ライト・エディションも使えそうです。
原稿執筆時点の最新バージョンは22.1です。

筆者は以下のような構成で試してみました。

もちろんQuestaも無償のStarter Editionを使っています。
また、cmake時にはCycloneVを指定する必要があります。

> cmake -G "NMake Makefiles" -DFPGA_DEVICE=CycloneV ..

後は前述の内容と特に変わらずに、エミュレーション・シミュレーション共に動作することを確認できました。

Platform Designerで作ったIPを呼び出してみる

oneAPI IP Authoring Flowで作ったIPは、手書きでインスタンス化するか、Platform Designerで呼び出すかの2択になります。ここでは、Platform DesignerでIPとして呼び出せるかを確認します。
公式サンプルもありますので、参考にしてください。

今回例として使っているpart2_dpcpp_functor_usmというサンプルについては、IPとして呼び出すためには、

> nmake fpga

または

> nmake report

で作成したものが使えます。

> nmake fpga_sim

で作成したものは使えないようなので注意してください。

では、まずインテル® Quartus® Prime 開発ソフトウェアを起動して、適当にProjectを作ります。IPを生成したときに指定したデバイスと同じものを指定してください。筆者はAgilexで試しました。

ここで、作成したIPがPlatform Designerから見えるようにしないといけないわけですが、方法は幾つかあります。
上記のサンプルでは、oneAPI IP Authoring Flowで生成されたprjディレクトリを丸ごとProject以下にコピーする方法がとられています。同じことをやっても面白くないので、ここではipxファイルを作って、IPのパスを教えてあげる方法をとります。

ipa.ipxというファイルを作って、内容を以下のように編集します。

<library>
	<path path="../fpga_compile/Tutorials/GettingStarted/fpga_compile/part2_dpcpp_functor_usm/build/vector_add_report.a.prj/*" />
</library>

ここではnmake reportで生成されたディレクトリを指定しています（nmake fpgaで生成されたディレクトリでもよいです）。上の画像の通り、作成したipa.ipxファイルをプロジェクトに登録しておきます。
これでPlatform Designerが当該ディレクトリをサーチしてくれるはずです。では、Platform Designerを起動してみましょう。新規になるので、Platform Designerファイル（.qsysファイル）は適当に新規作成します。

起動後、左側のIP CatalogのoneAPIのところを展開してみます。

vector_add_report_a_diというIPが見えるはずです。これが生成されたIPなので、これをダブルクリックしてみます。

正しくIPとして呼び出せそうですね。
ちなみに、device_exception_busという謎のバスが見えますが、これはOpenのまま放置して構いません。同様に、kernel_irqsも通常使用しないのでOpenのままにします。それ以外のものは接続の必要ありです。
avmで始まるバスは、IPがメモリを読みに行くためのマスターバスですね。csrで始まるバスは、IPに対するレジスタ設定用のバスになっています。レジスタマップ情報は、nmake実行時に生成されたprjディレクトリに生成されます（*register_map.hppというファイル名になります）。詳細についてはoneAPI Programming Guideを参考にしてみてください。IP Authoring Flowの章が参考になるかと思います。

適当に回路っぽく接続してみました。

こんな感じで動かせるはずです。

最後に

oneAPI IP Authoring Flowの前身のツールであるIntel® High Level Synthesis Compilerは、既に登場から時間がたっており使いやすいですが、本ツールはまだ出来立てということもあり、まだ足りていないところもあったりします。でも、oneAPI本体と統合されたことでFPGAボードを用意すれば手軽に実機確認ができる等、メリットも沢山あります。是非試してみてください！

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.