これは何か

PYNQ-Z1 を使って遊んでみます。

まずは、以下ができるようになる事を目指します。

vivado を使って動く bit ファイルを作れるようになる
- IP Integrator を使って IP の配置や配線をする
jupyter を使ってコンフィグレーションし、python から操作できるようになる

する事

LED を点滅させる
- AXI GPIO を利用し、CPU から LED を操作する

1-1. まずはじめに

PYNQ とは

PYNQ は Zynq を python/jupyter から試験できる環境をとても簡単に提供する、Xilinx のオープンソースプロジェクトです。
- 提供されるブートイメージを SD カードに書き込んで、起動するだけで、Linux と jupyter が立ち上がるのですぐに取り組めます
Zynq は、1 チップの上に FPGA と CPU が同居した SoC (System on a Chip) です。FPGA で処理したデータを CPU で直接読み取れるので、ソフトウェアとの同居が容易です。

PYNQ-Z1 とは

PYNQ の実装のうちの一つです
- Digilent が作っている評価ボードです
例えば、下記のサイトから購入できます (2.5 万円くらいのようです)

役に立ちそうなリンク集

PYNQ 公式情報
- http://www.pynq.io/
  - PYNQ の公式ページです。様々な情報がまとめられています
- https://pynq.readthedocs.io/en/latest/getting_started.html
  - 公式ドキュメントです (必読)
  - 評価ボードのセットアップ方法から、pynq 技術の詳細 (Overlays の概要や、python pynq モジュールの詳細) が網羅されています
- チュートリアル : https://github.com/Xilinx/PYNQ_Workshop
PYNQ-Z1 公式情報
- https://reference.digilentinc.com/reference/programmable-logic/pynq-z1/start
  - PYNQ-Z1 の公式ページです。関連する情報がまとめられています
  - ボード上の配線図や、vivado に登録して使うボード情報、制約ファイルのテンプレートが置いてあります
- https://reference.digilentinc.com/reference/programmable-logic/pynq-z1/reference-manual
  - PYNQ-Z1 のマニュアルです
  - 評価ボード上の各端子の説明が書かれています
PYNQ その他
- PYNQ を使って Python で手軽に FPGA を活用 (1) - (5)
PYNNQ-Z1 で使われている Zynq XC7Z020-1CLG400C に関する情報
- DS190 : https://japan.xilinx.com/support/documentation/data_sheets/j_ds190-Zynq-7000-Overview.pdf
  - Zynq-7000 シリーズのデータシート。性能の詳細がまとめられている。
- UG865 : https://japan.xilinx.com/support/documentation/user_guides/j_ug865-Zynq-7000-Pkg-Pinout.pdf
  - Zynq-7000 シリーズの、ピン配置など
その他、Xilinx の公式ドキュメント
- Xilinx から、たくさんのドキュメントが出ているので、いろいろ探してみて、どこに何があるのか把握できるようになっておくといいでしょう
- vivado 関連
  - https://japan.xilinx.com/support/documentation-navigation/self-paced-tutorials/vivado-design-suite.html
- Artix7 (Zynq XC7Z020 の FPGA 部分) の資料
  - https://japan.xilinx.com/products/silicon-devices/fpga/artix-7.html#documentation
FPGA を勉強するとき
- https://www.acri.c.titech.ac.jp/wordpress/
  - アダプティブコンピューティング研究推進体 (ACRi) が公開している FPGA に関係する記事です。量・質ともにすごいです。
- https://ja.wikipedia.org/wiki/FPGA
  - まずは wikipedia でしょ
- FPGAの原理と構成
  - https://shop.ohmsha.co.jp/shopdetail/000000004588/
- FPGAプログラミング大全 Xilinx編
  - https://www.shuwasystem.co.jp/book/9784798047539.html

1-2. 開発の準備

開発に取り掛かる前に、環境の準備をします。

pynq のセットアップ

公式ドキュメント : PYNQ-Z1 Setup Guideを参考に、セットアップします。
- PYNQ を使って Python で手軽に FPGA を活用 (2) にも手順が書いてあります
手順は次の通りです：
1. image を公式サイト (PYNQ Boot Image) からダウンロード
2. image を SD カードに書き込む
  - mac なら、balenaEtcher などのソフトを使うと簡単で安心です
3. 公式ドキュメントの通りに、ボード上のジャンパを設定
4. SD カードを挿入して起動
  - IP : 192.168.2.99
  - サブネットマスク : 255.255.255.0
  - として起動する
5. 手元の PC のネットワーク設定を PYNQ-Z1 と同じ設定にする
  - 例えば、IP: 192.168.2.10, サブネットマスク: 255.255.255.0
6. PC と PYNQ-Z1 を繋ぐ
  - 直接 LAN ケーブルで繋ぐ場合は、クロスケーブルにする必要があるかもしれません
  - PC -- スイッチングハブ -- PYNQ と繋ぐ場合はどの LAN ケーブルでもいけるはず
