08 CI

何をテストできるか

CI ランナーに Vivado が導入されていない場合が一般的であるため、必要な前提条件に応じてテストを 3 段階に分けている。

段階	Vivado	ライセンス	ハードウェア	実行環境
lint + 単体テスト	不要	不要	不要	通常のランナー
イメージ + 可用性テスト	不要	不要	不要	通常のランナー
フルセルフテスト + 実フロー	必要	必要	任意	セルフホストランナー

同梱の .github/workflows/ci.yml はこの 3 ジョブ構成である。

単体テスト

make check      # ピン留め検証 + shellcheck + hadolint + Tcl 構文 + bats

bats のテストは、コンテナエンジンのスタブを PATH に配置し、vvd が組み立てるコマンドラインをそのまま検証する。検証対象はマウント構成、ライセンス注入、ディスプレイ方式、JTAG 方式、権限、およびエラー時の終了コードである。

可用性テスト (Vivado なし)

Vivado が存在しない環境でも、コンテナの実体を検証できる。

VVD_VIVADO_MODE=none VVD_DISPLAY_MODE=xvfb vvd selftest

VVD_VIVADO_MODE=none は、このコンテナに Vivado が存在しないことを宣言する指定である。ホスト側の Vivado 探索を行わず、Vivado を必要とするステージを skip する。

ステージ	Vivado 不在時	内容
`image`	実行	イメージが存在し、entrypoint が動作する
`libs`	実行	Vivado が dlopen する共有ライブラリ 22 個がすべて解決する
`identity`	実行	`/work` に作成されたファイルが呼び出しユーザの所有となる
`display`	実行	コンテナ内から X ディスプレイに接続できる
`env`	skip	`vivado` / `xsim` / `hw_server` が PATH に含まれる
`version`	skip	`vivado -version` が期待バージョンを返す
`tcl`	skip	Tcl スクリプトが完走し、`/work` に書き込める
`license`	skip	ライセンスがコンテナから参照できる
`sim`	skip	同梱のスモークテストベンチが PASS する
`synth`	skip	同梱のスモーク設計が合成できる
`jtag`	skip	`hw_server` に接続してスキャンチェーンを読み取る

前提条件が満たされないステージは、失敗ではなく skip として扱う。ただし mount / image モードで Vivado が見つからない場合は、意図しない環境の不整合であるため失敗として扱う。VVD_SELFTEST_REQUIRE_VIVADO=0 を指定すれば skip に変更できる。

libs ステージは実用上の効果が大きい。Vivado は GUI や特定の IP フローに入って初めてライブラリを dlopen するため、共有ライブラリの欠落は数十分を要する合成の最終段階で表面化しやすい。このステージはそれを起動直後に検出する。

セルフホストランナー

Vivado、ライセンス、ケーブルを備えたマシンに vivado ラベルを付与して登録し、リポジトリ変数を設定する。

変数	例
`VVD_HW_RUNNER`	`true` (このジョブを有効化する値)
`VVD_LICENSE`	`2100@license.example.com`
`VVD_XILINX_ROOT`	`/tools/Xilinx`

runs-on: [self-hosted, vivado]
steps:
  - run: ./bin/vvd build
  - run: ./bin/vvd doctor --deep || true
  - run: ./bin/vvd -C examples/blinky selftest
  - run: ./bin/vvd -C examples/blinky sim
  - run: ./bin/vvd -C examples/blinky flow

自身のプロジェクトへの組み込み

サブモジュールとして取り込んでいる場合:

- uses: actions/checkout@<commit-sha>       # v6.0.3
  with:
    submodules: recursive

- name: Build the container image
  run: ./tools/vvd/bin/vvd build

- name: Simulate
  env:
    VVD_LICENSE: $
  run: ./tools/vvd/bin/vvd sim

- name: Synthesise and implement
  env:
    VVD_LICENSE: $
  run: ./tools/vvd/bin/vvd flow

- uses: actions/upload-artifact@<commit-sha>   # v4.6.2
  if: always()
  with:
    name: reports
    path: |
      build/reports/
      build/logs/
      build/*.bit

タイミング未達は vvd impl が失敗として扱うため、追加の判定は不要である。未達を許容する場合は VVD_ALLOW_TIMING_VIOLATION=1 を指定する。

キャッシュ

VVD_CACHE_DIR (既定値は $XDG_CACHE_HOME/vivado-container-suite) がコンテナの $HOME となる。IP のキャッシュやツール設定がここに保存されるため、ランナー間で共有するとビルド時間を短縮できる。

- uses: actions/cache@<commit-sha>
  with:
    path: ~/.cache/vivado-container-suite
    key: vvd-cache-$-$

ピン留めのドリフト検出

lock-drift ジョブが make lock-check を実行し、上流のイメージダイジェストや apt スナップショットとロックファイルの差分を報告する。continue-on-error: true を指定しているため、上流の更新のみでプルリクエストが失敗することはなく、ロックファイルの更新をレビュー可能な差分として扱える。

make lock          # ロックファイルを更新する (要ネットワーク)

デバッグ

vvd --dry-run flow      # 実行されるコンテナコマンドを表示する
vvd -v flow             # デバッグログを出力する
vvd info --all --cmd    # 解決済みの設定とコマンド全体を表示する