ZYBO Z7-10/Z7-20用のPYNQ環境の構築

Pocket

ZYBO Z7-20でPYNQを使う からだいぶ時間がたって手順がちょっと変わってしまっていました.そこで,あらためて,公式ドキュメントを参考に環境を構築して,ZYBo Z7-10/Z7-20で動作するPYNQ環境を作るまでの手順を紹介します.
作業環境のOSは Ubuntu 22.04で,PYNQのビルド環境はVirtualBox上の Ubuntu 20.04 上に構築します.セットアップするPYNQは,3.0.1 です.ビルドに使用するVivadoとPetaLinuxは2022.1です.https://www.xilinx.com/support/download.html からダウンロードしておきます.

Vivadoのインストール

ホストOSにVivado 2022.1をインストールして,2022.1.1と2022.1.2までアップデートしておきましょう.ここでは,以降,/tools/Xilinx/Vivado/2022.1 にVivadoがインストールされていると想定して話をすすめます.PYNQ v2.5以降ではSDxは不要になっている(というか,なくなった)ので,普通にVivadoをインストールすればOKです.

後述のVirtualBox環境上にVivadoをインストールしてもいいのですが,PYNQの環境構築時以外は,ホストOS上で直接Vivadoを起動した方が嬉しいから,というのがホストOS上にVivadoをインストールする理由です.

Ubuntu 22.04上で正常にインストール,起動するためには,

$ sudo apt install libtinfo5 libncurses-dev libxt-dev

が必要かもしれません(インストーラが固まってしまったら試してみてください).

Vivadoのインストールが終わったら,ZYBO Z7-20のボードファイルを使ってプロジェクトを作れるようにセットアップします.

https://github.com/Digilent/vivado-boards を一式をダウンロードしたら,/tools/Xilinx/Vivado/2022.1/data/xhub/boards/XilinxBoardStore/boards/Digilent ディレクトリを作成して,その下に,new/board_files 以下のファイルをコピーします.

VirtualBoxのインストール

ドキュメント通りVagrant使うのがいいのかもしれませんが,あとからもUbuntu 20.04環境を別に流用することもあるかもしれない,と,手動でセットアップしました.
Download VirtualBox for Linux Hosts から,virtualbox-7.0_7.0.10-158379~Ubuntu~jammy_amd64.deb をダウンロードして apt でインストールしました.

VirtualBox上にUbuntu 20.04をインストール

VirtualBoxをインストールしたら,Ubuntu 20.04.6をセットアップします.PetaLinuxのドキュメントには,サポートOSとして 20.04.3 までしか記載されてませんが,Ubuntuのダウンロードサイトから普通にダウンロードできる 20.04.6 を使います.好みで server 版を選択しました.

OSのセットアップが終わったら,開発環境一式をインストールして,Guest Additionalをセットアップします.

$ sudo apt update
$ sudo apt install build-essential
$ sudo mount /dev/cdrom /mnt # Devices -> Insert Guest Additions CD imagee...の後.
$ cd /mnt
$ sudo ./VBoxLinuxAdditions.run 

OSをセットアップしたら,ホストOSの /tools を ゲストOSでも /tools にマウントして Vivado を使えるようにしておきます.その他,必要に応じて,ホストOSの /home を ゲストOSの適当な場所にマウントする,とか,ホストオンリーネットワークで,ホストOS-ゲストOS間のやりとりが楽になるようにしておくとよいでしょう.

また,PYNQビルド中に sudo が必要になるので,気にならない環境なのであれば,visudo を使うなどして, /etc/sudoers に,

ユーザ名    ALL=NOPASSWD:    ALL

と設定して,パスワード不要で sudo を使えるようにしておくと便利です.

PYNQのビルド準備

PYNQのリポジトリクローンして,セットアップスクリプトを実行しましょう…というのが公式の手順ですが,途中で必要なライブラリやリポジトリが不足して詰まるので先にセットアップ,インストールしておきます.

$ sudo dpkg --add-architecture i386
$ sudo apt update
$ sudo apt install libncurses-dev
$ sudo apt install libtinfo-dev libtinfo5

特に, dpkg --add-architecture i386 を実行しておかないと,途中で,

E: Unable to locate package zlib1g:i386

とか言われてやりなおしが必要になります.準備ができたら,PYNQリポジトリをクローンして,セットアップスクリプトを実行しましょう.ここで,$WORKは,好きな作業ディレクトリです.

cd $WORK
git clone https://github.com/Xilinx/PYNQ.git
cd $WORK/PYNQ/sdbuild
./scripts/setup_host.sh

必要なパッケージのインストールと,crosstool-ngqemu のビルドが進行します.セットアップが終わったら,$HOME/.bashrc

PATH=/opt/qemu/bin:/opt/crosstool-ng/bin:$PATH

を追加しておきましょう.ビルド環境のセットアップが終わったら,ビルド時に必要な,事前ビルド済みのLinuxイメージをダウンロードしておきます.具体的には,pynq.io – Development Boardsから,PYNQ rootfs arm v3.0.1Prebuilt PYNQ source distribution binary v3.0.1 をダウンロードして,それぞれ

