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:
Be quiet - so don't print all those informative messages about what it is doing.
Pre-define a value. This is just the same as putting:
'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.
Specify a directory to search for include files (just like VerilogXL).
Specify a directory to search for modules (just like VerilogXL). Note that v2html doesn't do any fancy search orders like VerilogXL - it just searches the directories in the order that you specify them on the command line.
Specify an extension use when searching for modules (just like VerilogXL). You can specify multiple extensions using +libext+EXT1+EXT2+EXT2 or by specifying multiple +libext+EXT options.
Specify a library file to use (just like VerilogXL).
Specify a file to get more command line options from. For instance you could put a list of all your files in src_files and then use -f src_file. You can also put in just about anything that you can put on the command line. Comments can be included using # or // at the start of the line. Wildcards are not allowed in the file names. Use single or double quotes to quote arguments that have spaces in them for example:
# 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.
A mail address of the site maintainer. This is placed in a field at the bottom of each file like this:
This page:
Maintained by: Joe_Bloggs@barking.com
Created: Thu Nov 6 08:53:37 1997
From: test2.v
Incremental mode. At the moment this isn't very incremental! v2html checks the dates on all of the files that it read last time it ran and all of the output files it generated. If any of the input files are newer than the output files, or if the command line options have changed it deletes all of the files it made last time and rebuilds everything. The delete is done to stop old files accumulating in the output directory.
v2html keeps track of all the information it needs to do this in a file called .v2html_incr .
Set the output directory for the html files. The default is the current directory.
The appearance of all the different elements of the html page can be altered using a cascading style sheet. By default v2html uses a file called v2html.css in the same directory as the html files. You can customize the appearance of the html files by editing this file (v2html will create one if it does not exist, but will not overwrite an existing one).
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
Set the name of the file that the hierarchy is written to. The default
is hierarchy.html. This is also used as a base for the index file
names. These file names are formed put appending -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).
Set the name of a top module you want in the hierarchy. You can specify multiple -ht options to specify multiple top modules.
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.
Specifies some text to put at the top of the hierarchy. For instance:
v2html -hc "This is our ASIC" *.v
Turns on printing of tasks and functions in the hierarchy. By default they are not printed.
In order to speed up viewing v2html splits large verilog files across multiple html pages. This option lets you specify how many lines you want on a page. The default is 1000.
No ``No modules''. By default the hierarchy contains three sections, the hierarchies of the top modules, a list of files containing no modules and a list of unconnected modules (modules that are not instantiated but also do not qualify as top modules). The -nnm makes v2html skip printing the list of files containing no modules. See -nu.
No unconnected. See -nnm. Makes v2html skip writing the list of unconnected modules in the hierarchy file.
No hierarchy. Don't print out the hierarchy.
No indexes. Don't print out the indexes.
By default v2html 'greys out' any code that is ifdefed out. The -ni turns this greying out off. Note that v2html always ignores code that is ifdefed out when it is parsing.
Compress the html files generated (and make sure the links point to the compressed versions). This can be useful if you convert machine generated code, like ASIC RAM macros which are huge before they are converted and even bigger afterwards.
The executable to use to compress the html files if -z is used. The
Default is 'compress -f'. For instance to use gzip use -zc 'gzip -f'
(the -f stops gzip prompting you about overwriting files).
The extension that your compress executable uses. The default is '.Z'. If you were using gzip then you'd want -ze .gz
Frame mode. Using -F turns on the generation of framed output where a top level frame file is generated that creates three frames in your browser, the top one for the hierarchy the middle one for the code and the bottom one for any definitions to appear in.
The default name for the frame file is frame.html. This default can be overridden by specifying a file name after the -F option.
Same as -F but arranges the frames vertically so that the hierarchy is down the side.
Link to the source. This causes the file name in From field of the page footer to become a link to the unconverted verilog file:
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
Activate CGI features which allow the user to hide and show regions of the hierarchy in a similar way to the old file manager on windows 3.1. This method only works if you put the files on a web server.
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.
Specify the key to use for to stop people looking at hierarchy files that are protected by web-server security. The default is to use a random key, but this means that you can't have bookmarks of the hierarchy in various states (because the bookmark will contain the key, and the key will change each time you run v2html). To get round this problem you can use -k and always have the same key string. The key can be any string of digits and letters.
Deactivate Javascript features that allow the user to hide and collapse regions of the hierarchy.
The Javascript version of the hierarchy uses cookies to remember the state you left the hierarchy in, so when you next visit the hierarchy page it will be in the same state. If you hate cookies then use the -ncookies option to turn them off.
Turn off the generation of javascript that does the signal popup window. Specifying this option also turns off ``Quick Search''.
Expand tabs to the specified value.
Turn on lots of debugging information.
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.