Xilinx Vivadoで上手にバージョン管理する方法

以前よりVivadoプロジェクトをバージョン管理したいと考えていた訳ですが、なかなか自分の開発フローに馴染まず諦めていました。

Vivadoのプロジェクトをsubversionやらで管理するの面倒・・・ってのVisual Studioとかは特に問題にならんのかな？
— KazuHira (@hiratch) December 2, 2014

こんな感じで、バージョン管理をしたいというのはみんな思っているみたいなので、真面目に取りかかることに。

まず、Xilinxの公式的なドキュメントとしてバージョン管理について、xapp1165「Vivado Design Suiteにおけるバージョン管理システムの使用」*1というアプリケーションノートがあります。リファレンスデザイン*2もありますので、まずはこれを実行して、どういう構成となっているのか見るとよいと思います。基本的には、このドキュメント・リファレンスデザインに基づいて自分にあったファイル管理等を行えるようにしていきます。

まず、職場での使用を考えると、

Vivadoはプロジェクトモードで使用(GUIのプロジェクトモードしか使えない人がいる)
プロジェクトに依存しないIPやVerilog/VHDLのコードは別にgitで管理されてる(ものもある)

という状況です。なので、適当にコンフィグで指定したディレクトリからファイルを検索してプロジェクトを自動的に生成するようなものを作り、生成されたプロジェクトはバージョン管理対象外にすればよいと考えました。これは、Xilinxのリファレンスデザインのプロジェクトベースの管理と考え方は同じです。異なる点はXilinxのスクリプトではIP(xciファイル)に関してはManage IPを使って管理していますが、私の考えている方法はIPも含めて特定のディレクトリ内のファイルはすべてまとめて管理するようにします。

＃一応、ドキュメントの推薦としてはManage IPを使うようにかかれています。

たとえば、下のようにプロジェクト固有のファイルはsrcs以下にまとめられていて、共通に使っているファイルは git submoduleでsubmodule以下に入っているような構成をとります。そして、srcsとsubmodule/test_hdl/hdlのファイルをデザインソースとして使い、submodule/test_ipをIPレポジトリに追加するように設定します。また、ブロックデザインで作成したデータは、.bdファイルではなくExport Block DesignしたTcl(.bd.tcl)で管理するようにします。

project_files
- srcs (プロジェクト固有のファイル)
  - board.xdc (制約)
  - clk_50MHz.xci (IP)
  - design_sample.bd.tcl (Block Design)
  - top.v (Verilogコード)
- submodule（プロジェクトに依存しないファイル git submodule）
  - test_hdl (HDLで管理)
    - hdl
      - adder.v
    - sim
      - test.v
  - test_ip (Create and Package IPのIPで管理)
    - component.xml
    - reverse_bit.v
      - xgui
        
        reverse_bit_v1_0.tcl

基本的にはXilinxのリファレンスデザイン、Write Project Tcl、Vivado GUIで操作したときのログを参考にしつつ、プロジェクト固有になりそうなところとプロジェクトごとに変わりそうなところを分離してスクリプトを書きます。分離したスクリプト(default.*.tcl)はsrcsにでも入れて、sourceするようにしておきます。

あとは全体の設定としてconfig.tclみたいなものを作ってプロジェクトごとに必要な設定をするようにします。

＃実際にはMakefileで読み込んだconfig.mkからconfig.tclを作るようにしています。

set PROJECT_NAME   test
set PROJECT_DIR    project
set SRCS_DIRS      [list ../srcs ../submodule/test_hdl/hdl ]
set SIMS_DIRS      [list ]
set TOP_MODULE     top
set PART           xc7a35tcpg236-1
set PROJECT_CONFIG ../srcs/default.project.tcl
set SYNTH_CONFIG   ../srcs/default.synth.tcl
set IMPL_CONFIG    ../srcs/default.impl.tcl
set IP_REPO_PATHS  [list ../submodule/test_ip]
set RUN_JOBS    8

サンプルプロジェクトの実行

サンプルで作ったプロジェクトはgithubにあげていますので、下記のようにコマンドを打てばプロジェクト作成と合成・インプリ・bitstreamの生成までを行ってくれます（多分）。

＃config.mkにVivadoの設定があるので適宜変更は必要

git clone https://github.com/a5teri5m/vivado_vcs.git 
cd vivado_vcs
git submodule init
git submodule update
make

とりあえずは、これで必要な最低限のファイルだけを管理することはできるようになります。実際の修正は、run_vivado.sh を実行してGUI上でおこなったり、ファイルを直接編集しておこないます。 IPの設定やBlock Designを編集した場合には make export_xci_design や make export_bd_design でxciファイルとBlock Designをsrcsにコピーします(現状はSRCS_DIRSリストの1つめのディレクトリへコピー)

現状分かっている問題

Makefileの依存関係が適当
- なので、プロジェクトを毎回消して、作ってになっている
- Tclもプロジェクト消すこと前提のコードになっている部分が多い
IPのOut-of-Contextに対応していないから合成が遅い
make export_xci_design や make export_bd_design した後、手動で修正が必要な部分がある（メモリのcoeファイルパスを相対パスに変更とか）
- 修正の度に、手動で変更しているのでうまく設定できるようにしたい
すべてのDesign Sourcesに対応していない。(create_deasign.tclに必要になったら付け加える予定)