Why Doxygen?
I was looking for a documentation generator for Verilog, and remembered some designer from a partner company using
Doxygen for this. To have Doxygen support Verilog, there an add-on called
Doxverilog. Good thing about them is, both are free. Although HDL design tools often (hugely) lag behind on software IDEs, there seem to be a few commercial tools out there with built-in source documentation, such as Mentor Graphics's
HDL Designer. Now I can personally see the benefit of using an IDE for HDL development, such as on-the-fly documentation generation and using it to provide context help while coding, like Eclipse does (very helpful). But in my experience, HDL designers are not very fond of IDEs and tend to panic if you try and drag them away from their precious vi. So we're back to stand-alone source documentation tools. A short tour on Google showed me there isn't much else going round that fulfills my requirements, so I thought I'd give this Doxygen a spin.
Installation
NOTE: there have been a number of updates on Doxverilog since this post, see
this post for an updated installation guide.
Installing Doxverilog is quite easy, just download
here and the README basically explains how. It's actually a patch to Doxygen 1.7.0, get it
here. I followed Doxverilog's README, but not unlike most source builds, I ran into a couple of problems. For the record, I'm installing on Linux RHEL4, which by default installs bison (GNU Bison) 1.875c, and flex version 2.5.4.
First problem I ran into was:
verilogparser.cpp:5476: error: invalid conversion from `void*' to `yyGLRState**'
As said, RHEL4 uses bison 1.875c, and if I had read the README thoroughly (not one of my favorite activities) I could have noticed Doxverilog requires Bison 2.1 or higher. So I got it
here. That got rid of the above, and presented problem number two:
g++ -o ../bin/doxygen ../objects/main.o -L../lib -ldoxygen -ldoxycfg -lqtools -lmd5 -lpthread
../lib/libdoxygen.a(eclipsehelp.o)(.text+0x23): In function `EclipseHelp::EclipseHelp()':
: undefined reference to `FTextStream::FTextStream()'
It was because the ftextstream files were stripped from the src/libdoxygen.pro file by the patch. I fixed it by removing the corresponding changes from the patch file.
Now that I had successfully built doxygen, the output was not very useful, it recognized half of the Verilog code and I got strange double quotes in doxygen's report. Turns out I was stupid enough to overlook that Flex 2.5.4 is actually not newer than 2.5.35 (yeah I know...). So I got it
here, and now all runs fine.
I've put the makefile I created, to recreate the installation steps, including downloading necessary packages and compile bison and flex,
here.
Running
Doxygen is really friendly. Just type doxygen and it'll show you what to do next. You can document your Verilog using special tags like //% for single line, and /*% ... */ for multiline comments, just put them in the right places (mostly intuitive). Doxygen will extract your design hierarchy, auto-document a selected set of design elements such as modules, ports, etc. and annotate them with your Doxygen tagged comments.
I built a template first:
/opt/doxygen/bin/doxygen -s -g verilog.cfg
Then modified the template:
OPTIMIZE_OUTPUT_VERILOG = YES
EXTENSION_MAPPING = va=VERILOG vams=VERILOG
INPUT = files / directories
EXCLUDE_SYMBOLS = wreal
PREDEFINED = wrealZState=0 wrealXState=0
Setting OPTIMIZE_OUTPUT_VERILOG to YES is required for proper Verilog handling. You cannot combine languages, Doxygen is not suited for that. Well, actually, you can enable OPTIMIZE_OUTPUT_VERILOG and combine both Verilog and VHDL input files, but it will not properly document the VHDL files, and you cannot also enable OPTIMIZE_OUTPUT_VHDL. This is a tool restriction, sad but true.
You'll have to add the EXTENSION_MAPPINGs to make Doxygen treat non-.v files as Verilog. Use INPUT to define the files or directories you want Doxygen to parse.
Verilog AMS
Doxverilog does not support Verilog AMS natively. I pulled a few small tricks to work around the issues that gave me when documenting my Verilog AMS files. One of them is already explained above for handling the file extensions. Additionally, I used EXLUDE_SYMBOLS to make Doxygen skip the wreal declarations. It doesn't understand them will recognize them as module instantiations, so I prefer to skip them. Cadence NCSim supports wreal signal values wrealZState and wrealXState. Doxygen will not recognize them, but by predefining them you can tell Doxygen it's ok, and get rid of the messages in report.
Result
Doxygen can generate multiple document types, such as HTML (main focus), RTF, Latex, etc. The content is well structured, and the hierarchy lists and diagrams are useful. Templates are customizable, easy to use. Pity you can't combine VHDL and Verilog in a single run. It's also very extensible, you can totally run off with it and write additional documentation into pages, in a Latex like language for formatting. Personally, I don't think you should do that, limit yourself to documentation that is required to interpret the one generated by Doxygen, and write IP user guides in a conventional word processor.
I can truly recommend Doxverilog to document your HDL. It forces you to document your code in the most convenient way in my opinion, and if at some point you decide to use some other source documentation tool, it shouldn't be hard to transcribe your comments, if necessary at all.
