PCIe版Xillybus入門(1)：デモを動かしてPCと通信してみた

# はじめに
この記事はXillybusのデモをKintex7の評価ボードKC705で動かしてみるまでの記録です．
PCと通信するアプリケーションを作るときの第一段階です．
デモはPCから送信したデータがそのままFPGAを通ってループして帰ってくるだけです．

FPGAボードとの通信はUARTやEthernetなど様々なものが存在しますが，今回は高速なPCI-Expressを用いてホストPCとFPGA間の通信を確立します．

しかし，PCIeデバイスを実装するには，PCIe回路のみならず，デバイスドライバなどソフトウェア側の整備も必要となり実装のハードルはUARTとは比較になりません（UARTも真面目に作ると難しいけど）．

そこで，この面倒くさい部分の開発，いわば車輪の再発明を回避し，できるだけ早い段階から自分の作りたい部分に集中できる環境としてXillybus[^1]を選択し，試してみることにしました．

[^1]: [Xillybus公式サイト](http://xillybus.com/)

# Xillybusとは？

XillybusはWindowsPCまたはLinuxPCとFPGA間でPCIeを介してデータのやり取りを可能とするIPコアです．ウェブサイトからダウンロードして使うことができます．また，WindowsやLinux向けのデバイスドライバも提供されていますので，必要なものはすべて揃っています．さらに，英語ですが，公式ドキュメント[^2]もそれなりに整備されています．

[^2]: [Xillybus公式ドキュメント一覧](http://xillybus.com/doc)

Xillybusによるデータ転送の仕組みは，PC側のデバイスファイルに書き込んだデータが自動的にFPGAに転送され，FPGA側ではFIFOのインタフェースでデータを受け取ることができるようになるというものです．逆も同様で，FPGA側からFIFOにデータを書き込んで，PC側からデバイスファイルをreadすればデータを受け取ることができます．以下に図で示します．

![BasicArchitectureOfXillybus.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/357417/29ebc539-d24b-8749-5c93-30c633c848e0.png)


もう少し詳しいことは[Product brief](http://xillybus.com/downloads/xillybus_product_brief.pdf)を参照してください．

また，転送速度ですが，公式サイトによると～800[MB/s]ほどになるそうです．また，最新のRevision B/XLを用いると，3.5[GB/s]まで実現できるそうです．理論値だと思いますがUARTとは比べ物にならない速度でモリモリとデータを転送できます．今回はRevision B/XLは使用しません．

# ライセンス
Xillybusは評価目的や教育目的であれば費用はかかりませんが，商用利用の場合はライセンスを取得する必要があります．
詳しくは[公式サイト](http://xillybus.com/licensing)を読んでください．

# 環境
今回使用した環境は以下のとおりです．

- FPGAボード: Kintex-7 KC705
- KC705のホストPC OS: Ubuntu 18.04
- Vivado: 18.04 Linux版 (上記ホストマシンとは別のマシン）

# 準備
必要なものを集めましょう．
まず，Xillybusのソースコード(FPGAに書き込む回路)を[こちら](http://xillybus.com/pcie-download)からダウンロードします．Kintex7の項目の"Click here to download"をおしてダウンロードです．

![InkedSnapCrab_NoName_2019-6-24_14-1-37_No-00_LI.jpg](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/357417/1662db3a-fda4-a40c-210b-22fb7b309e2e.jpeg)

続いて，マニュアルのたぐいも集めます．
[XillybusのDocumentations](http://xillybus.com/doc)からダウンロードできます．とりあえず以下のものを入手しておきます．

- Getting started with Xillybus on a Linux host
- Getting started with the  demo bundle for Xilinx

1つ目はLinuxマシンでXillybusを使うためのデバイスドライバのインストール方法からデモプログラムの実行までのソフトウェア側の話を一通り網羅したマニュアルです．2つ目は，FPGAに書き込む回路(bitstreamファイル)の生成について解説されたものです．

# デモの環境構築と実行
デモを実行するまでの流れは以下のようになります．

1. VivadoでFPGAに書き込むXillybusのデモ用プロジェクトを論理合成し，FPGAに書き込むbitstreamファイルを生成
2. FPGAに書き込み
3. FPGAのホストPCを再起動
4. デモを動かす

## FPGAの書き込みまで
ダウンロードしてきたXillybusのソースコードのフォルダにはTclスクリプトでVivadoのプロジェクトを生成できるようになっています．まずは，Vivadoのプロジェクトを生成しますので，Vivadoを起動します．

起動したら，Tools > Run Tcl Script...を選択．
![InkedSnapCrab_Vivado 20183@Chariot_2019-6-24_14-7-26_No-00_LI.jpg](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/357417/0ad999ce-7e33-49f9-49d1-1c61d9ca2974.jpeg)

続いて，実行するTclスクリプトを選択します．ダウンロードしてきたXillybusのフォルダを開くと，

- blockdesign
- verilog
- vhdl

など複数フォルダがありますが，自分の環境に合わせて選択します．RTLを書きたくないので今回はblockdesignを選択しました．
それぞれのフォルダ内にある，"xillydemo-vivado.tcl"を選択し，OKを押すと，自動的にプロジェクトが生成されます．

![InkedSnapCrab_Vivado 20183@Chariot_2019-6-24_14-8-8_No-00_LI.jpg](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/357417/d3d3349a-7d4e-1ac2-1a14-734d7ec21adc.jpeg)

しばらくするとVivadoのプロジェクトが作られ，おなじみの画面が開きます．試しに，blockdesignを開いてみると，以下のようになっていました．受信したデータをそのまま返信するだけのシンプルなものです．

Xillybus IP CoreがXillybusの機能を提供する本体です．詳しい説明は割愛しますが，from_host_write_32, from_host_write_8がホストPCから送られてきたデータを受信するポート，to_host_read_32とto_host_read_8がそれぞれホストへ向けてデータを送信するポートです．データの幅が8bitと32bitの2種類あり，それぞれ対応しています．図を見てわかるように受信ポートがそのまま送信ポートにつながっており，データがそのままホストPCへループするようになっています．

![InkedSnapCrab_xillydemo - [homesanseihls_projectxillybusxillybus-eval-kintex7-20dblockdesignvivadoxillydemoxpr] - _2019-6-24_14-10-42_No-00_LI.jpg](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/357417/3f258896-a527-730d-16af-4e072b86c071.jpeg)

特に何もせず，そのまま，Generate Bitstreamボタンを押しましょう．「論理合成から実行しますか？」のようなことを聞かれるので，OKを押して進みます．私の環境ではいくつかCritical warningが出ましたが，OKを押して進んでしまいました．bitstreamが出来上がるまでしばらく待ちます．

以上で，エラーなく終われば，bitstreamの生成は完了です．
続いて，FPGAのコンフィギュレーションを行います．

"Open Hardware Manager"を押して，Hardware Managerを開きます．
![InkedSnapCrab_NoName_2019-6-26_16-57-35_No-00_LI.jpg](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/357417/63bf6179-05b7-ecdb-47c1-cb5101e3850d.jpeg)

上部にある"Open target"を押して，コンフィギュレーションするFPGAを開きます．現在Vivadoを実行しているPCにFPGAボードが刺さっている場合は，Auto Connectを押せばOKです．私は別のPCにXilinxのHardware Serverを入れてリモートコンフィギュレーションするので，"Open New Target..."を選択しました（Hardware Serverの話はまた別でまとめたいと思います）．

![SnapCrab_xillydemo - [homesanseihls_projectxillybus-eval-kintex7-20dblockdesignvivadoxillydemoxpr] - Vivado 2_2019-6-26_16-57-58_No-00.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/357417/b3499b83-1d64-76cc-c59c-95872c9740e1.png)

最後に，画面上部に表示されている"Program device"をクリックして，bitファイルを選択しOKで書き込みが完了します．

以上で，FPGAのハードウェア側の準備は完了です．ボードの電源は入れっぱなしで待機しましょう．

## ホストOS側の準備
Ubuntu 14.04以降の場合は，デバイスドライバのインストールは不要と"Getting started with Xillybus on a Linux host"の2.1.1の"Linux distributions with pre-installed driver"に記載されています．

FPGAにXillybusのデモ回路を書き込んだら，Xillybusデバイスとしてボードを認識させるため，ホストPCを再起動します．
このとき，FPGAボードの電源は入れたままにしてください．切ってしまうと書き込んだ回路が消えてしまいます．

再起動すると，/dev以下に"xillybus_hogehoge..."なるファイルができていると思います．

## デモの実行
今回はPCから送信したデータがFPGAを通ってそのままPCに帰ってくる，というものがFPGAに実装されています．
Xillybusの場合，/dev以下のxillybus_readやxillybus_writeなるファイルがFPGA側のFIFOにXillybusを介して接続されているような状態になっています．
ですので，xillybus_read_8を読み込むとXillybusを介してFPGAのFIFOのデータを読み出すことができます．
一方，xillybus_write_8に書き込むことで，xillybusを介してFPGAにデータを送信することができます．FPGA側からはFIFOとしてデータを取り出せます．
ただし，今回はblockdesignでvivadoプロジェクトを作ったので，FPGA側のインタフェースはFIFOではなくAXI-Streamになっています．

では，データをFPGAに送って，戻ってきたものを表示させてみましょう．
ターミナルを2つ開きます．

1つ目で，

```shell
sudo cat /dev/xillybus_read_8
```
とします．
これでデータの受信準備完了です．

2つ目のターミナルで，

```shell
sudo cat > /dev/xillybus_write_8
```
とします．これで書き込み待機状態になります．
Permission deniedの場合は，chmodで権限を変更してください．

2つ目のターミナルが書き込み待機になっているので，なにか文字を入力して，Enterを押しましょう．
すると，Xillybusを介してFPGAへデータが送られ，そのままループして帰ってきて，1つ目のターミナルに入力した文字が表示されます．

ちゃんと入力した文字が表示されたら，デモの動作は成功です．

# 終わりに
今回は配布されている最も単純なデモを試してみました．/dev以下のファイルを読み書きするだけでPCIeを介してFPGAとやり取りできるのは便利ですね．
他にも，Cで書かれたデモ用プログラムがあるようなので，それを試してみるのもいいかもしれません．
とりあえず，自分用のメモも兼ねて，手順をまとめました．

Xillybusの使い方のまとめや，自作回路によるデータ処理の実装などまとめていきたいと思います．
その2へ続く・・・はず．

第2回の記事です↓
[PCIe版Xillybus入門(2) ：XillybusにHLSで作成した回路を接続してみる(画像ネガポジ反転)](https://qiita.com/HoriThe3rd/items/8eb241fc0575473a0826)