はじめに

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

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

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

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

注意

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

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

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

ボード: Ultra96-V2/KV260
Linux カーネル: Linux 5.10.0 (linux-xlnx 5.10.0 v2021.1)
ディストリビューション: Ubuntu 20.04 or Debian 11

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

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

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

Debian11: https://github.com/ikwzm/ZynqMP-FPGA-Linux
Ubuntu20.04: https://github.com/ikwzm/ZynqMP-FPGA-Ubuntu20.04

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

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

Debian Package の入手

XRT 2.11.0 ビルド編で説明した方法で XRT の Debian Packageをビルドするか、次の URL にある Debian Package をダウンロードしてください。

2021.1_EDGE_0_Debian_11

リポジトリ: https://github.com/ikwzm/ZynqMP-FPGA-XRT
ブランチ: 2021.1_EDGE_0_Debian_11
XRT バージョン: 2.11.0
Linux ディストリビューション: Debian 11
パッケージファイル: xrt_202110.2.11.0_Edge_Debian_11-arm64.deb

fpga@ubuntu-fpga:~/work$ git clone --depth 1 --branch 2021.1_EDGE_0_Debian_11 https://github.com/ikwzm/ZynqMP-FPGA-XRT

2021.1_EDGE_0_Ubuntu_20.04

fpga@ubuntu-fpga:~/work$ git clone --depth 1 --branch 2021.1_EDGE_0_Ubuntu_20.04 https://github.com/ikwzm/ZynqMP-FPGA-XRT

インストールする前に

XRT 2021.1_EDGE をインストールするためには、あらかじめ C コンパイラおよび linux kernel header がインストールされていなければなりません。

何故なら、XRT には zocl というカーネルモジュールが含まれています。このカーネルモジュールをインストールするために dkms (Dynamic Kernel Module Support) という仕組みを使っています。dkms の仕組みは、インストール時にソースコードをコンパイルしてカーネルモジュールを動的に生成します。そのためには、あらかじめ C コンパイラと linux header がインストールされていなければなりません。

なお、ZynqMP-FPGA-Linux および ZynqMP-FPGA-Ubuntu20.04 の Linux header は https://github.com/ikwzm/ZynqMP-FPGA-Linux に Debian パッケージとして用意されています。

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

apt コマンドで Debian Package をインストールします。なお、このパッケージをインストールする時、その工程の途中で、dkms の仕組みを使って zocl カーネルモジュールをビルドします。そのためインストールに時間がかかります。

apt-install.log

fpga@ubuntu-fpga:~$ cd work/ZynqMP-FPGA-XRT
fpga@ubuntu-fpga:~/work/ZynqMP-FPGA-XRT$ sudo apt install  ./xrt_202110.2.11.0_Edge_Debian_11-arm64.deb
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
Note, selecting 'xrt' instead of './xrt_202110.2.11.0_Edge_Debian_11-arm64.deb'
The following additional packages will be installed:
  dctrl-tools distro-info-data dkms libboost-filesystem1.74.0
  libboost-program-options1.74.0 libprotobuf23 libuuid1 lsb-release
  ocl-icd-libopencl1 ocl-icd-opencl-dev opencl-c-headers opencl-clhpp-headers
  uuid-dev
Suggested packages:
  debtags menu opencl-icd opencl-clhpp-headers-doc
Recommended packages:
  fakeroot linux-headers-686-pae | linux-headers-amd64 | linux-headers-generic
  | linux-headers uuid-runtime libgl1-mesa-dev | libgl-dev
The following NEW packages will be installed:
  dctrl-tools distro-info-data dkms libboost-filesystem1.74.0
  libboost-program-options1.74.0 libprotobuf23 lsb-release ocl-icd-libopencl1
  ocl-icd-opencl-dev opencl-c-headers opencl-clhpp-headers uuid-dev xrt
The following packages will be upgraded:
  libuuid1
