SOC1-208: Refactored and Created HTML generation scripts

bin/htmlgen/filelist_compile.py

+#!/usr/bin/env python3
+#------------------------------------------------------------------------------------
+# Verilog Filelist compilation script
+# A joint work commissioned on behalf of SoC Labs, under Arm Academic Access license.
+#
+# Contributors
+#
+# David Mapstone (d.a.mapstone@soton.ac.uk)
+# Copyright (c) 2023, SoC Labs (www.soclabs.org)
+#------------------------------------------------------------------------------------
+
+import argparse
+import os
+
+verilog_extensions = (".v", ".sv")
+
+filelist_header = """//-----------------------------------------------------------------------------
+// AUTOGENERATED: Compiled Filelist
+// A joint work commissioned on behalf of SoC Labs, under Arm Academic Access license.
+//
+// Contributors
+//
+// David Mapstone (d.a.mapstone@soton.ac.uk)
+//
+// Copyright � 2021-3, SoC Labs (www.soclabs.org)
+//-----------------------------------------------------------------------------
+//-----------------------------------------------------------------------------
+// Abstract : Verilog Command File with expanded system variables
+//-----------------------------------------------------------------------------
+
+"""
+
+def env_var_substitute(path):
+    # Interpret the path and remove brackets from path
+    sub_path = path.translate(str.maketrans('', '', '()'))
+    # Expand environment variables in Path
+    sub_path = os.path.expandvars(sub_path)
+    return sub_path
+
+def read_list(filelist):
+    # Create Filelist List Structure
+    compiled_filelist = []
+    # Open Filelist and Read Lines
+    f = open(filelist, "r")
+    filelines = f.readlines()
+    f.close()
+    # Remove Black Lines from list
+    filelines = [x.rstrip("\n") for x in filelines]
+    filelines = [x for x in filelines if x != ""]
+    # Iterate over list and process
+    for line in filelines:
+        # Remove whitespace and split line into arguments
+        line_list = line.strip().split()
+        # print(line_list)
+        # Check Line isn't a comment
+        if not line_list[0].startswith("//"):
+            # If line is a reference to another filelist 
+            if line_list[0] == "-f":
+                # Recursively call this function and append list to this compiled Filelist
+                print(line_list[1])
+                compiled_filelist += read_list(env_var_substitute(line_list[1]))
+
+            elif line_list[0] == "-y":
+                # Append to filelist
+                for file in os.listdir(env_var_substitute(line_list[1])):
+                    if file.endswith(verilog_extensions): 
+                        compiled_filelist.append(env_var_substitute(line_list[1])+"/"+str(file))
+            
+            elif line_list[0].startswith("+incdir+"):
+                # Append to filelist
+                for file in os.listdir(env_var_substitute(line_list[0].lstrip("+incdir+"))):
+                    if file.endswith(verilog_extensions): 
+                        compiled_filelist.append(env_var_substitute(line_list[0].lstrip("+incdir+"))+"/"+str(file))
+                
+            # If file list a verilog file
+            elif line_list[0].endswith(verilog_extensions):
+                # Append to filelist
+                compiled_filelist.append(env_var_substitute(line_list[0]))
+    return compiled_filelist
+            
+
+def filelist_compile(args):
+    input_filelist = args.filelist
+    output_filelist = args.output
+    print("------------------")
+    print("Compiling Filelist")
+    print("------------------")
+    filelist = read_list(input_filelist)
+    filelist = [x+"\n" for x in filelist]
+    filelist_str = filelist_header
+    for path in filelist: filelist_str += path
+    print("Compile Done")
+    print("------------------")
+    f_outlist = open(output_filelist, "w")
+    f_outlist.write(filelist_str)
+    f_outlist.close()
+
+if __name__ == "__main__":
+    # Capture Arguments from Command Line
+    parser = argparse.ArgumentParser(description='Compiles Filelist to Read')
+    parser.add_argument("-f", "--filelist", type=str, help="Input Filelist to Read")
+    parser.add_argument("-o", "--output", type=str, help="Output Filelist location")
+    args = parser.parse_args()
+    filelist_compile(args)
\ No newline at end of file

bin/htmlgen/makefile

+#-----------------------------------------------------------------------------
+# HTML Generatoration Makefile 
+# A joint work commissioned on behalf of SoC Labs, under Arm Academic Access license.
+#
+# Contributors
+#
+# David Mapstone (d.a.mapstone@soton.ac.uk)
+#
+# Copyright � 2021-3, SoC Labs (www.soclabs.org)
+#-----------------------------------------------------------------------------
+
+# Top-level module of Hierarchy
+TOP_MODULE      ?= nanosoc_chip
+
+# Filelist to give to v2html
+FILELIST        ?= $(PROJECT_DIR)/flist/project/system.flist
+
+# Directory to store generated HTML
+OUT_DIR         ?= $(PROJECT_DIR)
+
+# Name of generated filelist by python script
+OUTPUT_FILELIST := $(OUT_DIR)/filelist.flist
+
+bootrom:
+	make -C $(NANOSOC_TECH_DIR)/system bootrom
+
+htmlgen: bootrom
+	@echo building HTML tree
+	@mkdir -p $(OUT_DIR)/build
+	@(cd $(OUT_DIR)/build; \
+	rm *.html; rm *.gif; \
+	$(SOCTOOLS_FLOW_DIR)/bin/htmlgen/filelist_compile.py -f $(FILELIST) -o $(OUTPUT_FILELIST) ; \
+	$(SOCTOOLS_FLOW_DIR)/bin/htmlgen/v2html/v2html -f $(OUTPUT_FILELIST) -ht $(TOP_MODULE) ; )

bin/htmlgen/v2html/LICENCE.TXT

+			v2html Conversion Software
+
+			Limited Copyright Licence
+
+BACKGROUND
+
+The accompanying v2html conversion software (the software) is a 
+copyrighted work.  This document describes conditions under which the 
+software can be copied, modified and distributed.
+
+All rights, including copyright, in the software are retained by the 
+owner(s) as identified in each software file.
+
+Subject to the conditions described below, you may modify source 
+files included with the software and distribute the modified 
+versions.  The software accompanying this notice may include such 
+derivative works.
+
+CONDITIONS FOR AUTHORIZED COPYING, MODIFICATION AND DISTRIBUTION
+
+If you agree to all of the following conditions, you may copy, modify 
+and distribute the software subject to these conditions.
+
+You do not need to agree to these conditions.  However, if you do not 
+agree to all of the following conditions, you are not authorized to 
+do anything with regard to the copyrighted work that is within the 
+exclusive domain of a copyright owner, such as copying, modification, 
+and distribution.
+
+(1) No fee (monetary or otherwise) may be charged for the software or 
+any derivative work (whether in exchange for copying, distribution, 
+use, or otherwise).
+
+(2) The software includes copyright notices, references to this 
+document, and warnings concerning the intended use of the software.  
+All such notices are to be included in all copies of the software.  
+Any code copied or moved to a file not having such notices must be 
+accompanied by such notices.  Notices that are displayed to a user 
+during execution of the software are to remain intact.
+
+(3) This document may not be modified.  A copy of this document must 
+be included with each copy of the software, including derivative 
+works.
+
+(4) Failure to abide by these conditions terminates any rights that 
+you may otherwise have had under this licence.
+
+(5) NO WARRANTY:  The software has NO warranty from anyone; for 
+example, there is NO warranty that the software is error free and 
+there is NO warranty with respect to infringement of patents, 
+copyrights or any other intellectual property rights.  The software 
+is provided "AS IS."  NO support is provided for the software.
+
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A 
+PARTICULAR PURPOSE ARE SPECIFICALLY DISCLAIMED.
+
+(6) LIMITATIONS OF REMEDIES AND LIABILITY:
+In no event shall Hewlett-Packard be liable for direct, indirect, 
+special, incidental or consequential damages (including lost 
+profits), whether based on contract, tort or any other legal theory.
+
+(7) DERIVATIVE WORKS:  In this document, the phrase "derivative work" 
+is intended to include only those works that include sufficient 
+copyrightable material from the software such that the derivative 
+work would be a copyright infringement if made without authorization 
+of the owner of the copyright in the software.
+

