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

注意(2023年5月10日追記)
--------------------------------------------------

この記事は2021年3月に投稿(2021年11月追記)したものであり、古い内容が含まれています。2023年5月10に以下の記事を投稿しましたので参照してください。

 * [「UltraZed/Ultra96/Ultra96-V2/KV260/KR260 向け Debian (11.7) GNU/Linux ブートイメージの提供」 @Qiita](https://qiita.com/ikwzm/items/5ba7bbb54e65fdfab367)

注意(2021年11月25日追記)
--------------------------------------------------

この記事は 2021年3月に投稿したものであり、古い内容が含まれています。2021年11月25日に以下の記事を投稿しましたので参照していください。

* [「UltraZed/Ultra96/Ultra96-V2/KV260 向け Debian GNU/Linux (v2021.1版) ブートイメージの提供」 @Qiita](https://qiita.com/ikwzm/items/a9adc5a7329b2eb36895)

はじめに
--------------------------------------------------

この記事は、UltraZed/Ultra96/Ultra96-V2 用に Boot Loader(U-Boot等)、Linux Kernel、Debian10(buster) Root File System を以下の URL に用意したので、そのインストール方法を説明します。Boot Loader や Linux Kernel のビルドが面倒くさいという方はどうぞ。

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


概要
--------------------------------------------------

* Hardware
  + UltraZed-EG-IOCC : Xilinx Zynq UltraScale+ MPSoC Starter Kit by Avnet.
  + Ultra96    : Xilinx Zynq UltraScale+ MPSoC development board based on the Linaro 96Boards specification. 
  + Ultra96-V2 : updates and refreshes the Ultra96 product that was released in 2018.
* Boot Loader
  + FSBL(First Stage Boot Loader for ZynqMP)
  + PMU Firmware(Platform Management Unit Firmware)
  + BL31(ARM Trusted Firmware Boot Loader stage 3-1)
  + U-Boot xilinx-v2019.2 (customized)
* Linux Kernel Version v5.4.0
  + [linux-xlnx](https://github.com/Xilinx/linux-xlnx) tag=xilinx-v2020.2
  + Enable Device Tree Overlay with Configuration File System
  + Enable FPGA Manager
  + Enable FPGA Bridge
  + Enable FPGA Reagion
  + Enable ATWILC3000 Linux Driver for Ultra96-V2
  + Enable CIFS (Common Internet File System)
  + Enable Xilinx APF Accelerator driver
  + Enable Xilinx APF DMA engines support
* Debian10.9(buster) Root File System
  + Installed build-essential
  + Installed device-tree-compiler
  + Installed ruby ruby-msgpack ruby-serialport
  + Installed python python3 msgpack-rpc-python
  + Installed u-boot-tools
  + Installed Other package list -> https://github.com/ikwzm/ZynqMP-FPGA-Linux/blob/v2020.2.1/files/debian10-dpkg-list.txt
* FPGA Device Drivers and Services
  + [fclkcfg    (FPGA Clock Configuration Device Driver)](https://github.com/ikwzm/fclkcfg)
  + [u-dma-buf  (User space mappable DMA Buffer)](https://github.com/ikwzm/udmabuf)

インストール
--------------------------------------------------

### ダウンロード

github から次のようにダウンロードしてください。現時点の最新バージョンは v2020.2.1 です。なお、いくつかのイメージファイルはかなり大きいので、Git LFS(Large File Storage)を使っています。お使いの環境に git-lfs がインストールされている必要があります。
**注：リポジトリ全体のダウンロードには時間がかかるため、必要なブランチのみをダウンロードしてください。**

```console
shell$ git clone --depth 1 --branch v2020.2.1 git://github.com/ikwzm/ZynqMP-FPGA-Linux
shell$ cd ZynqMP-FPGA-Linux
shell$ git lfs pull
```

### ファイルの説明

 * target/Ultra96
   + boot/
     - boot.bin                                                    : Stage 1 Boot Loader
     - uEnv.txt                                                    : U-Boot environment variables for linux boot
     - image-5.4.0-xlnx-v2020.2-zynqmp-fpga                        : Linux Kernel Image       (use Git LFS)
     - devicetree-5.4.0-xlnx-v2020.2-zynqmp-fpga-ultra96.dtb       : Linux Device Tree Blob   
     - devicetree-5.4.0-xlnx-v2020.2-zynqmp-fpga-ultra96.dts       : Linux Device Tree Source
 * target/Ultra96-V2
   + boot/
     - boot.bin                                                    : Stage 1 Boot Loader
     - uEnv.txt                                                    : U-Boot environment variables for linux boot
     - image-5.4.0-xlnx-v2020.2-zynqmp-fpga                        : Linux Kernel Image       (use Git LFS)
     - devicetree-5.4.0-xlnx-v2020.2-zynqmp-fpga-ultra96v2.dtb     : Linux Device Tree Blob   
     - devicetree-5.4.0-xlnx-v2020.2-zynqmp-fpga-ultra96v2.dts     : Linux Device Tree Source
 * target/UltraZed-EG-IOCC/
   + boot/
     - boot.bin                                                    : Stage 1 Boot Loader
     - uEnv.txt                                                    : U-Boot environment variables for linux boot
     - image-5.4.0-xlnx-v2020.2-zynqmp-fpga                        : Linux Kernel Image       (use Git LFS)
     - devicetree-5.4.0-xlnx-v2020.2-zynqmp-fpga-uz3eg-iocc.dtb    : Linux Device Tree Blob   
     - devicetree-5.4.0-xlnx-v2020.2-zynqmp-fpga-uz3eg-iocc.dts    : Linux Device Tree Source
 * debian10-rootfs-vanilla.tgz                                     : Debian10 Root File System (use Git LFS)
 * linux-image-5.4.0-xlnx-v2020.2-zynqmp-fpga_5.4.0-xlnx-v2020.2-zynqmp-fpga-3_arm64.deb   : Linux Image Package      (use Git LFS)
 * linux-headers-5.4.0-xlnx-v2020.2-zynqmp-fpga_5.4.0-xlnx-v2020.2-zynqmp-fpga-3_arm64.deb : Linux Headers Package    (use Git LFS)
 * fclkcfg-5.4.0-xlnx-v2020.2-zynqmp-fpga_1.7.2-1_arm64.deb        : fclkcfg(1.7.2) Device Driver and Services Package
 * u-dma-buf-5.4.0-xlnx-v2020.2-zynqmp-fpga_3.2.4-0_arm64.deb      : u-dma-buf(3.2.4) Device Driver and Services Package

### SD-Card のフォーマット

 1. SD-Card のパーティション１を VFAT File System でファイルシステムを作ります。
 2. SD-Card のパーティション２を ext4 File System でファイルシステムを作ります。

Linux での SD-Card のフォーマット方法は次の URL を参照してください。

 * https://github.com/ikwzm/ZynqMP-FPGA-Linux/blob/master/doc/install/format-disk-zynq.md

### SD-Card への書き込み

#### 0. SD-Card のマウント

```console
shell# mount /dev/sdc1 /mnt/usb1
shell# mount /dev/sdc2 /mnt/usb2
```

#### 1. Boot Partition のコピー

##### Ultra96 の場合

SD-Card のパーティション１(下の例では/dev/sdc1)に target/Ultra96/boot/ 下のファイルをコピーします。

```console
shell# cp target/Ultra96/boot/*                                           /mnt/usb1
```

##### Ultra96-V2 の場合

SD-Card のパーティション１(下の例では/dev/sdc1)に target/Ultra96-V2/boot/ 下のファイルをコピーします。

```console
shell# cp target/Ultra96-V2/boot/*                                        /mnt/usb1
```

##### UltraZed の場合

SD-Card のパーティション１(下の例では/dev/sdc1)に target/UltraZed-EG-IOCC/boot/ 下のファイルをコピーします。

```console
shell# cp target/UltraZed-EG-IOCC/boot/*                                  /mnt/usb1
```

#### 2. RootFS Partition の生成

SD-Card のパーティション２(下の例では/dev/sdc2)に debian10-rootfs-vanilla.tgz の中身を展開します。展開したルートファイルシステムの home/fpga にデバイスドライバの Debian パッケージをあらかじめコピーしておくと良いでしょう。後から network 経由でコピーしてもかまいません。

```console
shell# tar xfz debian10-rootfs-vanilla.tgz -C                             /mnt/usb2
shell# mkdir                                                              /mnt/usb2/home/fpga/debian
shell# cp linux-image-5.4.0-xlnx-v2020.2-zynqmp-fpga_5.4.0-xlnx-v2020.2-zynqmp-fpga-3_arm64.deb   /mnt/usb2/home/fpga/debian
shell# cp linux-headers-5.4.0-xlnx-v2020.2-zynqmp-fpga_5.4.0-xlnx-v2020.2-zynqmp-fpga-3_arm64.deb /mnt/usb2/home/fpga/debian
shell# cp fclkcfg-5.4.0-xlnx-v2020.2-zynqmp-fpga_1.3.0-1_arm64.deb       /mnt/usb2/home/fpga/debian
shell# cp u-dma-buf-5.4.0-xlnx-v2020.2-zynqmp-fpga_3.0.1-0_arm64.deb     /mnt/usb2/home/fpga/debian
```

#### 3. Boot Partition を見えるように fstab を設定

Boot Partition を Linux 側から常時見えるようにしておくと便利です。その場合は、あらかじめ fstab にブートパーティションをマウントするように設定しておくと良いでしょう。すでに fstab には configfs のマウントが設定されているので注意してください。

```console
shell# mkdir /mnt/usb2/mnt/boot
shell# cat <<EOT >> /mnt/usb2/etc/fstab
/dev/mmcblk0p1	/mnt/boot	auto	defaults	0	0
EOT
```

余談: このくらいの記述ならあらかじめ debian10-rootfs-vanilla.tgz に書いておけば良いのに、何故わざわざ後で設定するのか疑問に思われるかもしれません。その理由は、debian10-rootfs-vanilla.tgz が Ultra96 と UltraZed と共用だからです。Ultra96 の SD-Card のブートパーティションは ```/dev/mmcblk0p1``` ですが、UltraZed の SD-Card のブートパーティションは ```/dev/mmcblk1p1``` です。しかも UltraZed には /dev/mmcblk0p1 というのも存在していて、あらかじめ debian10-rootfs-vanilla.tgz に書いてしまっていると UltraZed では間違えて別のデバイスにアクセスしてしまいます。そこで、面倒ですが後で設定するようにしました。

#### 4. network の設定

Ultra96/Ultra96-V2 は WiFi を通じてネットワークに接続します。あらかじめホスト側で設定ファイルを作って RootFS に書いておくと良いかもしれません。もちろん、後で Ultra96/Ultra96-V2 を起動してそちらで設定してもかまいません。

ここでは SSID を ssssssssに、パスフレーズを ppppppppp に、暗号化したアクセスキーを xxxx とします。

まずは wpa_passphrase に SSID とパスフレーズを入力して暗号化したアクセスキーを作ります。

```console
shell# wpa_passphrase ssssssss ppppppppp
network={
	ssid="ssssssss"
	#psk="ppppppppp"
	psk=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
}
```

##### 4.1 /etc/network/interfaces.d/wlan0 に直接記述

SSID と暗号化したアクセスキーをネットワーク設定ファイル(/etc/network/interfaces.d/wlan0)に直接記述します。

```text:/mnt/usb2/etc/network/interfaces.d/wlan0

auto  wlan0
iface wlan0 inet dhcp
	wpa-ssid ssssssss
	wpa-psk  xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

##### 4.2 /etc/wpa_supplicant/wpa_supplicant.conf に記述

ネットワーク設定ファイル(/etc/network/interfaces.d/wlan0)に、次のように、ブート時に wpa_supplicant.conf を読み込んで Wifi を設定するように記述します。

```text:/mnt/usb2/etc/network/interfaces.d/wlan0

auto  wlan0
iface wlan0 inet dhcp
wpa-conf /etc/wpa_supplicant/wpa_supplicant.conf

```

SSID と暗号化したアクセスキーをWifi設定ファイル(/etc/wpa_supplicant/wpa_supplicant.conf)に記述します。

```text:/etc/wpa_supplicant/wpa_supplicant.conf
ctrl_interface=/run/wpa_supplicant
update_config=1

network={
	ssid="ssssssss"
	psk=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
}
```

なお、ステルス SSID の場合、スキャンを強制的に行う必要があります。この場合は、/etc/wpa_supplicant/wpa_supplicant.conf に ```scan_ssid=1``` を追加します。

```text:/etc/wpa_supplicant/wpa_supplicant.conf
ctrl_interface=/run/wpa_supplicant
update_config=1

network={
	ssid="ssssssss"
	scan_ssid=1
	key_mgmt=WPA-PSK
	psk=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
}
```

パスフレーズ無し の SSID に接続する場合は、```key_mgmt=NONE```(NONE は大文字) にすると良いようです。

```text:/etc/wpa_supplicant/wpa_supplicant.conf
ctrl_interface=/run/wpa_supplicant
update_config=1

network={
	ssid="ssssssss"
	scan_ssid=1
	key_mgmt=NONE
}
```

#### 5. SD-Card のアンマウント

```console
shell# umount /mnt/usb1
shell# umount /mnt/usb2
```

### デバイスドライバ パッケージのインストール

####  Ultra96/Ultra96-V2/UltraZed をブートして root でログイン

root'password is "admin".

```console
debian-fpga login: root
Password:
root@debian-fpga:~#
```

#### Linux Image Package のインストール

debian10-rootfs-vanilla.tgz にはすでに v2020.2.1 の Linux Image Package(linux-image-5.4.0-xlnx-v2020.2-zynqmp-fpga_5.4.0-xlnx-v2020.2-zynqmp-fpga-3_arm64.deb) がインストールされています。ですので、以下の作業は不要ですが、なんらかの事情で再インストールする際の参考にしてください。

```console
root@debian-fpga:~# cd /home/fpga/debian
root@debian-fpga:/home/fpga/debian# dpkg -i linux-image-5.4.0-xlnx-v2020.2-zynqmp-fpga_5.4.0-xlnx-v2020.2-zynqmp-fpga-3_arm64.deb
(Reading database ... 46095 files and directories currently installed.)
Preparing to unpack linux-image-5.4.0-xlnx-v2020.2-zynqmp-fpga_5.4.0-xlnx-v2020.2-zynqmp-fpga-3_arm64.deb ...
Unpacking linux-image-5.4.0-xlnx-v2020.2-zynqmp-fpga (5.4.0-xlnx-v2020.2-zynqmp-fpga-3) over (5.4.0-xlnx-v2020.2-zynqmp-fpga-3) ...
Setting up linux-image-5.4.0-xlnx-v2020.2-zynqmp-fpga (5.4.0-xlnx-v2020.2-zynqmp-fpga-3) ...
```

#### Linux Header Package のインストール

dpkg を使って linux-headers-5.4.0-xlnx-v2020.2-zynqmp-fpga_5.4.0-xlnx-v2020.2-zynqmp-fpga-3_arm64.deb をインストールします。

```console
root@debian-fpga:~# cd /home/fpga/debian
root@debian-fpga:/home/fpga/debian# dpkg -i linux-headers-5.4.0-xlnx-v2020.2-zynqmp-fpga_5.4.0-xlnx-v2020.2-zynqmp-fpga-3_arm64.deb
Selecting previously unselected package linux-headers-5.4.0-xlnx-v2020.2-zynqmp-fpga_5.4.0-xlnx-v2020.2-zynqmp-fpga-3_arm64.deb
(Reading database ... 46095 files and directories currently installed.)
Preparing to unpack linux-headers-5.4.0-xlnx-v2020.2-zynqmp-fpga_5.4.0-xlnx-v2020.2-zynqmp-fpga-3_arm64.deb ...
Unpacking linux-headers-5.4.0-xlnx-v2020.2-zynqmp-fpga (5.4.0-xlnx-v2020.2-zynqmp-fpga-3) over (5.4.0-xlnx-v2020.2-zynqmp-fpga-3) ...
Setting up linux-headers-5.4.0-xlnx-v2020.2-zynqmp-fpga (5.4.0-xlnx-v2020.2-zynqmp-fpga-3) ...
make: Entering directory '/usr/src/linux-headers-5.4.0-xlnx-v2020.2-zynqmp-fpga'
  HOSTCC  scripts/basic/fixdep
  HOSTLD  scripts/kconfig/conf
scripts/kconfig/conf  --syncconfig Kconfig
  HOSTCC  scripts/dtc/dtc.o
  HOSTCC  scripts/dtc/flattree.o
  HOSTCC  scripts/dtc/fstree.o
  HOSTCC  scripts/dtc/data.o
  HOSTCC  scripts/dtc/livetree.o
  HOSTCC  scripts/dtc/treesource.o
  HOSTCC  scripts/dtc/srcpos.o
  HOSTCC  scripts/dtc/checks.o
  HOSTCC  scripts/dtc/util.o
  HOSTCC  scripts/dtc/dtc-lexer.lex.o
  HOSTCC  scripts/dtc/dtc-parser.tab.o
  HOSTLD  scripts/dtc/dtc
  HOSTCC  scripts/kallsyms
  HOSTCC  scripts/conmakehash
  HOSTCC  scripts/sortextable
  HOSTCC  scripts/asn1_compiler
  HOSTCC  scripts/extract-cert
  CC      scripts/mod/empty.o
  HOSTCC  scripts/mod/mk_elfconfig
  MKELF   scripts/mod/elfconfig.h
  HOSTCC  scripts/mod/modpost.o
  CC      scripts/mod/devicetable-offsets.s
  HOSTCC  scripts/mod/file2alias.o
  HOSTCC  scripts/mod/sumversion.o
  HOSTLD  scripts/mod/modpost
make: Leaving directory '/usr/src/linux-headers-5.4.0-xlnx-v2020.2-zynqmp-fpga'
```

#### fclkcfg デバイスドライバのインストール

dpkg を使って fclkcfg-5.4.0-xlnx-v2020.2-zynqmp-fpga_1.7.2-1_arm64.deb をインストールします。

```console
root@debian-fpga:~# cd /home/fpga/debian
root@debian-fpga:/home/fpga/debian# dpkg -i fclkcfg-5.4.0-xlnx-v2020.2-zynqmp-fpga_1.7.2-1_arm64.deb
sudo: unable to resolve host debian-fpga: Name or service not known
(Reading database ... 46095 files and directories currently installed.)
Preparing to unpack fclkcfg-5.4.0-xlnx-v2020.2-zynqmp-fpga_1.7.2-1_arm64.deb ...
Unpacking fclkcfg-5.4.0-xlnx-v2020.2-zynqmp-fpga (1.7.2-1) over (1.7.2-1) ...
Setting up fclkcfg-5.4.0-xlnx-v2020.2-zynqmp-fpga (1.7.2-1) ...
```

#### udmabuf デバイスドライバのインストール

dpkg を使って u-dma-buf-5.4.0-xlnx-v2020.2-zynqmp-fpga_3.2.4-0_arm64.deb をインストールします。

```console
root@debian-fpga:~# cd /home/fpga/debian
root@debian-fpga:/home/fpga/debian# dpkg -i u-dma-buf-5.4.0-xlnx-v2020.2-zynqmp-fpga_3.2.4-0_arm64.deb
sudo: unable to resolve host debian-fpga: Name or service not known
(Reading database ... 46095 files and directories currently installed.)
Preparing to unpack u-dma-buf-5.4.0-xlnx-v2020.2-zynqmp-fpga_3.2.4-0_arm64.deb ...
Unpacking u-dma-buf-5.4.0-xlnx-v2020.2-zynqmp-fpga (3.2.4-0) over (3.2.4-0) ...
Setting up u-dma-buf-5.4.0-xlnx-v2020.2-zynqmp-fpga (3.2.4-0) ...
```

参考
--------------------------------------------------

 * https://github.com/ikwzm/ZynqMP-FPGA-Linux
 * https://github.com/ikwzm/ZynqMP-U-Boot-Ultra96
 * https://github.com/ikwzm/ZynqMP-U-Boot-Ultra96-V2
 * https://github.com/ikwzm/ZynqMP-U-Boot-UltraZed-EG-IOCC

現時点の最新バージョンは v2020.2.1 ですが、それ以前のバージョンをインストールする際は以下の記事を参照してください。

 * [「UltraZed/Ultra96/Ultra96-V2 向け Debian GNU/Linux (v2019.2版) ブートイメージの提供」 @Qiita](https://qiita.com/ikwzm/items/92221c5ea6abbd5e991c)
 * [「UltraZed/Ultra96/Ultra96-V2 向け Debian GNU/Linux (v2019.1版) ブートイメージの提供」 @Qiita](https://qiita.com/ikwzm/items/0c6f110aa19e368af03d)
 * [「Ultra96 向け Debian GNU/Linux (v2018.2版) ブートイメージの提供」 @Qiita](https://qiita.com/ikwzm/items/975ab6997905700dd2e0)
 * [「UltraZed 向け Debian GNU/Linux (v2018.2版) ブートイメージの提供」 @Qiita](https://qiita.com/ikwzm/items/6e0506fc161d1da58e9c)