File: README.pod

package info (click to toggle)
verilator 4.010-1
  • links: PTS, VCS
  • area: main
  • in suites: sid
  • size: 24,724 kB
  • sloc: cpp: 71,936; perl: 11,784; ansic: 8,379; yacc: 2,826; lex: 1,661; makefile: 668; sh: 175
file content (211 lines) | stat: -rw-r--r-- 7,139 bytes parent folder | download | duplicates (3)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
# DESCRIPTION: DOCUMENT source run through perl to produce README file
# Use 'make README' to produce the output file

=pod

=head1 NAME

This is the Verilator package README file.

=head1 DISTRIBUTION

http://www.veripool.org/verilator

This package is Copyright 2003-2019 by Wilson Snyder.  (Report bugs to
L<http://www.veripool.org/>.)

Verilator is free software; you can redistribute it and/or modify it under
the terms of either the GNU Lesser General Public License Version 3 or the
Perl Artistic License Version 2.0.  (See the documentation for more
details.)

This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
more details.

=head1 DESCRIPTION

Verilator converts synthesizable (generally not behavioral) Verilog code
into C++ or SystemC code.  It is not a complete simulator, just a
translator.

Verilator is invoked with parameters similar to GCC or Synopsys's VCS.  It
reads the specified Verilog code, lints it, and optionally adds coverage
code.  For C++ format, it outputs .cpp and .h files.  For SystemC format,
it outputs .cpp and .h files using the standard SystemC headers.

The resulting files are then compiled with C++.  The user writes a little
C++ wrapper file, which instantiates the top level module.  This is
compiled in C++, and linked with the Verilated files.

The resulting executable will perform the actual simulation.

=head1 SUPPORTED SYSTEMS

Verilator is developed and has primary testing on Ubuntu.  Versions have
also built on Redhat Linux, Macs OS-X, HPUX and Solaris.  It should run
with minor porting on any Linix-ish platform.  Verilator also works on
Windows under Cygwin, and Windows under MinGW (gcc -mno-cygwin).  Verilated
output (not Verilator itself) compiles under MSVC++ 2008 and newer.

=head1 INSTALLATION

For more details see
L<http://www.veripool.org/projects/verilator/wiki/Installing>.

If you will be modifying Verilator, you should use the "git" method as it
will let you track changes.

=over 4

=item

The latest version is available at L<http://www.veripool.org/verilator>.

Download the latest package from that site, and decompress.

    tar xvzf verilator_version.tgz

=item

If you will be using SystemC (vs straight C++ output), download SystemC
from L<http://www.systemc.org>.  Follow their installation instructions.
You will need to set SYSTEMC_INCLUDE to point to the include directory with
systemc.h in it, and SYSTEMC_LIBDIR to points to the directory with
libsystemc.a in it.  (Older installations may set SYSTEMC and SYSTEMC_ARCH
instead.)

=item

To use Verilator you will need the C<perl>, C<make> (or C<gmake>), and
C<g++> (or C<clang>) packages.

To use Verilator FST tracing you will need the C<gtkwave> and C<libgz> (on
Ubuntu C<zlibc> C<zlib1g> C<zlib1g-dev>) packages installed.

To compile Verilator in addition to the above you need the C<flex>,
C<bison> and C<texi2html> packages installed.

=item

C<cd> to the Verilator directory containing this README.

=item

You now have to decide how you're going to eventually install the kit.

Note Verilator builds the current value of VERILATOR_ROOT, SYSTEMC_INCLUDE,
and SYSTEMC_LIBDIR as defaults into the executable, so try to have them
correct before configuring.

=over 4

=item 1.

Our personal favorite is to always run Verilator from the kit directory.
This allows the easiest experimentation and upgrading.  It's also how most
EDA tools operate; to run you point to the tarball, no install is needed.

    export VERILATOR_ROOT=`pwd`   # if your shell is bash
    setenv VERILATOR_ROOT `pwd`   # if your shell is csh
    ./configure

=item 2.

To install globally onto a "cad" disk with multiple versions of every tool,
and add it to path using Modules/modulecmd:

    unset VERILATOR_ROOT      # if your shell is bash
    unsetenv VERILATOR_ROOT   # if your shell is csh
    # For the tarball, use the version number instead of git describe
    ./configure --prefix /CAD_DISK/verilator/`git describe | sed "s/verilator_//"`

    After installing you'll want a module file like the following:

    set install_root /CAD_DISK/verilator/{version-number-used-above}
    unsetenv VERILATOR_ROOT
    prepend-path PATH $install_root/bin
    prepend-path MANPATH $install_root/man
    prepend-path PKG_CONFIG_PATH $install_root/share/pkgconfig

=item 3.

The next option is to install it globally, using the normal system paths:

    unset VERILATOR_ROOT      # if your shell is bash
    unsetenv VERILATOR_ROOT   # if your shell is csh
    ./configure

=item 4.

Alternatively you can configure a prefix that install will populate, as
most GNU tools support:

    unset VERILATOR_ROOT      # if your shell is bash
    unsetenv VERILATOR_ROOT   # if your shell is csh
    ./configure --prefix /opt/verilator-VERSION

Then after installing you will need to add /opt/verilator-VERSION/bin to
PATH.

=back

=item

Type C<make> to compile Verilator.

Type C<make test> to check the compilation.

Configure with C<--enable-longtests> for more complete developer tests.
Additional packages may be required for these tests.

You may get a error about a typedef conflict for uint32_t.  Edit
verilated.h to change the typedef to work, probably to @samp{typedef
unsigned long uint32_t;}.

=item

If you used the VERILATOR_ROOT scheme you're done.  Programs should set the
environment variable VERILATOR_ROOT to point to this distribution, then
execute $VERILATOR_ROOT/bin/verilator, which will find the path to all
needed files.

If you used the prefix scheme, now do a C<make install>.  To run verilator,
have the verilator binary directory in your PATH (this should already be
true if using the default configure), and make sure VERILATOR_ROOT is not
set.

You may now wish to consult the examples directory. Type C<make> inside any
example directory to run the example.

=back

=head1 USAGE DOCUMENTATION

Detailed documentation and the man page can be seen by running:

    bin/verilator --help

or reading verilator.txt in the same directory as this README.

=head1 DIRECTORY STRUCTURE

The directories in the kit after de-taring are as follows:

    bin/verilator               => Compiler Wrapper invoked to Verilate code
    include/                    => Files that should be in your -I compiler path
    include/verilated*.cpp      => Global routines to link into your simulator
    include/verilated*.h        => Global headers
    include/verilated.v         => Stub defines for linting
    include/verilated.mk        => Common makefile
    src/                        => Translator source code
    examples/hello_world_c      => Example simple Verilog->C++ conversion
    examples/hello_world_sc     => Example simple Verilog->SystemC conversion
    examples/tracing_c          => Example Verilog->C++ with tracing
    examples/tracing_sc         => Example Verilog->SystemC with tracing
    test_regress                => Internal tests

=head1 LIMITATIONS

See verilator.txt (or execute C<bin/verilator --help>) for limitations.