$ cp jammy.arm.3.0.1.gz $WORK/PYNQ/sdbuild/prebuilt/pynq_rootfs.arm.tar.gz
$ cp pynq-3.0.1.tar.gz $WORK/PYNQ/sdbuild/prebuilt/pynq_sdist.tar.gz

としてコピーします.

PetaLinuxのインストール

最後にPetaLinux 2022.1をインストールしましょう.ダウンロードしておいた petalinux-v2022.1-04191534-installer.run をゲストOS上にコピーして,

$ chmod 755 petalinux-v2022.1-04191534-installer.run
$ ./petalinux-v2022.1-04191534-installer.run -d /opt/xilinx/petalinux-v2022.1-04191534

としてインストールします.インストール先のディレクトリ名に,v2022.1 とバージョン名をいれておく必要があります.

試しにビルド(オプション)

ビルド環境が正しく構築できたかどうか,リポジトリにビルドスクリプトが用意されているPYNQ Z-1向けの環境をビルドして試してみましょう.

VivadoとPetaLinuxの環境変数を読み込んで

$ source /tools/Xilinx/Vivado/2022.1/settings64.sh
$ source /opt/xilinx/petalinux-v2022.1-04191534/settings.sh

$WORK/PYNQ/sdbuild ディレクトリに移動して make します.

$ cd $WORK/PYNQ/sdbuild
$ BOARDS=Pynq-Z1 make

環境構築が終わっていれば,1-2時間後くらいに $WORK/PYQN/sdbuild/outputs/Pynq-Z1-3.0.1.img が生成されるはずです.

ZYBO Z7-10/Z7-20向けPYNQ環境のビルド

FPGAデザインの作成,スペックファイルおよび必要なファイルの用意,ビルド,の3手順が必要です.

FPGAデザインの作成

Z7-10/Z7-20用のビルド環境は用意されていないので自分で作成します.ベースとなるFPGAデザインは,ZYBO Z7-20でPYNQを使う で紹介した

のような簡単なものを作成すればOKです.Vivadoは2022.1を使うこと,プロジェクトをZ7-20向けに作成する(たとえZ7-10で実行するとしても)ことが肝です.

Generate Bitstreamに成功したら,PYNQ環境のビルドに必要なファイル .xsa.bit.hwh.bitファイルを取り出します.

.xsaファイル

File -> Export -> Export Hardware... でダイアログを開き,途中 Include bitstream を選択して作成します.ここでは,デフォルトのままdesign_1_wrapper.xsa という名前で保存しました.

.bitファイル

./zybo_z7_20_base.runs/impl_1/design_1_wrapper.bit にあります.ここでは,base.bit という名前で保存しました.

.hwhファイル

./zybo_z7_20_base.gen/sources_1/bd/design_1/hw_handoff/design_1.hwh にあります.

.tclファイル

Open Block Design でブロックデザインを開いたら File -> Export -> Export -> Export Block Design... で 生成できます.design_1.tcl という名前で保存しました.

スペックファイルおよび必要なファイルの準備

Z7-10/Z7-20向け環境用のファイルを $WORK/PYNQ/myboards/Z7-20/ ディレクトリの下に準備することにします.

スペックファイル

以下の内容で $WORK/PYNQ/myboards/Z7-20/Z7-20.spec を作成します.以前は不要だった xrt がないと,PYNQ上でのオーバレイに失敗するので注意してください.

ARCH_Z7-20 := arm
BSP_Z7-20 :=
BITSTREAM_Z7-20 := base.bit
STAGE4_PACKAGES_Z7-20 := pynq ethernet xrt

必要なファイルの配置

FPGAデザインおよび空のPythonスクリプト boot.py$WORK/PYNQ/myboards/Z7-20/に以下のように配置します.

$WORK/PYNQ/myboards/Z7-20/
├── Z7-20.spec
├── base.bit
├── boot.py
├── design_1.hwh
├── design_1.tcl
└── petalinux_bsp
    └── hardware_project
        └── design_1_wrapper.xsa

ビルド

ビルド用のMakefileのある $WORK/PYNQ/sdbuild に移動して make を実行します.ターゲットを,BOARDDIRBOARDS で指定する必要があることに注意してください.

$ cd $WORK/PYNQ/sdbuild/
$ BOARDDIR=$WORK/PYNQ/myboards BOARDS=Z7-20 make all

これで,1-2時間後くらいに $WORK/PYQN/sdbuild/outputs/Z7-20-3.0.1.img が生成されるはずです.SDカードに dd などで書き込んで ZYBO Z7-10/Z7-20を起動してみましょう.なお,ボード上の Programming mode select jumper のジャンバが SD になっていることを確認して起動してください.

起動

UART越しで /dev/ttyUSB1115200 で開いて接続すれば,起動時のログが流れるはずです.また,起動してしばらくすると,192.168.2.99xilinxユーザでログインできる他,Webブラウザで192.168.2.99:9090 にアクセスすれば Jupyter Notebookにログインすることができます(パスワードは xilinx です).