Ultra96/Ultra96-V2/KV260 向け Debian GNU/Linux および Ubuntu20.04 で XRT(Xilinx Runtime) を動かす(2.11.0 インストール編)







# はじめに


筆者は Ultra96/Ultra96-V2/KV260(ZynqMP) 向けに Debian GNU/Linux[1] と Ubuntu20.04[2] を提供しています。また、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.8.1 ビルド編]
  * [XRT 2.6.0 ビルド編]
* インストール編
  *  __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


```console
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


* リポジトリ: https://github.com/ikwzm/ZynqMP-FPGA-XRT
* ブランチ: [2021.1_EDGE_0\_Ubuntu_20.04]
* XRT バージョン:  2.11.0
* Linux ディストリビューション: Ubuntu 20.04
* パッケージファイル: xrt_202110.2.11.0_Edge_Ubuntu_20.04-arm64.deb


```console
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  カーネルモジュールをビルドします。そのためインストールに時間がかかります。


```console: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 の例を示します。


```devicetree: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 にプログラムしておく必要があるのです。




# 参考


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


[1]: https://github.com/ikwzm/ZynqMP-FPGA-Linux "https://github.com/ikwzm/ZynqMP-FPGA-Linux"
[2]: https://github.com/ikwzm/ZynqMP-FPGA-Ubuntu20.04 "https://github.com/ikwzm/ZynqMP-FPGA-Ubuntu20.04"
[3]: https://github.com/Xilinx/XRT "https://github.com/Xilinx/XRT"
[4]: https://qiita.com/ikwzm/items/2ff7d5429da8ace7c0bd "『Linux Kernel 4.10 でのFPGAのサポート事情』@Qiita"
[ZynqMP-FPGA-Linux]: https://github.com/ikwzm/ZynqMP-FPGA-Linux "https://github.com/ikwzm/ZynqMP-FPGA-Linux"
[XRT]: https://github.com/Xilinx/XRT "https://github.com/Xilinx/XRT"
[2021.1_EDGE_0\_Debian_11]: https://github.com/ikwzm/ZynqMP-FPGA-XRT/tree/2021.1_EDGE_0_Debian_11
[2021.1_EDGE_0\_Ubuntu_20.04]: https://github.com/ikwzm/ZynqMP-FPGA-XRT/tree/2021.1_EDGE_0_Ubuntu_20.04
[2020.2_EDGE_1\_Debian_10]: https://github.com/ikwzm/ZynqMP-FPGA-XRT/tree/2020.2_EDGE_1_Debian_10
[2020.2_EDGE_1\_Ubuntu_20.04]: https://github.com/ikwzm/ZynqMP-FPGA-XRT/tree/2020.2_EDGE_1_Ubuntu_20.04
[2019.2_Ultra96_3]: https://github.com/ikwzm/ZynqMP-FPGA-XRT/tree/2019.2_Ultra96_3
[概要編]: https://qiita.com/ikwzm/items/0d3a8adfe725cd17f932 "『Ultra96/Ultra96-V2/KV260 向け Debian GNU/Linux および Ubuntu20.04 で XRT(Xilinx Runtime) を動かす(概要編)』@Qiita"
[XRT 2.11.0 ビルド編]: https://qiita.com/ikwzm/items/ad4ef8a3fe085c80cf32 "『Ultra96/Ultra96-V2/KV260 向け Debian GNU/Linux および Ubuntu20.04で XRT(Xilinx Runtime) を動かす(2.11.0 ビルド編)』@Qiita"
[XRT 2.8.1 ビルド編]: https://qiita.com/ikwzm/items/765dc4046746d35ef45c "『Ultra96/Ultra96-V2 向け Debian GNU/Linux で XRT(Xilinx Runtime) を動かす(2.8.1 ビルド編)』@Qiita"
[XRT 2.6.0 ビルド編]: https://qiita.com/ikwzm/items/d8013ea91125a3fc46aa "『Ultra96/Ultra96-V2 向け Debian GNU/Linux で XRT(Xilinx Runtime) を動かす(2.6.0 ビルド編)』@Qiita"
[XRT 2.6.0 インストール編]: https://qiita.com/ikwzm/items/6612eacc4a0d324a0a68 "『Ultra96/Ultra96-V2 向け Debian GNU/Linux で XRT(Xilinx Runtime) を動かす(2.6.0 インストール編)』@Qiita"
[実践編]: https://qiita.com/ikwzm/items/58cfea3f9d0f42840511 "『Ultra96/Ultra96-V2 向け Debian GNU/Linux で XRT(Xilinx Runtime) を動かす(実践編)』@Qiita"
[Vitis編]: https://qiita.com/ikwzm/items/e70d8d0e44fe3784a708 "『Ultra96/Ultra96-V2 向け Debian GNU/Linux で XRT(Xilinx Runtime) を動かす(Vitis編)』@Qiita"
[『UltraZed/Ultra96/Ultra96-V2/KV260 向け Debian GNU/Linux (v2021.1版) ブートイメージの提供』@Qiita]: https://qiita.com/ikwzm/items/a9adc5a7329b2eb36895 "『UltraZed/Ultra96/Ultra96-V2/KV260 向け Debian GNU/Linux (v2021.1版) ブートイメージの提供』@Qiita"
[『UltraZed/Ultra96/Ultra96-V2 向け Debian GNU/Linux (v2019.2版) ブートイメージの提供』@Qiita]: https://qiita.com/ikwzm/items/92221c5ea6abbd5e991c "『UltraZed/Ultra96/Ultra96-V2 向け Debian GNU/Linux (v2019.2版) ブートイメージの提供』@Qiita"
[『Linux Kernel 4.10 でのFPGAのサポート事情』@Qiita]: https://qiita.com/ikwzm/items/2ff7d5429da8ace7c0bd "『Linux Kernel 4.10 でのFPGAのサポート事情』@Qiita"
[『FPGA の Partial Reconfiguration の紹介(Vivado デザインフロー編)』@Qiita]: https://qiita.com/ikwzm/items/1ffb695bc1b6c8679710 "『FPGA の Partial Reconfiguration の紹介(Vivado デザインフロー編)』@Qiita"