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ユーザーはコメントに説明なんか書かない”からでしょうか。。
