Tuesday, May 13, 2014

Doxverilog on Ubuntu 14.04


If you haven't got these packages installed already (not default on clean 14.04 install):
 
sudo apt-get install flex
sudo apt-get install bison
sudo apt-get install g++
sudo apt-get install dos2unix

Then simply:

svn checkout svn://svn.berlios.de/doxverilog/trunk
rm -rf doxygen
unzip trunk/doxverilog/Doxverilog2.8/project/doxygen-1.8.5.zip
cd doxygen
dos2unix configure
chmod 755 configure
./configure
make all

Tuesday, April 22, 2014

Doxverilog has been updated


Since my previous post on using Doxverilog, there have been a number of updates. Here's an updated installation guide for version 2.8 (patches version 1.8.5 of Doxygen). It has been tested on RHEL 5.7, using SVN version revision 85. The ZIP file found on BerliOS seems corrupt (at time of writing), so use SVN as shown below.

svn checkout svn://svn.berlios.de/doxverilog/trunk
wget ftp://ftp.stack.nl/pub/users/dimitri/doxygen-1.8.5.src.tar.gz
gtar zxf doxygen-1.8.5.src.tar.gz
cp trunk/doxverilog/Doxverilog2.8/sources/* doxygen-1.8.5/src
cp trunk/doxverilog/Doxverilog2.8/verilog.patch doxygen-1.8.5
cd doxygen-1.8.5
patch -p1 < verilog.patch
./configure
make all |& tee ../make.log

Again, the above is tested on RHEL 5.7. If you run into issues on Ubuntu 14.04, check this.

Thursday, August 11, 2011

Documenting Verilog (AMS) using Doxygen/Doxverilog

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.