bin/htmlgen/v2html/README

+
+v2html - verilog to html converter
+----------------------------------
+
+See LICENCE.TXT for details of licencing.
+
+See http://www.burbleland.com/v2html for more information.
+
+Files included:
+
+README		- this file
+v2html 		- v2html perl script
+v2html-cgi	- CGI helper script (for collapsible hierarchy)
+LICENCE.TXT	- licence
+v2html.man.html - man page in html format
+v2html.1	- man page in nroff format
+
+- Make sure you have perl version 5.004 or later (perl -v tells you
+  the version).
+
+Unix Installation
+-----------------
+
+- Copy v2html to somewhere like /usr/local/bin.
+- If you are using the CGI script then see your web-server's documentation
+  on where to put CGI scripts.
+- Copy v2html.1 to somewhere like /usr/local/man.
+
+If your copy of perl is not in /usr/bin then you will have to edit the
+first line of v2html and v2html-cgi to refer to where your copy of
+perl in installed. Alternatively you could install a link from 
+/usr/bin/perl to your copy of perl.
+
+Windows Installation
+--------------------
+
+- Put the v2html script somewhere (eg C:\v2html)
+- Then, assuming you have Perl installed as c:\perl\bin\perl.exe, you should
+ be able to run v2html from a DOS box with a command like this:
+
+  c:\perl\bin\perl.exe c:\v2html\v2html -f my_cmd_file.vc
+
+

bin/htmlgen/v2html/v2html-cgi

