FPGA+SoC+Linux+Device Tree Overlay+FPGA Region(ブートイメージの提供)

## 注意(2022年4月7日追記)

この記事は2017年に投稿し、2018年に更新したもので、古い内容が含まれています。2022年4月7日の時点で FPGA-SoC-Linux のリリースバージョンは v2.1.1 です。詳細は https://github.com/ikwzm/FPGA-SoC-Linux を見てください。


## はじめに

次の記事で Linux Kernel 4.10 から新たにサポートされた FPGA Region を紹介しました。

* [「Linux Kernel 4.10 での FPGA のサポート事情」 @Qiita](https://qiita.com/ikwzm/items/2ff7d5429da8ace7c0bd)

上の記事は紹介だけでしたが、実際に動作する環境もあった方が良いかと思い、以下の URL に ZYBO/ZYBO-Z7/PYNQ-Z1/DE0-Nano-SoC 用のビルド済みの U-Boot、Linux Kernel、Debian9-rootfs、デバイスドライバ(dtbocfgやudmabuf等)のパッケージを用意しました。

* [https://github.com/ikwzm/FPGA-SoC-Linux](https://github.com/ikwzm/FPGA-SoC-Linux)

Linux や u-boot のビルドが面倒くさいという方はどうぞ。

なお、現時点での Linux の Device Tree Overlay のサポートは暫定的かつ限定的なもので、将来どうなるかは未だ不明な部分があることをご了承ください。ここで紹介している dtbocfg と言ったデバイスドライバは、現時点で Linux が提供していないユーザー側とのインターフェースを私が勝手に追加したものです。

## 概要

* Hardware
  + ZYBO    : Xilinx Zynq-7000 ARM/FPGA SoC Trainer Board by Digilent
  + ZYBO-Z7 : Xilinx Zynq-7020 Development Board by Digilent
  + PYNQ-Z1 : Python Productive for Zynq by Digilent
  + DE0-Nano-SoC : Altera SoC FPGA Development Kit by Terasic
  + DE10-Nano    : Altera SoC FPGA Development Kit by Terasic
* U-Boot v2016.03 or v2017.11
  + Build U-Boot v2016.03 for ZYBO, PYNQ-Z1
  + Build U-Boot v2017.11 for ZYBO-Z7, DE0-Nano-SoC, DE10-Nano
  + Customized boot by uEnv.txt
  + Customized boot by boot.scr
  + Enable bootmenu
* Linux Kernel Version v4.14.34
  + Available in both Xilinx-Zynq-7000 and Altera-SoC in a single image
  + Enable Device Tree Overlay
  + Enable FPGA Manager
  + Enable FPGA Bridge
  + Enable FPGA Reagion
  + Patch for issue #3(USB-HOST does not work with PYNQ-Z1)
* Debian9(stretch) Root File System
  + Installed build-essential
  + Installed device-tree-compiler
  + Installed ruby ruby-msgpack ruby-serialport
  + Installed python python3 python3-numpy msgpack-rpc-python
  + Installed u-boot-tools
  + Installed Other package list -> https://github.com/ikwzm/FPGA-SoC-Linux/blob/master/files/dpkg-list.txt
* FPGA Device Drivers and Services
  + [dtbocfg    (Device Tree Blob Overlay Configuration File System)](https://github.com/ikwzm/dtbocfg)
  + [fclkcfg    (FPGA Clock Configuration Device Driver)](https://github.com/ikwzm/fclkcfg)
  + [udmabuf    (User space mappable DMA Buffer)](https://github.com/ikwzm/udmabuf)
  + [zptty      (Pseudo TeleTYpewriter for FPGA Device)](https://github.com/ikwzm/PTTY_AXI4)


## インストール

### ダウンロード

github から次のようにダウンロードしてください。
現時点の最新バージョンは v0.8.0 です。チェックアウトしてください。
なお、いくつかのイメージファイルはかなり大きいので、Git LFS(Large File Storage)を使っています。
お使いの環境に git-lfs がインストールされている必要があります。


```console
shell$ git clone --depth=1 --branch v0.8.0 git://github.com/ikwzm/FPGA-SoC-Linux
shell$ cd FPGA-SoC-Linux
shell$ git lfs pull
```

各ハードウェアへの詳細なインストール方法は doc/install/ の下のドキュメントを参照してください。

| Board Type    |   URL                                                                           |
|:--------------|:--------------------------------------------------------------------------------|
| ZYBO          | https://github.com/ikwzm/FPGA-SoC-Linux/blob/master/doc/install/zynq-zybo.md    |
| ZYBO-Z7       | https://github.com/ikwzm/FPGA-SoC-Linux/blob/master/doc/install/zynq-zybo-z7.md |
| PYNQ-Z1       | https://github.com/ikwzm/FPGA-SoC-Linux/blob/master/doc/install/zynq-pynq-z1.md |
| DE0-Nano-SoC  | https://github.com/ikwzm/FPGA-SoC-Linux/blob/master/doc/install/de0-nano-soc.md |
| DE10-Nano     | https://github.com/ikwzm/FPGA-SoC-Linux/blob/master/doc/install/de10-nano.md    |

### ファイルの説明

#### ZYBO

 * tareget/zynq-zybo/
   + boot/
     - boot.bin                                                    : Stage 1 Boot Loader(U-boot-spl)
     - design_1_wrapper.bit                                        : FPGA configuration file (Xilinx Bitstream Format)
     - u-boot.img                                                  : Stage 2 Boot Loader(U-boot)
     - uEnv.txt                                                    : U-Boot environment variables for linux boot
     - zImage-4.14.34-armv7-fpga                                   : Linux Kernel Image       (use Git LFS)
     - devicetree-4.14.34-zynq-zybo.dtb                            : Linux Device Tree Blob   
     - devicetree-4.14.34-zynq-zybo.dts                            : Linux Device Tree Source
   + examples/                                                     : Example Programs
 * debian9-rootfs-vanilla.tgz                                      : Debian9 Root File System (use Git LFS)
 * linux-image-4.14.34-armv7-fpga_4.14.34-armv7-fpga-1_armhf.deb   : Linux Image Package      (use Git LFS)
 * linux-headers-4.14.34-armv7-fpga_4.14.34-armv7-fpga-1_armhf.deb : Linux Headers Package    (use Git LFS)
 * dtbocfg-ctrl_0.0.5-1_all.deb                                    : dtbocfg Control Pakcage  (use Git LFS)
 * dtbocfg-4.14.34-armv7-fpga_0.0.5-1_armhf.deb                    : dtbocfg Kernel Module    (use Git LFS)
 * fclkcfg-4.14.34-armv7-fpga_1.0.0-1_armhf.deb                    : fclkcfg Kernel Module    (use Git LFS)
 * udmabuf-4.14.34-armv7-fpga_1.1.0-1_armhf.deb                    : udmabuf Kernel Module    (use Git LFS)
 * zptty-4.14.34-armv7-fpga_1.0.0-1_armhf.deb                      : zptty   Kernel Module    (use Git LFS)

#### ZYBO-Z7

 * tareget/zynq-zybo-z7/
   + boot/
     - boot.bin                                                    : Stage 1 Boot Loader(U-boot-spl)
     - u-boot.img                                                  : Stage 2 Boot Loader(U-boot)
     - uEnv.txt                                                    : U-Boot environment variables for linux boot
     - zImage-4.14.34-armv7-fpga                                   : Linux Kernel Image       (use Git LFS)
     - devicetree-4.14.34-zynq-zybo-z7.dtb                         : Linux Device Tree Blob   
     - devicetree-4.14.34-zynq-zybo-z7.dts                         : Linux Device Tree Source
 * debian9-rootfs-vanilla.tgz                                      : Debian9 Root File System (use Git LFS)
 * linux-image-4.14.34-armv7-fpga_4.14.34-armv7-fpga-1_armhf.deb   : Linux Image Package      (use Git LFS)
 * linux-headers-4.14.34-armv7-fpga_4.14.34-armv7-fpga-1_armhf.deb : Linux Headers Package    (use Git LFS)
 * dtbocfg-ctrl_0.0.5-1_all.deb                                    : dtbocfg Control Pakcage  (use Git LFS)
 * dtbocfg-4.14.34-armv7-fpga_0.0.5-1_armhf.deb                    : dtbocfg Kernel Module    (use Git LFS)
 * fclkcfg-4.14.34-armv7-fpga_1.0.0-1_armhf.deb                    : fclkcfg Kernel Module    (use Git LFS)
 * udmabuf-4.14.34-armv7-fpga_1.1.0-1_armhf.deb                    : udmabuf Kernel Module    (use Git LFS)
 * zptty-4.14.34-armv7-fpga_1.0.0-1_armhf.deb                      : zptty   Kernel Module    (use Git LFS)

#### PYNQ-Z1

 * tareget/zynq-pynqz1/
   + boot/
     - boot.bin                                                    : Stage 1 Boot Loader(U-boot-spl)
     - u-boot.img                                                  : Stage 2 Boot Loader(U-boot)
     - uEnv.txt                                                    : U-Boot environment variables for linux boot
     - zImage-4.14.34-armv7-fpga                                   : Linux Kernel Image       (use Git LFS)
     - devicetree-4.14.34-zynq-pynqz1.dtb                          : Linux Device Tree Blob   
     - devicetree-4.14.34-zynq-pynqz1.dts                          : Linux Device Tree Source
   + examples/                                                     : Example Programs
 * debian9-rootfs-vanilla.tgz                                      : Debian9 Root File System (use Git LFS)
 * linux-image-4.14.34-armv7-fpga_4.14.34-armv7-fpga-1_armhf.deb   : Linux Image Package      (use Git LFS)
 * linux-headers-4.14.34-armv7-fpga_4.14.34-armv7-fpga-1_armhf.deb : Linux Headers Package    (use Git LFS)
 * dtbocfg-ctrl_0.0.5-1_all.deb                                    : dtbocfg Control Pakcage  (use Git LFS)
 * dtbocfg-4.14.34-armv7-fpga_0.0.5-1_armhf.deb                    : dtbocfg Kernel Module    (use Git LFS)
 * fclkcfg-4.14.34-armv7-fpga_1.0.0-1_armhf.deb                    : fclkcfg Kernel Module    (use Git LFS)
 * udmabuf-4.14.34-armv7-fpga_1.1.0-1_armhf.deb                    : udmabuf Kernel Module    (use Git LFS)
 * zptty-4.14.34-armv7-fpga_1.0.0-1_armhf.deb                      : zptty   Kernel Module    (use Git LFS)

#### DE0-Nano-SoC

 * target/de0-nano-soc/
   + boot/
     - DE0_NANO_SOC.rbf                                            : FPGA configuration file  (Raw Binary Format)
     - uEnv.txt                                                    : U-Boot environment variables for linux boot
     - zImage-4.14.34-armv7-fpga                                   : Linux Kernel Image       (use Git LFS)
     - devicetree-4.14.34-socfpga.dtb                              : Linux Device Tree Blob   
     - devicetree-4.14.34-socfpga.dts                              : Linux Device Tree Source
   + u-boot/
     - u-boot-spl.sfp                                              : Stage 1 Boot Loader(U-boot-spl)
     - u-boot.img                                                  : Stage 2 Boot Loader(U-boot)
   + examples/                                                     : Example Programs
 * debian9-rootfs-vanilla.tgz                                      : Debian9 Root File System (use Git LFS)
 * linux-image-4.14.34-armv7-fpga_4.14.34-armv7-fpga-1_armhf.deb   : Linux Image Package      (use Git LFS)
 * linux-headers-4.14.34-armv7-fpga_4.14.34-armv7-fpga-1_armhf.deb : Linux Headers Package    (use Git LFS)
 * dtbocfg-ctrl_0.0.5-1_all.deb                                    : dtbocfg Control Pakcage  (use Git LFS)
 * dtbocfg-4.14.34-armv7-fpga_0.0.5-1_armhf.deb                    : dtbocfg Kernel Module    (use Git LFS)
 * fclkcfg-4.14.34-armv7-fpga_1.0.0-1_armhf.deb                    : fclkcfg Kernel Module    (use Git LFS)
 * udmabuf-4.14.34-armv7-fpga_1.1.0-1_armhf.deb                    : udmabuf Kernel Module    (use Git LFS)
 * zptty-4.14.34-armv7-fpga_1.0.0-1_armhf.deb                      : zptty   Kernel Module    (use Git LFS)

#### DE10-Nano

 * target/de10-nano/
   + boot/
     - uEnv.txt                                                    : U-Boot environment variables for linux boot
     - zImage-4.14.34-armv7-fpga                                   : Linux Kernel Image       (use Git LFS)
     - devicetree-4.14.34-socfpga.dtb                              : Linux Device Tree Blob   
     - devicetree-4.14.34-socfpga.dts                              : Linux Device Tree Source
   + u-boot/
     - u-boot-spl.sfp                                              : Stage 1 Boot Loader(U-boot-spl)
     - u-boot.img                                                  : Stage 2 Boot Loader(U-boot)
 * debian9-rootfs-vanilla.tgz                                      : Debian9 Root File System (use Git LFS)
 * linux-image-4.14.34-armv7-fpga_4.14.34-armv7-fpga-1_armhf.deb   : Linux Image Package      (use Git LFS)
 * linux-headers-4.14.34-armv7-fpga_4.14.34-armv7-fpga-1_armhf.deb : Linux Headers Package    (use Git LFS)
 * dtbocfg-ctrl_0.0.5-1_all.deb                                    : dtbocfg Control Pakcage  (use Git LFS)
 * dtbocfg-4.14.34-armv7-fpga_0.0.5-1_armhf.deb                    : dtbocfg Kernel Module    (use Git LFS)
 * fclkcfg-4.14.34-armv7-fpga_1.0.0-1_armhf.deb                    : fclkcfg Kernel Module    (use Git LFS)
 * udmabuf-4.14.34-armv7-fpga_1.1.0-1_armhf.deb                    : udmabuf Kernel Module    (use Git LFS)
 * zptty-4.14.34-armv7-fpga_1.0.0-1_armhf.deb                      : zptty   Kernel Module    (use Git LFS)

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

 1. SD-Card のパーティション１を FAT File System でファイルシステムを作ります。
 2. SD-Card のパーティション２を ext3 File System でファイルシステムを作ります。
 3. DE0-Nano-Soc/DE10-Nano の場合は、SD-Card のパーティション３を 特殊パーティション(パーティションタイプ=0xa2)にします。ファイルシステムは作りません。

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

| Board Type                      |   URL                                                                                       |
|:--------------------------------|:--------------------------------------------------------------------------------|
| Zynq-7000(ZYBO/ZYBO-Z7/PYNQ-Z1) | https://github.com/ikwzm/FPGA-SoC-Linux/blob/master/doc/install/format-disk-zynq.md         |
| Cyclen5(DE0-Nano-SoC/DE10-Nano) | https://github.com/ikwzm/FPGA-SoC-Linux/blob/master/doc/install/format-disk-de0-nano-soc.md |

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

 1. SD-Card のパーティション１(下の例では/dev/sdc1)に target/```$platform```/boot/ 下のファイルをコピーします。```$platform```には ```zynq-zybo```、```zynq-zybo-z7```、```zynq-pynqz1```、```de0-nano-soc```、```de10-nano``` の何れかを指定します。
 2. SD-Card のパーティション２(下の例では/dev/sdc2)に debian9-rootfs-vanilla.tgz の中身を展開します。
 3. 展開したルートファイルシステムの home/fpga にデバイスドライバの Debian パッケージをあらかじめコピーしておくと良いでしょう。後から network 経由でコピーしてもかまいません。
 4. DE0-Nano-Soc の場合は、SD-Card のパーティション３(下の例では/dev/sdc3)に target/de0-nano-soc/u-boot/ 下のファイルイメージを dd を使って書き込みます。

````console
shell# mount /dev/sdc1 /mnt/usb1
shell# mount /dev/sdc2 /mnt/usb2
shell# cp target/$platform/boot/*                                         /mnt/usb1
shell# tar xfz debian9-rootfs-vanilla.tgz -C                              /mnt/usb2
shell# mkdir                                                              /mnt/usb2/home/fpga/debian
shell# cp linux-image-4.14.34-armv7-fpga_4.14.34-armv7-fpga-1_armhf.deb   /mnt/usb2/home/fpga/debian
shell# cp linux-headers-4.14.34-armv7-fpga_4.14.34-armv7-fpga-1_armhf.deb /mnt/usb2/home/fpga/debian
shell# cp dtbocfg-ctrl_0.0.5-1_all.deb                                    /mnt/usb2/home/fpga/debian
shell# cp dtbocfg-4.14.34-armv7-fpga_0.0.5-1_armhf.deb                    /mnt/usb2/home/fpga/debian
shell# cp fclkcfg-4.14.34-armv7-fpga_1.0.0-1_armhf.deb                    /mnt/usb2/home/fpga/debian
shell# cp udmabuf-4.14.34-armv7-fpga_1.1.0-1_armhf.deb                    /mnt/usb2/home/fpga/debian
shell# cp zptty-4.14.34-armv7-fpga_1.0.0-1_armhf.deb                      /mnt/usb2/home/fpga/debian
shell# umount mnt/usb1
shell# umount mnt/usb2
````

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

#### リブートして fpga または root でログイン

fpga　のパスワードは "fpga"　です。

```console
debian-fpga login: fpga
Password:
fpga@debian-fpga:~$
```

root のパスワードは "admin" です。

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

#### Linux Kernel Image パッケージのインストール

dpkg を使って linux-image-4.14.34-armv7-fpga_4.14.34-armv7-fpga-1_armhf をインストールします。

なお、v0.8.0 にある debian9-rootfs-vanilla.tgz を RootFS として使う場合は、すでにこのパッケージはインストールされているので、ここで改めてインストールする必要はありません。

```console
fpga@debian-fpga:~$ cd /home/fpga/debian
fpga@debian-fpga:~/debian$ sudo dpkg -i linux-image-4.14.34-armv7-fpga_4.14.34-armv7-fpga-1_armhf.deb
Selecting previously unselected package linux-image-4.14.34-armv7-fpga.
(Reading database ... 94098 files and directories currently installed.)
Preparing to unpack linux-image-4.14.34-armv7-fpga_4.14.34-armv7-fpga-1_armhf.deb ...
Unpacking linux-image-4.14.34-armv7-fpga (4.14.34-armv7-fpga-1) ...
Setting up linux-image-4.14.34-armv7-fpga (4.14.34-armv7-fpga-1) ...
```

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

##### dtbocfg kernel module package

```console
fpga@debian-fpga:~$ cd /home/fpga/debian
fpga@debian-fpga:~/debian$ sudo dpkg -i dtbocfg-4.14.34-armv7-fpga_0.0.5-1_armhf.deb
Selecting previously unselected package dtbocfg-4.14.34-armv7-fpga.
(Reading database ... 94204 files and directories currently installed.)
Preparing to unpack dtbocfg-4.14.34-armv7-fpga_0.0.5-1_armhf.deb ...
Unpacking dtbocfg-4.14.34-armv7-fpga (0.0.5-1) ...
Setting up dtbocfg-4.14.34-armv7-fpga (0.0.5-1) ...
```

##### fclkcfg kernel module package

```console
fpga@debian-fpga:~$ cd /home/fpga/debian
fpga@debian-fpga:~/debian$ sudo dpkg -i fclkcfg-4.14.34-armv7-fpga_1.0.0-1_armhf.deb
Selecting previously unselected package fclkcfg-4.14.34-armv7-fpga.
(Reading database ... 94210 files and directories currently installed.)
Preparing to unpack fclkcfg-4.14.34-armv7-fpga_1.0.0-1_armhf.deb ...
Unpacking fclkcfg-4.14.34-armv7-fpga (1.0.0-1) ...
Setting up fclkcfg-4.14.34-armv7-fpga (1.0.0-1) ...
```

##### udmabuf kernel module package

```console
fpga@debian-fpga:~$ cd /home/fpga/debian
fpga@debian-fpga:~/debian$ sudo dpkg -i udmabuf-4.14.34-armv7-fpga_1.1.0-1_armhf.deb
Selecting previously unselected package udmabuf-4.14.34-armv7-fpga.
(Reading database ... 94215 files and directories currently installed.)
Preparing to unpack udmabuf-4.14.34-armv7-fpga_1.1.0-1_armhf.deb ...
Unpacking udmabuf-4.14.34-armv7-fpga (1.1.0-1) ...
Setting up udmabuf-4.14.34-armv7-fpga (1.1.0-1) ...
```

##### zptty kernel module package

```console
fpga@debian-fpga:~$ cd /home/fpga/debian
fpga@debian-fpga:~/debian$ sudo dpkg -i zptty-4.14.34-armv7-fpga_1.0.0-1_armhf.deb
Selecting previously unselected package zptty-4.14.34-armv7-fpga.
(Reading database ... 94220 files and directories currently installed.)
Preparing to unpack zptty-4.14.34-armv7-fpga_1.0.0-1_armhf.deb ...
Unpacking zptty-4.14.34-armv7-fpga (1.0.0-1) ...
Setting up zptty-4.14.34-armv7-fpga (1.0.0-1) ...
```

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

dpkg を使って dtbocfg-ctrl_0.0.5-1_all.deb をインストールします。

```console
fpga@debian-fpga:~$ cd /home/fpga/debian
fpga@debian-fpga:~/debian$ sudo dpkg -i dtbocfg-ctrl_0.0.5-1_all.deb
(Reading database ... 94225 files and directories currently installed.)
Preparing to unpack dtbocfg-ctrl_0.0.5-1_all.deb ...
Removed /etc/systemd/system/multi-user.target.wants/device-tree-overlay.service.
[ 2585.357805] systemd[1]: apt-daily-upgrade.timer: Adding 33min 33.391369s random time.
[ 2585.369573] systemd[1]: apt-daily.timer: Adding 3h 6min 23.779244s random time.
Unpacking dtbocfg-ctrl (0.0.5-1) over (0.0.5-1) ...
Setting up dtbocfg-ctrl (0.0.5-1) ...
Created symlink /etc/systemd/system/multi-user.target.wants/device-tree-overlay.service → /etc/systemd/system/device-tree-overlay.service.
[ 2586.021204] systemd[1]: apt-daily-upgrade.timer: Adding 25min 37.588039s random time.
[ 2586.032858] systemd[1]: apt-daily.timer: Adding 1h 39min 25.182099s random time.
[ 2586.126863] dtbocfg: loading out-of-tree module taints kernel.
[ 2586.133337] dtbocfg_module_init
[ 2586.140904] dtbocfg_module_init: OK
```

パッケージのインストールに成功すると dtbocfg デバイスドライバが有効になり、以降は systemctl で起動制御が出来るようになります。

```console
fpga@debian-fpga:~$ sudo lsmod
Module                  Size  Used by
dtbocfg                16384  0
```

```console
fpga@debian-fpga:~/debian$ sudo systemctl status device-tree-overlay.service
● device-tree-overlay.service - Device Tree Overlay Service.
   Loaded: loaded (/etc/systemd/system/device-tree-overlay.service; enabled; ven
   Active: active (exited) since Fri 2018-04-13 15:29:12 JST; 2min 7s ago
  Process: 2863 ExecStart=/sbin/modprobe dtbocfg (code=exited, status=0/SUCCESS)
 Main PID: 2863 (code=exited, status=0/SUCCESS)
   CGroup: /system.slice/device-tree-overlay.service
Apr 13 15:29:12 debian-fpga systemd[1]: Starting Device Tree Overlay Service..
Apr 13 15:29:12 debian-fpga systemd[1]: Started Device Tree Overlay Service..
```

## 参考

 * [https://github.com/ikwzm/FPGA-SoC-Linux](https://github.com/ikwzm/FPGA-SoC-Linux)
 * [「Linux Kernel 4.10 での FPGA のサポート事情」 @Qiita](https://qiita.com/ikwzm/items/2ff7d5429da8ace7c0bd)
 * [「FPGA+SoC+LinuxでDevice Tree Overlayを試してみた」 @Qiita](http://qiita.com/ikwzm/items/ec514e955c16076327ce)
 * [「FPGA+SoC+Linux で FPGA Manager を試してみた」 @Qiita](http://qiita.com/ikwzm/items/9eb4d49545636162057e)
 * [「FPGA+SoC+Linux で FPGA Manager を試してみた(まとめ)」 @Qiita](http://qiita.com/ikwzm/items/393d483131bcf6ad7cb0)
 * [「FPGA+SoC+Linux で FPGA Manager を試してみた(まとめ2)」 @Qiita](http://qiita.com/ikwzm/items/4f89cf7cb42f6cc2705f)