1 upgraded, 13 newly installed, 0 to remove and 32 not upgraded.
Need to get 191 kB/12.2 MB of archives.
After this operation, 60.2 MB of additional disk space will be used.
Do you want to continue? [Y/n]
Get:1 http://security.debian.org bullseye-security/main arm64 libuuid1 arm64 2.36.1-8+deb11u1 [83.4 kB]
Get:2 http://ftp.jp.debian.org/debian bullseye/main arm64 distro-info-data all 0.51+deb11u1 [7624 B]
Get:3 http://security.debian.org bullseye-security/main arm64 uuid-dev arm64 2.36.1-8+deb11u1 [99.6 kB]
Get:4 /home/fpga/debian/xrt_202110.2.11.0_Edge_Debian_11-arm64.deb xrt arm64 2.11.0 [10.3 MB]
Fetched 191 kB in 0s (590 kB/s)
Selecting previously unselected package distro-info-data.
(Reading database ... 43119 files and directories currently installed.)
Preparing to unpack .../distro-info-data_0.51+deb11u1_all.deb ...
Unpacking distro-info-data (0.51+deb11u1) ...
Selecting previously unselected package lsb-release.
Preparing to unpack .../lsb-release_11.1.0_all.deb ...
Unpacking lsb-release (11.1.0) ...
Selecting previously unselected package dctrl-tools.
Preparing to unpack .../dctrl-tools_2.24-3_arm64.deb ...
Unpacking dctrl-tools (2.24-3) ...
Setting up distro-info-data (0.51+deb11u1) ...
Setting up lsb-release (11.1.0) ...
Selecting previously unselected package dkms.
(Reading database ... 43179 files and directories currently installed.)
Preparing to unpack .../archives/dkms_2.8.4-3_all.deb ...
Unpacking dkms (2.8.4-3) ...
Preparing to unpack .../libuuid1_2.36.1-8+deb11u1_arm64.deb ...
Unpacking libuuid1:arm64 (2.36.1-8+deb11u1) over (2.36.1-8) ...
Setting up libuuid1:arm64 (2.36.1-8+deb11u1) ...
Selecting previously unselected package libboost-filesystem1.74.0:arm64.
(Reading database ... 43239 files and directories currently installed.)
Preparing to unpack .../0-libboost-filesystem1.74.0_1.74.0-9_arm64.deb ...
Unpacking libboost-filesystem1.74.0:arm64 (1.74.0-9) ...
Selecting previously unselected package libboost-program-options1.74.0:arm64.
Preparing to unpack .../1-libboost-program-options1.74.0_1.74.0-9_arm64.deb ...
Unpacking libboost-program-options1.74.0:arm64 (1.74.0-9) ...
Selecting previously unselected package libprotobuf23:arm64.
Preparing to unpack .../2-libprotobuf23_3.12.4-1_arm64.deb ...
Unpacking libprotobuf23:arm64 (3.12.4-1) ...
Selecting previously unselected package ocl-icd-libopencl1:arm64.
Preparing to unpack .../3-ocl-icd-libopencl1_2.2.14-2_arm64.deb ...
Unpacking ocl-icd-libopencl1:arm64 (2.2.14-2) ...
Selecting previously unselected package opencl-c-headers.
Preparing to unpack .../4-opencl-c-headers_3.0~2020.12.18-1_all.deb ...
Unpacking opencl-c-headers (3.0~2020.12.18-1) ...
Selecting previously unselected package opencl-clhpp-headers.
Preparing to unpack .../5-opencl-clhpp-headers_3.0~2.0.13-1_all.deb ...
Unpacking opencl-clhpp-headers (3.0~2.0.13-1) ...
Selecting previously unselected package ocl-icd-opencl-dev:arm64.
Preparing to unpack .../6-ocl-icd-opencl-dev_2.2.14-2_arm64.deb ...
Unpacking ocl-icd-opencl-dev:arm64 (2.2.14-2) ...
Selecting previously unselected package uuid-dev:arm64.
Preparing to unpack .../7-uuid-dev_2.36.1-8+deb11u1_arm64.deb ...
Unpacking uuid-dev:arm64 (2.36.1-8+deb11u1) ...
Selecting previously unselected package xrt.
Preparing to unpack .../8-xrt_202110.2.11.0_Edge_Debian_11-arm64.deb ...
Unpacking xrt (2.11.0) ...
Setting up libboost-program-options1.74.0:arm64 (1.74.0-9) ...
Setting up libboost-filesystem1.74.0:arm64 (1.74.0-9) ...
Setting up libprotobuf23:arm64 (3.12.4-1) ...
Setting up uuid-dev:arm64 (2.36.1-8+deb11u1) ...
Setting up opencl-clhpp-headers (3.0~2.0.13-1) ...
Setting up opencl-c-headers (3.0~2020.12.18-1) ...
Setting up ocl-icd-libopencl1:arm64 (2.2.14-2) ...
Setting up dctrl-tools (2.24-3) ...
Setting up dkms (2.8.4-3) ...
Setting up ocl-icd-opencl-dev:arm64 (2.2.14-2) ...
Setting up xrt (2.11.0) ...
Unloading old XRT Linux kernel modules
rmmod: ERROR: Module zocl is not currently loaded
Invoking DKMS common.postinst for xrt
Loading new xrt-2.11.0 DKMS files...
Building for 5.10.0-xlnx-v2021.1-zynqmp-fpga
Building initial module for 5.10.0-xlnx-v2021.1-zynqmp-fpga
Done.
zocl.ko:
Running module version sanity check.
 - Original module
   - No original module exists within this kernel
 - Installation
   - Installing to /lib/modules/5.10.0-xlnx-v2021.1-zynqmp-fpga/updates/dkms/
depmod....
DKMS: install completed.
Finished DKMS common.postinst
Loading new XRT Linux kernel modules
[  367.042753] zocl: loading out-of-tree module taints kernel.
Processing triggers for libc-bin (2.31-13+deb11u2) ...

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 にプログラムされます4。

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

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

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

参考