Xillybus の「Hello, world」テスト
これは、Xillybus を使い始める手順の 3 番目のステップです。Xillybus を含むビットストリーム (bitstream) がすでに FPGA に書き込まれ、ホストにはドライバがインストールされている状態です。ここでは、簡単なテストを行います。このテストの目的は、デバイスファイルが正しく作成され、動作することを確認することです。
このページでは、Linux ホスト上の Xillybus について説明します。Microsoft Windows については、類似のページがあります。
ここでは PCIe を使う Xillybus に焦点を当てますが、XillyUSB でもほとんど同じです。相違点はこのページの最後にまとめてあります。Xillinux については、PCIe に直接関係する項目を除けば、すべて同じように動作します。
このトピックの詳細については、Linux での Xillybus 入門を参照してください。
PCIe デバイスは認識されていますか?
最初に確認すべきことは、コンピュータが FPGA を PCIe デバイスとして認識しているかどうかです。この目的には lspci コマンドを使います。このコマンドは、コンピュータが PCIe バス上で見つけたすべてのデバイスを表示します。非常に長いリストになることもあります。
たとえば、Xilinx / AMD 製 FPGA で Xillybus を使っている場合は、次のようになります。
$ lspci [ ... several lines ... ] 01:00.0 Class ff00: Xilinx Corporation Device ebeb [ ... several lines ... ]
また、Altera の場合:
01:00.0 Class ff00: Altera Corporation Unknown device ebeb
出力はお使いのコンピュータによって少し異なるかもしれません。重要なのは「ebeb」です。これはデバイス ID であり、Xillybus デバイスであることを示しています。
lspci の出力にこのような行がなければ、FPGA 側に何か問題があります。多くの場合、原因は、FPGA に書き込まれているビットストリーム (bitstream) についての思い違いです。
ドライバは正しく起動しましたか?
次のステップは、ドライバの状態を確認することです。最も簡単な方法は、カーネルログの中から「xillybus」という文字列を探すことです。例:
$ dmesg | grep xillybus
xillybus_pcie 0000:01:00.0: can't disable ASPM; OS doesn't have ASPM control
xillybus_pcie 0000:01:00.0: Created 5 device files.
出力の形式はコンピュータによって異なります。ASPM についての行は正常なもので、エラーを示すものではありません。ただし、そのような行がなくても問題ありません。
「Created 5 device files」という行があれば、ドライバが Xillybus を正常に初期化できたことを示しています。この行がない場合は、ドライバの初期化で問題が発生しています。
カーネルログに Xillybus 関連の他の行がある場合、それが何が悪かったのかを説明する手がかりになります。これは通常、FPGA のロジックに問題があることを意味します。特に、FPGA 内の PCIe ブロックの設定が間違っている場合に発生しがちです。たとえば、デモバンドル (demo bundle) の PCIe ブロックのパラメータを変更すると、ドライバが正しく初期化されなくなることがあります。
カーネルログに「xillybus」を含む行がないのに、lspci の出力に「ebeb」の行があった場合はどうなるでしょうか。その場合、ドライバがカーネルにロードされていないことを意味します。これを確認するには、lsmod を使います。
$ lsmod | grep xillybus xillybus_pcie 16384 0 xillybus_core 28672 1 xillybus_pcie
この例は、ドライバがカーネルにロードされているときの正しい出力です。数値(16384 や 28672)は異なることがあります。xillybus_class もこのリストに表示される可能性があります。
ドライバをインストールしたばかりの場合は、コンピュータを再起動するか、insmod で手動でドライバをロードする必要があることに注意してください。
「Hello, world」
ドライバは 5 つのデバイスファイルを作成します。/dev/xillybus_read_8、/dev/xillybus_read_32、/dev/xillybus_write_8、/dev/xillybus_write_32、/dev/xillybus_mem_8 です。IP Core Factory でカスタム IP コア (custom IP core) を作成すると、作成されるデバイスファイルの数、名前、プロパティを自由に選択できることに注意してください。
しかし、今は FPGA にデモバンドルが書き込まれています。このうち 2 つのデバイスファイルを試してみましょう。
デモバンドルには、read_8 と write_8 の間にループバックがあります。つまり、コンピュータが write_8 にデータを書き込むと、FPGA がそのデータを read_8 を通じてまったく同じ内容で返します。これはあくまでデモ用に用意されているものです。このループバックに、それ以外の実用的な用途はありません。
テストの手順は次のとおりです。コンピュータでターミナルウィンドウを 2 つ開きます。あるいは、シェルのプロンプトが 2 つ得られる方法なら何でも構いません。たとえば、ssh 接続を 2 つ使う方法もあります。
1 つ目のシェルのプロンプトで、次のように入力します。
$ cat /dev/xillybus_read_8
次に、2 つ目のシェルのプロンプトで、次のように入力します。
$ cat > /dev/xillybus_write_8
次に、2 つ目のターミナルで何か入力して ENTER を押します。すると、1 つ目のターミナルに同じ文字列が表示されます。これは、入力したテキストが書き込み用デバイスファイル(write_8)に書き込まれ、FPGA に到達し、最後に読み出し用デバイスファイル(read_8)としてコンピュータへ戻ってくる流れを示しています。
この例は単純ですが、その仕組みを理解することは重要です。特に、FPGA 内部のロジックがどのようにしてこれを実現しているのかを理解することが大切です。それは、ご自身のロジックを組み込むための出発点になります。
これらのコマンドが permission denied(権限がない)エラーで失敗する場合は、root として再度実行してください。あるいは、前のページで提案したように udev ファイルをインストールしてください。
XillyUSB
XillyUSB を使っている場合も、上記のすべてが当てはまります。ただし、いくつかの違いがあります。
XillyUSB には、FPGA との物理的な接続の品質を調べるための showdiagnostics というツールがあります。生のデータリンクにエラーがないことを確認するため、このツールを使うことを強くお勧めします。XillyUSB が完全に動作しているように見えても、この確認を行うことが重要です。その理由は、USB 3.0 プロトコルが生のデータリンク上のエラーを隠してしまう一方で、これらのエラーがバグのように見えるまれな問題を引き起こす可能性があるからです。
この種のエラーを許容する理由はありません。解決策は簡単なことが多く、たとえばコンピュータの別の USB ポートを使うだけで済みます。
その他の相違点:
- lspci の代わりに lsusb を使います。
- ドライバのモジュールは xillyusb、および場合によっては xillybus_class です。
- ドライバをインストールした後、コンピュータを再起動する必要はありません。デバイスを USB ポートに接続すると(切断状態から接続すると)、ドライバは自動的にロードされます。
- デバイスファイルの名前は少し異なります。たとえば、/dev/xillybus_read_8 の代わりに、/dev/xillyusb_00_read_8 という名前になります。「00」の部分は異なる場合があります。