仕事：PYNQとOverlayによる開発手順確立
nikuPYNQとOverlayを触ったことはあるものの、いい感じに開発に取り込む手順を確立していないのでこれを考案したい。
nikuまずは、手持ちのPYNQ-Z1の公式の情報源からPYNQをつかってブートするまでの手順をまとめてみる
nikuPYNQ-Z1はDIGILENTのボードで がある意味公式の情報源だろう
このページでPYNQを関係の情報がないか探してみると
PYNQ Manual:
PYNQ Github:
が見つかった
nikuどちらが、当面の目標である。PYNQのPrecompiled Imageを使ったブートに近いかというと
であろう。
よって、まずはこのページを読んでみる
niku
の概要に記載されている情報の自分用要約：
・PYNQとは：ザイリンクスのオープンソースプロジェクトのこと
（勉強時点での感想：正式にはプロジェクト名だったということか、とはいえ、プロジェクトから派生した成果物のこともPYNQと読んでいるに違いない）
・PYNQの目的：Zynq All Programmable Systems on Chips (APSoC)を使用した組み込みシステムの設計を容易にすること
・プロジェクトの情報源：
niku
のセクション
Precompiled Imageの自分用要約：
・PYNQはさまざまなボードをサポートしている。
・サポートしているボード一覧のURL：https://www.pynq.io/boards.html
・Precompiled Imageを使ってPYNQを利用する手順：
- precompiled imageをダウンロードする
- micro SDカードにprecompiled imageを書き込む
- micro SDカードからボードをブート
（勉強時点での感想：すでに当面の目標であるPYNQのPrecompiled Imageを使ったブートのざっくりとした手順が記載されている）
セクションQuick Startの自分用要約：
・SDカードにprecompiled imageを書き込む方法の詳細が記載されているURL：
（勉強時点での感想：上記の大まかな手順を実際に実行する際に読まねばならないだろう）
niku
のセクション
Python Source Codeはブートには関係なさそうなので今は省略
Board Files and OverlaysはOverlayに関係しそうなので現時点の目標からは離れているが一応記録
・Vivadoプロジェクト、ビットストリーム、サンプルノートブックなどボードに関連したすべてのファイルは/boardsフォルダにある（github上に表示されているやつ）
・Linuxなら対応するオーバーレイフォルダ（例）/boards/Pynq-Z1/baseでmakeを実行することでオーバーレイを再構築できるらしい（再構築する意義は現時点では不明）
残りのセクションは現時点では特に関心がないので省略
nikuPYNQ-Z1 のPrecompiled ImageのSDカードを作成する方法
imageのダウンロード
で
Downloadable PYNQ imagesの
PYNQ-Z1 SD card image v3.0.1からダウンロード
ファイル：pynq_z1_v3.0.1.zipがダウンロードされるので
これを展開すると
ファイル：pynq_z1_v3.0.1.img
が得られる。
SD Cardにイメージを書き込む
USBのSD Cardリーダーを接続して /dev/sdbであることを確認
sudo dd bs=4M if=pynq_z1_v3.0.1.img of=/dev/sdb
でSDカードにイメージを書き込む
niku今SD Card回りで作業できないので、周辺知識を勉強
PYNQ Overlays
を参考に勉強する
The AMD-Xilinx® Zynq® All Programmable deviceについて覚える
SOCである
dual-core ARM® Cortex®-A9 processorがベース＝PS部がベース
PS部＝Processing System または PSと呼ぶ
（※私見：いままでFPGAのほうが主とみなしてたけど、PSが主と考えるべきなのかもしれん）
PSにFPGA fabric（結構ファブリックという言い回しがでてくるのはFPGAを指しているのかもしれん）＝PL部が統合されている。
PL部＝Programmable Logic または PL
Overlayについて
PSは多数の周辺機器へのインターフェース（memory controllers, USB, Uart, IIC, SPI etc）が含まれており（※私見：PLにアクセスする手段は固定であることを暗黙的に匂わせているのではなかろうか）、PL Overlayで追加のハードウェアIPを使用して拡張できる。（私見：多分PSはOSなどPS関連のイメージで決定される固定のCPU動作で動かして、別途PL部分を再プログラミング可能であることを示唆しているのかも）
PYNQについて
PYNQはPL OverlayをPSで実行されているPythonから制御できるようにするPythonインターフェースを提供する。
nikuPYNQ-Z1をブート後の操作
を参考にブート後の操作手順を記録する
- PYNQ-Z1とLANケーブルで接続しているPCのIPアドレスを192.168.2.100に設定
- ping 192.168.2.99でレスポンスがあることを確認
- Webブラウザからhttp://192.168.2.99にアクセス
- passwordが問われるのでxilinxと入力
- jupyter notebookが表示されるので色々試してみる
以上
nikuPYNQ Overlay 続き
を参考に読み進めていく
Loading an Overlay
デフォルトでは PSブート時にbase と呼ばれる overlay(≒bitstream)がPLにダウンロードされる。
自作のoverlay(≒bitstream)はPS動作中にPLにダウンロード可能。
overlayに含まれるもの
- FPGA fabricをConfigurationするbitstream
- 利用可能なIPを決定する Vivado design HWH file
- IPを属性として公開するためのPython API
と書いたはいいものの、わからないことが多すぎる
bitstream：わかる
Vivado design HWH file：わからない
Python API：わからない
ので、とりあえずこのページを読み進めるものの、わからなかったら調べる
Overlayをロードする手順
from pynq import Overlay
overlay = Overlay("base.bit")
以上がoverlayをロードする方法である。
要はOverlayクラスをインスタンス化するときに引数としてbitstreamのファイルパスを指定しなくてはならない
ことが重要なことの一つで、ここからは推測できないが、このOverlayをインスタンス化する際にbitstreamファイルに対し何かしらの規則を満たした（場所？名前？）HWHファイルが解析されるらしい。HWH fileは利用可能なIPを決定するという知識から、HWHによって自作bitstreamファイルに対してPYNQでアクセス可能なレジスタなどが決まってくるのだろう。
基本オーバーレイおそらくbaseのことだろうが、、それもBaseOverlayというクラスで利用できるようだ。
baseオーバーレイのビットストリームファイルを自動的に読み込むのかと思ったら、インスタンス化の際にビットストリームファイルのパスを指定しているし、HWHファイルの読み方が変わってくるということなのだろうか？謎である。
BaseOverlayについて
from pynq.overlays.base import BaseOverlay
base_overlay = BaseOverlay("base.bit")
help(base_overlay)
を実行すると、BaseOverlayオブジェクトについての解説が出力され
__init__メソッドのNoteに
Note ---- This class requires a Vivado '.hwh' file to be next to bitstream file with same name (e.g. base.bit and base.hwh).
とあり、bitファイルと同名のhwhファイルを同じディレクトリ階層に配置しろって書いてある
上記の謎が少しだけとけた
nikuHWHファイルについて
とりあえず、結局HWHファイルについては謎なので、どこかに情報がないか調べたら にちょっとだけ記述があった。
The HWH (hardware handoff) file is automatically generated from the Vivado IP Integrator block design and it is used by PYNQ to automatically identify the Zynq system configuration, IP including versions, interrupts, resets, and other control signals.
つまり、HWHはhardware handoff fileの略称で Vivado IP integrator block designで自動的に生成され、
PYNQによって、自動的にZynq system configurationをどうすればいいか認識するのに利用されるようだ。
また、
The HWH file is automatically generated by Vivado when generating the bitstream. The HWH file must be provided with the bitstream file as part of an overlay. The PYNQ PL class will automatically parse the HWH file.
とのこと、まあVivadoでbitstreamファイル生成時に自動的に作られるから、PYNQで使うときは忘れずにbitファイルとhwhファイルをもってこいということ。
nikuPYNQ-Z1 Overlayについて
を読んでいく
PYNQ-Z1ボード用のPYNQ imageにはデフォルトで次のオーバーレイが含まれている
- Base Overlay
https://pynq.readthedocs.io/en/latest/pynq_overlays/pynqz1/pynqz1_base_overlay.html - Logictools Overlay
https://pynq.readthedocs.io/en/latest/pynq_overlays/pynqz1/pynqz1_logictools_overlay.html
このボードで利用できるサードパーティー製のOverlayもある詳しくは
nikuPYNQ-Z1 Base Overlayについて
を読んでいく
Base Overlay
Base Overlayの目的はPYNQがボード上の周辺機器をすぐに使用できるようにすること。
このデザインには、ターゲットボード上の周辺機器を制御するハードウェアIPが含まれていて、これらのIPをZynqPSに接続する。
とりあえず、Base Overlayが存在するボードはシステム起動後すぐにPythonから周辺機器にアクセス可能であることを意味しているようだ。
Base Overlayにはボード上の周辺機器用のIPが含まれているため、新しいカスタマイズされたOverlayを作成するためのレファレンスデザインとして利用できる。
（どこでカスタマイズする元のデータが手に入るか後でしっかり調査する必要がある。多分
にある）
PYNQ-Z1 Block Diagram
PYNQ-Z1のBase OverlayとそのI/Oに関するブロック図が記載されている。
中間の節は飛ばして
Python API
Rebuilkding the Overlay
Base Overlayのプロジェクトファイルは
<PYNQ repository>/boards/<board>/base
Linux
LinuxでBaseOverlayをリビルドしたい場合はMakefileが与えられている。
このMakefileは２つのtclファイルを呼び出して、デザイン中で使われているHLS IPをコンパイルして、Overlayとしてビルドする。
手順は
# 自分の環境ではVivadoは/tools/Xilinx/Vivado/2022.1/にインストールされているので
source /tools/Xilinx/Vivado/2022.1/settings64.sh
cd <PYNQ repository>/boards/Pynq-Z1/base
make
この手順はVivadoのプロジェクトファイルが
<PYNQ repository>/boards/Pynq-Z1/base/base/base.xpr
に生成されるため、めちゃ重要
nikuPYNQ community projectsを読む
最後に？ を起点に情報をひろっていく
当面読んでいきたいのは
nikuPYNQ_Workshopを読んでみる
このあたりから読んどけば、PYNQからPLのIOを操作するための流れはわかる（PYNQ-Z1とかBaseOverlayがあるやつのみ）
niku
を見る
ぶっちゃけ
に書いてあることを動画化しただけ
HLSを使ってない人にはあんまり意味ないかも
を見る
AXI DMAの実例かな、あとでもっときちんと見てみる