/var/log/messages

debugging with sixth sense

Creating Overlays

Pynq なドキュメントにて以下を発見。

確認メモを投入してみます。

Introduction

Overlay は Programmable Logic design のクラス、とありますね。特定のタスクに最適化、か。設定できるようにデザインされてて幅広いアプリケーションが再利用できるとのこと。 Python な interface 持ってて Python パケジのように使える、のかどうか。

このセクションでは overlay を作るプロセスの概要と PYNQ への統合を案内するのだけれど、ハードウェアデザインなプロセスの詳細まではカバーできかねる、と。

Vivado design

overlay はふたつの主なパーツ、Programmable Logic (PL) および Python API から成ります。

Xilinx Vivado は PL デザインを作るのに使われます。Zynq PL をプログラムするのに使われるバイナリを生成。

Vivado の free な webpack バージョンは PYNQ-Z1 ボードの overlay が作れるみたい。

Zynq の標準的なデザインプロセスとはいくつかの違いがあるらしい。Zynq のデザインは PL デザインと PS 構成の設定という二点のパーツから成る模様。PS 構成というのは PL で使われるクロックを含めたシステムクロックの設定を含むとのこと。

ボード起動時に使われる PYNQ イメージは起動時に ZYNQ PS を設定する、のか。Overlay はプログラマが必要とされる時に download され、Zynq PS が設定しない模様。これは overlay デザイナは vivado プロジェクトにおいて PS 設定を PYNQ イメージの設定にマッチさせることを確実に行なうべき、ということを意味する、なのかな。

以下の設定は新規 vivado overlay プロジェクトのために使われるべき。

vivado プロジェクト設定:

  • ターゲットデバイス: xc7z020clg400-1

PL クロック設定

  • FCLK_CLK0: 100.00MHz
  • FCLK_CLK1: 142.86MHz
  • FCLK_CLK2: 200.00MHz
  • FCLK_CLK3: 166.67MHz

PYNQ-Z1 Master XDC (I/O 制約) は PYNQ-Z1 リソースサイトで利用できる?

PS 設定が正しいことが確実な overlay デザインで開始することが推奨される。base overlay のためのソースファイルが pynq github にて見つけることができ、リビルドも可能。

Block Diagram Tcl

vivado block diagram のための tcl も bitstream と一緒に export されるべき。これは Python にパースされる overlay に関する情報を許可します。詳細は次の節。

あなたのプロジェクトあるいは block diagram を build するためにカスタムな tcl ファイルを使うことができます。が、カスタムな tcl file は正確にパースしないかもしれません。block diagram のための tcl を export するためには vivado を使うべき。

vivado GUI から block diagram のための tcl を生成するためには

  • File > Export > Block Design をクリック

あるいは以下を tcl console から動かします。

write_bd_tcl

tcl のファイル名は .bit なファイル名と match すべき。my_overlay.bit なら my_overlay.tcl みたく。

tcl は overlay がインスタンス化される時にパースされます (download された時ではない)。

1
2
from pynq import Overlay
ol = Overlay("base.bit") # ここで tcl がパースされる

overlay を download しようとした時に tcl が有効でない、または tcl のファイル名が .bit なファイル名と match しないとエラーが表示されるでしょう。

ip_dict

overlay パケジは特定の overlay の中の IP の名前を含む ip_dict と呼ばれる辞書を生成します。その辞書は Python コードの中の名前による IP (?) の参照に使うことができ、ハードコードされたアドレスよりはそっち使ったほうが良い。overlay の中で有効な IP をチェックもできる。

overlay の IP 辞書の確認の方法は以下。

1
2
3
from pynq import Overlay
OL = Overlay("base.bit")
OL.ip_dict

ここで戻る IP 辞書のエントリは key-value ペアで以下なカンジ

1
'SEG_mg_bram_ctrl_l_Mem0' : ['0x40000000', '0x10000', None]

Note, this parses the tcl file that was exported with the bitstream. It does not do check the overlay currently running in the PL.

エントリのキーは IP インスタンスの名前; 全ての IP インスタンスの名前は *.tcl ファイル (base.tcl など) の address segment section からパースされます。エントリの値はみっつの item なリストになります

  • 最初の item は IP のベースアドレス
  • 二番目の item は adress レンジ
  • 三番目は IP の状態が、なのかな

Similarly, the PL package can be used to find the adressable IPs currently in the programmable logic:

1
2
from pynq import PL
PL.ip_dict

Existing Overlays

base overlay は Pynq リポジトリに含まれます。

それぞれのフォルダにある makefile は vivado プロジェクトをリビルドするため、そして overlay のために生成される bitstream を生成するために使われます。The bitstream and tcl for the overlay are available on the board (base.bit is loaded by default when the board boots), and in the project repository:

vivado は overlay のデザインと build を行なうために導入。

Interfacing to an overlay

MMIO

PYNQ は Zynq PS と PL 間の簡易なコミュニケーションのための MMIO Python クラスを含みます。Once the overlay has been created, and the memory map is known, the MMIO can be used to access memory mapped locations int the PL.