+#!/usr/local/bin/perl -w
+###############################################################################
+# 
+# File:         v2html-cgi
+# RCS:          $Header: v2html-cgi,v 3.1 1999/09/21 18:38:43 cc Exp $
+# Description:  CGI script for helping v2html generated html
+# Author:       Costas Calamvokis
+# Created:      Wed Sep  3 08:52:08 1997
+# Modified:     Tue Sep 21 11:34:21 1999 (Costas Calamvokis) v2html@burbleland.com
+# Language:     Perl
+#
+# Copyright 1998 Costas Calamvokis
+# Copyright 1997 Hewlett-Packard Company
+#
+#  This file nay be copied, modified and distributed only in accordance
+#  with the terms of the limited licence contained in the accompanying
+#  file LICENCE.TXT.
+#
+###############################################################################
+
+#
+# Currently does:
+#  Expanding/compressing hierarchies:
+#   - Takes a query like ?k=9437645&x=XXXXCCXC&in=hierarchy.html
+#    and generates html of the hierarchy in in accoring to the string
+#    x, each character in the string x represents one list in the .html
+#    file which can either be eXpanded or Compressed.
+#   - After each module it also generates a [X] or [C] link which when
+#      clicked causes this script to be called again with a new string
+#      which results in that module being expanded or compressed.
+#   - This is made much easier by v2html which marks each list that is
+#       with a candidate for expansion/compression with a 
+#       number when it generates the html code.
+#
+
+# only have one file error message to avoid leaking information
+#  through errors (uncomment the helpful error during debugging)
+$file_error_message= "v2html-cgi error.<P>\n";
+
+print "Content-Type: text/html\n\n";
+
+# environment variables that should be set by the web server
+&check_input('QUERY_STRING',%ENV);
+&check_input('SCRIPT_NAME',%ENV);
+&check_input('PATH_INFO',%ENV);
+&check_input('PATH_TRANSLATED',%ENV);
+
+# Get the arguements specified in the URL
+%args= getcgivars();
+
+# query variables that should be set in the URL 
+#  (eg .. ?k=9999x=CXCX&in=hierarchy.html
+&check_input('x',%args);
+&check_input('f',%args);
+&check_input('in',%args);
+&check_input('k',%args);
+
+$k             = $args{'k'};
+$expand_string =$args{'x'};
+$infile        = $args{'in'};
+$framed        = $args{'f'};
+
+# remove the / from script name if it is there
+$ENV{'SCRIPT_NAME'} =~ s#^/## ; 
+
+# set up the cgi script and path info that we'll put in the expand/compress
+#  links
+$cgi_script_and_path_info= "/" . $ENV{'SCRIPT_NAME'} . $ENV{'PATH_INFO'};
+
+
+$marker = "  <!-- v2html_handle --> ";
+$printing=1; # start out printing the file
+$ul_id=0;
+
+# Work out the hierarchy file to read
+$file=$ENV{'PATH_TRANSLATED'} . $infile;
+
+# Remove any .. in the file name so people can't look at files
+#  that are not under the web root
+$file=~ s/\.\.//g;
+
+# open the hierarchy file
+unless (open(F,"<$file")) { 
+    print $file_error_message;
+    # this less cryptic message could give intruders clues about your files
+    #print "Couldn't open $ENV{'PATH_TRANSLATED'}$infile\n";
+    exit;
+}
+
+
+# check that the hierarchy file starts with "<!- v2html hierarchy" comment
+#  and that the key is correct
+$_ = <F>;
+&security_check_hierarchy($_);
+
+
+# Have a look for the briefcase icons - if they don't exist
+#  use [C] and [X]
+&find_icons;
+
+# set up the extra infomation needed to do framed output
+if ($framed eq "1") {     $target='target="upper"'; }
+else                {     $target='';               }
+
+#
+# main loop
+#
+while (<F>) {
+    # print the place to find the .v.html files at the bottom of the
+    #  header - if we don't do this then it'll look for them under
+    #  the cgi-bin directory
+    if (m&</head>&) {
+	print "<base href=\"http://$ENV{'SERVER_NAME'}" .
+	    ":$ENV{'SERVER_PORT'}$ENV{'PATH_INFO'}\">\n";    
+    }
+
+    if ($printing) {
+	if (m&<ul> <!-- ul_id=([0-9]+) -->&) {
+	    if (&check_expand_string($1)) {
+		# This is expanded now, so print compressor
+		print $marker .
+		    "<A name=\"ul_id_$1\"></A>\n";
+		print $marker .
+		    "<A $target href=\"$cgi_script_and_path_info?k=$k&x=" . 
+			&new_expand_string($1,"C") . 
+			    "&in=$infile&f=$framed#ul_id_$1\"> $icon_c</A>\n";
+		# keep printing
+		print $_;
+	    }
+	    else {
+		$ul_id=$1;
+		# This is compressed now, so print expander
+		print $marker .
+		    "<A name=\"ul_id_$ul_id\"></A>\n";
+		print $marker .
+		    "<A $target href=\"$cgi_script_and_path_info?k=$k&x=" . 
+			&new_expand_string($ul_id,"X") . 
+			    "&in=$infile&f=$framed#ul_id_$1\"> $icon_x</A>\n";
+		# stop printing
+		$printing=0;
+	    }
+	}
+	else {
+	    # print everything else except compressors and expanders
+	    #  which are generated fresh each time
+	    if (! m/$marker/) {
+		print $_;
+	    }
+	}
+    }
+    else {
+	# not printing, look for the end of the ul_id which stopped the
+	#  print.
+	if (m&</ul> <!-- ul_id=$ul_id -->&) {
+	    $printing=1;
+	}
+    }
+
+    
+
+}
+
+exit;
+
+###########################################################################
+# Subroutines
+###########################################################################
+
+#
+# Takes one arguement - the number in the character string to
+#  look at.
+# Returns 1 if the list is expanded and 0 if it is compressed
+#  if the number is off the end of the expand string then it
+#  returns 1
+#
+sub check_expand_string {
+    local($u) = @_;
+    local($c);
+
+    if ($expand_string eq 'A') {
+	return 1;
+    }
+    elsif (length($expand_string)>$u) {
+	$c = substr($expand_string,$u,1);
+	if ($c eq 'X'){ 
+	    return 1;
+	}
+	else {
+	    return 0;
+	}
+    }
+    else {
+	return 0;
+    }
+
+}
+
+#
+# Generate a new expand_string for a compressor or an expander link
+#  Takes two arguments, the number of the list and the new character
+#  to put in ('C' for compressor, 'X' for expander)
+#
+sub new_expand_string {
+    local($u,$c) = @_;
+    local($new_string,$l);
+
+    $l = length($expand_string);
+    if ($l > $u) {
+	$new_string = $expand_string;
+	substr($new_string,$u,1) = $c;
+    }
+    else {
+	if ($expand_string eq "A") {
+	    $new_string = "X" . "X" x ($u-$l) . $c;
+	}
+	else {
+	    $new_string = $expand_string . "C" x ($u-$l) . $c;
+	}
+    }
+
+    return $new_string;
+}
+
+#
+# check that the input array %a has an element $s
+#
+sub check_input {
+    local($s,%a) = @_;
+    if (!exists($a{$s})) {
+	print "v2html-cgi: fatal error, didn't get required parameter $s.<P>\n";
+	if ($s eq 'k') {
+	    print " This may be because the hierarchy was generated\n" .
+	     " by v2html 2.0. If so regenerate using a newer version<P>\n";
+	}
+	exit;
+    }
+}
+
+#
+# Read all CGI vars into an associative array.
+# If multiple input fields have the same name, they are concatenated into
+#   one array element and delimited with the \0 character.
+# This is a simple version, that assumes a request method of GET.
+#
+sub getcgivars {
+    local(%in) ;
+    local($name, $value) ;
+
+    # Resolve and unencode name/value pairs into %in
+    foreach (split('&', $ENV{'QUERY_STRING'})) {
+        s/\+/ /g ;
+        ($name, $value)= split('=', $_, 2) ;
+        $name=~ s/%(..)/sprintf("%c",hex($1))/ge ;
+        $value=~ s/%(..)/sprintf("%c",hex($1))/ge ;
+        $in{$name}.= "\0" if defined($in{$name}) ;  # concatenate multiple vars
+        $in{$name}.= $value ;
+    }
+
+    return %in ;
+
+}
+
+#
+# Do security checks on the hierarchy file
+#  make sure we don't:
+#   serve files that are not v2html hierarchies
+#   serve files that users can't get access to through the http demon
+#    (by checking that the key is right)
+#
+sub security_check_hierarchy {
+    my ($first_line) = @_;
+
+    if ($first_line =~ /^<!-- v2html hierarchy/) {
+	if ($first_line =~ /^<!-- v2html hierarchy K=$k /) {
+	    print $first_line;
+	}
+	else {
+	    print $file_error_message;
+	    # this less cryptic message could give intruders clues about your files
+	    #print "$ENV{'PATH_TRANSLATED'}$infile: bad key<P>\n";
+	    exit;
+	}
+    }
+    else {
+	print $file_error_message;
+	# this less cryptic message could give intruders clues about your files
+	#print "$ENV{'PATH_TRANSLATED'}$infile is not a v2html hierarchy file\n";
+	exit;
+    }
+}
+
+#
+# Look for the briefcase icons - if they don't exist use [C] and [X]
+#
+sub find_icons {
+    
+ if (( -r "$ENV{'PATH_TRANSLATED'}/v2html-c.gif" ) &&
+     ( -r "$ENV{'PATH_TRANSLATED'}/v2html-x.gif" )) {
+     $icon_c = "<IMG align=bottom border=0 SRC=\"v2html-c.gif\">";
+     $icon_x = "<IMG align=bottom border=0 SRC=\"v2html-x.gif\">";
+ }
+ else {
+     $icon_c = " [C]";
+     $icon_x = " [X]";
+ }
+
+
+}
+
+
+

bin/htmlgen/v2html/v2html.1

