Subversion Repositories veristruct

\documentclass[a4paper]{article} \usepackage[dvips]{graphicx}

\usepackage[margin=2cm,nohead]{geometry} \usepackage{pslatex}

\usepackage{listings}

\setlength{\parindent}{0pt} \setlength{\parskip}{10pt}

\renewcommand{\familydefault}{\sfdefault}

\begin{document}

\author{Michael Cowell} \title{Veristruct: An IEEE1364.1995 (Verilog

  1995) Preprocessor}

\maketitle{}

% \tableofcontents{}

% \pagebreak{}

\section{Overview}

\label{sec:overview}

Veristruct is an an IEEE1364.1995 preprocessor that adds some C-style

struct support to the Verilog language. It takes as input Veristruct

files (with a \texttt{.vs} extension) and struct definition files

(with a \texttt{.struct} extension). It outputs standard Verilog files

(with a \texttt{.v} extension). Veristruct files are, for the most

part, standard Verilog files---but, as well as the normal

\texttt{nets} and \texttt{regs}, bundled, hierarchical variables can

be declared and used.

Veristruct can process one veristruct file per invocation (which may

include many \texttt{.struct} struct definition files).

Veristruct is written in object oriented Perl. Please feel free to fix

any bugs you find!\footnote{That includes those in this

  documentation.}

\section{Installation}

\label{sec:installation}

First you will have to get Veristruct. A tarball of the latest release

should be available at the Rachael SPARC