7. PYNQ を起動する
  - 起動完了すると、LED が派手に光ります。1 分ほどかかります。
  - CPU は速くないので、起動完了まで待ってから作業に取り掛かる方が無難な印象です。
8. PC から web ブラウザで http://192.168.2.99:9090 へアクセスを試み、jupyter のページが表示されれば成功です
9. jupyter の [New] -> [Terminal] を選択するか、ssh でログインし (その場合、 user : xilinx, password: xilinx)、IP アドレス設定を変更しておくと、いいでしょう
  - sudo vi /etc/network/interfaces.d/eth0
    - IP アドレスを適当に変える
10. その後、手元の環境のネットワークに接続できます
  - Internet へアクセス可能になったら、まず最初に、update しておくといいと思います
    - sudo apt update
    - sudo apt upgrade -y
    - 結構時間がかかります。upgrade 中は待ちましょう。裏で upgrade が走っていたら競合してエラーが出ます。その場合は、待ちましょう。

vivado の準備

公式ページから、適当な Vivado のバージョンを選び、ダウンロードして、インストールします。
- この記事では、Vivado Design Suite - HLx Edition 2019.1 Full Product Installation を Linux 自己解凍型ウェブインストーラでインストールしました
- 新しいバージョン Vivado Design Suite - HLx Edition - 2020.1 などでも大丈夫だと思います
vivado での bit ファイル生成 (倫理合成・配置配線・ファイル生成) は、結構 CPU を食うので、用意できるなら、良い CPU を搭載した PC を開発マシンにできるといいでしょう。
- マルチプロセスには対応しているようですが、いつも、1 プロセスだけ処理が終わるまでに時間かかっているので、クロックが速い CPU の方が有利かもしれません

PYNQ-Z1 関連ファイルの準備

以下のファイルをダウンロードして準備しておきます。

ボードファイル
- https://pynq.readthedocs.io/en/latest/overlay_design_methodology/board_settings.html#vivado-board-files
- より、[Download the Pynq-Z1 board files] をクリックしてダウンロードします
- 解凍し、pynq-z1 フォルダを得ます
- pynq-z1 フォルダを /tools/Xilinx/Vivado/2019.1/data/boards/board_files/ に設置します (Linux の場合)
  - 例えば、cp -r pynq-z1 /tools/Xilinx/Vivado/2019.1/data/boards/board_files/
XDC 制約ファイル
- https://reference.digilentinc.com/reference/programmable-logic/pynq-z1/start
- より、[Master XDC] の Download をクリックしてダウンロードします
- 解凍して、PYNQ-Z1_C.xdc ファイルを得ます
- vivado から毎回参照して使うので、わかりやすい場所に置いておきます

1-3. プロジェクトの作成

例えば、デスクトップのアイコンをクリックします。

Vivado が起動します。

「Create Project」をクリックして、プロジェクトを新規作成しましょう。

プロジェクトの名前と場所を指定します。asobu ディレクトリの asobu01 プロジェクトとしました。

RTL (Register Transfer Level) プロジェクトを選択します。

ボードを選択します
- pynq-z1-関連ファイルの準備でボードファイルを登録していない場合、先に登録してください
Boards をクリックし、検索窓に pynq と入力すると絞り込まれます
PYNQ-Z1 をクリックし、Next をクリックします

これで、プロジェクトの初期設定が完了です。

このような画面になるはずです。

1-4. IP Integrator で IP を配置する

では、ここから、IP Integrator を使って、開発していきます。

大まかな手順は下記です：

ZYNQ (CPU) の IP を配置する
AXI GPIO の IP を配置する
AXI GPIO の output に LED を接続する
AXI GPIO -- ZYNQ の間を接続する (自動)

1-4-1. ZYNQ の IP を配置する

IP INTEGRATOR の Create Block Design をクリックします
ウィンドウが出てきます
名前はなんでもいいですが、とりあえずそのままにしておきましょう
OK をクリックします

モードが、PROJECT MANAGER から BLOCK DESIGN に切り替わります。

Diagram 内の、ADD IP をクリックし、
zynq で検索して、
ZYNQ7 Processing System をダブルクリックします。

IP が配置されました

1-4-2. AXI GPIO の IP を配置する

同じ要領で、AXI GPIO を配置します。

IP が追加されました。

1-4-3. AXI GPIO の出力に LED を接続する

GPIO を LED に接続しましょう。
まず、LED ポートを作ります。

名前を LED にして、Direction は Output, Type は Data にしておきます。

LED ポートが追加されました。

GPIO の出力を 32 ch から 1 ch に変更します。

GPIO IP の設定ウィンドウが出てきます
IP Configuration タブをクリックし、
All Outputs を ON
GPIO Width を 1 に変更し、
OK します

GPIO が出力のみ、1 ch になりました。

GPIO の gpio_io_o[0:0] の出力部分にマウスカーソルを持っていき、鉛筆マークになったら、ドラッグして、LED と繋ぎます。

