Converted Asciidoc documentation into reStructuredText (RST) format.

This commit is contained in:
Wilson Snyder 2021-03-12 13:52:47 -05:00
parent b52b063c16
commit c99f01b7fe
24 changed files with 2099 additions and 1761 deletions

View File

@ -1,6 +1,6 @@
---
name: Bug report
about: Something isn't working as expected, and it isn't "Unsupported." (Note our contributor agreement at https://github.com/verilator/verilator/blob/master/docs/CONTRIBUTING.adoc)
about: Something isn't working as expected, and it isn't "Unsupported." (Note our contributor agreement at https://github.com/verilator/verilator/blob/master/docs/CONTRIBUTING.rst)
title: ''
labels: new
assignees: ''

View File

@ -1,6 +1,6 @@
---
name: Feature Request
about: Request something should be supported, or a new feature added. (Note our contributor agreement at https://github.com/verilator/verilator/blob/master/docs/CONTRIBUTING.adoc)
about: Request something should be supported, or a new feature added. (Note our contributor agreement at https://github.com/verilator/verilator/blob/master/docs/CONTRIBUTING.rst)
title: ''
labels: new
assignees: ''

View File

@ -1,6 +1,6 @@
---
name: Q and A, or Other
about: Ask a question, not related to a specific bug or feature request. (Note our contributor agreement at https://github.com/verilator/verilator/blob/master/docs/CONTRIBUTING.adoc)
about: Ask a question, not related to a specific bug or feature request. (Note our contributor agreement at https://github.com/verilator/verilator/blob/master/docs/CONTRIBUTING.rst)
title: ''
labels: new
assignees: ''

View File

@ -1 +1 @@
We appreciate your contributing to Verilator. If this is your first commit, please add your name to docs/CONTRIBUTORS, and read our contributing guidelines in docs/CONTRIBUTING.adoc.
We appreciate your contributing to Verilator. If this is your first commit, please add your name to docs/CONTRIBUTORS, and read our contributing guidelines in docs/CONTRIBUTING.rst.

View File

@ -1,5 +1,5 @@
# DESCRIPTION: Github actions config
# This name is key to badges in README.adoc, so we use the name build
# This name is key to badges in README.rst, so we use the name build
# SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
name: build

View File

@ -1,5 +1,4 @@
# DESCRIPTION: Github actions config
# This name is key to badges in README.adoc, so we use the name build
# SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
name: clang-format

View File

@ -10,6 +10,8 @@ The contributors that suggested a given feature are shown in []. Thanks!
** Add context->time() and context->timeInc() API calls, to set simulation time.
These now are recommended in place of the legacy sc_time_stamp().
**** Converted Asciidoc documentation into reStructuredText (RST) format.
**** --inhibit-sim is planned for deprecation, file a bug if this is still being used.
**** Fix range inheritance on port without data type (#2753). [Embedded Go]

View File

@ -124,7 +124,7 @@ DISTFILES_INC = $(INFOS) .gitignore \
Changes \
LICENSE \
MANIFEST.SKIP \
README.adoc \
README.rst \
verilator-config.cmake.in \
verilator-config-version.cmake.in \
bin/verilator \
@ -134,16 +134,16 @@ DISTFILES_INC = $(INFOS) .gitignore \
bin/verilator_includer \
bin/verilator_profcfunc \
docs/.gitignore \
docs/CONTRIBUTING.adoc \
docs/CONTRIBUTING.rst \
docs/CONTRIBUTORS \
docs/Makefile.in \
docs/TODO \
docs/doxygen-mainpage \
docs/doxygen.config \
docs/install.adoc \
docs/internals.adoc \
docs/install.rst \
docs/internals.rst \
docs/verilator_logo.png \
docs/xml.adoc \
docs/xml.rst \
install-sh configure *.pod \
include/*.[chv]* \
include/*.in \

View File

@ -1,154 +0,0 @@
// 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/fa78caa433c84a4ab9049c43e9debc6f[Code Quality,link=https://www.codacy.com/gh/verilator/verilator]
image:https://codecov.io/gh/verilator/verilator/branch/master/graph/badge.svg[Coverage,link=https://codecov.io/gh/verilator/verilator]
image:https://github.com/verilator/verilator/workflows/build/badge.svg[Build Status (GitHub),link=https://github.com/verilator/verilator/actions?query=workflow%3Abuild]
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",grid="rows"]
|===
^.^| *Welcome to Verilator, the fastest Verilog/SystemVerilog simulator.*
+++ <br/> +++ &bullet; Accepts synthesizable Verilog or SystemVerilog
+++ <br/> +++ &bullet; Performs lint code-quality checks
+++ <br/> +++ &bullet; Compiles into multithreaded {cpp}, or SystemC
+++ <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 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 SystemVerilog to
{cpp} or SystemC, or 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,
Verilator compiles your code into a much faster optimized and optionally
thread-partitioned model, which is in turn wrapped inside a
{cpp}/SystemC 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
closed-source Verilog simulators (Carbon Design Systems Carbonator,
Modelsim, Cadence Incisive/NC-Verilog, Synopsys VCS, VTOC, and Pragmatic
CVer/CVC). But, Verilator is open-sourced, so you can spend on computes
rather than licenses. Thus Verilator gives you the best cycles/dollar.
For more information on how Verilator stacks up to some of the other
closed-sourced and open-sourced 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://github.com/verilator/verilator-announce[Subscribe to verilator announcements]
* 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-2021 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.

160
README.rst Normal file
View File

@ -0,0 +1,160 @@
.. Github doesn't render images unless absolute URL
.. Do not know of a conditional tag, "only: github" nor "github display" works
.. image:: https://img.shields.io/badge/License-LGPL%20v3-blue.svg
:target: https://www.gnu.org/licenses/lgpl-3.0]
.. image:: https://img.shields.io/badge/License-Artistic%202.0-0298c3.svg
:target: https://opensource.org/licenses/Artistic-2.0
.. image:: https://api.codacy.com/project/badge/Grade/fa78caa433c84a4ab9049c43e9debc6f
:target: https://www.codacy.com/gh/verilator/verilator
.. image:: https://codecov.io/gh/verilator/verilator/branch/master/graph/badge.svg
:target: https://codecov.io/gh/verilator/verilator
.. image:: https://github.com/verilator/verilator/workflows/build/badge.svg
:target: https://github.com/verilator/verilator/actions?query=workflow%3Abuild
Welcome to Verilator
====================
.. list-table::
* - **Welcome to Verilator, the fastest Verilog/SystemVerilog simulator.**
* Accepts synthesizable Verilog or SystemVerilog
* Performs lint code-quality checks
* Compiles into multithreaded C++, or SystemC
* Creates XML to front-end your own tools
- |Logo|
* - |verilator multithreaded performance bg min|
- **Fast**
* Outperforms many commercial simulators
* Single- and multi-threaded output models
* - **Widely Used**
* Wide industry and academic deployment
* Out-of-the-box support from Arm, and RISC-V vendor IP
- |verilator usage 400x200 min|
* - |verilator community 400x125 min|
- **Community Driven & Openly Licensed**
* Guided by the `CHIPS Alliance`_ and `Linux Foundation`_
* Open, and free as in both speech and beer
* More simulation for your verification budget
* - **Commercial Support Available**
* Commercial support contracts
* Design support contracts
* Enhancement contracts
- |verilator support 400x125 min|
What Verilator Does
===================
Verilator is invoked with parameters similar to GCC or Synopsys's VCS. It
"Verilates" the specified 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 C++/SystemC wrapper file, which instantiates the
"Verilated" model of the user's top level module. These C++/SystemC files
are then compiled by a C++ 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 `Icarus Verilog`_ for this.) However, if you
are looking for a path to migrate SystemVerilog to C++ or SystemC, or your
team is comfortable writing just a touch of C++ code, Verilator is the tool
for you.
Performance
===========
Verilator does not simply convert Verilog HDL to C++ or SystemC. Rather,
Verilator compiles your code into a much faster optimized and optionally
thread-partitioned model, which is in turn wrapped inside a C++/SystemC
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 `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
closed-source Verilog simulators (Carbon Design Systems Carbonator,
Modelsim, Cadence Incisive/NC-Verilog, Synopsys VCS, VTOC, and Pragmatic
CVer/CVC). But, Verilator is open-sourced, so you can spend on computes
rather than licenses. Thus Verilator gives you the best cycles/dollar.
For more information on how Verilator stacks up to some of the other
closed-sourced and open-sourced Verilog simulators, see the `Verilog
Simulator Benchmarks
<https://www.veripool.org/verilog_sim_benchmarks.html>`_. (If you
benchmark Verilator, please see the notes in the `Verilator manual (PDF)
<https://verilator.org/verilator_doc.pdf>`_, and also if possible post on
the forums the results; there may be additional tweaks possible.)
Installation & Documentation
============================
For more information:
- `Verilator installation and package directory structure
<https://verilator.org/install>`_
- `Verilator manual (HTML) <https://verilator.org/verilator_doc.html>`_,
or `Verilator manual (PDF) <https://verilator.org/verilator_doc.pdf>`_
- `Subscribe to verilator announcements
<https://github.com/verilator/verilator-announce>`_
- `Verilator forum <https://verilator.org/forum>`_
- `Verilator issues <https://verilator.org/issues>`_
Support
=======
Verilator is a community project, guided by the `CHIPS Alliance`_ under the
`Linux Foundation`_.
We appreciate and welcome your contributions in whatever form; please see
`Contributing to Verilator
<https://github.com/verilator/verilator/blob/master/docs/CONTRIBUTING.rst>`_.
Thanks to our `Contributors and Sponsors
<https://verilator.org/verilator_doc.html#CONTRIBUTORS>`_.
Verilator also supports and encourages commercial support models and
organizations; please see `Verilator Commercial Support
<https://verilator.org/verilator_commercial_support>`_.
Related Projects
================
- `GTKwave <http://gtkwave.sourceforge.net/>`_ - Waveform viewer for
Verilator traces.
- `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-2021 by Wilson Snyder. (Report bugs to
`Verilator Issues <https://verilator.org/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.
.. _CHIPS Alliance: https://chipsalliance.org
.. _Icarus Verilog: http://iverilog.icarus.com
.. _Linux Foundation: https://www.linuxfoundation.org
.. |Logo| image:: https://www.veripool.org/img/verilator_256_200_min.png
.. |verilator multithreaded performance bg min| image:: https://www.veripool.org/img/verilator_multithreaded_performance_bg-min.png
.. |verilator usage 400x200 min| image:: https://www.veripool.org/img/verilator_usage_400x200-min.png
.. |verilator community 400x125 min| image:: https://www.veripool.org/img/verilator_community_400x125-min.png
.. |verilator support 400x125 min| image:: https://www.veripool.org/img/verilator_support_400x125-min.png

View File

@ -2127,7 +2127,7 @@ or all inputs go directly to always_ff statements, as is typical, then you
can change non-clock inputs on the negative edge of the input clock, which
will be faster as there will be fewer eval() calls.
For more information on evaluation, see docs/internals.adoc in the
For more information on evaluation, see docs/internals.rst in the
distribution.
@ -5766,7 +5766,7 @@ L<verilator_coverage>, L<verilator_gantt>, L<verilator_profcfunc>, L<make>,
L<verilator --help> which is the source for this document,
and docs/internals.adoc in the distribution.
and docs/internals.rst in the distribution.
=cut

View File

@ -1,49 +0,0 @@
= Verilator Docker Build Environment
This Verilator Build container is set up to compile and test a Verilator
build. It uses the following parameters:
* Source repository (default: https://github.com/verilator/verilator)
* Source revision (default: master)
* Compiler (GCC 9.3.0, clang 10.0.0, default: 9.3.0)
The container is published as `verilator/verilator-buildenv` on
https://hub.docker.com/repository/docker/verilator/verilator-buildenv[docker hub].
To run the basic build using the current Verilator master:
docker run -ti verilator/verilator-buildenv
To also run tests:
docker run -ti verilator/verilator-buildenv test
To change the compiler:
docker run -ti -e CC=clang-10 -e CXX=clang++-10 verilator/verilator-buildenv test
The tests that involve gdb are not working due to security restrictions.
To run those too:
....
docker run -ti -e CC=clang-10 -e CXX=clang++-10 --cap-add=SYS_PTRACE --security-opt seccomp=unconfined verilator/verilator-buildenv test
....
Rather then building using a remote git repository you may prefer to use a
working copy on the local filesystem. Mount the local working copy path as
a volume and use that in place of git. When doing this be careful to have
all changes committed to the local git area. To build the current HEAD from
top of a repository:
....
docker run -ti -v ${PWD}:/tmp/repo -e REPO=/tmp/repo -e REV=`git rev-parse --short HEAD` --cap-add=SYS_PTRACE --security-opt seccomp=unconfined verilator/verilator-buildenv test
....
== Rebuilding
To rebuild the Verilator-buildenv docker image, run:
docker build .
This will also build SystemC under all supported compiler variants to
reduce the SystemC testing time.

View File

@ -0,0 +1,64 @@
================================
Verilator Build Docker Container
================================
This Verilator Build Docker Container is set up to compile and test a
Verilator build. It uses the following parameters:
- Source repository (default: https://github.com/verilator/verilator)
- Source revision (default: master)
- Compiler (GCC 9.3.0, clang 10.0.0, default: 9.3.0)
The container is published as ``verilator/verilator-buildenv`` on `docker
hub
<https://hub.docker.com/repository/docker/verilator/verilator-buildenv>`__.
To run the basic build using the current Verilator master:
::
docker run -ti verilator/verilator-buildenv
To also run tests:
::
docker run -ti verilator/verilator-buildenv test
To change the compiler:
::
docker run -ti -e CC=clang-10 -e CXX=clang++-10 verilator/verilator-buildenv test
The tests that involve gdb are not working due to security restrictions.
To run those too:
::
docker run -ti -e CC=clang-10 -e CXX=clang++-10 --cap-add=SYS_PTRACE --security-opt seccomp=unconfined verilator/verilator-buildenv test
Rather then building using a remote git repository you may prefer to use a
working copy on the local filesystem. Mount the local working copy path as
a volume and use that in place of git. When doing this be careful to have
all changes committed to the local git area. To build the current HEAD from
top of a repository:
::
docker run -ti -v ${PWD}:/tmp/repo -e REPO=/tmp/repo -e REV=`git rev-parse --short HEAD` --cap-add=SYS_PTRACE --security-opt seccomp=unconfined verilator/verilator-buildenv test
Rebuilding
==========
To rebuild the Verilator-buildenv docker image, run:
::
docker build .
This will also build SystemC under all supported compiler variants to
reduce the SystemC testing time.

View File

@ -1,59 +0,0 @@
= Verilator Executable Docker Container
The Verilator Executable Docker Container allows you to run Verilator
easily as a docker image, e.g.:
docker run -ti verilator/verilator:latest --version
This will install the container, run the latest Verilator and print
Verilator's version.
Containers are automatically built for all released versions, so you may
easily compare results across versions, e.g.:
docker run -ti verilator/verilator:4.030 --version
Verilator needs to read and write files on the local system. To simplify
this process, use the `verilator-docker` convenience script. This script
takes the version number, and all remaining arguments are passed through to
Verilator. e.g.:
./verilator-docker 4.030 --version
or
./verilator-docker 4.030 --cc test.v
If you prefer not to use `verilator-docker` you must give the container
access to your files as a volume with appropriate user rights. For example
to Verilate test.v:
....
docker run -ti -v ${PWD}:/work --user $(id -u):$(id -g) verilator/verilator:latest --cc test.v
....
This method can only access files below the current directory. An
alternative is setup the volume `-workdir`.
You can also work in the container by setting the entrypoint
(don't forget to mount a volume if you want your work persistent):
docker run -ti --entrypoint /bin/bash verilator/verilator:latest
You can also use the container to build Verilator at a specific
commit:
docker build --build-arg SOURCE_COMMIT=<commit> .
== Internals
The Dockerfile builds Verilator and removes the tree when completed to
reduce the image size. The entrypoint is set as a wrapper script
(`verilator-wrap.sh`). That script 1. calls Verilator, and 2. copies the
Verilated runtime files to the `obj_dir` or the `-Mdir` respectively. This
allows the user to have the files to they may later build the C++ output
with the matching runtime files. The wrapper also patches the Verilated
Makefile accordingly.
There is also a hook defined that is run by docker hub via automated
builds.

74
ci/docker/run/README.rst Normal file
View File

@ -0,0 +1,74 @@
=====================================
Verilator Executable Docker Container
=====================================
The Verilator Executable Docker Container allows you to run Verilator
easily as a docker image, e.g.:
::
docker run -ti verilator/verilator:latest --version
This will install the container, run the latest Verilator and print
Verilator's version.
Containers are automatically built for all released versions, so you may
easily compare results across versions, e.g.:
::
docker run -ti verilator/verilator:4.030 --version
Verilator needs to read and write files on the local system. To simplify
this process, use the ``verilator-docker`` convenience script. This script
takes the version number, and all remaining arguments are passed through to
Verilator. e.g.:
::
./verilator-docker 4.030 --version
or
::
./verilator-docker 4.030 --cc test.v
If you prefer not to use ``verilator-docker`` you must give the container
access to your files as a volume with appropriate user rights. For example
to Verilate test.v:
::
docker run -ti -v ${PWD}:/work --user $(id -u):$(id -g) verilator/verilator:latest --cc test.v
This method can only access files below the current directory. An
alternative is setup the volume ``-workdir``.
You can also work in the container by setting the entrypoint (don't forget
to mount a volume if you want your work persistent):
::
docker run -ti --entrypoint /bin/bash verilator/verilator:latest
You can also use the container to build Verilator at a specific commit:
::
docker build --build-arg SOURCE_COMMIT=<commit> .
Internals
=========
The Dockerfile builds Verilator and removes the tree when completed to
reduce the image size. The entrypoint is set as a wrapper script
(``verilator-wrap.sh``). That script 1. calls Verilator, and 2. copies the
Verilated runtime files to the ``obj_dir`` or the ``-Mdir``
respectively. This allows the user to have the files to they may later
build the C++ output with the matching runtime files. The wrapper also
patches the Verilated Makefile accordingly.
There is also a hook defined that is run by docker hub via automated
builds.

View File

@ -1,82 +0,0 @@
= How to contribute to Verilator
Thanks for using Verilator! We welcome your contributions in whatever form.
This contributing document contains some suggestions that may make
contributions flow more efficiently.
==== Did you find a bug?
* Please **Ensure the bug was not already reported** by searching
https://verilator.org/issues[Verilator Issues].
* If you're unable to find an open issue addressing the problem,
https://verilator.org/issues/new[open a new Verilator issue].
** Be sure to include a **code sample** or an **executable test case**
demonstrating the bug and expected behavior that is not occurring.
** The ideal example works against other simulators, and is in the
test_regress/t test format, as described in
link:internals.adoc[docs/internals].
==== Did you write a patch that fixes a bug?
* Please https://verilator.org/issues/new[Open a new issue].
* You may attach a patch to the issue, or (preferred) may request a GitHub
pull request.
** Verilator uses GitHub Actions to provide continuous integration. You may
want to enable Actions on your GitHub branch to ensure your changes
keep the tests passing. See link:internals.adoc[docs/internals].
* Your source-code contributions must be certified as open source, under
the https://developercertificate.org/[Developer Certificate of
Origin]. On your first contribution, you must either:
** Have your patch include the addition of your name to
link:CONTRIBUTORS[docs/CONTRIBUTORS] (preferred).
** Use "git -s" as part of your commit. This adds a "signed-of-by"
attribute which will certify your contribution as described in the
https://github.com/wking/signed-off-by/blob/master/Documentation/SubmittingPatches[Signed-of-By
convention].
** Email, or post in an issue a statement that you certify your
contributions.
** In any of these cases your name will be added to
link:CONTRIBUTORS[docs/CONTRIBUTORS] and you are agreeing all future
contributions are also certified.
** We occasionally accept contributions where people do not want their name
published. Please email us; you must still privately certify your
contribution.
* Your test contributions are generally considered released into the
Creative Commons Public Domain (CC0), unless you request otherwise or put
a GNU/Artistic license on your file.
* Most important is we get your patch. If you'd like to clean up
indentation and related issues ahead of our feedback, that is
appreciated; please see the coding conventions in
link:internals.adoc[docs/internals].
==== Do you have questions?
* Please see FAQ section and rest of the
https://verilator.org/verilator_doc.html[Verilator manual],
or https://verilator.org/verilator_doc.pdf[Verilator manual (PDF)].
* Ask any question in the
https://verilator.org/forum[Verilator forum].
==== Code of Conduct
* Our contributors and participants pledge to make participation in our
project and our community a positive experience for everyone. We follow
the https://www.contributor-covenant.org/version/1/4/code-of-conduct.html[Contributor
Covenant version 1.4].
Thanks!

93
docs/CONTRIBUTING.rst Normal file
View File

@ -0,0 +1,93 @@
=========================
Contributing to Verilator
=========================
Thanks for using Verilator! We welcome your contributions in whatever form.
This contributing document contains some suggestions that may make
contributions flow more efficiently.
Did you find a bug?
===================
- Please **Ensure the bug was not already reported** by searching
`Verilator Issues <https://verilator.org/issues>`__.
- If you're unable to find an open issue addressing the problem, `open a
new Verilator issue <https://verilator.org/issues/new>`__.
- Be sure to include a **code sample** or an **executable test case**
demonstrating the bug and expected behavior that is not occurring.
- The ideal example works against other simulators, and is in the
test_regress/t test format, as described in `docs/internals
<internals.rst>`__.
Did you write a patch that fixes a bug?
=======================================
- Please `Open a new issue <https://verilator.org/issues/new>`__.
- You may attach a patch to the issue, or (preferred) may request a
GitHub pull request.
- Verilator uses GitHub Actions to provide continuous integration. You
may want to enable Actions on your GitHub branch to ensure your changes
keep the tests passing. See `docs/internals <internals.rst>`__.
- Your source-code contributions must be certified as open source,
under the `Developer Certificate of
Origin <https://developercertificate.org/>`__. On your first
contribution, you must either:
- Have your patch include the addition of your name to `docs/CONTRIBUTORS
<CONTRIBUTORS>`__ (preferred).
- Use "git -s" as part of your commit. This adds a "signed-of-by"
attribute which will certify your contribution as described in the
`Signed-of-By convention
<https://github.com/wking/signed-off-by/blob/master/Documentation/SubmittingPatches>`__.
- Email, or post in an issue a statement that you certify your
contributions.
- In any of these cases your name will be added to `docs/CONTRIBUTORS
<CONTRIBUTORS>`__ and you are agreeing all future contributions are
also certified.
- We occasionally accept contributions where people do not want their
name published. Please email us; you must still privately certify your
contribution.
- Your test contributions are generally considered released into the
Creative Commons Public Domain (CC0), unless you request otherwise or
put a GNU/Artistic license on your file.
- Most important is we get your patch. If youd like to clean up
indentation and related issues ahead of our feedback, that is
appreciated; please see the coding conventions in `docs/internals
<internals.rst>`__.
Do you have questions?
======================
- Please see FAQ section and rest of the `Verilator
manual <https://verilator.org/verilator_doc.html>`__, or `Verilator
manual (PDF) <https://verilator.org/verilator_doc.pdf>`__.
- Ask any question in the `Verilator forum
<https://verilator.org/forum>`__.
Code of Conduct
===============
- Our contributors and participants pledge to make participation in our
project and our community a positive experience for everyone. We follow
the `Contributor Covenant version 1.4
<https://www.contributor-covenant.org/version/1/4/code-of-conduct.html>`__.
Thanks!

View File

@ -19,8 +19,8 @@
#### Start of system configuration section. ####
ASCIIDOCTOR = asciidoctor
DOXYGEN = doxygen
RST2HTML = rst2html
#### End of system configuration section. ####
######################################################################
@ -30,8 +30,8 @@ DOXYGEN = doxygen
default:
@echo "error: make not supported here, run 'make docs' from Verilator top-level"
%.html: %.adoc
$(ASCIIDOCTOR) $< -n -o $@
%.html: %.rst
$(RST2HTML) $< $@
clean mostlyclean distclean maintainer-clean::
rm -f $(SCRIPTS) *.tmp

View File

@ -1,303 +0,0 @@
= Verilator Installation
:toc: right
// Github doesn't render unless absolute URL
image::https://www.veripool.org/img/verilator_256_200_min.png[Logo,256,200,role="right"]
== Introduction
This discusses how to install Verilator. For more general information
please see https://verilator.org[verilator.org].
== Quick-start
=== Install From a Package Manager
Using a distribution's package manager is the easiest way to get
started. (Note packages are unlikely to have the most recent version, so
Git, below, maybe a better alternative.) To install as a package:
apt-get install verilator
If this works, skip down to <<Running Verilator>>.
=== Docker
Verilator is available in pre-built Docker containers. See
https://github.com/verilator/verilator/blob/master/ci/docker/run/README.adoc
=== Git
Installing Verilator with Git provides the most flexibility.
For additional options and details see the additional sections below. In
brief:
// Also update README
....
# Prerequisites:
#sudo apt-get install git make autoconf g++ flex bison
#sudo apt-get install libfl2 # Ubuntu only (ignore if gives error)
#sudo apt-get install libfl-dev # Ubuntu only (ignore if gives error)
git clone https://github.com/verilator/verilator # Only first time
## Note the URL above is not a page you can see with a browser, it's for git only
# Every time you need to build:
unsetenv VERILATOR_ROOT # For csh; ignore error if on bash
unset VERILATOR_ROOT # For bash
cd verilator
git pull # Make sure git repository is up-to-date
git tag # See what versions exist
#git checkout master # Use development branch (e.g. recent bug fixes)
#git checkout stable # Use most recent stable release
#git checkout v{version} # Switch to specified release version
autoconf # Create ./configure script
./configure
make
sudo make install
# Now see "man verilator" or online verilator.pdf's for the example tutorials
....
If this works, skip down to <<Running Verilator>>.
== Detailed Build Instructions
This section describes details of the build process, and assumes you are
building from Git or a tarball. For using a pre-built binary for your
Linux distribution, see instead <<Install From a Package Manager>>.
=== OS Requirements
Verilator is developed and has primary testing on Ubuntu, with additional
testing on FreeBSD and Apple OS-X. Versions have also built on Redhat
Linux, HPUX and Solaris. It should run with minor porting on any
GNU/Linux-ish platform. Verilator also works on Windows under Cygwin, and
Windows under MinGW (gcc -mno-cygwin). Verilated output (not Verilator
itself) compiles under all the options above, plus MSVC++.
=== Install Prerequisites
To build or run Verilator you need these standard packages:
sudo apt-get install perl python3 make
sudo apt-get install g++ # Alternatively, clang
sudo apt-get install libgz # Non-Ubuntu (ignore if gives error)
sudo apt-get install libfl2 libfl-dev zlibc zlib1g zlib1g-dev # Ubuntu only (ignore if gives error)
To build or run the following are optional but should be installed for
good performance:
sudo apt-get install ccache # If present at build, needed for run
sudo apt-get install libgoogle-perftools-dev numactl perl-doc
To build Verilator you will need to install these packages; these do not
need to be present to run Verilator:
sudo apt-get install git autoconf flex bison
Those developing Verilator itself may also want these (see internals.adoc):
sudo apt-get install gdb asciidoctor graphviz cmake clang clang-format gprof lcov
cpan install Pod::Perldoc
cpan install Parallel::Forker
==== Install SystemC
If you will be using SystemC (vs straight C++ output), download
https://www.accellera.org/downloads/standards/systemc[SystemC].
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.)
==== Install GTKWave
To make use of Verilator FST tracing you will want
http://gtkwave.sourceforge.net/[GTKwave] installed, however this is not
required at Verilator build time.
=== Obtain Sources
You may use Git or a tarball for the sources. Git is the supported option.
(If using a historical build that uses a tarball, tarballs are obtained
from https://www.veripool.org/projects/verilator/wiki/Download[Verilator
Downloads]; we presume you know how to use it, and is not described here.)
Get the sources from the repository: (You need do this only once, ever.)
git clone https://github.com/verilator/verilator # Only first time
## Note the URL above is not a page you can see with a browser, it's for git only
Enter the checkout and determine what version/branch to use:
cd verilator
git pull # Make sure we're up-to-date
git tag # See what versions exist
#git checkout master # Use development branch (e.g. recent bug fix)
#git checkout stable # Use most recent release
#git checkout v{version} # Switch to specified release version
=== Auto Configure
Create the configuration script:
autoconf # Create ./configure script
=== Eventual Installation Options
Before configuring the build, you have to decide how you're going to
eventually install the kit. Verilator will be compiling the current value
of `VERILATOR_ROOT`, `SYSTEMC_INCLUDE`, and `SYSTEMC_LIBDIR` as defaults
into the executable, so they must be correct before configuring.
These are the options:
==== 1. Run-in-Place from VERILATOR_ROOT
Our personal favorite is to always run Verilator in-place from its Git
directory. This allows the easiest experimentation and upgrading, and
allows many versions of Verilator to co-exist on a system.
export VERILATOR_ROOT=`pwd` # if your shell is bash
setenv VERILATOR_ROOT `pwd` # if your shell is csh
./configure
# Running will use files from $VERILATOR_ROOT, so no install needed
Note after installing (below steps), a calling program or shell must set
the environment variable `VERILATOR_ROOT` to point to this Git directory,
then execute `$VERILATOR_ROOT/bin/verilator`, which will find the path to
all needed files.
==== 2. Install into a CAD Disk
You may eventually be installing onto a project/company-wide "CAD" tools
disk that may support multiple versions of every tool. Target the build to
a destination directory name that includes the Verilator version name:
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_//"`
Note after installing (below steps), if you use
http://modules.sourceforge.net/[modulecmd], you'll want a module file like
the following:
.modulecmd's verilator/version file
----
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
----
==== 3. Install into a Specific Path
You may eventually install Verilator into a specific installation prefix,
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 (below steps) you will need to add
`/opt/verilator-VERSION/bin` to `$PATH`.
==== 4. Install System Globally
The final option is to eventually install Verilator globally, using the
normal system paths:
unset VERILATOR_ROOT # if your shell is bash
unsetenv VERILATOR_ROOT # if your shell is csh
./configure
Then after installing (below) the binary directories should already be in
your `$PATH`.
=== Configure
The command to configure the package was described in the previous step.
Developers should configure to have more complete developer tests.
Additional packages may be required for these tests.
export VERILATOR_AUTHOR_SITE=1 # Put in your .bashrc
./configure --enable-longtests ...above options...
=== Compile
Compile Verilator:
make -j
=== Test
Check the compilation by running self-tests:
make test
=== Install
If you used any but the <<1. Run-in-Place from VERILATOR_ROOT>> scheme,
install to the OS-standard place:
make install
== Running Verilator
To run Verilator, see the example sections in the
https://verilator.org/verilator_doc.html[Verilator manual (HTML)],
or https://verilator.org/verilator_doc.pdf[Verilator manual (PDF)].
Also see the `examples/` directory that is part of the kit, and is installed
(in a OS-specific place, often in e.g. `/usr/local/share/verilator/examples`).
cd examples/make_hello_c
make
Note if you did a `make install` above you should not have `VERILATOR_ROOT`
set in your environment; it is built into the executable.
== Announcements
To get notified of new releases, go to
https://github.com/verilator/verilator-announce[Verilator announcement
repository] and follow the instructions there.
== Directory Structure
Some relevant files and directories in this package are as follows:
Changes => Version history
README.adoc => This document
bin/verilator => Compiler wrapper invoked to Verilate code
docs/ => Additional documentation
examples/make_hello_c => Example GNU-make simple Verilog->C++ conversion
examples/make_hello_sc => Example GNU-make simple Verilog->SystemC conversion
examples/make_tracing_c => Example GNU-make Verilog->C++ with tracing
examples/make_tracing_sc => Example GNU-make Verilog->SystemC with tracing
examples/make_protect_lib => Example using --protect-lib
examples/cmake_hello_c => Example building make_hello_c with CMake
examples/cmake_hello_sc => Example building make_hello_sc with CMake
examples/cmake_tracing_c => Example building make_tracing_c with CMake
examples/cmake_tracing_sc => Example building make_tracing_sc with CMake
examples/cmake_protect_lib => Example building make_protect_lib with CMake
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.mk => Common Makefile
src/ => Translator source code
test_regress => Internal tests
For files created after a design is Verilated, see the
https://verilator.org/verilator_doc.html[Verilator manual (HTML)],
or https://verilator.org/verilator_doc.pdf[Verilator manual (PDF)].
== License
Copyright 2008-2021 by Wilson Snyder. 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.
// SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0

397
docs/install.rst Normal file
View File

@ -0,0 +1,397 @@
|Logo|
======================
Verilator Installation
======================
.. contents::
:depth: 3
Introduction
============
This discusses how to install Verilator. For more general information
please see `verilator.org <https://verilator.org>`__.
Quick-start
===========
Install From a Package Manager
------------------------------
Using a distribution's package manager is the easiest way to get
started. (Note packages are unlikely to have the most recent version, so
Git, below, maybe a better alternative.) To install as a package:
::
apt-get install verilator
If this works, skip down to `Running Verilator <#_running_verilator>`__.
Docker
------
Verilator is available in pre-built Docker containers. See
https://github.com/verilator/verilator/blob/master/ci/docker/run/README.rst
Git
---
Installing Verilator with Git provides the most flexibility. For
additional options and details see the additional sections below. In
brief:
::
# Prerequisites:
#sudo apt-get install git make autoconf g++ flex bison
#sudo apt-get install libfl2 # Ubuntu only (ignore if gives error)
#sudo apt-get install libfl-dev # Ubuntu only (ignore if gives error)
git clone https://github.com/verilator/verilator # Only first time
## Note the URL above is not a page you can see with a browser, it's for git only
# Every time you need to build:
unsetenv VERILATOR_ROOT # For csh; ignore error if on bash
unset VERILATOR_ROOT # For bash
cd verilator
git pull # Make sure git repository is up-to-date
git tag # See what versions exist
#git checkout master # Use development branch (e.g. recent bug fixes)
#git checkout stable # Use most recent stable release
#git checkout v{version} # Switch to specified release version
autoconf # Create ./configure script
./configure
make
sudo make install
# Now see "man verilator" or online verilator.pdf's for the example tutorials
If this works, skip down to `Running Verilator <#_running_verilator>`__.
Detailed Build Instructions
===========================
This section describes details of the build process, and assumes you are
building from Git or a tarball. For using a pre-built binary for your
Linux distribution, see instead `Install From a Package
Manager <#_install_from_a_package_manager>`__.
OS Requirements
---------------
Verilator is developed and has primary testing on Ubuntu, with additional
testing on FreeBSD and Apple OS-X. Versions have also built on Redhat
Linux, HPUX and Solaris. It should run with minor porting on any
GNU/Linux-ish platform. Verilator also works on Windows under Cygwin, and
Windows under MinGW (gcc -mno-cygwin). Verilated output (not Verilator
itself) compiles under all the options above, plus MSVC++.
Install Prerequisites
---------------------
To build or run Verilator you need these standard packages:
::
sudo apt-get install perl python3 make
sudo apt-get install g++ # Alternatively, clang
sudo apt-get install libgz # Non-Ubuntu (ignore if gives error)
sudo apt-get install libfl2 libfl-dev zlibc zlib1g zlib1g-dev # Ubuntu only (ignore if gives error)
To build or run the following are optional but should be installed for good
performance:
::
sudo apt-get install ccache # If present at build, needed for run
sudo apt-get install libgoogle-perftools-dev numactl perl-doc
To build Verilator you will need to install these packages; these do not
need to be present to run Verilator:
::
sudo apt-get install git autoconf flex bison
Those developing Verilator itself may also want these (see internals.rst):
::
sudo apt-get install gdb asciidoctor graphviz cmake clang clang-format gprof lcov
cpan install Pod::Perldoc
cpan install Parallel::Forker
Install SystemC
~~~~~~~~~~~~~~~
If you will be using SystemC (vs straight C++ output), download `SystemC
<https://www.accellera.org/downloads/standards/systemc>`__. 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.)
Install GTKWave
~~~~~~~~~~~~~~~
To make use of Verilator FST tracing you will want `GTKwave
<http://gtkwave.sourceforge.net/>`__ installed, however this is not
required at Verilator build time.
Obtain Sources
--------------
You may use Git or a tarball for the sources. Git is the supported
option. (If using a historical build that uses a tarball, tarballs are
obtained from `Verilator Downloads
<https://www.veripool.org/projects/verilator/wiki/Download>`__; we presume
you know how to use it, and is not described here.)
Get the sources from the repository: (You need do this only once, ever.)
::
git clone https://github.com/verilator/verilator # Only first time
## Note the URL above is not a page you can see with a browser, it's for git only
Enter the checkout and determine what version/branch to use:
::
cd verilator
git pull # Make sure we're up-to-date
git tag # See what versions exist
#git checkout master # Use development branch (e.g. recent bug fix)
#git checkout stable # Use most recent release
#git checkout v{version} # Switch to specified release version
Auto Configure
--------------
Create the configuration script:
::
autoconf # Create ./configure script
Eventual Installation Options
-----------------------------
Before configuring the build, you have to decide how you're going to
eventually install the kit. Verilator will be compiling the current value
of ``VERILATOR_ROOT``, ``SYSTEMC_INCLUDE``, and ``SYSTEMC_LIBDIR`` as
defaults into the executable, so they must be correct before configuring.
These are the options:
1. Run-in-Place from VERILATOR_ROOT
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Our personal favorite is to always run Verilator in-place from its Git
directory. This allows the easiest experimentation and upgrading, and
allows many versions of Verilator to co-exist on a system.
::
export VERILATOR_ROOT=`pwd` # if your shell is bash
setenv VERILATOR_ROOT `pwd` # if your shell is csh
./configure
# Running will use files from $VERILATOR_ROOT, so no install needed
Note after installing (below steps), a calling program or shell must set
the environment variable ``VERILATOR_ROOT`` to point to this Git directory,
then execute ``$VERILATOR_ROOT/bin/verilator``, which will find the path to
all needed files.
2. Install into a CAD Disk
~~~~~~~~~~~~~~~~~~~~~~~~~~
You may eventually be installing onto a project/company-wide "CAD" tools
disk that may support multiple versions of every tool. Target the build to
a destination directory name that includes the Verilator version name:
::
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_//"`
Note after installing (below steps), if you use `modulecmd
<http://modules.sourceforge.net/>`__, you'll want a module file like the
following:
**modulecmd's verilator/version file.**
::
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
3. Install into a Specific Path
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You may eventually install Verilator into a specific installation prefix,
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 (below steps) you will need to add
``/opt/verilator-VERSION/bin`` to ``$PATH``.
4. Install System Globally
~~~~~~~~~~~~~~~~~~~~~~~~~~
The final option is to eventually install Verilator globally, using the
normal system paths:
::
unset VERILATOR_ROOT # if your shell is bash
unsetenv VERILATOR_ROOT # if your shell is csh
./configure
Then after installing (below) the binary directories should already be
in your ``$PATH``.
Configure
---------
The command to configure the package was described in the previous step.
Developers should configure to have more complete developer tests.
Additional packages may be required for these tests.
::
export VERILATOR_AUTHOR_SITE=1 # Put in your .bashrc
./configure --enable-longtests ...above options...
Compile
-------
Compile Verilator:
::
make -j
Test
----
Check the compilation by running self-tests:
::
make test
Install
-------
If you used any but the `1. Run-in-Place from VERILATOR_ROOT
<#_1_run_in_place_from_verilator_root>`__ scheme, install to the
OS-standard place:
::
make install
Running Verilator
=================
To run Verilator, see the example sections in the `Verilator manual (HTML)
<https://verilator.org/verilator_doc.html>`__, or `Verilator manual (PDF)
<https://verilator.org/verilator_doc.pdf>`__.
Also see the ``examples/`` directory that is part of the kit, and is
installed (in a OS-specific place, often in e.g.
``/usr/local/share/verilator/examples``).
::
cd examples/make_hello_c
make
Note if you did a ``make install`` above you should not have
``VERILATOR_ROOT`` set in your environment; it is built into the
executable.
Announcements
=============
To get notified of new releases, go to `Verilator announcement repository
<https://github.com/verilator/verilator-announce>`__ and follow the
instructions there.
Directory Structure
===================
Some relevant files and directories in this package are as follows:
::
Changes => Version history
README.rst => This document
bin/verilator => Compiler wrapper invoked to Verilate code
docs/ => Additional documentation
examples/make_hello_c => Example GNU-make simple Verilog->C++ conversion
examples/make_hello_sc => Example GNU-make simple Verilog->SystemC conversion
examples/make_tracing_c => Example GNU-make Verilog->C++ with tracing
examples/make_tracing_sc => Example GNU-make Verilog->SystemC with tracing
examples/make_protect_lib => Example using --protect-lib
examples/cmake_hello_c => Example building make_hello_c with CMake
examples/cmake_hello_sc => Example building make_hello_sc with CMake
examples/cmake_tracing_c => Example building make_tracing_c with CMake
examples/cmake_tracing_sc => Example building make_tracing_sc with CMake
examples/cmake_protect_lib => Example building make_protect_lib with CMake
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.mk => Common Makefile
src/ => Translator source code
test_regress => Internal tests
For files created after a design is Verilated, see the `Verilator manual
(HTML) <https://verilator.org/verilator_doc.html>`__, or `Verilator
manual (PDF) <https://verilator.org/verilator_doc.pdf>`__.
License
=======
Copyright 2008-2021 by Wilson Snyder. 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.
.. |Logo| image:: https://www.veripool.org/img/verilator_256_200_min.png

File diff suppressed because it is too large Load Diff

1213
docs/internals.rst Normal file

File diff suppressed because it is too large Load Diff

View File

@ -1,72 +0,0 @@
= Verilator XML Output
:toc: right
// Github doesn't render unless absolute URL
image::https://www.veripool.org/img/verilator_256_200_min.png[Logo,256,200,role="right"]
== Introduction
This document describes Verilator's XML output. For more general information
please see https://verilator.org[verilator.org].
== General
Verilator's XML output is enabled with the `--xml-only` flag. It contains
limited information about the elaborated design including files, modules,
instance hierarchy, logic and data types. There is no formal schema since part
of the structure of the XML document matches the compiled code which would
require the schema to describe legal SystemVerilog structure. The intended
usage is to enable other downstream tools to take advantage of Verilator's
parser.
== Structure
The XML document consists of 4 sections within the top level `verilator_xml`
element:
`<files>`...`</files>`::
This section contains a list of all design files read, including the
built-in constructs and the command line as their own entries. Each
`<file>` has an attribute `id` which is a short ASCII string unique to that
file. Other elements' `loc` attributes use this id to refer to a particular
file.
`<module_files>`...`</module_files>`::
All files containing Verilog module definitions are listed in this section.
This element's contents is a subset of the `<files>` element's contents.
`<cells>`...`</cells>`::
The cells section of the XML document contains the design instance
hierarchy. Each instance is represented with the `<cell>` element with the
following attributes:
* `fl` (deprecated): The file id and line number where the module was
instanced. Use `loc` instead.
* `loc`: The file id, first line number, last line number, first column
number and last column number of the identifier where the module was
instanced, separated by commas.
* `name`: The instance name.
* `submodname`: The module name uniquified with particular parameter values (if any).
* `hier`: The full hierarchy path.
`<netlist>`...`</netlist>`::
The netlist section contains a number of `<module>`...`</module>` elements,
each describing the contents of that module, and a single `<typetable>`...
`</typetable>` element which lists all used types used within the
modules. Each type has a numeric `id` attribute that is referred to by
elements in the `<module>` elements using the `dtype_id` attribute.
== Distribution
Copyright 2020-2021 by Wilson Snyder. 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.
// SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0

81
docs/xml.rst Normal file
View File

@ -0,0 +1,81 @@
|Logo|
===========================
Verilator XML Output Format
===========================
Introduction
============
This document describes Verilator's XML output. For more general
information please see `verilator.org <https://verilator.org>`__.
General
=======
Verilator's XML output is enabled with the ``--xml-only`` flag. It contains
limited information about the elaborated design including files, modules,
instance hierarchy, logic and data types. There is no formal schema since
part of the structure of the XML document matches the compiled code which
would require the schema to describe legal SystemVerilog structure. The
intended usage is to enable other downstream tools to take advantage of
Verilator's parser.
Structure
=========
The XML document consists of 4 sections within the top level
``verilator_xml`` element:
``<files>``\ ... ``</files>``
This section contains a list of all design files read, including the
built-in constructs and the command line as their own entries. Each
``<file>`` has an attribute ``id`` which is a short ASCII string
unique to that file. Other elements' ``loc`` attributes use this id
to refer to a particular file.
``<module_files>``\ ... ``</module_files>``
All files containing Verilog module definitions are listed in this
section. This element's contents is a subset of the ``<files>``
element's contents.
``<cells>``\ ... ``</cells>``
The cells section of the XML document contains the design instance
hierarchy. Each instance is represented with the ``<cell>`` element
with the following attributes:
- ``fl`` (deprecated): The file id and line number where the module
was instanced. Use ``loc`` instead.
- ``loc``: The file id, first line number, last line number, first
column number and last column number of the identifier where the
module was instanced, separated by commas.
- ``name``: The instance name.
- ``submodname``: The module name uniquified with particular
parameter values (if any).
- ``hier``: The full hierarchy path.
``<netlist>``\ ... ``</netlist>``
The netlist section contains a number of
``<module>``\ ... ``</module>`` elements, each describing the
contents of that module, and a single ``<typetable>``\ ...
``</typetable>`` element which lists all used types used within the
modules. Each type has a numeric ``id`` attribute that is referred to
by elements in the ``<module>`` elements using the ``dtype_id``
attribute.
.. __distribution:
Distribution
============
Copyright 2020-2021 by Wilson Snyder. 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.
.. |Logo| image:: https://www.veripool.org/img/verilator_256_200_min.png