website\footnote{\texttt{https://www.rachaelsparc.org}}.

Alternatively, you can check out the source directly with a command

like:

$$\hbox{\texttt{svn co

    https://www.rachaelsparc.org/repository/projects/tools/veristruct/}}$$

Note that code in SVN is not guaranteed to produce correct output or

even run, but you will probably get more features than in the release

tarball.

Next, you need to add the Veristruct classes to your Perl

distribution.  One day I might put Veristruct in CPAN and this process

will be automated, but until then you'll need to do things

manually. First work out where you want to place the classes. They

need to be in your Perl include path. You can either add the folder

that you've got Veristruct in to your Perl include path---or find out

what's in your \texttt{@INC} (run something like \texttt{perl -e

  'print join(", ",@INC);'}) and copy the \texttt{Verilog} folder from

the Veristruct root into one of those directories.

Finally, you need to put the \texttt{veristruct.pl} script (the

application) somewhere in your shell path. Once again you can either

change your shell's \texttt{PATH} variable to point to your veristruct

folder, or copy \texttt{veristruct.pl} to \texttt{/usr/local/bin} or

something. If you're copying it, you might want to strip \texttt{.pl}

off of the name (to have a nicer looking command).

\section{Command-line Options}

\label{sec:options}

The following table describes each of the Veristruct application's

command line arguments:

\begin{center}

  \begin{tabular}{|l|p{10cm}|}

    \hline \textbf{Argument} & \textbf{Action} \\

    \hline \texttt{--help}, \texttt{-h} & Prints usage information. \\

    \hline \texttt{--debug}, \texttt{-d} & Prints debugging information

    while parsing the input files. This is useful if (for instance) Veristruct

    fails to parse a syntactically valid file, and you are interested in what

    mistake it made. Note: this option is intended for developers.\\

    \hline \texttt{--write}, \texttt{-w} & By default Veristruct will not overwrite

    an existing file with the same name as the output file. This options causes

    it to do so.\\

    \hline \texttt{--infile=file}, \texttt{-i file} & This compulsory argument

    should be used to specify the input \texttt{.vs} file. Note: the \texttt{.vs}

    extension is not compulsory, but is recommended for clarity.\\

    \hline \texttt{--outfilef=file}, \texttt{-o file} & This compulsory argument

    should be used to specify the output \texttt{.v} file. Note: the \texttt{.v}

    extension is not compulsory, but is recommended for clarity.\\

    \hline \texttt{--libpath=path}, \texttt{-L path} & This argument (which can

    be used multiple times) should be used to specify the search path

    used when trying to locate \texttt{.struct} files referenced in the input.

    It can be either a path, or a comma separated list of paths.\\

    \hline

  \end{tabular}

\end{center}

The command line arguments are not case sensitive, and it is

sufficient to specify just enough of the command as is unique

(although this is not recommended, because more commands may be added

in the future).

\section{Input \& Output Files}

\label{sec:files}

Veristruct takes two sorts of input files, \texttt{.vs} (or

Veristruct) files and \texttt{.struct} (or struct definition)

files. Following is a description of the two.

\subsection{Veristruct files --- .vs}

\label{sec:vs_files}

Veristruct files are, for the most part, standard IEEE1364.1995

(Verilog) files.  The following extra syntax is allowed:

\begin{itemize}

\item \textbf{\texttt{`sinclude}}: This extra pre-processor directive

  can be used to instruct Veristruct to read in a struct definition

  file. The file to be read in should follow immediately after the

  token (with possible whitespace, other than line breaks). This

  directive may be used as many times as desired, to read in any

  number of \texttt{.struct} files. Note: the directive should not be

  used inside modules, and surrounding \texttt{`ifdef} directives will

  \textbf{not} be honoured.

\item \textbf{\texttt{reg}, \texttt{wire} and port struct

    declarations}: If any of these Verilog declarations are followed

  by the name of a defined struct, the next word will interpreted as

  an instance of that struct. All uses of that variable, throughout

  the rest of the module (and, in the case of module port lists,

  earlier in the module as well) will be recognised by Veristruct as

  struct references, and will be re-written in the output file. Arrays

  of structs can be declared in the same way that normal vectors are

  declared (the range should precede the struct name).

\item \textbf{Struct element references}: Any expression token (or

  l-value) in the input \texttt{.vs} file of the form

  \texttt{inst\_name.element} (of arbitrary element depth, and with

  optional ranges) are recognised and processed by Veristruct. The

  semantics are the same as in C. Note that slices of struct elements,

  where the struct is declared as an array, are not allowed as

  l-values.

\end{itemize}

Whole structs can only be used as l-values if the expression to the

right is also a whole struct, of the same type, and nothing else.

Wire declarations can include assignments, as usual.

\subsection{Struct declaration files --- .struct}

\label{sec:struct_files}

The EBNF for struct declaration files is:

\texttt{struct\_file := struct\_block \\

  struct\_block := struct\_defn \{ struct\_block \} \\

  struct\_defn := \textbf{struct} struct\_name

  \textbf{\{} elem\_block \textbf{\};} \\

  elem\_block := elem \textbf{;} \{ elem\_block \} \\

  elem := wire\_element | signed\_element | struct\_element \\

  wire\_element := \textbf{wire}((elem\_name \textbf{[} max \textbf{:}

  min \textbf{]})

  | (elem\_name) | (elem\_name \textbf{`} define\_string)) \\

  signed\_element := \textbf{signed}((elem\_name \textbf{[} max

  \textbf{:} min \textbf{]})

  | (elem\_name) | (elem\_name \textbf{`} define\_string)) \\

  struct\_element := struct\_name elem\_name }

The atomic tokens are:

\begin{itemize}

\item \texttt{struct\_name}: A valid Verilog variable name. Trying to

  use ``wire'' (which is illegal anyway) is doubly bad. Double

  underscores are not allowed (this is not actually enforced, but is a

  very bad idea).

\item \texttt{elem\_name}: Similar to above.

\item \texttt{max}: An integer greater than \texttt{min}.

\item \texttt{min}: An integer less than \texttt{max}.

\item \texttt{define\_string}: Any string without whitespace.

\end{itemize}

The semantics are similar to C. Note the main syntactical difference

is that a name does not need to be specified twice (as in C, after the

closing brace). C-style comments are allowed wherever (they are

stripped out prior to parsing). Line comments count as a line break,

block comments count as nothing.

\subsection{IEEE1364.1995 (Verilog) file --- .v}

\label{sec:v_files}

Veristruct outputs IEEE1364.1995 compliant \texttt{.v} files. Structs

declarations are expanded into their elements, and struct element

references are expanded into formally compliant variable names. Double

underscores are used to indicate depth.

When entire structs are referenced (instance names are used without

element references) a guess is made as to what is desired. In

sensitivity lists and module port lists, the name is exploded into its

constituent elements (and appropriate separator tokens are added). In

module instance port lists, it is assumed that the module being

instantiated has multiple ports with the instance name as the base

(that will be the case if the module was written in Veristruct).

\section{Limitations}

\label{sec:limitations}

The following limitations currently exist within Veristruct:

\begin{itemize}

\item \textbf{Namespace collisions not detected}: Veristruct currently

  does no checking for namespace collisions. If you don't use double

  underscores in your variables names, though, you should be fine.

\item \textbf{Limited lvalue support}: Slices of some struct elements

  (and whole structs, in most contexts) cannot be lvalues. Veristruct

  will return an error when it encounters these.

\item \textbf{Structs can only be declared in \texttt{.struct} files}:

  This is a deliberate limitation. It avoids polluting the Verilog

  syntax even more.

\item \textbf{\texttt{`ifdef}s ignored}: Because Veristruct is not

  designed to replace the normal Verilog preprocessor, it does not do

  its job. As such, you will need to ensure that do not rely on your

  structs being conditionally included using normal pre-processor

  directives. There are many ways around this. Ranges in structs can

  be tick defined, and variable declarations can be surrounded in

  \texttt{`ifdef}s, which will get honoured later.

\end{itemize}

\section{Changes}

\label{sec:changes}

\textbf{Changes since the 0.1 release}\footnote{References to issue

  IDs refer to the Rachael SPARC Scarab bug tracking system. Go to

  \texttt{https://www.rachaelsparc.org/scarab/issues} to see

  details.}:

\begin{itemize}

\item Signed support added (as per the request made by luked in

  RCHL10).

\item Bugfixes discussed in RCHL12.

\end{itemize}

\section{Examples}

\label{sec:examples}

\lstset{numbers=left, numberstyle=\tiny, stepnumber=1, numbersep=5pt,

  basicstyle=\ttfamily, keywordstyle=\ttfamily,

  identifierstyle=\ttfamily, commentstyle=\ttfamily,

  stringstyle=\ttfamily, breaklines}

\subsection{Example .struct file}

\label{sec:ex_struct_file}

Here is an example .struct file:

\lstinputlisting{../test.struct}

\subsection{Example .vs file}

\label{sec:ex_vs_file}

And an example .vs file that uses those structs:

\lstinputlisting{../test.vs}

\subsection{Example .v file}

\label{sec:ex_v_file}

Finally, here the the .v file that Veristruct outputs:

\lstinputlisting{../test.v}

\end{document}