1-4-4. ZYNQ と AXI GPIO を接続する

Diagram 上部の、Run Connection Automation をクリックします
そのまま、OK をクリック

自動配線されます。
Regenerate Layout をクリックして、見た目を整理します。
ZYNQ と GPIO が AXI Interconnect を介して配線されました。

Run Block Automation も実行しておきます。

デザインが完成しました。

Validate Design を実行して、エラーがない事を確認しておきます。

1-5. HDL Wrapper を生成する

作ったデザインを HDL Wrapper にします。

Sources から、デザインの上で右クリックし、Create HDL Wrapper をクリックします。

デフォルトで OK します

wrapper が作られました

1-6. 制約ファイルを設定する

デザインで定義した port を、実際の FPGA のピンと対応付けする制約を設定します。

Sources の Constraints で右クリックし、Add Sources をクリックします。

テンプレートファイルを追加したいので、Add Files を選択

pynq-z1-関連ファイルの準備でダウンロードしておいた、PYNQ-Z1_C.xdc ファイルを選択して、OK

xdc ファイルが追加されているので、ダブルクリックして開きます。

PYNQ-Z1 に実装されている、全ての端子の記述例が記載されています。
デフォルトでは、全てコメントアウトされているので、適宜、コメントアウトを外して設定していきます。

今回は、LED ポートを LED に接続したいので、27 行目のコメントアウトを解除して、get_ports の指定を LED に変更しました。

1-7. 生成する

設定が全て完了したので、bit ファイルを生成しましょう。

Flow Navigator の PROGRAM AND DEBUG から、Generate Bitstream をクリックします。

倫理合成・配置配線・ファイル生成が実行されます。少し時間がかかります。

問題なければ、正常に終わったと告げるウィンドウが出てきます。
失敗した場合は、エラーが出るので確認します。

Open Implemented Design をクリックすると、実装を確認できます。

1-8. PYNQ で実行する

PYNQ から生成した bit ファイルを実行するために、次の手順を踏みます：

.bit ファイルと .hwh ファイルを pynq にアップロード
pynq の python 上で pynq モジュールを import してプログラミングする

1-8-1. ファイルのアップロード

FPGA にコンフィグレーションする .bit ファイルと、python の pynq.overlays モジュールから参照させるために使う .hwh ファイルの 2 つをアップロードする必要があります。

ここでは、この 2 つのファイルを、pynq のモジュールの所定の場所にコピーする事で、どこからでも参照できるようにします。

以下、手順です。

pynq に xilinx ユーザーでログインします
- ssh の場合は、ssh xilinx@(設定したIPアドレス: 以下、仮に 192.168.2.99 とします)
- jupyter から terminal を立ち上げる場合、root ユーザーとなるので、以下のコマンドを実施後に、chown で所有者を変更しておくと良いです
/home/xilinx/pynq/overlays 以下に、プロジェクトのフォルダを作ります
- mkdir /home/xilinx/pynq/overlays/asobu01
次に、Vivado で作業していた PC に移ります
まず、~/vivado/asobu/asobu01/asobu01.runs/impl_1 の中にある、design_1_wrapper.bit を、pynq の /home/xilinx/pynq/overlays/asobu01/asobu01.bit としてコピーします。
- 例えば、scp ~/vivado/asobu/asobu01/asobu01.runs/impl_1/design_1_wrapper.bit xilinx@192.168.2.99:pynq/overlays/asobu01/asobu01.bit
続いて、~/vivado/asobu/asobu01/asobu01.srcs/sources_1/bd/design_1/hw_handoff の中にある design_1.hwh ファイルを、pynq の /home/xilinx/pynq/overlays/asobu01/asobu01.hwh コピーします
- 例えば、scp ~/vivado/asobu/asobu01/asobu01.srcs/sources_1/bd/design_1/hw_handoff/design_1.hwh xilinx@192.168.2.99:pynq/overlays/asobu01/asobu01.hwh

1-8-2. jupyter で実行

jupyter にログインし (http://192.168.2.99:9090 へアクセスします。パスワードを聞かれたら、xilinx と入れます) 、適当なノートブックファイルを生成します。

その後、ファイル名をクリックして、ノートブックを開きます。
そして編集します。コードを入力後、Shift+Enter で実行できます。

import pynq    # pynq モジュールをインポート

fpga = pynq.Overlay('asobu01.bit')  # asobu01.bit をコンフィグレーションし、
                                    # python から扱えるように初期化します

gpio = pynq.MMIO(fpga.ip_dict['axi_gpio_0']['phys_addr'], length=0x1000)
                                    # GPIO へのアクセスを得ます

gpio.write(offset=0, data=0)       # データを書きます。
gpio.write(offset=0, data=1)       # data=0 で消灯、data=1 で点灯するはずです

PYNQ で遊ぶ : 1. LED を点滅させる