/var/log/messages

Mar 8, 2019 - 11 minute read - Comments - programming

Creating Overlays

以下なドキュメントの無断機械翻訳を自分メモ。

Introduction

PYNQの紹介で説明したように、オーバーレイはソフトウェアライブラリに似ています。 プログラマは実行時にオーバーレイをZynq®PLにダウンロードして、ソフトウェアアプリケーションに必要な機能を提供できます。

オーバーレイはプログラマブルロジックデザインの一種です。 プログラマブルロジックデザインは通常、特定のタスクに対して高度に最適化されています。 ただし、オーバーレイは構成可能で、幅広いアプリケーションに再利用できるように設計されています。 PYNQオーバーレイはPythonインタフェースを持ち、ソフトウェアプログラマが他のPythonパッケージと同じように使用できるようにします。

プログラマはオーバーレイを使用できますが、通常はオーバーレイを作成しません。これはハードウェア設計者にとって特別な作業だからです。

このセクションでは、オーバーレイを作成してそれをPYNQに統合するプロセスの概要を説明しますが、ハードウェア設計プロセスの詳細については説明しません。

Vivado design

オーバーレイは2つの主要部分で構成されています。プログラマブルロジック(PL)設計とPython API

ザイリンクスVivadoソフトウェアを使用してPLデザインを作成します。これにより、Zynq PLのプログラムに使用されるビットストリームまたはバイナリファイル(.bitファイル)が生成されます。

無料のWebパック版のVivadoをPYNQ-Z1ボードと共に使用すると、オーバーレイを作成できます。 https://www.xilinx.co.jp/products/design-tools/vivado/vivado-webpack.html

標準のZynqデザインプロセスと、PYNQのオーバーレイデザインとの間にはいくつかの違いがあります。 ZynqデザインのVivadoプロジェクトは2つの部分で構成されています。 PL設計、およびPS構成設定。 PS設定には、PLで使用されるクロックを含むシステムクロックの設定が含まれています。

ボードを起動するために使用されるPYNQイメージは、起動時にZynq PSを構成します。オーバーレイはプログラマの要求に応じてダウンロードされ、Zynq PSを再設定しません。つまり、オーバーレイデザイナーは、VivadoプロジェクトのPS設定をPYNQイメージ設定と一致させる必要があります。

新しいVivadoオーバーレイプロジェクトには、次の設定を使用する必要があります。

Vivadoプロジェクト設定:

対象デバイス:xc7z020clg400-1
PLクロック構成

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

PYNQ-Z1マスターXDC(I / O制約)は、Digilent PYNQ-Z1リソースサイトで入手できます。https://reference.digilentinc.com/reference/programmable-logic/pynq-z1/start

PS設定が正しいことを確認するために、既存のオーバーレイデザインから始めることをお勧めします。 ベースオーバーレイのソースファイルは、pynq GitHubにあります。プロジェクトは、次のmakefileを使用して再構築できます。

<GitHub repository>/Pynq-Z1/vivado/base

Block Diagram Tcl

Vivadoブロックダイアグラムのtclもビットストリームと一緒にエクスポートする必要があります。これにより、オーバーレイに関する情報をPythonに解析することができます(たとえば、オーバーレイ内のIPのリスト)。 tclファイルをクエリする方法の詳細については、次のセクションを参照してください。

カスタムtclファイルを使用してプロジェクトを構築したり、ダイアグラムをブロックすることはできますが、カスタムtclファイルは正しく解析されない可能性があります。ブロックダイアグラムのtclをエクスポートするにはVivadoを使用する必要があります。これにより、Pythonで正しく解析できるようになります。

Vivado GUIからブロックダイアグラムのtclを生成するには、次の手順に従います。

  • File -> Export -> Block Design をクリックします。

または、tclコンソールで次のコマンドを実行してください。

write_bd_tcl

tclファイル名は、.bitファイル名と一致する必要があります。例えば my_overlay.bitとmy_overlay.tcl です。

tclはオーバーレイがインスタンス化されるときに解析されます(ダウンロードされるときではありません)。

