verilator/README.adoc

// Github doesn't render images unless absolute URL
:!toc:

ifdef::env-github[]
image:https://img.shields.io/badge/License-LGPL%20v3-blue.svg[license LGPLv3,link=https://www.gnu.org/licenses/lgpl-3.0]
image:https://img.shields.io/badge/License-Artistic%202.0-0298c3.svg[license Artistic-2.0,link=https://opensource.org/licenses/Artistic-2.0]
image:https://api.codacy.com/project/badge/Grade/48478c986f13400682ffe4a5e0939b3a[Code Quality,link=https://www.codacy.com/gh/verilator/verilator]
image:https://travis-ci.com/verilator/verilator.svg?branch=master[Build Status (Travis CI),link=https://travis-ci.com/verilator/verilator]
endif::[]

ifdef::env-github[]
:link_verilator_contributing: link:docs/CONTRIBUTING.adoc
:link_verilator_install: link:docs/install.adoc
endif::[]
ifndef::env-github[]
:link_verilator_contributing: https://github.com/verilator/verilator/blob/master/docs/CONTRIBUTING.adoc
:link_verilator_install: https://verilator.org/install
endif::[]
:link_verilator_commercial_support: https://verilator.org/verilator_commercial_support

== Welcome to Verilator

[cols="a,a",indent=0,frame="none"]
|===
^.^| *Welcome to Verilator, the fastest free Verilog HDL simulator.*
+++ <br/> +++ &bullet; Accepts synthesizable Verilog or SystemVerilog
+++ <br/> +++ &bullet; Performs lint code-quality checks
+++ <br/> +++ &bullet; Compiles into multithreaded {cpp}, SystemC, or (soon) {cpp}-under-Python
+++ <br/> +++ &bullet; Creates XML to front-end your own tools
<.^|image:https://www.veripool.org/img/verilator_256_200_min.png[Logo,256,200]

>.^|image:https://www.veripool.org/img/verilator_multithreaded_performance_bg-min.png[,388,178]
^.^| *Fast*
+++ <br/> +++ &bullet; Outperforms many commercial simulators
+++ <br/> +++ &bullet; Single- and multi-threaded output models

^.^| *Widely Used*
+++ <br/> +++ &bullet; Wide industry and academic deployment
+++ <br/> +++ &bullet; Out-of-the-box support from Arm, and RISC-V vendor IP
<.^|image:https://www.veripool.org/img/verilator_usage_400x200-min.png[,400,200]

>.^|image:https://www.veripool.org/img/verilator_community_400x125-min.png[,400,125]
^.^| *Community Driven & Openly Licensed*
+++ <br/> +++ &bullet; Guided by the https://chipsalliance.org/[CHIPS Alliance] and https://www.linuxfoundation.org/[Linux Foundation]
+++ <br/> +++ &bullet; Open, and free as in both speech and beer
+++ <br/> +++ &bullet; More simulation for your verification budget

^.^| *Commercial Support Available*
+++ <br/> +++ &bullet; Commercial support contracts
+++ <br/> +++ &bullet; Design support contracts
+++ <br/> +++ &bullet; Enhancement contracts
<.^|image:https://www.veripool.org/img/verilator_support_400x125-min.png[,400,125]

|===

== What Verilator Does

Verilator is invoked with parameters similar to GCC or Synopsys's VCS.  It
"Verilates" the specified synthesizable Verilog or SystemVerilog code by
reading it, performing lint checks, and optionally inserting assertion
checks and coverage-analysis points.  It outputs single- or multi-threaded
.cpp and .h files, the "Verilated" code.

The user writes a little {cpp}/SystemC wrapper file, which instantiates the
"Verilated" model of the user's top level module.  These {cpp}/SystemC
files are then compiled by a {cpp} compiler (gcc/clang/MSVC++).  The
resulting executable performs the design simulation.  Verilator also
supports linking its generated libraries, optionally encrypted, into other
simulators.

Verilator may not be the best choice if you are expecting a full featured
replacement for NC-Verilog, VCS or another commercial Verilog simulator, or
if you are looking for a behavioral Verilog simulator e.g. for a quick
class project (we recommend http://iverilog.icarus.com[Icarus Verilog] for
this.)  However, if you are looking for a path to migrate synthesizable
Verilog to {cpp} or SystemC, and your team is comfortable writing just a
touch of {cpp} code, Verilator is the tool for you.

== Performance

Verilator does not simply convert Verilog HDL to {cpp} or SystemC.  Rather
than only translate, Verilator compiles your code into a much faster
optimized and optionally thread-partitioned model, which is in turn wrapped
inside a {cpp}/SystemC/Python module.  The results are a compiled Verilog
model that executes even on a single-thread over 10x faster than standalone
SystemC, and on a single thread is about 100 times faster than interpreted
Verilog simulators such as http://iverilog.icarus.com[Icarus
Verilog]. Another 2-10x speedup might be gained from multithreading
(yielding 200-1000x total over interpreted simulators).

Verilator has typically similar or better performance versus the commercial
Verilog simulators (Carbon Design Systems Carbonator, Modelsim, Cadence
Incisive/NC-Verilog, Synopsys VCS, VTOC, and Pragmatic CVer/CVC). But,
Verilator is free, so you can spend on computes rather than licenses. Thus
Verilator gives you more cycles/dollar than anything else available.

For more information on how Verilator stacks up to some of the other
commercial and free Verilog simulators, see the
https://www.veripool.org/verilog_sim_benchmarks.html[Verilog Simulator
Benchmarks].  (If you benchmark Verilator, please see the notes in the
https://verilator.org/verilator_doc.pdf[Verilator manual (PDF)], and also
if possible post on the forums the results; there may be additional tweaks
possible.)

== Installation & Documentation

For more information:

* {link_verilator_install}[Verilator installation and package directory
  structure]

* https://verilator.org/verilator_doc.html[Verilator manual (HTML)],
or https://verilator.org/verilator_doc.pdf[Verilator manual (PDF)]

* https://verilator.org/forum[Verilator forum]

* https://verilator.org/issues[Verilator Issues]

== Support

Verilator is a community project, guided by the
https://chipsalliance.org/[CHIPS Alliance] under the
https://www.linuxfoundation.org/[Linux Foundation].

We appreciate and welcome your contributions in whatever form; please see
{link_verilator_contributing}[Contributing to Verilator].  Thanks to our
https://verilator.org/verilator_doc.html#CONTRIBUTORS[Contributors and
Sponsors].

Verilator also supports and encourages commercial support models and
organizations; please see {link_verilator_commercial_support}[Verilator
Commercial Support].

== Related Projects

* http://gtkwave.sourceforge.net/[GTKwave] - Waveform viewer for Verilator
traces.

* http://iverilog.icarus.com[Icarus Verilog] - Icarus is a full featured
interpreted Verilog simulator. If Verilator does not support your needs,
perhaps Icarus may.

== Open License

Verilator is Copyright 2003-2020 by Wilson Snyder.  (Report bugs to
https://verilator.org/issues[Verilator Issues].)

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.