+.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sh \" Subsection heading
+.br
+.if t .Sp
+.ne 5
+.PP
+\fB\\$1\fR
+.PP
+..
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings.  \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
+.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
+.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
+.\" nothing in troff, for use with C<>.
+.tr \(*W-
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+.    ds -- \(*W-
+.    ds PI pi
+.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
+.    ds L" ""
+.    ds R" ""
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds -- \|\(em\|
+.    ds PI \(*p
+.    ds L" ``
+.    ds R" ''
+'br\}
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.if \nF \{\
+.    de IX
+.    tm Index:\\$1\t\\n%\t"\\$2"
+..
+.    nr % 0
+.    rr F
+.\}
+.\"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.hy 0
+.if n .na
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
+.    \" fudge factors for nroff and troff
+.if n \{\
+.    ds #H 0
+.    ds #V .8m
+.    ds #F .3m
+.    ds #[ \f1
+.    ds #] \fP
+.\}
+.if t \{\
+.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+.    ds #V .6m
+.    ds #F 0
+.    ds #[ \&
+.    ds #] \&
+.\}
+.    \" simple accents for nroff and troff
+.if n \{\
+.    ds ' \&
+.    ds ` \&
+.    ds ^ \&
+.    ds , \&
+.    ds ~ ~
+.    ds /
+.\}
+.if t \{\
+.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+.    \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+.    \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+.    \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+.    ds : e
+.    ds 8 ss
+.    ds o a
+.    ds d- d\h'-1'\(ga
+.    ds D- D\h'-1'\(hy
+.    ds th \o'bp'
+.    ds Th \o'LP'
+.    ds ae ae
+.    ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "V2HTML 1"
+.TH V2HTML 1 "January 2009" "v2html 7.30.1.3" "v2html"
+.SH "NAME"
+v2html \- Verilog to HTML converter
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+\&\fBv2html\fR [options] file1 [file2] ...
+.PP
+\&\fBv2html\fR 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:
+.IP "\- modules" 5
+.IX Item "- modules"
+.PD 0
+.IP "\- tasks" 5
+.IX Item "- tasks"
+.IP "\- functions" 5
+.IX Item "- functions"
+.IP "\- includes" 5
+.IX Item "- includes"
+.IP "\- defines" 5
+.IX Item "- defines"
+.IP "\- parameters" 5
+.IX Item "- parameters"
+.IP "\- inputs,outputs,inouts" 5
+.IX Item "- inputs,outputs,inouts"
+.IP "\- signals: wire, reg etc." 5
+.IX Item "- signals: wire, reg etc."
+.IP "\- mail addresses in comments" 5
+.IX Item "- mail addresses in comments"
+.IP "\- http \s-1URLS\s0 (http://....) in comments" 5
+.IX Item "- http URLS (http://....) in comments"
+.PD
+.PP
+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.
+.PP
+Once you have the html files they can be installed on a web\-server, or
+simply viewed using \*(L"Open File...\*(R" in your web browser.
+.PP
+Details on navigating around the converted files, and many examples
+can be found at http://www.burbleland.com/v2html/v2html.html .
+.PP
+Note that as of version 5.0 \fBv2html\fR uses \fIcascading style sheets\fR
+to colour the display. This means that pages viewed with old browsers
+that do not support \fIcascading style sheets\fR (for instance Netscape
+3) will not be coloured.
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+In addition to the switches detailed below \fBv2html\fR 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.
+.PP
+Switches:
+.IP "\fB\-q\fR" 5
+.IX Item "-q"
+Be quiet \- so don't print all those informative messages about what
+it is doing.
+.IP "\fB+define+NAME[=VALUE]\fR" 5
+.IX Item "+define+NAME[=VALUE]"
+Pre-define a value. This is just the same as putting:
+.Sp
+.Vb 1
+\&        \(aqdefine NAME [VALUE]
+.Ve
+.Sp
+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 \fBv2html\fR.
+.IP "\fB+incdir+DIR\fR" 5
+.IX Item "+incdir+DIR"
+Specify a directory to search for include files (just like VerilogXL).
+.IP "\fB\-y\fR\ \s-1DIR\s0" 5
+.IX Item "-yDIR"
+Specify a directory to search for modules (just like VerilogXL). Note that
+\&\fBv2html\fR 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.
+.IP "\fB+libext+EXT\fR" 5
+.IX Item "+libext+EXT"
+Specify an extension use when searching for modules (just like
+VerilogXL). You can specify multiple extensions using
+\&\fB+libext+EXT1+EXT2+EXT2\fR or by specifying multiple \fB+libext+EXT\fR
+options.
+.IP "\fB\-v\fR\ \s-1LIBFILE\s0" 5
+.IX Item "-vLIBFILE"
+Specify a library file to use (just like VerilogXL).
+.IP "\fB\-f\fR\ command_lines_options_file" 5
+.IX Item "-fcommand_lines_options_file"
+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 \fB\-f\fR\ 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:
+.Sp
+.Vb 3
+\&          # v2html \-f file \- turn on gzip compression
+\&          \-z \-ze .gz
+\&          \-zc \(aqgzip  \-f\(aq
+.Ve
+.Sp
+You can have as many \-f options as you want and you can probably put
+\&\-f options in the file too.
+.IP "\fB\-m\fR\ mail_addr" 5
+.IX Item "-mmail_addr"
+A mail address of the site maintainer. This is placed in a field at
+the bottom of each file like this:
+.Sp
+.Vb 4
+\& This page:
+\&         Maintained by:         Joe_Bloggs@barking.com
+\&         Created:               Thu Nov 6 08:53:37 1997
+\&         From:                  test2.v
+.Ve
+.IP "\fB\-i\fR" 5
+.IX Item "-i"
+Incremental mode. At the moment this isn't very incremental! \fBv2html\fR
+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 \fBdeletes\fR all of the files it made last time and rebuilds
+everything. The delete is done to stop old files accumulating in the
+output directory.
+.Sp
+\&\fBv2html\fR keeps track of all the information it needs to do this in
+a file called .v2html_incr .
+.IP "\fB\-o\fR\ output_dir" 5
+.IX Item "-ooutput_dir"
+Set the output directory for the html files. The default is the current
+directory.
+.IP "\fB\-css\fR\ cascading_style_sheet" 5
+.IX Item "-csscascading_style_sheet"
+The appearance of all the different elements of the html page can be altered
+using a \fIcascading style sheet\fR. By default \fBv2html\fR uses a file called
+\&\fIv2html.css\fR in the same directory as the html files. You can customize the
+appearance of the html files by editing this file (\fBv2html\fR will create one
+if it does not exist, but will not overwrite an existing one). 
+.Sp
+If you have many different html directories which you want to use the
+one central cascading style sheet then you can use the \fB\-css\fR option
+to specify one. For example:
+.Sp
+.Vb 1
+\&        \-css http://www.barking.com/joes_style.css
+.Ve
+.IP "\fB\-h\fR\ hier_file" 5
+.IX Item "-hhier_file"
+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(CW\*(C`\-f\*(C'\fR, \f(CW\*(C`\-m\*(C'\fR,
+\&\f(CW\*(C`\-s\*(C'\fR, \f(CW\*(C`\-t\*(C'\fR and \f(CW\*(C`\-fn\*(C'\fR to the part of the hierarchy file name
+before the first dot (so hier.htm will put the files index in
+hier\-f.htm).
+.IP "\fB\-ht\fR\ top_module" 5
+.IX Item "-httop_module"
+Set the name of a top module you want in the hierarchy. You can specify
+multiple \fB\-ht\fR options to specify multiple top modules. 
+.Sp
+If you don't specify any \fB\-ht\fR options then \fBv2html\fR 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 \fBv2html\fR has found
+the definition of.
+.IP "\fB\-hc\fR\ hierarchy_comment" 5
+.IX Item "-hchierarchy_comment"
+Specifies some text to put at the top of the hierarchy. For instance:
+.Sp
+.Vb 1
+\&   v2html \-hc "This is our ASIC" *.v
+.Ve
+.IP "\fB\-htf\fR" 5
+.IX Item "-htf"
+Turns on printing of tasks and functions in the hierarchy. By default they
+are not printed.
+.IP "\fB\-lines\fR\ max_lines_per_file" 5
+.IX Item "-linesmax_lines_per_file"
+In order to speed up viewing \fBv2html\fR 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.
+.IP "\fB\-nnm\fR" 5
+.IX Item "-nnm"
+No \*(L"No modules\*(R". 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 \fB\-nnm\fR makes
+\&\fBv2html\fR skip printing the list of files containing no modules.
+See \fB\-nu\fR.
+.IP "\fB\-nu\fR" 5
+.IX Item "-nu"
+No unconnected. See \fB\-nnm\fR. Makes \fBv2html\fR skip writing the list
+of unconnected modules in the hierarchy file.
+.IP "\fB\-nh\fR" 5
+.IX Item "-nh"
+No hierarchy. Don't print out the hierarchy.
+.IP "\fB\-nindex\fR" 5
+.IX Item "-nindex"
+No indexes. Don't print out the indexes.
+.IP "\fB\-ni\fR" 5
+.IX Item "-ni"
+By default \fBv2html\fR 'greys out' any code that is ifdefed out. The \fB\-ni\fR
+turns this greying out off. Note that v2html always ignores code that is
+ifdefed out when it is parsing.
+.IP "\fB\-z\fR" 5
+.IX Item "-z"
+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 \s-1ASIC\s0 \s-1RAM\s0 macros which are huge before they are
+converted and even bigger afterwards.
+.IP "\fB\-zc\fR\ compresser" 5
+.IX Item "-zccompresser"
+The executable to use to compress the html files if \fB\-z\fR is used. The
+Default is 'compress \f(CW\*(C`\-f\*(C'\fR'. For instance to use gzip use \fB\-zc\fR 'gzip \f(CW\*(C`\-f\*(C'\fR'
+(the \f(CW\*(C`\-f\*(C'\fR stops gzip prompting you about overwriting files).
+.IP "\fB\-ze\fR\ compressed_extension" 5
+.IX Item "-zecompressed_extension"
+The extension that your compress executable uses. The default is '.Z'. If you
+were using gzip then you'd want \fB\-ze\fR .gz
+.IP "\fB\-F\fR\ [frame_file.html]" 5
+.IX Item "-F[frame_file.html]"
+Frame mode. Using \fB\-F\fR 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.
+.Sp
+The default name for the frame file is frame.html. This default
+can be overridden by specifying a file name after the \fB\-F\fR option.
+.IP "\fB\-VF\fR\ [frame_file.html]" 5
+.IX Item "-VF[frame_file.html]"
+Same as \fB\-F\fR but arranges the frames vertically so that the hierarchy is
+down the side.
+.IP "\fB\-s\fR" 5
+.IX Item "-s"
+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:
+.Sp
+.Vb 4
+\& This page:
+\&         Maintained by:         Joe_Bloggs@barking.com
+\&         Created:               Thu Nov 6 08:53:37 1997
+\&         From:                  /asic/verilog/test2.v
+.Ve
+.Sp
+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.
+.Sp
+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 \fB\-s\fR to work:
+.Sp
+.Vb 3
+\&  1) In the output directory with verilog files specified by relative paths:
+\&        cd /home/www/verilog
+\&        v2html \-s ../../asic/verilog/*.v
+.Ve
+.Sp
+.Vb 3
+\& 2) In any directory with verilog files specified by absolute paths:
+\&        cd /anywhere
+\&        v2html \-s \-o /home/www/verilog   /home/asic/verilog/*.v
+.Ve
+.IP "\fB\-c\fR\ /cgi_script\ /path_to_html_files" 5
+.IX Item "-c/cgi_script/path_to_html_files"
+Activate \s-1CGI\s0 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.
+.Sp
+To use this you must have installed the v2html \s-1CGI\s0 script on your
+web\-server. The /cgi_script is the name of the \s-1CGI\s0 script (with path).
+The /path_to_v_files is the directory you are putting your html files.
+.Sp
+These paths are the paths your web server sees (not the full paths on
+the system) so is the same path that appears after \fIhttp://server\fR when 
+accessing the files.
+.Sp
+Here's an example:
+.Sp
+.Vb 2
+\&  cp v2html\-cgi /opt/CERNhttpd/cgi\-bin/ 
+\&  chmod 755 /opt/CERNhttpd/cgi\-bin/v2html\-cgi
+.Ve
+.Sp
+.Vb 2
+\&  cd /home/web/v2html/example/ex1
+\&  v2html \-c /cgi\-bin/v2html\-cgi /v2html/example/ex1 ../verilog/*.v
+.Ve
+.Sp
+Note that \fBv2html\fR can't check the parameters to \fB\-c\fR while
+converting the files. You'll have to do it yourself by viewing the
+hierarchy in your web browser and clicking on \fB[Hide\ All]\fR at the
+top of the hierarchy. Make sure you view the file using the web server
+(use \fIhttp://server/v2html/example/ex1/hierarchy.html\fR rather than
+\&\fIfile:/home/web/v2html/example/ex1/hierarchy.html\fR).
+.Sp
+Depending on your webserver you may also need to use the \-css to
+specify the full \s-1URL\s0 to your cascading stylesheet eg:
+.Sp
+.Vb 3
+\& 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
+.Ve
+.Sp
+If you get a message like this when you click on \fB[Hide\ All]\fR:
+.Sp
+.Vb 2
+\&  Bad script request \-\- neither \(aq/opt/CERNhttpd/cgi\-bin/v2html\-cg\(aq 
+\&        nor \(aq/opt/CERNhttpd/cgi\-bin/v2html\-cg.pp\(aq is executable
+.Ve
+.Sp
+Then either there is either a problem with the installation of the cgi
+script or you have incorrectly specified the first parameter to \fB\-c\fR.
+.Sp
+If you get a message like this:
+.Sp
+.Vb 1
+\&  v2html error.
+.Ve
+.Sp
+then you have probably got the second parameter to \fB\-c\fR wrong.
+.IP "\fB\-k\fR\ key_string" 5
+.IX Item "-kkey_string"
+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 \fBv2html\fR). To get
+round this problem you can use \fB\-k\fR and always have the same
+key string. The key can be any string of digits and letters.
+.IP "\fB\-njshier\fR" 5
+.IX Item "-njshier"
+Deactivate Javascript features that allow the user to hide and
+collapse regions of the hierarchy.
+.IP "\fB\-ncookies\fR" 5
+.IX Item "-ncookies"
+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 \fB\-ncookies\fR option
+to turn them off.
+.IP "\fB\-nsigpopup\fR" 5
+.IX Item "-nsigpopup"
+Turn off the generation of javascript that does the signal popup window.
+Specifying this option also turns off \*(L"Quick Search\*(R".
+.IP "\fB\-tab\fR\ value" 5
+.IX Item "-tabvalue"
+Expand tabs to the specified value.
+.IP "\fB\-debug\fR" 5
+.IX Item "-debug"
+Turn on lots of debugging information.
+.SH "AUTHOR"
+.IX Header "AUTHOR"
+Costas Calamvokis <\fIv2html730@burbleland.com\fR>.
+.SH "EXAMPLES"
+.IX Header "EXAMPLES"
+Here is an example where \fBv2html\fR is run in the directory containing
+the verilog files (note the \fB\-o\fR option):
+.PP
+.Vb 3
+\&  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
+.Ve
+.PP
+As the verilog files don't have absolute paths and we aren't running
+in the destination directory can't use \fB\-s\fR (link to source) as the
+links \fBv2html\fR will create wouldn't allow the web server to find the
+files.
+.PP
+Here is an example where \fBv2html\fR is run in the directory where
+we want the html files (no \fB\-o\fR option):
+.PP
+.Vb 4
+\&  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
+.Ve
+.PP
+Here we can use the \fB\-s\fR option because we are running the the destination
+directory, so the links \fBv2html\fR creates to the source will work
+(providing the web server is allowed to server files from
+/users/jb/verilog_files).
+.SH "DIAGNOSTICS"
+.IX Header "DIAGNOSTICS"
+By default \fBv2html\fR 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 \fBv2html\fR produces, so if
+you have a problem first try \fB\-q\fR (quiet) to see if there are any warnings
+you missed in the deluge of messages.
+.PP
+Most of the Error messages concern failures to open files, I guess these
+will be caused by bad permissions, or you pointing \fBv2html\fR at files
+or directories that don't exist.
+.PP
+The errors that say things like:
+.PP
+.Vb 5
+\&   Warning: Confused in t.v line 2 (state=SIGNAL_AFTER_NAME):
+\&   wire g  xx;
+\&           ^
+\&mean that you have written some verilog that I wasn\(aqt expecting \- send
+\&it to me and I\(aqll see what I can do.
+.Ve
+.PP
+Most of the warnings concern things that \fBv2html\fR 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
+\&\fB\-f\fR option something like this:
+.PP
+.Vb 2
+\&  ls /path/*.v | grep \-v old_module_file.v > src_files
+\&  v2html \-f src_files
+.Ve
+.PP
+Generally \fBv2html\fR 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.

bin/htmlgen/v2html/v2html.man.html

+<?xml version="1.0" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>v2html - Verilog to HTML converter</title>
+<meta http-equiv="content-type" content="text/html; charset=utf-8" />
+<link rev="made" href="mailto:root@localhost" />
+</head>
+
+<body style="background-color: white">
+
+<p><a name="__index__"></a></p>
+<!-- INDEX BEGIN -->
+
+<ul>
+
+	<li><a href="#name">NAME</a></li>
+	<li><a href="#synopsis">SYNOPSIS</a></li>
+	<li><a href="#description">DESCRIPTION</a></li>
+	<li><a href="#author">AUTHOR</a></li>
+	<li><a href="#examples">EXAMPLES</a></li>
+	<li><a href="#diagnostics">DIAGNOSTICS</a></li>
+</ul>
+<!-- INDEX END -->
+
+<hr />
+<p>
+</p>
+<h1><a name="name">NAME</a></h1>
+<p>v2html - Verilog to HTML converter</p>
+<p>
+</p>
+<hr />
+<h1><a name="synopsis">SYNOPSIS</a></h1>
+<p><strong>v2html</strong> [options] file1 [file2] ...</p>
+<p><strong>v2html</strong> 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:</p>
+<dl>
+<dt><strong><a name="item__2d_modules">- modules</a></strong></dt>
+
+<dt><strong><a name="item__2d_tasks">- tasks</a></strong></dt>
+
+<dt><strong><a name="item__2d_functions">- functions</a></strong></dt>
+
+<dt><strong><a name="item__2d_includes">- includes</a></strong></dt>
+
+<dt><strong><a name="item__2d_defines">- defines</a></strong></dt>
+
+<dt><strong><a name="item__2d_parameters">- parameters</a></strong></dt>
+
+<dt><strong><a name="item__2d_inputs_2coutputs_2cinouts">- inputs,outputs,inouts</a></strong></dt>
+
+<dt><strong><a name="item__2d_signals_3a_wire_2c_reg_etc_2e">- signals: wire, reg etc.</a></strong></dt>
+
+<dt><strong><a name="item__2d_mail_addresses_in_comments">- mail addresses in comments</a></strong></dt>
+
+<dt><strong><a name="item_urls">- http URLS (http://....) in comments</a></strong></dt>
+
+</dl>
+<p>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.</p>
+<p>Once you have the html files they can be installed on a web-server, or
+simply viewed using ``Open File...'' in your web browser.</p>
+<p>Details on navigating around the converted files, and many examples
+can be found at <a href="http://www.burbleland.com/v2html/v2html.html">http://www.burbleland.com/v2html/v2html.html</a> .</p>
+<p>Note that as of version 5.0 <strong>v2html</strong> uses <em>cascading style sheets</em>
+to colour the display. This means that pages viewed with old browsers
+that do not support <em>cascading style sheets</em> (for instance Netscape
+3) will not be coloured.</p>
+<p>
+</p>
+<hr />
+<h1><a name="description">DESCRIPTION</a></h1>
+<p>In addition to the switches detailed below <strong>v2html</strong> 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.</p>
+<p>Switches:</p>
+<dl>
+<dt><strong><a name="item__2dq"><strong>-q</strong></a></strong></dt>
+
+<dd>
+<p>Be quiet - so don't print all those informative messages about what
+it is doing.</p>
+</dd>
+<dt><strong><a name="item__2bdefine_2bname_5b_3dvalue_5d"><strong>+define+NAME[=VALUE]</strong></a></strong></dt>
+
+<dd>
+<p>Pre-define a value. This is just the same as putting:</p>
+<pre>
+        'define NAME [VALUE]</pre>
+<p>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 <strong>v2html</strong>.</p>
+</dd>
+<dt><strong><a name="item__2bincdir_2bdir"><strong>+incdir+DIR</strong></a></strong></dt>
+
+<dd>
+<p>Specify a directory to search for include files (just like VerilogXL).</p>
+</dd>
+<dt><strong><a name="item__2dy_dir"><strong>-y</strong>&nbsp;DIR</a></strong></dt>
+
+<dd>
+<p>Specify a directory to search for modules (just like VerilogXL). Note that
+<strong>v2html</strong> 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.</p>
+</dd>
+<dt><strong><a name="item__2blibext_2bext"><strong>+libext+EXT</strong></a></strong></dt>
+
+<dd>
+<p>Specify an extension use when searching for modules (just like
+VerilogXL). You can specify multiple extensions using
+<strong>+libext+EXT1+EXT2+EXT2</strong> or by specifying multiple <strong>+libext+EXT</strong>
+options.</p>
+</dd>
+<dt><strong><a name="item__2dv_libfile"><strong>-v</strong>&nbsp;LIBFILE</a></strong></dt>
+
+<dd>
+<p>Specify a library file to use (just like VerilogXL).</p>
+</dd>
+<dt><strong><a name="item__2df_command_lines_options_file"><strong>-f</strong>&nbsp;command_lines_options_file</a></strong></dt>
+
+<dd>
+<p>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 <strong>-f</strong>
+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:</p>
+<pre>
+          # 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.</pre>
+</dd>
+<dt><strong><a name="item__2dm_mail_addr"><strong>-m</strong>&nbsp;mail_addr</a></strong></dt>
+
+<dd>
+<p>A mail address of the site maintainer. This is placed in a field at
+the bottom of each file like this:</p>
+<pre>
+ This page:
+         Maintained by:         Joe_Bloggs@barking.com
+         Created:               Thu Nov 6 08:53:37 1997
+         From:                  test2.v</pre>
+</dd>
+<dt><strong><a name="item__2di"><strong>-i</strong></a></strong></dt>
+
+<dd>
+<p>Incremental mode. At the moment this isn't very incremental! <strong>v2html</strong>
+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 <strong>deletes</strong> all of the files it made last time and rebuilds
+everything. The delete is done to stop old files accumulating in the
+output directory.</p>
+<p><strong>v2html</strong> keeps track of all the information it needs to do this in
+a file called .v2html_incr .</p>
+</dd>
+<dt><strong><a name="item__2do_output_dir"><strong>-o</strong>&nbsp;output_dir</a></strong></dt>
+
+<dd>
+<p>Set the output directory for the html files. The default is the current
+directory.</p>
+</dd>
+<dt><strong><a name="item__2dcss_cascading_style_sheet"><strong>-css</strong>&nbsp;cascading_style_sheet</a></strong></dt>
+
+<dd>
+<p>The appearance of all the different elements of the html page can be altered
+using a <em>cascading style sheet</em>. By default <strong>v2html</strong> uses a file called
+<em>v2html.css</em> in the same directory as the html files. You can customize the
+appearance of the html files by editing this file (<strong>v2html</strong> will create one
+if it does not exist, but will not overwrite an existing one).</p>
+<p>If you have many different html directories which you want to use the
+one central cascading style sheet then you can use the <strong>-css</strong> option
+to specify one. For example:</p>
+<pre>
+        -css <a href="http://www.barking.com/joes_style.css">http://www.barking.com/joes_style.css</a></pre>
+</dd>
+<dt><strong><a name="item__2dh_hier_file"><strong>-h</strong>&nbsp;hier_file</a></strong></dt>
+
+<dd>
+<p>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 <code>-f</code>, <code>-m</code>,
+<a href="#item__2ds"><code>-s</code></a>, <code>-t</code> and <code>-fn</code> to the part of the hierarchy file name
+before the first dot (so hier.htm will put the files index in
+hier-f.htm).</p>
+</dd>
+<dt><strong><a name="item__2dht_top_module"><strong>-ht</strong>&nbsp;top_module</a></strong></dt>
+
+<dd>
+<p>Set the name of a top module you want in the hierarchy. You can specify
+multiple <strong>-ht</strong> options to specify multiple top modules.</p>
+<p>If you don't specify any <strong>-ht</strong> options then <strong>v2html</strong> 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 <strong>v2html</strong> has found
+the definition of.</p>
+</dd>
+<dt><strong><a name="item__2dhc_hierarchy_comment"><strong>-hc</strong>&nbsp;hierarchy_comment</a></strong></dt>
+
+<dd>
+<p>Specifies some text to put at the top of the hierarchy. For instance:</p>
+<pre>
+   v2html -hc &quot;This is our ASIC&quot; *.v</pre>
+</dd>
+<dt><strong><a name="item__2dhtf"><strong>-htf</strong></a></strong></dt>
+
+<dd>
+<p>Turns on printing of tasks and functions in the hierarchy. By default they
+are not printed.</p>
+</dd>
+<dt><strong><a name="item__2dlines_max_lines_per_file"><strong>-lines</strong>&nbsp;max_lines_per_file</a></strong></dt>
+
+<dd>
+<p>In order to speed up viewing <strong>v2html</strong> 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.</p>
+</dd>
+<dt><strong><a name="item__2dnnm"><strong>-nnm</strong></a></strong></dt>
+
+<dd>
+<p>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 <strong>-nnm</strong> makes
+<strong>v2html</strong> skip printing the list of files containing no modules.
+See <strong>-nu</strong>.</p>
+</dd>
+<dt><strong><a name="item__2dnu"><strong>-nu</strong></a></strong></dt>
+
+<dd>
+<p>No unconnected. See <strong>-nnm</strong>. Makes <strong>v2html</strong> skip writing the list
+of unconnected modules in the hierarchy file.</p>
+</dd>
+<dt><strong><a name="item__2dnh"><strong>-nh</strong></a></strong></dt>
+
+<dd>
+<p>No hierarchy. Don't print out the hierarchy.</p>
+</dd>
+<dt><strong><a name="item__2dnindex"><strong>-nindex</strong></a></strong></dt>
+
+<dd>
+<p>No indexes. Don't print out the indexes.</p>
+</dd>
+<dt><strong><a name="item__2dni"><strong>-ni</strong></a></strong></dt>
+
+<dd>
+<p>By default <strong>v2html</strong> 'greys out' any code that is ifdefed out. The <strong>-ni</strong>
+turns this greying out off. Note that v2html always ignores code that is
+ifdefed out when it is parsing.</p>
+</dd>
+<dt><strong><a name="item__2dz"><strong>-z</strong></a></strong></dt>
+
+<dd>
+<p>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.</p>
+</dd>
+<dt><strong><a name="item__2dzc_compresser"><strong>-zc</strong>&nbsp;compresser</a></strong></dt>
+
+<dd>
+<p>The executable to use to compress the html files if <strong>-z</strong> is used. The
+Default is 'compress <code>-f</code>'. For instance to use gzip use <strong>-zc</strong> 'gzip <code>-f</code>'
+(the <code>-f</code> stops gzip prompting you about overwriting files).</p>
+</dd>
+<dt><strong><a name="item__2dze_compressed_extension"><strong>-ze</strong>&nbsp;compressed_extension</a></strong></dt>
+
+<dd>
+<p>The extension that your compress executable uses. The default is '.Z'. If you
+were using gzip then you'd want <strong>-ze</strong> .gz</p>
+</dd>
+<dt><strong><a name="item__2df__5bframe_file_2ehtml_5d"><strong>-F</strong>&nbsp;[frame_file.html]</a></strong></dt>
+
+<dd>
+<p>Frame mode. Using <strong>-F</strong> 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.</p>
+<p>The default name for the frame file is frame.html. This default
+can be overridden by specifying a file name after the <strong>-F</strong> option.</p>
+</dd>
+<dt><strong><a name="item__2dvf__5bframe_file_2ehtml_5d"><strong>-VF</strong>&nbsp;[frame_file.html]</a></strong></dt>
+
+<dd>
+<p>Same as <strong>-F</strong> but arranges the frames vertically so that the hierarchy is
+down the side.</p>
+</dd>
+<dt><strong><a name="item__2ds"><strong>-s</strong></a></strong></dt>
+
+<dd>
+<p>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:</p>
+<pre>
+ This page:
+         Maintained by:         Joe_Bloggs@barking.com
+         Created:               Thu Nov 6 08:53:37 1997
+         From:                  /asic/verilog/test2.v</pre>
+<p>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.</p>
+<p>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 <strong>-s</strong> to work:</p>
+<pre>
+  1) In the output directory with verilog files specified by relative paths:
+        cd /home/www/verilog
+        v2html -s ../../asic/verilog/*.v</pre>
+<pre>
+ 2) In any directory with verilog files specified by absolute paths:
+        cd /anywhere
+        v2html -s -o /home/www/verilog   /home/asic/verilog/*.v</pre>
+</dd>
+<dt><strong><a name="item__2dc__2fcgi_script__2fpath_to_html_files"><strong>-c</strong>&nbsp;/cgi_script&nbsp;/path_to_html_files</a></strong></dt>
+
+<dd>
+<p>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.</p>
+<p>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.</p>
+<p>These paths are the paths your web server sees (not the full paths on
+the system) so is the same path that appears after <em><a href="http://server">http://server</a></em> when 
+accessing the files.</p>
+<p>Here's an example:</p>
+<pre>
+  cp v2html-cgi /opt/CERNhttpd/cgi-bin/ 
+  chmod 755 /opt/CERNhttpd/cgi-bin/v2html-cgi</pre>
+<pre>
+  cd /home/web/v2html/example/ex1
+  v2html -c /cgi-bin/v2html-cgi /v2html/example/ex1 ../verilog/*.v</pre>
+<p>Note that <strong>v2html</strong> can't check the parameters to <strong>-c</strong> while
+converting the files. You'll have to do it yourself by viewing the
+hierarchy in your web browser and clicking on <strong>[Hide&nbsp;All]</strong> at the
+top of the hierarchy. Make sure you view the file using the web server
+(use <em><a href="http://server/v2html/example/ex1/hierarchy.html">http://server/v2html/example/ex1/hierarchy.html</a></em> rather than
+<em>file:/home/web/v2html/example/ex1/hierarchy.html</em>).</p>
+<p>Depending on your webserver you may also need to use the -css to
+specify the full URL to your cascading stylesheet eg:</p>
+<pre>
+ v2html -c /cgi-bin/v2html-cgi /v2html/examples/millennium_clock/hier_cgi
+  -css <a href="http://www.burbleland.com/v2html/examples/millennium_clock/hier_cgi/v2html.css">http://www.burbleland.com/v2html/examples/millennium_clock/hier_cgi/v2html.css</a>
+  *.v</pre>
+<p>If you get a message like this when you click on <strong>[Hide&nbsp;All]</strong>:</p>
+<pre>
+  Bad script request -- neither '/opt/CERNhttpd/cgi-bin/v2html-cg' 
+        nor '/opt/CERNhttpd/cgi-bin/v2html-cg.pp' is executable</pre>
+<p>Then either there is either a problem with the installation of the cgi
+script or you have incorrectly specified the first parameter to <strong>-c</strong>.</p>
+<p>If you get a message like this:</p>
+<pre>
+  v2html error.</pre>
+<p>then you have probably got the second parameter to <strong>-c</strong> wrong.</p>
+</dd>
+<dt><strong><a name="item__2dk_key_string"><strong>-k</strong>&nbsp;key_string</a></strong></dt>
+
+<dd>
+<p>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 <strong>v2html</strong>). To get
+round this problem you can use <strong>-k</strong> and always have the same
+key string. The key can be any string of digits and letters.</p>
+</dd>
+<dt><strong><a name="item__2dnjshier"><strong>-njshier</strong></a></strong></dt>
+
+<dd>
+<p>Deactivate Javascript features that allow the user to hide and
+collapse regions of the hierarchy.</p>
+</dd>
+<dt><strong><a name="item__2dncookies"><strong>-ncookies</strong></a></strong></dt>
+
+<dd>
+<p>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 <strong>-ncookies</strong> option
+to turn them off.</p>
+</dd>
+<dt><strong><a name="item__2dnsigpopup"><strong>-nsigpopup</strong></a></strong></dt>
+
+<dd>
+<p>Turn off the generation of javascript that does the signal popup window.
+Specifying this option also turns off ``Quick Search''.</p>
+</dd>
+<dt><strong><a name="item__2dtab_value"><strong>-tab</strong>&nbsp;value</a></strong></dt>
+
+<dd>
+<p>Expand tabs to the specified value.</p>
+</dd>
+<dt><strong><a name="item__2ddebug"><strong>-debug</strong></a></strong></dt>
+
+<dd>
+<p>Turn on lots of debugging information.</p>
+</dd>
+</dl>
+<p>
+</p>
+<hr />
+<h1><a name="author">AUTHOR</a></h1>
+<p>Costas Calamvokis &lt;<em><a href="mailto:v2html730@burbleland.com">v2html730@burbleland.com</a></em>&gt;.</p>
+<p>
+</p>
+<hr />
+<h1><a name="examples">EXAMPLES</a></h1>
+<p>Here is an example where <strong>v2html</strong> is run in the directory containing
+the verilog files (note the <strong>-o</strong> option):</p>
+<pre>
+  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</pre>
+<p>As the verilog files don't have absolute paths and we aren't running
+in the destination directory can't use <strong>-s</strong> (link to source) as the
+links <strong>v2html</strong> will create wouldn't allow the web server to find the
+files.</p>
+<p>Here is an example where <strong>v2html</strong> is run in the directory where
+we want the html files (no <strong>-o</strong> option):</p>
+<pre>
+  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</pre>
+<p>Here we can use the <strong>-s</strong> option because we are running the the destination
+directory, so the links <strong>v2html</strong> creates to the source will work
+(providing the web server is allowed to server files from
+/users/jb/verilog_files).</p>
+<p>
+</p>
+<hr />
+<h1><a name="diagnostics">DIAGNOSTICS</a></h1>
+<p>By default <strong>v2html</strong> 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 <strong>v2html</strong> produces, so if
+you have a problem first try <strong>-q</strong> (quiet) to see if there are any warnings
+you missed in the deluge of messages.</p>
+<p>Most of the Error messages concern failures to open files, I guess these
+will be caused by bad permissions, or you pointing <strong>v2html</strong> at files
+or directories that don't exist.</p>
+<p>The errors that say things like:</p>
+<pre>
+   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.</pre>
+<p>Most of the warnings concern things that <strong>v2html</strong> 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
+<strong>-f</strong> option something like this:</p>
+<pre>
+  ls /path/*.v | grep -v old_module_file.v &gt; src_files
+  v2html -f src_files</pre>
+<p>Generally <strong>v2html</strong> 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.</p>
+
+</body>
+
+</html>

tools/htmlgen

+#!/bin/bash

tools/socpull

+#!/bin/bash
+
+# Update all Submodules to latest commit
+cd $DESIGN_ROOT; git submodule foreach --recursive git pull
+# for d in $DESIGN_ROOT/* ; do
+#     if [ -f "$d/.git" ]; then
+#         echo "Git Pulling $d"
+#         cd $d; git pull; cd ..
+#     fi
+# done
\ No newline at end of file

tools/socsim

+#-----------------------------------------------------------------------------
+# SoC Labs socsim script to run required simulation
+# A joint work commissioned on behalf of SoC Labs, under Arm Academic Access license.
+#
+# Contributors
+#
+# David Mapstone (d.a.mapstone@soton.ac.uk)
+#
+# Copyright 2023, SoC Labs (www.soclabs.org)
+#-----------------------------------------------------------------------------
+
+#!/usr/bin/env bash
+
+# Check arguments passed to SoCSim
+if [ $# -eq 0 ]
+  then
+    echo "No arguments supplied"
+else 
+
+    # If clean command passed in clean a specific directory or all
+    if [ ${1} == "clean" ]; then
+        if [ $# -eq 1 ];  then
+            echo "No clean arguments supplied"
+        else
+            if [ ${2} == "all" ]; then
+                # Clean all simualation directories
+                echo "Cleaning all Project Simulation Directories"
+                rm -rf $PROJECT_DIR/simulate/sim
+                mkdir -p $PROJECT_DIR/simulate/sim
+            else
+                # Remove specific simulaiton directory
+                SIM_DIR=$PROJECT_DIR/simulate/sim/${2}
+                if [ -d "$SIM_DIR" ]; then
+                    rm -rf $SIM_DIR
+                else 
+                    echo "Simulation Directory '${2}' doesn't exist"
+                fi
+            fi
+        fi
+    fi
+
+    # Find a simulation script in the SoCSim environments of all subrepos
+    simscript=$(find ${SOCSIM_PATH//:/\ } -name "${1}.sh")
+
+    # Run Script if Found
+    $simscript $@
+fi
\ No newline at end of file