はじめに

筆者は Ultra96/Ultra96-V2(ZynqMP) 向けに Debian GNU/Linux を提供しています1。また、XRT(Xilinx Runtime) はXilinx社が提供する開発環境(Vitis)で開発したプログラムをプラットフォームで動かすための環境です2。

本来なら MPSoC Edge Device 用の XRT は Xilinx が提供する Linux 環境(Petalinux) でしか動きませんが、XRT を Ultra96/Ultra96-V2 向け Debian GNU/Linux で動かすための手順を幾つかのパートに分けて説明します。

概要編
ビルド編
インストール編(この記事)
実践編
Vitis編

この記事では XRT を Ultra96/Ultra96-V2 向け Debian GNU/Linux にインストールする手順について説明します。

注意

この記事で紹介している Debian Package は Xilinx 社の公式なものではありません。

対応するプラットフォーム

現時点でインストール出来ることを確認しているのは次のプラットフォームのみです。

ボード: Ultra96-V2
Linux カーネル: Linux 4.19.0 (linux-xlnx 4.19.0 v2019.2)
ディストリビューション: Ubuntu 18.04 or Debian10

Linux Kernel は以下の URL にあります。

https://github.com/ikwzm/ZynqMP-FPGA-Linux

ディストリビューションは以下の URL にあります。

Debian10: https://github.com/ikwzm/ZynqMP-FPGA-Linux
Ubuntu18.04: https://github.com/ikwzm/ZynqMP-FPGA-Ubuntu18.04-Ultra96

それぞれの URL を参照して Ultra96 にインストールしてください。また、以下の記事も参考にしてください。

『UltraZed/Ultra96/Ultra96-V2 向け Debian GNU/Linux (v2019.2版) ブートイメージの提供』@Qiita

Debian Package の入手

『Ultra96/Ultra96-V2 向け Debian GNU/Linux で XRT(Xilinx Runtime) を動かす(ビルド編)』@Qiitaで説明した方法で XRT の Debian Packageをビルドするか、次の URL にある Debian Package をダウンロードしてください。

https://github.com/ikwzm/ZynqMP-FPGA-XRT
- xrt_202010.2.6.0_Ubuntu_18.04-arm64-xrt.deb

インストールする前に

インストールする前に以下のパッケージをインストールしておいてください。

ocl-icd-opencl-dev (>= 2.2.0)
libboost-dev (>=1.65)
libboost-filesystem-dev (>=1.65)
uuid-dev (>= 2.27.1)
dkms (>= 2.2.0)
libprotoc-dev (>=2.61)
libssl-dev (>=1.0.2)
protobuf-compiler (>=2.6.1)
libncurses5-dev (>=6.0)
lsb-release
libxml2-dev (>=2.9.1)
libyaml-dev (>= 0.1.6)
libc6 (>= 2.27)
python (>= 2.7)
python-pip
libudev-dev

上で紹介したパッケージは、xrt_202010.2.6.0_Ubuntu_18.04-arm64-xrt.deb をビルドした際に明示的に依存関係にあることを宣言したものです。

また、上記以外にも、以下のパッケージをインストールしておいてください。

python-pyopencl

このパッケージがインストールされていないと、xrt_202010.2.6.0_Ubuntu_18.04-arm64-xrt.deb のインストールの際に pyopencl を pip でインストールしようとします。pip で pyopencl をインストールする場合は C で書かれたプログラムをコンパイルする必要があり、いろいろとトラブルが発生して結局インストールに失敗しました。最初から Debian/Ubuntu 用にビルド済みの pyopencl をインストールしておいたほうがトラブルが発生しなくて済みます。

XRT(Xilinx Runtime) Package のインストール

dpkg コマンドでxrt_202010.2.6.0_Ubuntu_18.04-arm64-xrt.deb をインストールします。なお、このパッケージをインストールする時、その工程の途中で、dkms の仕組みを使って zocl カーネルモジュールをビルドします。そのためインストールに時間がかかります。

fpga@ubuntu-fpga:~$ cd work/ZynqMP-FPGA-XRT
fpga@ubuntu-fpga:~/work/ZynqMP-FPGA-XRT$ sudo dpkg -i xrt_202010.2.6.0_Ubuntu_18.04-arm64-xrt.deb
Selecting previously unselected package xrt.
(Reading database ... 114691 files and directories currently installed.)
Preparing to unpack xrt_202010.2.6.0_Ubuntu_18.04-arm64-xrt.deb ...
Unpacking xrt (2.6.0) ...
Setting up xrt (2.6.0) ...
Unloading old XRT Linux kernel modules
rmmod: ERROR: Module zocl is not currently loaded
Invoking DKMS common.postinst for xrt
debconf: unable to initialize frontend: Dialog
debconf: (Dialog frontend will not work on a dumb terminal, an emacs shell buffer, or without a controlling terminal.)
debconf: falling back to frontend: Readline
Loading new xrt-2.6.0 DKMS files...
Building for 4.19.0-xlnx-v2019.2-zynqmp-fpga
Building initial module for 4.19.0-xlnx-v2019.2-zynqmp-fpga
Done.
zocl:
Running module version sanity check.
 - Original module
   - No original module exists within this kernel
 - Installation
   - Installing to /lib/modules/4.19.0-xlnx-v2019.2-zynqmp-fpga/updates/dkms/
