Verilog用のドキュメントジェネレータdoxverilogをインストールして試しました。SourceForgeのダウンロードデータが壊れているので、インストールにかなり苦戦しました。
doxverilogについて
doxverilogはVerilogソースコードのコメントからドキュメントを生成するツールです。Doxygenへのパッチとして提供されています。VHDLはDoxygenで正式にサポートされているようですが、Verilogは残念ながら正式にはサポートされていません。
データのダウンロード
doxverilogを検索すると、まず最初にSourceForgeのdoxverilogのページが見つかります。しかし、ユーザーレビューのコメントを見ると、ダウンロードデータに問題があるようです。
!! ATTENTION !! : If you want to download doxverilog and have error like “corrupted files”, just rename .zip to .tag.gz and all archive would open. Then you can try some tools to check integrity. As an alternative you may download 2.7 version from github: github.com/ewa/doxverilog The only difference is that 2.8 uses doxygen-1.8.5 while 2.7 uses doxygen-1.8.1
・(最新のバージョン2.8の)ダウンロードデータが解凍できない時には、.zip を.tar.gzにリネームしてみる
・またはgithubからバージョン2.7を使ったほうが良い
と書かれているので、実際にデータ(Doxverilog2.8.zip)をダウンロードして解凍してみました。環境はubuntu14.04LTE 32bitです。
$ unzip Doxverilog2.8.zip Archive: Doxverilog2.8.zip error [Doxverilog2.8.zip]: missing 4 bytes in zipfile (attempting to process anyway) error [Doxverilog2.8.zip]: attempt to seek before beginning of zipfile (please check that you have transferred or created the zipfile in the appropriate BINARY mode and that you have compiled UnZip properly) (attempting to re-compensate) creating: Doxverilog2.8/ creating: Doxverilog2.8/.svn/ inflating: Doxverilog2.8/.svn/all-wcprops inflating: Doxverilog2.8/.svn/entries creating: Doxverilog2.8/.svn/prop-base/ creating: Doxverilog2.8/.svn/props/ creating: Doxverilog2.8/.svn/text-base/ inflating: Doxverilog2.8/.svn/text-base/ChangeLog.txt.svn-base inflating: Doxverilog2.8/.svn/text-base/README.svn-base inflating: Doxverilog2.8/.svn/text-base/verilog.patch.svn-base creating: Doxverilog2.8/.svn/tmp/ creating: Doxverilog2.8/.svn/tmp/prop-base/ creating: Doxverilog2.8/.svn/tmp/props/ creating: Doxverilog2.8/.svn/tmp/text-base/ inflating: Doxverilog2.8/ChangeLog.txt inflating: Doxverilog2.8/README creating: Doxverilog2.8/sources/ creating: Doxverilog2.8/sources/.svn/ inflating: Doxverilog2.8/sources/.svn/all-wcprops inflating: Doxverilog2.8/sources/.svn/entries creating: Doxverilog2.8/sources/.svn/prop-base/ creating: Doxverilog2.8/sources/.svn/props/ creating: Doxverilog2.8/sources/.svn/text-base/ inflating: Doxverilog2.8/sources/.svn/text-base/verilogdocgen.cpp.svn-base inflating: Doxverilog2.8/sources/.svn/text-base/verilogdocgen.h.svn-base inflating: Doxverilog2.8/sources/.svn/text-base/verilogparser.cpp.svn-base bad CRC 50e9e4dd (should be 1ddd7af8) file #27: bad zipfile offset (local header sig): 95320 (attempting to re-compensate) file #27: bad zipfile offset (local header sig): 95320 file #28: bad zipfile offset (local header sig): 97420 file #29: bad zipfile offset (local header sig): 114541 file #30: bad zipfile offset (local header sig): 158749 file #31: bad zipfile offset (local header sig): 160565 file #32: bad zipfile offset (local header sig): 177882 file #33: bad zipfile offset (local header sig): 179246 file #34: bad zipfile offset (local header sig): 180821 file #35: bad zipfile offset (local header sig): 204415 file #36: bad zipfile offset (local header sig): 207356 file #37: bad zipfile offset (local header sig): 214652 file #38: bad zipfile offset (local header sig): 231647 file #39: bad zipfile offset (local header sig): 234041 file #40: bad zipfile offset (local header sig): 234102 file #41: bad zipfile offset (local header sig): 234173 file #42: bad zipfile offset (local header sig): 234240 file #43: bad zipfile offset (local header sig): 234311 file #44: bad zipfile offset (local header sig): 242386 file #45: bad zipfile offset (local header sig): 244151 file #46: bad zipfile offset (local header sig): 305497 file #47: bad zipfile offset (local header sig): 307577 file #48: bad zipfile offset (local header sig): 324674 inflating: Doxverilog2.8/sources/verilogscanner.h inflating: Doxverilog2.8/sources/verilogscanner.l inflating: Doxverilog2.8/sources/VFileLine.cpp inflating: Doxverilog2.8/sources/VFileLine.h inflating: Doxverilog2.8/sources/VPreLex.cpp inflating: Doxverilog2.8/sources/VPreLex.h inflating: Doxverilog2.8/sources/VPreLex.l inflating: Doxverilog2.8/sources/VPreProc.cpp inflating: Doxverilog2.8/sources/VPreProc.h inflating: Doxverilog2.8/verilog.patch
うーん、確かにエラーで解凍できません。次に.zipを.tar.gzにリネームして再度解凍を試してみます。
$ tar xvzf Doxverilog2.8.tar.gz gzip: stdin has more than one entry--rest ignored tar: Child returned status 2 tar: Error is not recoverable: exiting now
全然だめです。doxverilog作者のページに書かれているsvnレポジトリもダウンしているようです。ということで、諦めて（誰かが置いた）githubのバージョン2.7を試すことにします。
githubのDoxverilogを試す
https://github.com/ewa/doxverilogのデータを試してみます。
$git clone git://github.com/ewa/doxverilog.git Cloning into 'doxverilog'... remote: Counting objects: 942, done. remote: Total 942 (delta 0), reused 0 (delta 0), pack-reused 942 Receiving objects: 100% (942/942), 5.55 MiB | 1.25 MiB/s, done. Resolving deltas: 100% (300/300), done. Checking connectivity... done.
データはdoxverilogというディレクトリに格納されます。その中にDoxverilog2.7というパッチデータとdoxygen-1.8.1というDoxygenのディレクトリがあります。doxygen-1.8.1には既にパッチが適用されているようなので、通常のDoxygenコンパイル手順でdoxgen-1.8.1をコンパイルしてみます。手順はcongiureしてmake allするだけです。
$cd doxverilog
$cd doxygen-1.8.1
$./configure
Autodetected platform linux-g++...
Checking for GNU make tool... using /usr/bin/make
Checking for GNU install tool... using /usr/bin/install
Checking for dot (part of GraphViz)... not found!
Checking for perl... using /usr/bin/perl
Checking for flex... using /usr/bin/flex
Checking for bison... using /usr/bin/bison
Creating VERSION file.
Created doxygen.spec file, for rpm generation.
Created Makefile from Makefile.in...
Created qtools/Makefile from qtools/Makefile.in...
Created src/Makefile from src/Makefile.in...
Created examples/Makefile from examples/Makefile.in...
Created doc/Makefile from doc/Makefile.in...
Created addon/doxywizard/Makefile from addon/doxywizard/Makefile.in...
Created addon/doxmlparser/src/Makefile from addon/doxmlparser/src/Makefile.in...
Created addon/doxmlparser/test/Makefile from addon/doxmlparser/test/Makefile.in...
Created addon/doxmlparser/examples/metrics/Makefile from addon/doxmlparser/examples/metrics/Makefile.in...
Created libmd5/Makefile from libmd5/Makefile.in...
Created addon/doxyapp/Makefile from addon/doxyapp/Makefile.in...
Created qtools/qtools.pro from qtools/qtools.pro.in...
Created src/libdoxygen.pro from src/libdoxygen.pro.in...
Created src/libdoxycfg.pro from src/libdoxycfg.pro.in...
Created src/doxygen.pro from src/doxygen.pro.in...
Created addon/doxywizard/doxywizard.pro from addon/doxywizard/doxywizard.pro.in...
Created addon/doxmlparser/src/doxmlparser.pro from addon/doxmlparser/src/doxmlparser.pro.in...
Created addon/doxmlparser/test/xmlparse.pro from addon/doxmlparser/test/xmlparse.pro.in...
Created addon/doxmlparser/examples/metrics/metrics.pro from addon/doxmlparser/examples/metrics/metrics.pro.in...
Created libmd5/libmd5.pro from libmd5/libmd5.pro.in...
Created addon/doxyapp/doxyapp.pro from addon/doxyapp/doxyapp.pro.in...
Generating src/lang_cfg.h...
$make all
vhdlparser.cpp: In function ‘int vhdlScanYYparse()’:
vhdlparser.cpp:3100:56: error: expected ‘;’ before ‘}’ token
{ (yyval.qstr)=(yyvsp[-2].qstr)+","+(yyvsp[0].qstr)}
^
vhdlparser.cpp:3185:50: error: expected ‘;’ before ‘}’ token
{ currP=VhdlDocGen::GENERIC;parse_sec=GEN_SEC}
^
vhdlparser.cpp:4462:58: error: expected ‘;’ before ‘}’ token
{ (yyval.qstr)=(yyvsp[-3].qstr)+"="+(yyvsp[-1].qstr) }
^
vhdlparser.cpp:4484:58: error: expected ‘;’ before ‘}’ token
{ (yyval.qstr)=(yyvsp[-1].qstr)+" "+(yyvsp[0].qstr) }
^
vhdlparser.cpp:4490:41: error: expected ‘;’ before ‘}’ token
{ (yyval.qstr)=", "+(yyvsp[0].qstr) }
^
make[2]: *** [../objects/vhdlparser.o] Error 1
make[2]: Leaving directory `doxverilog/doxygen-1.8.1/src'
make[1]: *** [all] Error 2
make[1]: Leaving directory `doxverilog/doxygen-1.8.1/src'
make: *** [all] Error 2エラーでコンパイルが止まります。どうもvhdlparser.cppというファイルで”;”が不足している箇所があるようなので、vhdlparser.cppの次の5行の末尾付近に”;”を追加して再度コンパイルを試します。
3100: { (yyval.qstr)=(yyvsp[-2].qstr)+”,”+(yyvsp[0].qstr);}
3185: { currP=VhdlDocGen::GENERIC;parse_sec=GEN_SEC;}
4462: { (yyval.qstr)=(yyvsp[-3].qstr)+”=”+(yyvsp[-1].qstr);}
4484: { (yyval.qstr)=(yyvsp[-1].qstr)+” “+(yyvsp[0].qstr);}
4490: { (yyval.qstr)=(yyvsp[-1].qstr)+” “+(yyvsp[0].qstr);}
$make all : : make[2]: Leaving directory `doxverilog/doxygen-1.8.1/src' /usr/bin/make -f Makefile.doxygen PERL=/usr/bin/perl all make[2]: Entering directory `doxverilog/doxygen-1.8.1/src' g++ -c -pipe -D_LARGEFILE_SOURCE -Wall -W -fno-exceptions -O2 -I../qtools -I../libmd5 -I. -o ../objects/main.o main.cpp g++ -o ../bin/doxygen ../objects/main.o -L../lib -ldoxygen -ldoxycfg -lqtools -lmd5 -lpthread make[2]: Leaving directory `doxverilog/doxygen-1.8.1/src' make[1]: Leaving directory `doxverilog/doxygen-1.8.1/src'
一応コンパイルが成功しました。doxverilog/doxygen-1.8.1/binディレクトリにdoxygenという実行ファイルが生成されます。
簡単なサンプルのテスト
doxverilogのREADME(Doxverilog2.7/README)に記載されている設定ファイルとverilogソースコードで動作を確認してみます。READMEファイルから切り出したファイルは次の2つ(verilog.cfgとxor2.v)です。
PROJECT_NAME = Verilog Doxygen Test OUTPUT_DIRECTORY = verilog GENERATE_HTML = YES INPUT = ./xor2.v FILE_PATTERNS = *.v OPTIMIZE_OUTPUT_VERILOG = YES HIDE_PORT = yes EXTENSION_MAPPING = h=v QUIET = YES INHERIT_DOCS = YES EXTRACT_ALL = YES HIDE_SCOPE_NAMES = YE SOURCE_BROWSER = YES ENABLE_PREPROCESSING = YES MACRO_EXPANSION = yes SEARCH_INCLUDES = yes
//% @file xor2.v
//% @brief xor with two inputs
//% Xor Module brief description
//% Detailed description of this module
module XOR2 ( OUT, I0, I1 );
input I0; //% first input
input I1; //% second input
//% output
output OUT;
assign OUT = I0 ^ I1;
endmoduleドキュメントの生成は、”doxygen verilog.cfg”という形で設定ファイルを指定してdoxygenを実行するだけです。
$../doxygen-1.8.1/bin/doxygen verilog.cfg warning: argument `YE' for option HIDE_SCOPE_NAMES is not a valid boolean value Using the default: NO! warning: enabling OPTIMIZE_OUTPUT_VHDL assumes the following settings: INHERIT_DOCS = NO (was YES) HIDE_SCOPE_NAMES = YES (was NO) EXTRACT_PRIVATE = YES (was NO) ENABLE_PREPROCESSING = NO (was YES) EXTRACT_PACKAGE = YES (was NO) //% @file xor2.v //% @brief xor with two inputs //% @file xor2.v //% @brief xor with two inputs //% Xor Module brief description //% Detailed description of this module //% Xor Module brief description //% Detailed description of this module Preprocessing code of file doxverilog/simple_test/xor2.v... (null) (null) (null) (null)
実際に実行してみると”(null) (null)”といった怪しげなものが表示されますが、ドキュメント自体は生成されました。生成されたhtmlファイルはこちらです。
もうすこし複雑なVerilogコードで試してみる
多階層moudleのVerilogコードで階層図が生成されるか試してみたところ、正常に解析されました。
doxverilog生成図その1
doxverilog生成図その2
階層図を生成する機能は、オープンソースのVerilogコードを解析する場合などに役立ちそうです。
まとめ
・SourceForgeのバージョン2.8のデータは壊れている
・(誰かが置いた)githubのバージョン2.7のデータは一応動作する
Verilogは何故Doxgenで正式にサポートされないのでしょう。VHDLはサポートされているのに。やはり”Verilogユーザーはコメントに説明なんか書かない”からでしょうか。。
