SystemVerilog、VerilogをDoxygenでドキュメント化する

VHDLはDoxygenでドキュメント化できるが、VerilogもDoxygenでドキュメント化したいと思っていた。以前、Verification Engineerの戯言さんの”Doxygen Filter for System Verilog 2.3.0 Released”の記事を見て、気になっていたので、SystemVerilog、VerilogをDoxygenでドキュメント化してみることにした。この記事はその覚書だ。

Doxygenはバージョン1.6.3を使用している。まずは、Doxygen Tools (including a Filter for SystemVerilog) のWebページからDoxygen Toolsをダウンロードする。ダウンロードし解凍すると2.6.0.r130というフォルができて、下図のフォルダが生成される。


これをDoxygenのフォルダにコピーする。下図がコピーしたあとの状態だ。


ドキュメント化するVerilogファイルは、”Spartan3A Starter KitのDDR2 SDRAMコントローラのバーストテストのプロジェクト”のVerilogファイルとする。

Doxygenを使う前にスクリプトはperlを使用しているので、Windowsにperlが入っていない場合は、perlをインストールする。私は、ActivePerlを使用した。

Doxywizardをメニューから起動する。Wizardで設定を行い、Expertタブを設定する。
ExpertタブのBuildの項目でEXTRACT_ALLにチェックが入っていることを確認する。


ExpertタブのInputの項目でFILE_PATTERNSに .v と .sv の拡張子を追加する。


ExpertタブのInputの項目のINPUT_FILTERの項目にdoxygen/filter/idv_doxyfilter_sv.pl を指定する。FILE_PATTERNSの項目に .v と .sv の拡張子を追加する。