from pynq import Overlay
ol = Overlay("base.bit") # tcl is parsed here

オーバーレイをダウンロードしようとしたときにtclが利用できない場合、またはtclファイル名が.bitファイル名と一致しない場合は、エラーが表示されます。

ip_dict

Overlayパッケージは、特定のオーバーレイ(例えばbase.bit)内のIPの名前を含むip_dictと呼ばれる辞書を生成します。 辞書は、ハードコードされたアドレスではなく、Pythonコードの名前でIPを参照するために使用できます。 それはまたオーバーレイで利用可能なIPをチェックできます。

オーバーレイのIP辞書を表示するには、次のコマンドを実行します。

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

返されるこのIPディクショナリの各エントリはキーと値のペアです。

例えば:

'SEG_mb_bram_ctrl_1_Mem0': ['0x40000000', '0x10000', None]

これは、ビットストリームと共にエクスポートされたtclファイルを解析することに注意してください。 PLで現在実行されているオーバーレイはチェックされません。

エントリのキーはIPインスタンス名です。 すべてのIPインスタンス名は、アドレスセグメントセクションの* .tclファイル(base.tclなど)から解析されます。 エントリの値は3項目のリストです。

  • 最初の項目はアドレス指定可能なIPのベースアドレス(16進数)を示しています。
  • 2番目の項目は、アドレス範囲をバイト数(16進数)で示しています。
  • 3番目の項目は、IPに関連付けられている状態を記録します。 デフォルトではNoneですが、ユーザー定義も可能です。

同様に、PLパッケージを使用して、現在プログラマブルロジック内にあるアドレス可能なIPを見つけることができます。

from pynq import PL
PL.ip_dict

Existing Overlays

ベースオーバーレイはPynqレポジトリに含まれており、ここにあります。

<GitHub repository>/Pynq-Z1/vivado/base

各フォルダーには、Vivadoプロジェクトを再構築してオーバーレイのビットストリームを生成するために使用できるメイクファイルがあります。 オーバーレイ用のビットストリームとtclはボード上(ボードの起動時にデフォルトでbase.bitがロードされます)およびプロジェクトリポジトリで利用可能です。

<GitHubリポジトリ>/Pynq-Z1/bitstream/

オーバーレイを設計および構築するにはVivadoをインストールする必要があります。 既存のオーバーレイデザインを構築すると、プロジェクトをVivadoで開いて調べたり、新しいオーバーレイを作成するように変更したりできます。

Interfacing to an overlay

MMIO

PYNQには、Zynq PSとPL間の通信を簡素化するためのMMIO Pythonクラスが含まれています。 オーバーレイが作成され、メモリマップがわかったら、MMIOを使用してPL内のメモリマップ位置にアクセスできます。

MMIOのためのPythonコードはここで見られることができます:

<GitHub Repository>/python/pynq/mmio.py

MMIOクラスは、開始アドレスと範囲を指定することによってPL内のメモリ領域にアクセスできます。 例えば。 以下のコードは、0x40000000から0x40010000(SEG_mb_bram_ctrl_1_Mem0)までのPL内のメモリマップ位置へのアクセスを許可します。

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(65535バイト)の外側にアクセスすると、MMIOパッケージで例外が発生します。 設計者はまた、MMIOによってアクセスされるアドレスがPLにマップされたものを持つように注意する必要があります。 カスタムペリフェラルはアドレス空間に存在し、アドレス範囲がMMIOによってマッピングされている場合でも、特定のアドレスに接続されているものがない場合や、読み取り専用または書き込み専用の場合があります。 PLへの不正なアクセスはシステムエラーを引き起こし、Jupyterカーネルをクラッシュさせる可能性があります。

新しいハードウェア関数用のpythonドライバを作成するとき、MMIOはPythonモジュールの中にラップすることができます。

Zynq GPIOs

Zynq PSとPLの間のGPIOは、オーバーレイへの制御インターフェイスとしてPythonコードで使用できます。 GPIOに関する情報は、上で説明したip_dictと同様に、オーバーレイのGPIO辞書に保存されています。

