Skip to content

README_ja.md

Latest commit

 

History

History
183 lines (139 loc) · 12.2 KB

README_ja.md

File metadata and controls

183 lines (139 loc) · 12.2 KB
Raw

ModView

English

ModView は SystemVerilog のモジュール接続ビューアです。 RTL を解析し、モジュールがどう配線されているかを図として描きます。 図は並べ替えて保存できます。 OSS だけで構成された軽量な Web アプリケーションです。

ModView に同梱の JPEG エンコーダ例を表示した画面。左にモジュール一覧のサイドバー、右に描画された接続図

ModView でできること

ソースコードから階層を読み取る作業には時間がかかります。 商用の RTL ビューアはライセンスとインストールを前提とします。 ModView はそのどちらも必要としません。 .sv / .v ファイルの入ったフォルダを指定すれば、ブラウザ上に設計が描画されます。

  • Verible で解析する：モジュール、ポート、バス幅、パラメータ、インスタンスとその接続を抽出します。 SystemVerilog の interface 宣言と modport 宣言にも対応します。
  • ネット単位で配線を推論する：命名規則には依存しません。 同じ信号に接続されたポートがネットを構成し、そのうち 1 つをドライバとして選び、そこからリンクを描きます。 ソースを与えていないサブモジュールも図に現れ、各ネットの駆動状況からポート方向を推論します。
  • レイアウトを自動で決める：ELK.js による左から右への階層配置と直交エッジルーティングを使います。 すべてのエッジを同時に計算するため、線はノード本体も他の線も避けて通ります。
  • 階層をその場で見せる：さらにインスタンスを含むインスタンスは、子を内部に埋め込んだコンテナとして描画されます。
  • interface のバスをまとめる：1 つの interface インスタンスにつき 1 本の色付きトランクリンクに集約し、クリックで個々の信号に展開できます。
  • 編集して保存できる：ロックを解除してノードをドラッグすると、ドロップのたびに接続線が再ルーティングされます。 配置は JSON として保存し、読み込んで復元できます。

1 段階拡大すると構造が読み取れます。 次の画像はエンコーダの二重パイプラインで、block_distributor がブロックを 2 系統の dct_2d と quantizer の連鎖に振り分け、output_merger が並べ直したうえで rle_encoder と huffman_encoder へ渡します。

JPEG エンコーダの 8 つのモジュールインスタンスが名前とポート付きで見える図。block_distributor から 2 系統の dct と quantizer の連鎖へ分岐し、output_merger を経て RLE 段と Huffman 段へ進む

等倍まで拡大すると、2 段の間の AXI4-Stream ハンドシェイクが読み取れます。 入力ポートは左辺に青、出力ポートは右辺にオレンジで並び、クロックは赤、リセットは橙、ラベルにはバス幅が付きます。

u_dct_a と u_quant_a の 2 つのモジュールインスタンスを拡大した図。AXI4-Stream のポートと、接続線上の信号名が読み取れる

クイックスタート（Docker）

docker compose up --build

http://localhost:8080 を開いてください。 バックエンド API は http://localhost:8000 で公開されます。

クイックスタート（ローカル開発）

バックエンド（verible-verilog-syntax に PATH が通っている必要があります）:

cd backend
uv venv && uv pip install -e ".[dev]"
uv run uvicorn app.main:app --reload --port 8000

フロントエンド:

cd frontend
pnpm install --ignore-workspace
pnpm dev          # http://localhost:5173、/api を :8000 にプロキシします

使い方：同梱の JPEG エンコーダで試す

ModView を試すための実設計をリポジトリに同梱しています。 example/jpegenc/rtl にある baseline JPEG エンコーダで、12 個の SystemVerilog モジュールから成り、各段が AXI4-Stream で接続されています。

  1. ソースを読み込む。 Select Folder をクリックして example/jpegenc/rtl を選びます。 ディレクトリ配下の .sv / .v ファイルがすべて収集され、同じ場所にある仕様書の .md ファイルは無視されます。 ファイルを個別に選びたい場合は Select Files を使います。 1 回のリクエストで最大 20 000 ファイル、1 ファイル 50 MB、合計 500 MB まで受け付けます。

  2. 解析する。 Parse をクリックします。 サイドバーに 12 個のモジュールが並び、トップモジュールのドロップダウンは Top candidates（トップ候補）と Other modules（その他のモジュール）に分かれます。 一部のファイルの解析に失敗しても、成功した分は描画され、ステータスバーに View errors (N) リンクが表示されます。

  3. トップを選ぶ。 この設計では候補が jpeg_encoder_top だけなので、自動で選ばれます。 一覧にあるどのモジュールもトップにできます。 dct_2d をクリックすると、そのモジュール単体の接続を確認できます。

  4. 図を読む。 エンコーダは左から右へ流れます。 rgb2ycbcr から block_splitter、block_distributor を経て、dct_2d と quantizer の 2 系統の並列パイプラインに分かれ、output_merger で合流し、rle_encoder、huffman_encoder、bitstream_assembler へ進みます。 境界の I/O 端子は左端と右端に配置されます。 ホイールまたは + と − で拡大縮小し、Fit で設計全体を画面に収めます。

  5. 並べ替える。 図は編集ロック状態で開きます。 ツールバーのボタンは 編集ロック中 と表示され、どこをドラッグしても表示の移動（パン）になります。 ボタンを押して 編集可 に切り替えると、ノードをドラッグできます。 ドロップするたびに、ModView はすべての接続を再ルーティングし、親コンテナを子に合わせてリサイズします。 再ルーティングのためのボタンを押す必要はありません。

    ロックを解除してノードをドラッグした後の図。新しい位置に合わせて接続線が引き直されている

  6. 配線品質を戻す。 何度か動かすと、リンクごとの経路は初回描画より整わなくなります。 Re-layout は ELK のパイプライン全体を再実行して品質を戻します。 このとき ELK がノード位置を選び直すため、手動で整えた配置は破棄されます。

  7. 保存する。 Save（Ctrl+S / Cmd+S）でレイアウトを JSON としてダウンロードし、Load（Ctrl+O / Cmd+O）で復元します。

