1 |
5 |
julius |
\documentclass[a4paper]{article} \usepackage[dvips]{graphicx}
|
2 |
|
|
\usepackage[margin=2cm,nohead]{geometry} \usepackage{pslatex}
|
3 |
|
|
\usepackage{listings}
|
4 |
|
|
\setlength{\parindent}{0pt} \setlength{\parskip}{10pt}
|
5 |
|
|
\renewcommand{\familydefault}{\sfdefault}
|
6 |
|
|
\begin{document}
|
7 |
|
|
\author{Michael Cowell} \title{Veristruct: An IEEE1364.1995 (Verilog
|
8 |
|
|
1995) Preprocessor}
|
9 |
|
|
\maketitle{}
|
10 |
|
|
% \tableofcontents{}
|
11 |
|
|
% \pagebreak{}
|
12 |
|
|
\section{Overview}
|
13 |
|
|
\label{sec:overview}
|
14 |
|
|
Veristruct is an an IEEE1364.1995 preprocessor that adds some C-style
|
15 |
|
|
struct support to the Verilog language. It takes as input Veristruct
|
16 |
|
|
files (with a \texttt{.vs} extension) and struct definition files
|
17 |
|
|
(with a \texttt{.struct} extension). It outputs standard Verilog files
|
18 |
|
|
(with a \texttt{.v} extension). Veristruct files are, for the most
|
19 |
|
|
part, standard Verilog files---but, as well as the normal
|
20 |
|
|
\texttt{nets} and \texttt{regs}, bundled, hierarchical variables can
|
21 |
|
|
be declared and used.
|
22 |
|
|
|
23 |
|
|
Veristruct can process one veristruct file per invocation (which may
|
24 |
|
|
include many \texttt{.struct} struct definition files).
|
25 |
|
|
|
26 |
|
|
Veristruct is written in object oriented Perl. Please feel free to fix
|
27 |
|
|
any bugs you find!\footnote{That includes those in this
|
28 |
|
|
documentation.}
|
29 |
|
|
|
30 |
|
|
\section{Installation}
|
31 |
|
|
\label{sec:installation}
|
32 |
|
|
First you will have to get Veristruct. A tarball of the latest release
|
33 |
|
|
should be available at the Rachael SPARC
|
34 |
|
|
website\footnote{\texttt{https://www.rachaelsparc.org}}.
|
35 |
|
|
Alternatively, you can check out the source directly with a command
|
36 |
|
|
like:
|
37 |
|
|
$$\hbox{\texttt{svn co
|
38 |
|
|
https://www.rachaelsparc.org/repository/projects/tools/veristruct/}}$$
|
39 |
|
|
Note that code in SVN is not guaranteed to produce correct output or
|
40 |
|
|
even run, but you will probably get more features than in the release
|
41 |
|
|
tarball.
|
42 |
|
|
|
43 |
|
|
Next, you need to add the Veristruct classes to your Perl
|
44 |
|
|
distribution. One day I might put Veristruct in CPAN and this process
|
45 |
|
|
will be automated, but until then you'll need to do things
|
46 |
|
|
manually. First work out where you want to place the classes. They
|
47 |
|
|
need to be in your Perl include path. You can either add the folder
|
48 |
|
|
that you've got Veristruct in to your Perl include path---or find out
|
49 |
|
|
what's in your \texttt{@INC} (run something like \texttt{perl -e
|
50 |
|
|
'print join(", ",@INC);'}) and copy the \texttt{Verilog} folder from
|
51 |
|
|
the Veristruct root into one of those directories.
|
52 |
|
|
|
53 |
|
|
Finally, you need to put the \texttt{veristruct.pl} script (the
|
54 |
|
|
application) somewhere in your shell path. Once again you can either
|
55 |
|
|
change your shell's \texttt{PATH} variable to point to your veristruct
|
56 |
|
|
folder, or copy \texttt{veristruct.pl} to \texttt{/usr/local/bin} or
|
57 |
|
|
something. If you're copying it, you might want to strip \texttt{.pl}
|
58 |
|
|
off of the name (to have a nicer looking command).
|
59 |
|
|
|
60 |
|
|
\section{Command-line Options}
|
61 |
|
|
\label{sec:options}
|
62 |
|
|
The following table describes each of the Veristruct application's
|
63 |
|
|
command line arguments:
|
64 |
|
|
|
65 |
|
|
\begin{center}
|
66 |
|
|
\begin{tabular}{|l|p{10cm}|}
|
67 |
|
|
\hline \textbf{Argument} & \textbf{Action} \\
|
68 |
|
|
\hline \texttt{--help}, \texttt{-h} & Prints usage information. \\
|
69 |
|
|
\hline \texttt{--debug}, \texttt{-d} & Prints debugging information
|
70 |
|
|
while parsing the input files. This is useful if (for instance) Veristruct
|
71 |
|
|
fails to parse a syntactically valid file, and you are interested in what
|
72 |
|
|
mistake it made. Note: this option is intended for developers.\\
|
73 |
|
|
\hline \texttt{--write}, \texttt{-w} & By default Veristruct will not overwrite
|
74 |
|
|
an existing file with the same name as the output file. This options causes
|
75 |
|
|
it to do so.\\
|
76 |
|
|
\hline \texttt{--infile=file}, \texttt{-i file} & This compulsory argument
|
77 |
|
|
should be used to specify the input \texttt{.vs} file. Note: the \texttt{.vs}
|
78 |
|
|
extension is not compulsory, but is recommended for clarity.\\
|
79 |
|
|
\hline \texttt{--outfilef=file}, \texttt{-o file} & This compulsory argument
|
80 |
|
|
should be used to specify the output \texttt{.v} file. Note: the \texttt{.v}
|
81 |
|
|
extension is not compulsory, but is recommended for clarity.\\
|
82 |
|
|
\hline \texttt{--libpath=path}, \texttt{-L path} & This argument (which can
|
83 |
|
|
be used multiple times) should be used to specify the search path
|
84 |
|
|
used when trying to locate \texttt{.struct} files referenced in the input.
|
85 |
|
|
It can be either a path, or a comma separated list of paths.\\
|
86 |
|
|
\hline
|
87 |
|
|
\end{tabular}
|
88 |
|
|
\end{center}
|
89 |
|
|
|
90 |
|
|
The command line arguments are not case sensitive, and it is
|
91 |
|
|
sufficient to specify just enough of the command as is unique
|
92 |
|
|
(although this is not recommended, because more commands may be added
|
93 |
|
|
in the future).
|
94 |
|
|
|
95 |
|
|
\section{Input \& Output Files}
|
96 |
|
|
\label{sec:files}
|
97 |
|
|
Veristruct takes two sorts of input files, \texttt{.vs} (or
|
98 |
|
|
Veristruct) files and \texttt{.struct} (or struct definition)
|
99 |
|
|
files. Following is a description of the two.
|
100 |
|
|
|
101 |
|
|
\subsection{Veristruct files --- .vs}
|
102 |
|
|
\label{sec:vs_files}
|
103 |
|
|
Veristruct files are, for the most part, standard IEEE1364.1995
|
104 |
|
|
(Verilog) files. The following extra syntax is allowed:
|
105 |
|
|
|
106 |
|
|
\begin{itemize}
|
107 |
|
|
\item \textbf{\texttt{`sinclude}}: This extra pre-processor directive
|
108 |
|
|
can be used to instruct Veristruct to read in a struct definition
|
109 |
|
|
file. The file to be read in should follow immediately after the
|
110 |
|
|
token (with possible whitespace, other than line breaks). This
|
111 |
|
|
directive may be used as many times as desired, to read in any
|
112 |
|
|
number of \texttt{.struct} files. Note: the directive should not be
|
113 |
|
|
used inside modules, and surrounding \texttt{`ifdef} directives will
|
114 |
|
|
\textbf{not} be honoured.
|
115 |
|
|
\item \textbf{\texttt{reg}, \texttt{wire} and port struct
|
116 |
|
|
declarations}: If any of these Verilog declarations are followed
|
117 |
|
|
by the name of a defined struct, the next word will interpreted as
|
118 |
|
|
an instance of that struct. All uses of that variable, throughout
|
119 |
|
|
the rest of the module (and, in the case of module port lists,
|
120 |
|
|
earlier in the module as well) will be recognised by Veristruct as
|
121 |
|
|
struct references, and will be re-written in the output file. Arrays
|
122 |
|
|
of structs can be declared in the same way that normal vectors are
|
123 |
|
|
declared (the range should precede the struct name).
|
124 |
|
|
\item \textbf{Struct element references}: Any expression token (or
|
125 |
|
|
l-value) in the input \texttt{.vs} file of the form
|
126 |
|
|
\texttt{inst\_name.element} (of arbitrary element depth, and with
|
127 |
|
|
optional ranges) are recognised and processed by Veristruct. The
|
128 |
|
|
semantics are the same as in C. Note that slices of struct elements,
|
129 |
|
|
where the struct is declared as an array, are not allowed as
|
130 |
|
|
l-values.
|
131 |
|
|
\end{itemize}
|
132 |
|
|
|
133 |
|
|
Whole structs can only be used as l-values if the expression to the
|
134 |
|
|
right is also a whole struct, of the same type, and nothing else.
|
135 |
|
|
|
136 |
|
|
Wire declarations can include assignments, as usual.
|
137 |
|
|
|
138 |
|
|
\subsection{Struct declaration files --- .struct}
|
139 |
|
|
\label{sec:struct_files}
|
140 |
|
|
The EBNF for struct declaration files is:
|
141 |
|
|
|
142 |
|
|
\texttt{struct\_file := struct\_block \\
|
143 |
|
|
struct\_block := struct\_defn \{ struct\_block \} \\
|
144 |
|
|
struct\_defn := \textbf{struct} struct\_name
|
145 |
|
|
\textbf{\{} elem\_block \textbf{\};} \\
|
146 |
|
|
elem\_block := elem \textbf{;} \{ elem\_block \} \\
|
147 |
|
|
elem := wire\_element | signed\_element | struct\_element \\
|
148 |
|
|
wire\_element := \textbf{wire}((elem\_name \textbf{[} max \textbf{:}
|
149 |
|
|
min \textbf{]})
|
150 |
|
|
| (elem\_name) | (elem\_name \textbf{`} define\_string)) \\
|
151 |
|
|
signed\_element := \textbf{signed}((elem\_name \textbf{[} max
|
152 |
|
|
\textbf{:} min \textbf{]})
|
153 |
|
|
| (elem\_name) | (elem\_name \textbf{`} define\_string)) \\
|
154 |
|
|
struct\_element := struct\_name elem\_name }
|
155 |
|
|
|
156 |
|
|
The atomic tokens are:
|
157 |
|
|
\begin{itemize}
|
158 |
|
|
\item \texttt{struct\_name}: A valid Verilog variable name. Trying to
|
159 |
|
|
use ``wire'' (which is illegal anyway) is doubly bad. Double
|
160 |
|
|
underscores are not allowed (this is not actually enforced, but is a
|
161 |
|
|
very bad idea).
|
162 |
|
|
\item \texttt{elem\_name}: Similar to above.
|
163 |
|
|
\item \texttt{max}: An integer greater than \texttt{min}.
|
164 |
|
|
\item \texttt{min}: An integer less than \texttt{max}.
|
165 |
|
|
\item \texttt{define\_string}: Any string without whitespace.
|
166 |
|
|
\end{itemize}
|
167 |
|
|
|
168 |
|
|
The semantics are similar to C. Note the main syntactical difference
|
169 |
|
|
is that a name does not need to be specified twice (as in C, after the
|
170 |
|
|
closing brace). C-style comments are allowed wherever (they are
|
171 |
|
|
stripped out prior to parsing). Line comments count as a line break,
|
172 |
|
|
block comments count as nothing.
|
173 |
|
|
|
174 |
|
|
\subsection{IEEE1364.1995 (Verilog) file --- .v}
|
175 |
|
|
\label{sec:v_files}
|
176 |
|
|
Veristruct outputs IEEE1364.1995 compliant \texttt{.v} files. Structs
|
177 |
|
|
declarations are expanded into their elements, and struct element
|
178 |
|
|
references are expanded into formally compliant variable names. Double
|
179 |
|
|
underscores are used to indicate depth.
|
180 |
|
|
|
181 |
|
|
When entire structs are referenced (instance names are used without
|
182 |
|
|
element references) a guess is made as to what is desired. In
|
183 |
|
|
sensitivity lists and module port lists, the name is exploded into its
|
184 |
|
|
constituent elements (and appropriate separator tokens are added). In
|
185 |
|
|
module instance port lists, it is assumed that the module being
|
186 |
|
|
instantiated has multiple ports with the instance name as the base
|
187 |
|
|
(that will be the case if the module was written in Veristruct).
|
188 |
|
|
|
189 |
|
|
\section{Limitations}
|
190 |
|
|
\label{sec:limitations}
|
191 |
|
|
The following limitations currently exist within Veristruct:
|
192 |
|
|
\begin{itemize}
|
193 |
|
|
\item \textbf{Namespace collisions not detected}: Veristruct currently
|
194 |
|
|
does no checking for namespace collisions. If you don't use double
|
195 |
|
|
underscores in your variables names, though, you should be fine.
|
196 |
|
|
\item \textbf{Limited lvalue support}: Slices of some struct elements
|
197 |
|
|
(and whole structs, in most contexts) cannot be lvalues. Veristruct
|
198 |
|
|
will return an error when it encounters these.
|
199 |
|
|
\item \textbf{Structs can only be declared in \texttt{.struct} files}:
|
200 |
|
|
This is a deliberate limitation. It avoids polluting the Verilog
|
201 |
|
|
syntax even more.
|
202 |
|
|
\item \textbf{\texttt{`ifdef}s ignored}: Because Veristruct is not
|
203 |
|
|
designed to replace the normal Verilog preprocessor, it does not do
|
204 |
|
|
its job. As such, you will need to ensure that do not rely on your
|
205 |
|
|
structs being conditionally included using normal pre-processor
|
206 |
|
|
directives. There are many ways around this. Ranges in structs can
|
207 |
|
|
be tick defined, and variable declarations can be surrounded in
|
208 |
|
|
\texttt{`ifdef}s, which will get honoured later.
|
209 |
|
|
\end{itemize}
|
210 |
|
|
|
211 |
|
|
\section{Changes}
|
212 |
|
|
\label{sec:changes}
|
213 |
|
|
\textbf{Changes since the 0.1 release}\footnote{References to issue
|
214 |
|
|
IDs refer to the Rachael SPARC Scarab bug tracking system. Go to
|
215 |
|
|
\texttt{https://www.rachaelsparc.org/scarab/issues} to see
|
216 |
|
|
details.}:
|
217 |
|
|
\begin{itemize}
|
218 |
|
|
\item Signed support added (as per the request made by luked in
|
219 |
|
|
RCHL10).
|
220 |
|
|
\item Bugfixes discussed in RCHL12.
|
221 |
|
|
\end{itemize}
|
222 |
|
|
|
223 |
|
|
\section{Examples}
|
224 |
|
|
\label{sec:examples}
|
225 |
|
|
\lstset{numbers=left, numberstyle=\tiny, stepnumber=1, numbersep=5pt,
|
226 |
|
|
basicstyle=\ttfamily, keywordstyle=\ttfamily,
|
227 |
|
|
identifierstyle=\ttfamily, commentstyle=\ttfamily,
|
228 |
|
|
stringstyle=\ttfamily, breaklines}
|
229 |
|
|
|
230 |
|
|
\subsection{Example .struct file}
|
231 |
|
|
\label{sec:ex_struct_file}
|
232 |
|
|
Here is an example .struct file:
|
233 |
|
|
|
234 |
|
|
\lstinputlisting{../test.struct}
|
235 |
|
|
|
236 |
|
|
\subsection{Example .vs file}
|
237 |
|
|
\label{sec:ex_vs_file}
|
238 |
|
|
And an example .vs file that uses those structs:
|
239 |
|
|
|
240 |
|
|
\lstinputlisting{../test.vs}
|
241 |
|
|
|
242 |
|
|
\subsection{Example .v file}
|
243 |
|
|
\label{sec:ex_v_file}
|
244 |
|
|
Finally, here the the .v file that Veristruct outputs:
|
245 |
|
|
|
246 |
|
|
\lstinputlisting{../test.v}
|
247 |
|
|
\end{document}
|