v2html - Verilog to HTML converter
v2html [options] file1 [file2] ...
v2html is a perl 5 script that converts a bunch of verilog files to html, linking various things to their definitions. At the moment it handles:
It also generates a page containing all the modules it found arranged hierarchically and separate index pages for all of the files, modules, signals, tasks and functions.
Once you have the html files they can be installed on a web-server, or simply viewed using ``Open File...'' in your web browser.
Details on navigating around the converted files, and many examples can be found at http://www.burbleland.com/v2html/v2html.html .
Note that as of version 5.0 v2html uses cascading style sheets to colour the display. This means that pages viewed with old browsers that do not support cascading style sheets (for instance Netscape 3) will not be coloured.
In addition to the switches detailed below v2html also accepts and ignores most VCS/VerilogXL options and all other options starting with a plus. This means that you should be able to run it with the same command file you use for running simulations.
Switches:
'define NAME [VALUE]
at the top of each of your input files. The rather strange syntax is the same as VerilogXL's. This option is useful for controlling which ifdefs appear true to v2html.
# v2html -f file - turn on gzip compression
-z -ze .gz
-zc 'gzip -f'
You can have as many -f options as you want and you can probably put
-f options in the file too.
This page:
Maintained by: Joe_Bloggs@barking.com
Created: Thu Nov 6 08:53:37 1997
From: test2.v
v2html keeps track of all the information it needs to do this in a file called .v2html_incr .
If you have many different html directories which you want to use the one central cascading style sheet then you can use the -css option to specify one. For example:
-css http://www.barking.com/joes_style.css
-f, -m,
-s, -t and -fn to the part of the hierarchy file name
before the first dot (so hier.htm will put the files index in
hier-f.htm).
If you don't specify any -ht options then v2html will inspect the hierarchy and find all the top modules in the verilog files and print these out. The 'top modules' are modules that are not instantiated but instantiate other modules that v2html has found the definition of.
v2html -hc "This is our ASIC" *.v
-f'. For instance to use gzip use -zc 'gzip -f'
(the -f stops gzip prompting you about overwriting files).
The default name for the frame file is frame.html. This default can be overridden by specifying a file name after the -F option.
This page:
Maintained by: Joe_Bloggs@barking.com
Created: Thu Nov 6 08:53:37 1997
From: /asic/verilog/test2.v
For this to work your web server must have access to the source code. Also, you must either run v2html in the output directory or use absolute path names for the verilog files.
For example, if the source is in /home/asic/verilog and the html files want to end up in /home/www/verilog then there are two ways to run it to get -s to work:
1) In the output directory with verilog files specified by relative paths:
cd /home/www/verilog
v2html -s ../../asic/verilog/*.v
2) In any directory with verilog files specified by absolute paths:
cd /anywhere
v2html -s -o /home/www/verilog /home/asic/verilog/*.v
To use this you must have installed the v2html CGI script on your web-server. The /cgi_script is the name of the CGI script (with path). The /path_to_v_files is the directory you are putting your html files.
These paths are the paths your web server sees (not the full paths on the system) so is the same path that appears after http://server when accessing the files.
Here's an example:
cp v2html-cgi /opt/CERNhttpd/cgi-bin/ chmod 755 /opt/CERNhttpd/cgi-bin/v2html-cgi
cd /home/web/v2html/example/ex1 v2html -c /cgi-bin/v2html-cgi /v2html/example/ex1 ../verilog/*.v
Note that v2html can't check the parameters to -c while converting the files. You'll have to do it yourself by viewing the hierarchy in your web browser and clicking on [Hide All] at the top of the hierarchy. Make sure you view the file using the web server (use http://server/v2html/example/ex1/hierarchy.html rather than file:/home/web/v2html/example/ex1/hierarchy.html).
Depending on your webserver you may also need to use the -css to specify the full URL to your cascading stylesheet eg:
v2html -c /cgi-bin/v2html-cgi /v2html/examples/millennium_clock/hier_cgi -css http://www.burbleland.com/v2html/examples/millennium_clock/hier_cgi/v2html.css *.v
If you get a message like this when you click on [Hide All]:
Bad script request -- neither '/opt/CERNhttpd/cgi-bin/v2html-cg'
nor '/opt/CERNhttpd/cgi-bin/v2html-cg.pp' is executable
Then either there is either a problem with the installation of the cgi script or you have incorrectly specified the first parameter to -c.
If you get a message like this:
v2html error.
then you have probably got the second parameter to -c wrong.
Costas Calamvokis <v2html730@burbleland.com>.
Here is an example where v2html is run in the directory containing the verilog files (note the -o option):
cd /users/jb/verilog_files/
v2html -F my_frame.html -h my_hier.html -ht chip_top -htf -nu
-o /users/www/project/verilog -m Joe_Blogs@barking.com -s *.v
As the verilog files don't have absolute paths and we aren't running in the destination directory can't use -s (link to source) as the links v2html will create wouldn't allow the web server to find the files.
Here is an example where v2html is run in the directory where we want the html files (no -o option):
cd /users/www/project/verilog
v2html -F my_frame.html -h my_hier.html -ht chip_top -nu -htf
-m Joe_Blogs@barking.com -s
-c /cgi-bin/v2html-cgi /project/verilog ../../../jb/verilog_files/*.v
Here we can use the -s option because we are running the the destination directory, so the links v2html creates to the source will work (providing the web server is allowed to server files from /users/jb/verilog_files).
By default v2html tells you a lot about what it is doing (this is because it is slow and if it didn't you'd think it had crashed!). These messages can get in the way of the warnings v2html produces, so if you have a problem first try -q (quiet) to see if there are any warnings you missed in the deluge of messages.
Most of the Error messages concern failures to open files, I guess these will be caused by bad permissions, or you pointing v2html at files or directories that don't exist.
The errors that say things like:
Warning: Confused in t.v line 2 (state=SIGNAL_AFTER_NAME):
wire g xx;
^
mean that you have written some verilog that I wasn't expecting - send
it to me and I'll see what I can do.
Most of the warnings concern things that v2html will ignore because it found more than one of them. The most common is a duplicate module being found because an old copy of one of the files is lurking in your source directory. The easiest way around this is to use the -f option something like this:
ls /path/*.v | grep -v old_module_file.v > src_files v2html -f src_files
Generally v2html will ignore duplicate things (so for example modules won't appear in the hierarchy), but sometimes it will just pick one of them, so watch those warnings.