forked from github/verilator
Converted Asciidoc documentation into reStructuredText (RST) format.
This commit is contained in:
parent
b52b063c16
commit
c99f01b7fe
2
.github/ISSUE_TEMPLATE/bug_report.md
vendored
2
.github/ISSUE_TEMPLATE/bug_report.md
vendored
@ -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: ''
|
||||
|
2
.github/ISSUE_TEMPLATE/feature.md
vendored
2
.github/ISSUE_TEMPLATE/feature.md
vendored
@ -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: ''
|
||||
|
2
.github/ISSUE_TEMPLATE/questions.md
vendored
2
.github/ISSUE_TEMPLATE/questions.md
vendored
@ -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: ''
|
||||
|
2
.github/PULL_REQUEST_TEMPLATE.md
vendored
2
.github/PULL_REQUEST_TEMPLATE.md
vendored
@ -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.
|
||||
|
2
.github/workflows/build.yml
vendored
2
.github/workflows/build.yml
vendored
@ -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
|
||||
|
1
.github/workflows/clang-format.yml
vendored
1
.github/workflows/clang-format.yml
vendored
@ -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
|
||||
|
2
Changes
2
Changes
@ -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]
|
||||
|
10
Makefile.in
10
Makefile.in
@ -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 \
|
||||
|
154
README.adoc
154
README.adoc
@ -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/> +++ • Accepts synthesizable Verilog or SystemVerilog
|
||||
+++ <br/> +++ • Performs lint code-quality checks
|
||||
+++ <br/> +++ • Compiles into multithreaded {cpp}, or SystemC
|
||||
+++ <br/> +++ • 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/> +++ • Outperforms many commercial simulators
|
||||
+++ <br/> +++ • Single- and multi-threaded output models
|
||||
|
||||
^.^| *Widely Used*
|
||||
+++ <br/> +++ • Wide industry and academic deployment
|
||||
+++ <br/> +++ • 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/> +++ • Guided by the https://chipsalliance.org/[CHIPS Alliance] and https://www.linuxfoundation.org/[Linux Foundation]
|
||||
+++ <br/> +++ • Open, and free as in both speech and beer
|
||||
+++ <br/> +++ • More simulation for your verification budget
|
||||
|
||||
^.^| *Commercial Support Available*
|
||||
+++ <br/> +++ • Commercial support contracts
|
||||
+++ <br/> +++ • Design support contracts
|
||||
+++ <br/> +++ • 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
160
README.rst
Normal 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
|
@ -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
|
||||
|
||||
|
@ -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.
|
64
ci/docker/buildenv/README.rst
Normal file
64
ci/docker/buildenv/README.rst
Normal 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.
|
@ -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
74
ci/docker/run/README.rst
Normal 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.
|
@ -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
93
docs/CONTRIBUTING.rst
Normal 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 you’d 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!
|
@ -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
|
||||
|
@ -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
397
docs/install.rst
Normal 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
|
1026
docs/internals.adoc
1026
docs/internals.adoc
File diff suppressed because it is too large
Load Diff
1213
docs/internals.rst
Normal file
1213
docs/internals.rst
Normal file
File diff suppressed because it is too large
Load Diff
@ -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
81
docs/xml.rst
Normal 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
|
Loading…
Reference in New Issue
Block a user