depmod...
DKMS: install completed.
Finished DKMS common.postinst
Loading new XRT Linux kernel modules
Skipping pyopencl installation...

カーネルモジュールのビルド中に、うかつに Ctrl-C 等で中断しないで、終わるまで待ってあげてください。

Device Treeの準備

前節でインストールした Debian Package には XRT の MPSoC Edge Device 用の Linux カーネルモジュール zocl が含まれています。ただし、zocl は Linux にインストールしただけでは有効になりません。zocl を有効にするためには Device Tree が必要です。

ZynqMP-FPGA-Linux は Device Tree Overlay をサポートしています。Device Tree Overlay によって積極的に、 Linux 動作中の FPGA のプログラムやカーネルモジュールの追加および削除を行っています。zocl も Device Tree Overlay を使って有効にします。

以下に zocl を有効にするための Device Tree Overlay の例を示します。

zocl.dts

/dts-v1/; /plugin/;
/ {
        fragment@0 {
                target-path = "/fpga-full";
                __overlay__ {
                        firmware-name = "streaming_lap_filter5.bin";
                };
        };
        fragment@1 {
                target-path = "/amba_pl@0";
                __overlay__ {
                        #address-cells = <2>;
                        #size-cells = <2>;
                        zyxclmm_drm {
                                compatible = "xlnx,zocl";
                                status = "okay";
                                reg = <0x0 0xA0000000 0x0 0x10000>;
                        };
                       fclk0 {
                                compatible    = "ikwzm,fclkcfg-0.10.a";
                                clocks        = <&zynqmp_clk 0x47>;
                                insert-rate   = "100000000";
                                insert-enable = <1>;
                                remove-rate   = "1000000";
                                remove-enable = <0>;
                        };
                };
        };
};

この例では zyxclmm_drm ノードが zocl のデバイスツリーを示しています。

さらに、この Device Tree には重要な点があと２点あります。一つ目は、fclk0 で PL Clock 0 を 100MHz に設定している点です。

二つ目は、fpga-full ノードに対してfirmware-name プロパティを追加してビットストリームファイルを指定している点です。これにより Device Tree を Overlay した際に、指定されたビットストリームファイルが FPGA にプログラムされます3。

Xilinx のソフトウェア開発環境 Vitis によってビルドされた xclbin ファイルに含まれるビットストリームは、実は Partial Reconfiguration 用のものです。

Partial Reconfiguration というのは、もともと FPGA にプログラムされて動作している状態で、指定されたエリアだけを動的に書き換える技術です。つまり、Partial Reconfiguration する前に、ベースとなるビットストリームファイルが FPGA にプログラムされてなければなりません。また、Partial Reconfiguration の際には、通常の FPGA のプログラムと異なり、FPGA 全体に対してリセットを行いません。

zocl はxclbin ファイルを FPGA にプログラムする際には、Partial Reconfiguration モードでプログラムを行います。したがって zocl ドライバを有効にする前に、ベースとなるビットストリームファイルを FPGA にプログラムしておく必要があるのです。

2020年6月17日追記

元の記事では "#size-cells = <1>;" "reg = <0x0 0xA0000000 0x10000>;" になっていましたが、Linux Kernel 5.4 だとエラーになります。Linux Kernel 5.4 になってからは、 "#size-cells" の値にベースの Device Tree と異なる値を設定することができなくなったようです。

参考

https://github.com/Xilinx/XRT
https://github.com/ikwzm/ZynqMP-FPGA-Linux
https://github.com/ikwzm/ZynqMP-FPGA-XRT
https://github.com/ikwzm/ZynqMP-FPGA-Ubuntu18.04-Ultra96
『UltraZed/Ultra96/Ultra96-V2 向け Debian GNU/Linux (v2019.2版) ブートイメージの提供』@Qiita
『Linux Kernel 4.10 でのFPGAのサポート事情』@Qiita
『FPGA の Partial Reconfiguration の紹介(Vivado デザインフロー編)』@Qiita