MMIO な Python コードは以下で見れます。

MMIO クラスは PL に記載されている開始アドレスとレンジなメモリブロックにアクセスできます。以下のコードは SEG_mb_bram_ctrl_1_Mem0 にアクセスすることを許可します。

1
2
3
4
5
6
7
from pynq import MMIO

# an IP is located at 0x40000000
myip = MMIO(0x40000000, 0x10000)

# Read from the IP at offset 0
myip.read(0)

`

上の例だと 0x10000 なレンジの外へのアクセスは MMIO パケジにて例外が発生します。 (中略) PL への不正なアクセスはシステムエラーを引き起し、Jupyter カーネルをクラッシュさせるでしょう。

新たなハードウェアの手続きとして python ドライバを作るときには python モジュールの中に MMIO は wrap できます。

Zynq GPIOs

GPIO between the Zynq PS and PL can be used by Python code as a control interface to overlays. The information about a GPIO is kept in the GPIO dictionary of an overlay, similar to the ip_dict discussed above.

以下のコードで bitstream のための辞書を取得できます。

1
2
3
from pynq import Overlay
ol = Overlay("base.bit")
ol.gpio_dict

GPIO の辞書は二つの要素なリストの辞書な模様。

1
'mb_l_reset/Din': [0, None]

key は GPIO インスタンスの名前です。GPIO インスタンスの名前は vivado の *.tcl ファイルから読み込まれて parse されます。

二要素なリストの値

  • 最初のリスト要素は GPIO のインデクスを示します
  • 二番目の要素 (None) は GPIO の状態を示します。

以下のコードは FPGA ファブリックにある GPIO の辞書を取得するために使われます。

1
2
3
from pynq import PL
pl = PL
pl.gpio_dict

CFFI

CFFI (C Foreign Function Interface) は python から C のコードへの interface を簡易な方法を提供します。CFFI パケジは pynq イメージにインストール済みです。It supports an inline ABI (Application Binary Interface) compatibility mode, which allows you to dynamiccaly load and run functions from executable modules, and an API mode, which allows you to build C extendion modules.

以下は http://docs.python-guide.org/en/latest/scenarios/clibs/ から提供される API inline mode を示す Python から C の strlen を呼び出す例です

C の関数プロトタイプ

1
size_t strlen(const char*);

C の関数プロトタイプは cdef で渡されて clib を使って呼び出されます。

1
2
3
4
5
6
from cffi import FFi
ffi = FFI()
ffi.cdef("size_t strlen(const char*);")
clib = ffi.dlopen(None)
length = clib.strlen(b"String to be evaluated.")
print("{}".format(length))

shared ライブラリにある C の関数は CFFI を使って Python から呼び出すことができます。The shared library can be compiled online using the CFFI from Python, or it can be compiled offline.

CFFI および shared library についての情報は以下。

To see examples in PYNQ on how to use CFFI, refer to the CMA class or the Audio class, both located:

Packaging overlays

overlay, tcl, Python は filesystem のどこにでも配置可能ですがそれは良い方法ではありません。

base PYNQ overlay および tcl のデフォルトの場所は以下

The PYNQ Python can be found here

PYNQ は fork 可能で Python code の追加も可能。でもカスタム overlay のためには自身のリポジトリで作って overlay を使うためには pip で install できるようにパケジできます。

pip で云々は以下を確認のこと。

Example

The following example assume an overlay that exist in the root of a GitHub repository.

リポジトリは以下な構造を持つことを想定しています。

  • notebook/
  • new_overlay.ipynb

  • new_overlay

  • new_overlay.bit
  • new_overlay.tcl
  • __init.py
  • new_overlay.py

  • readme.md

  • license

リポジトリの root に setup.py を追加しなさい。This file will imports the necessary packages, and specifies some setup instructions for your package including the package name, version, url, and files to include.

setup.py の例:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
from setuptools import setup, find_packages
import subprocess
import sys
import shutil
import new_overlay

setup(
    name = "new_overlay",
    version = new_overlay.__version__,
    url = 'https://github.com/your_github/new_overlay',
    license = 'All rights reserved.',
    author = "Your Name",
    author_email = "your@email.com",
    packages = ['new_overlay'],
    package_data = {
    '' : ['*.bit','*.tcl','*.py','*.so'],
    },
    description = "New custom overlay for PYNQ-Z1"
)

package_data はパケジの一部としてどのようなファイルが導入されるかを記述します。

From a terminal, the new package can be installed by running:

1
sudo pip install --upgrade 'git+https://github.com/your_github/new_overlay'

Using Overlays

The PL can be dynamically reconfigured with new overlays as the system is running.

Loading overlays can be done in Python using the Overlay class:

The bitstream can then be downloaded from Python:

1
2
3
from pynq import Overlay
ol = Overlay("base.bit")
ol.download()

追記

なんか少し前の節に Introduction to Overlays というものを発見してます。別エントリにてメモを残す方向。

Comments