このidv_doxyfilter_sv.plスクリプトは.vと(たぶん）.svのみ解析するようなので、.vh のインクルードファイルがあると、そこは解析されない。そこで、ddr2_burst_test/Synth112の下のddr2_cont_parameters.vhをddr2_cont_parameters.vにコピーした。
これでRunタブからdoxygenをRUNすると、Verilogファイルがドキュメント化できた。

ここにドキュメント化したhtmlファイルを置いておく。
Doxygenの設定ファイルのサンプルをここに置いておく。このファイルを自分のパソコンにコピーして、Doxygen GUI frontendウインドウのFileメニューからOpen...を選んで、Doxygenの設定ファ イルのサンプルを選択すれば、私の行った設定を再現できる。その場合は、最低でも、WizardタブのSpecify the directory to scan for source code のSource cod directry とDestination directory、ExpertタブのInput項目のINPUT_FILTERのフォルダ名を変更する必要がある。

SystemVerilogはまだ本格的に書いたことがないので分からないが、SystemVerilogのドキュメント化ができると思う。

DoxygenでSHIFT-JISを使用する

中村様からメールで、SHIFT-JISで書いたVHDLのコメントを文字化けなくDoxygenでドキュメント化する方法を教えていただいた。
その方法はおっちょこちょいさんのブログのdoxygen備忘録に書いてあった。
それによると"DOXYFILE_ENCODING"と"INPUT_ENCODING"に"CP932"を設定すれば、SHIFT-JISで書いたVHDLのコメントをドキュメント化できるとのこと。中村様からは"INPUT_ENCODING"に"CP932"を設定するだけでOKとのことだった。実際にやってみたところ"INPUT_ENCODING"に"CP932"を設定するだけでOKだった。

Doxygen GUI での実際のやり方は、Doxygen GUI で"Expert..."ボタンをクリックする。


doxywizardダイアログが開くので、Inputタブをクリックして、"INPUT_ENCODING"に"CP932"を入力する。


これで、SHIFT-JISでも大丈夫だった。

本当に中村様、ありがとうございました。
そのほか、シーケンス図が作れる方法が書いてあるページを教えてもらった。そのうちに試してみようと思う。

Doxygenを使ってVHDLソースコードをドキュメント化してみました２

FPGAの部屋のブログ記事”Doxygenを使ってVHDLソースコードをドキュメント化してみました”でVHDLのソースコードを書きながら、ドキュメントを一緒に作っていたが、これはDoxygenが理解できるようなドキュメンテーションをソースに付加する必要があった。
皆さんご存知かもしれないが、Doxygen が理解できるようなドキュメンテーションは一切付いていないVHDLソースファイルをドキュメント化するタグがあったので書いておこうと思う。
それはDoxygenのマニュアルのここに書いてあるEXTRACT_ALL タグだ。このEXTRACT_ALL タグをYESにすると”EXTRACT_ALLタグが YES であれば、ドキュメントが得られなくても、ドキュメント内の要素は すべてドキュメントに出力するものとして扱います。”だそうだ。
実際にやってみた。自分でドキュメントを記述したものに比べれば落ちるが、特にコラボレーション図などは階層がわかってとてもよい。
Windows版でのEXTRACT_ALLタグのチェックの入れ方は、下のようにDoxygen GUI frontend ウインドウでExpert... ボタンをクリックする。出てきたdoxywizard で EXTRACT_ALL をチェックする。


これがDDR SDRAMコントローラVHDL版のDDRtest.vhdのDoxygenによるコラボレーション図 (EXTRACT_ALL = YES)


ちなみに、コラボレーション図のファイル名の書いてある四角をクリックすると、そのファイルのドキュメントが開く。

Doxygenを使ってVHDLソースコードをドキュメント化してみました

”コーヒーでも飲みながら検証の話でも”さんの火曜日, 2月 12, 2008、”DoxygenがVHDLをサポート”の記事でDoxygenがVHDLをサポートしたのを知った。
Doxygenがどんなものか、まったく知らなかったので、Windows版をダウンロードして、どんなものか触ってみたのだが、あまり良くわからずに放置していた。しかし、院生がC++で使っていたのを見たので、ぜひ使いたいと思い、今度は本気で使い方を探ってみた。
いろいろやってみた結果、だいぶ使い方がわかって来た。
”7セグメントLEDを何個ダイナミック点灯できるか？２”で使用した回路をDoxygenでドキュメント化してみた結果をここにおきます。

Doxygenの使い方メモ

・Doxygen設定
OPTIMIZE_OUTPUT_VHDL = YES
SOURCE_BROWSER = YES
OUTPUT_LANGUAGE = Japanese
STRIP_CODE_COMMENTS　　= NO
後は良くわからない。

・コメントの入れ方
doxygenのexamplesのmux.vhdlの書き方に加えて
１．日本語はUTF-8に変換する必要がある。
２．最初のコメントには、--! が使えないので、-- を使用する。
３．<は使えないようだ。portは --! を使用して、横に書けばOK。
４．component, signalの説明文は1行を使用し、上の行に --! を使ってコメントを書く。<を使って、同じ行の横に書くことはできない。
５．下位モジュールのインスタンシエーションの時のコメントは --! @details 説明。
６．process文にはラベルをつけたほうが良い。５．同様にコメントは --! @details 説明。
７．component文に横に --! で書いてもだめ。--! @param を使用して上に書く。
８．STRIP_CODE_COMMENTS = YES にしておくとdoxygenのコマンドが抜けてしまうので、STRIP_CODE_COMMENTS = NO にしておいたほうがスカスカにならなくて良い。

2008/03/06：追加
INLINE_SOURCES = YES にするとPROCESS文のソースがドキュメントに記載されます。

どなたか、下のようなPROCESS文でない組み合わせ回路をドキュメントにする方法を知っていたら教えてください。
nLEDDB <= not decout;

2008/03/11：追加
GENERATE_TREEVIEW = YES; にするとFRAMEができて、選びやすくなる。
ここに表示サンプルを置いておく。

2008/03/14：追加
VHDLのときにはEXTRACT_PRIVATE = YESにする必要があるそうだ。
最初のファイルのコメントの部分(@authorなどが書いてある部分)は空行をあけないほうがよさそうだ。
修正したサンプルを置いておく。