次のコードは、ビットストリームの辞書を取得するために使用できます。

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

GPIOディクショナリエントリはキーと値のペアです。ここで、valueは2つの項目のリストです。 GPIO辞書のエントリの例:

'mb_1_reset/Din' : [0, None]

キーはGPIOインスタンス名(mb_1_reset / Din)です。 GPIOインスタンス名はVivado * .tclファイル(base.tclなど)から読み込まれ解析されます。

値は2項目のリストです。

最初の項目はGPIOのインデックス(0)を示しています。 2番目の項目(なし)はGPIOの状態を示します。 デフォルトではNoneですが、ユーザー定義も可能です。 現在FPGAファブリック内にあるGPIOの辞書を取得するには、次のコードを使用できます。

from pynq import PL
pl = PL
pl.gpio_dict

CFFI

CFFI(C外部関数インターフェース)は、PythonからCコードとインターフェースをとるための簡単な方法を提供します。 CFFIパッケージはPYNQイメージにプレインストールされています。 実行可能モジュールから動的に関数をロードして実行することを可能にするインラインABI(Application Binary Interface)互換モード、およびC拡張モジュールを構築することを可能にするAPIモードをサポートします。

http://docs.python-guide.org/en/latest/scenarios/clibs/ から抜粋した次の例は、PythonからC関数strlen()を呼び出して、ABIインラインモードを示しています。

C関数プロトタイプ

size_t strlen(const char*);

The C function prototype is passed to cdef(), and can be called using clib.

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))

共有ライブラリ内のC関数は、C外部関数インタフェース(CFFI)を使用してPythonから呼び出すことができます。 共有ライブラリは、PythonのCFFIを使用してオンラインでコンパイルすることも、オフラインでコンパイルすることもできます。

CFFIと共有ライブラリの詳細については、以下を参照してください。

CFFIの使用方法に関するPYNQの例を参照するには、CMAクラスまたはAudioクラスを参照してください。両方とも次の場所にあります。

<GitHub Repository>/pynq/drivers

Packaging overlays

overlay、tcl、Pythonはファイルシステムのどこにでも配置できますが、これはお勧めできません。

基本PYNQオーバーレイとtclのデフォルトの場所は、次のとおりです。

<GitHub Repository>/Pynq-Z1/bitstream

PYNQ Pythonはここにあります。

<GitHub Repository>/python/pynq

githubからPYNQをフォークし、PYNQパッケージにPythonコードを追加することができます。 ただし、カスタムオーバーレイの場合は、独自のリポジトリを作成してパッケージ化し、他のユーザーがpipを使用してオーバーレイをインストールできるようにすることができます。

pipを使ってインストールするプロジェクトをパッケージ化する方法はいくつかあります。 一例を以下に提供する。

より多くの詳細とより多くの包装オプションについてはpip installを見てください。 https://pip.pypa.io/en/stable/reference/pip_install

Example

次の例では、GitHubリポジトリのルートに存在するオーバーレイを想定しています。

リポジトリが次のような構造になっているとします。

  • notebook/

    • new_overlay.ipynb
  • new_overlay/

    • new_overlay.bit
    • new_overlay.tcl
    • __init.py
    • new_overlay.py
  • readme.md

  • license

リポジトリのルートにsetup.pyを追加します。 このファイルは必要なパッケージをインポートし、パッケージ名、バージョン、URL、含めるファイルを含むパッケージのセットアップ手順を指定します。

setup.pyの例:

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は、パッケージの一部としてインストールされるファイルを指定します。

端末から、次のコマンドを実行して新しいパッケージをインストールできます。

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

Using Overlays

システムの稼働中に、PLを新しいオーバーレイで動的に再設定できます。

オーバーレイのロードは、Overlayクラスを使用してPythonで実行できます。

<GitHub Repository>/python/pynq/pl.py

ビットストリームはPythonからダウンロードできます。

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

First FPGA (1) Cloud Native Hiroshima

comments powered by Disqus