解析エラーの表示を確認するには、例題のファイルを 1 つ複製して構文を壊し、もう一度フォルダを解析してください。 解析できたモジュールは描画され、エラー一覧はステータスバーから開けます。

解析エラーのパネル。ファイル名と行と列を伴う 2 件の構文エラーが並び、背後には描画に成功した図がある

interface のトランクリンク

接続が SystemVerilog の interface に紐付く場合、その interface インスタンスの信号はすべて 1 本の太いトランクとして描かれます。 紐付きは modport 式（.bus(axi_bus.master)）による指定でも、<interface>.<modport> <name> 形式で宣言されたポート経由でも成立します。 ラベルは interface.modport、色はインスタンス名から決まります。 ロック解除中にトランクをクリックすると個々の信号に展開され、もう一度クリックすると元に戻ります。 JPEG エンコーダの例題は interface 構文を使っていないため、上の画面にこの機能は現れません。 backend/tests/fixtures/ のテストフィクスチャで動作を確認できます。

リポジトリ構成

modview/
├── backend/      FastAPI + Verible 解析サービス
├── frontend/     Vite + TypeScript + JointJS の図 UI
├── example/      jpegenc/rtl（使い方の説明で用いる設計）
├── docs/         architecture.md, api.md（+ _ja 日本語版）, images/
├── CHANGELOG.md  バージョン履歴
└── docker-compose.yml

テスト

cd backend  && uv run pytest          # CST ビジタと API
cd frontend && pnpm test              # 図のロジック
cd frontend && pnpm audit:routing     # フィクスチャに対するルーティングの簡易検査

バージョニング

本プロジェクトは Semantic Versioning に従います（MAJOR.MINOR.PATCH）。 現在のバージョンは初版である 0.1.0 です。 MAJOR が 0 の間は、HTTP API とレイアウト保存形式がマイナーリリースで変更される場合があります。 稼働中のバックエンドのバージョンは GET /api/health で確認でき、各バージョンの内容は CHANGELOG.md に記録します。 各リリースには vMAJOR.MINOR.PATCH 形式の注釈付き git タグを付けます（初版は v0.1.0）。

保存したレイアウトファイル内の version フィールド（現在は "1.0"）は保存形式のスキーマバージョンであり、上記のアプリケーションバージョンとは独立です。

パッケージと Docker イメージの名前は modview-backend と modview-frontend です。 ModView の名前を冠する最初のリリースより前に sv-module-viewer-* から改名したため、公開済みの成果物が途中で名前を変えることはありません。

ドキュメント

ライセンス

ModView 自身のソースコードは、2 つのパッケージとも MIT License で公開します（LICENSE を参照）。

同梱の例題設計は第三者のコンテンツであり、未改変のまま再配布しています。

パス 取得元 ライセンス
example/jpegenc/rtl https://github.com/aquaxis/jpegenc 取得元リポジトリの表示による MIT

サードパーティコンポーネントとそのライセンス:

コンポーネント ライセンス 備考
Verible Apache-2.0 バックエンドイメージにバイナリを同梱
verible_verilog_syntax.py Apache-2.0 backend/app/verible/ にベンダリング（© The Verible Authors）
JointJS Core（@joint/core） MPL-2.0 npm 経由で未改変のまま使用
ELK.js（elkjs） EPL-2.0 階層レイアウトと直交エッジルーティング
FastAPI / Uvicorn / Vite / TypeScript MIT

ベンダリングした verible_verilog_syntax.py は未改変で、元の Apache-2.0 ヘッダを保持しています。 JointJS は未改変の npm 依存として利用しており、MPL ライセンスのソースファイルを本リポジトリで改変することはありません。