-
Notifications
You must be signed in to change notification settings - Fork 529
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
0 parents
commit 54c704e
Showing
136 changed files
with
38,950 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,4 @@ | ||
# Sphinx build info version 1 | ||
# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done. | ||
config: 310eb518ac2147d317a98d36826c77cd | ||
tags: 645f666f9bcd5a90fca523b33c5a78b7 |
Empty file.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,225 @@ | ||
|
||
Getting Started as a Contributer | ||
================================ | ||
|
||
Icarus Verilog development is centered around the github repository at | ||
`github.com/steveicarus/iverilog <http://github.com/steveicarus/iverilog>`_. | ||
Contributing to Icarus Verilog requires a basic knowledge of git and github, | ||
so see the github documentation for more information. The sections below will | ||
step you through the basics of getting the source code from github, making a | ||
branch, and submitting a pull request for review. | ||
|
||
Getting Icarus Verilog | ||
---------------------- | ||
|
||
To start, you will need to clone the code. It is preferred that you use the | ||
"ssh" method, and the ssh based clone with the command: | ||
|
||
.. code-block:: console | ||
% git clone [email protected]:steveicarus/iverilog.git | ||
This assumes that you have a github account (accounts are free) and you have | ||
set up your ssh authentication keys. See the | ||
`Authentication Guides here <https://docs.github.com/en/authentication>`_. | ||
|
||
The "git clone" command will get you all the source: | ||
|
||
.. code-block:: console | ||
% git clone [email protected]:steveicarus/iverilog.git | ||
Cloning into 'iverilog'... | ||
remote: Enumerating objects: 66234, done. | ||
remote: Counting objects: 100% (6472/6472), done. | ||
remote: Compressing objects: 100% (4123/4123), done. | ||
remote: Total 66234 (delta 2412), reused 6039 (delta 2190), pack-reused 59762 | ||
Receiving objects: 100% (66234/66234), 27.98 MiB | 2.53 MiB/s, done. | ||
Resolving deltas: 100% (50234/50234), done. | ||
% cd iverilog/ | ||
Normally, this is enough as you are now pointing at the most current | ||
development code, and you have implicitly created a branch "master" that | ||
tracks the development head. However, If you want to actually be working on a | ||
specific version, say for example version 11, the v11-branch, you checkout | ||
that branch with the command: | ||
|
||
.. code-block:: console | ||
% git checkout --track -b v11-branch origin/v11-branch | ||
This creates a local branch that tracks the v11-branch in the repository, and | ||
switches you over to your new v11-branch. The tracking is important as it | ||
causes pulls from the repository to re-merge your local branch with the remote | ||
v11-branch. You always work on a local branch, then merge only when you | ||
push/pull from the remote repository. | ||
|
||
Now that you've cloned the repository and optionally selected the branch you | ||
want to work on, your local source tree may later be synced up with the | ||
development source by using the git command: | ||
|
||
.. code-block:: console | ||
% git pull | ||
Already up to date. | ||
Finally, configuration files are built by the extra step: | ||
|
||
.. code-block:: console | ||
% sh autoconf.sh | ||
Autoconf in root... | ||
Precompiling lexor_keyword.gperf | ||
Precompiling vhdlpp/lexor_keyword.gperf | ||
You will need autoconf and gperf installed in order for the script to work. | ||
If you get errors such as: | ||
|
||
.. code-block:: console | ||
% sh autoconf.sh | ||
Autoconf in root... | ||
autoconf.sh: 10: autoconf: not found | ||
Precompiling lexor_keyword.gperf | ||
autoconf.sh: 13: gperf: not found. | ||
You will need to install download and install the autoconf and gperf tools. | ||
|
||
Now you are ready to configure and compile the source. | ||
|
||
Icarus Specific Configuration Options | ||
------------------------------------- | ||
|
||
Icarus takes many of the standard configuration options and those will not be | ||
described here. The following are specific to Icarus Verilog: | ||
|
||
.. code-block:: none | ||
--enable-suffix[=suffix] | ||
This option allows the user to build Icarus with a default suffix or when | ||
provided a user defined suffix. All programs or directories are tagged with | ||
this suffix. e.g.(iverilog-0.8, vvp-0.8, etc.). The output of iverilog will | ||
reference the correct run time files and directories. The run time will check | ||
that it is running a file with a compatible version e.g.(you can not run a | ||
V0.9 file with the V0.8 run time). | ||
|
||
A debug options is: | ||
|
||
.. code-block:: none | ||
--with-valgrind | ||
This option adds extra memory cleanup code and pool management code to allow | ||
better memory leak checking when valgrind is available. This option is not | ||
need when checking for basic errors with valgrind. | ||
|
||
Compiling on Linux | ||
------------------ | ||
|
||
(Note: You will need to install bison, flex, g++ and gcc) This is probably the | ||
easiest step. Given that you have the source tree from the above instructions, | ||
the compile and install is generally as simple as: | ||
|
||
.. code-block:: console | ||
% ./configure | ||
configure: loading site script /usr/share/site/x86_64-unknown-linux-gnu | ||
checking build system type... x86_64-unknown-linux-gnu | ||
checking host system type... x86_64-unknown-linux-gnu | ||
checking for gcc... gcc | ||
checking whether the C compiler works... yes | ||
checking for C compiler default output file name... a.out | ||
checking for suffix of executables... | ||
[...and so on...] | ||
% make | ||
mkdir dep | ||
Using git-describe for VERSION_TAG | ||
g++ -DHAVE_CONFIG_H -I. -Ilibmisc -Wall -Wextra -Wshadow -g -O2 -MD -c main.cc -o main.o | ||
mv main.d dep/main.d | ||
g++ -DHAVE_CONFIG_H -I. -Ilibmisc -Wall -Wextra -Wshadow -g -O2 -MD -c async.cc -o async.o | ||
mv async.d dep/async.d | ||
g++ -DHAVE_CONFIG_H -I. -Ilibmisc -Wall -Wextra -Wshadow -g -O2 -MD -c design_dump.cc -o design_dump.o | ||
mv design_dump.d dep/design_dump.d | ||
g++ -DHAVE_CONFIG_H -I. -Ilibmisc -Wall -Wextra -Wshadow -g -O2 -MD -c discipline.cc -o discipline.o | ||
[...and so on...] | ||
The end result is a complete build of Icarus Verilog. You can install your | ||
compiled version with a command like this: | ||
|
||
.. code-block:: console | ||
% sudo make install | ||
Regression Tests | ||
---------------- | ||
|
||
Icarus Verilog comes with a fairly extensive regression test suite. As of | ||
2022, that test suite is included with the source in the "ivtest" | ||
directory. Contained in that directory are a couple driver scripts that run | ||
all the regression tests on the installed version of Icarus Verilog. So for | ||
example: | ||
|
||
.. code-block:: console | ||
% cd ivtest | ||
% ./vvp_reg.pl --strict | ||
will run all the regression tests for the simulation engine. (This is what | ||
most people will want to do.) You should rerun this test before submitting | ||
patches to the developers. Also, if you are adding a new feature, you should | ||
add test programs to the regression test suite to validate your new feature | ||
(or bug fix.) | ||
|
||
Note that pull requests will be required to pass these regression tests before | ||
being merged. | ||
|
||
Forks, Branches and Pull Requests | ||
--------------------------------- | ||
|
||
Currently, the preferred way to submit patches to Icarus Verilog is via pull | ||
requests. | ||
`Pull requests <https://docs.github.com/en/github-ae@latest/pull-requests>`_ | ||
can be created from the main repository if you have write access (very few | ||
people have write access) or more commonly from a fork, so the first step is | ||
to create a fork that you can work with. It is easy enough to create a fork, | ||
just go to the | ||
`github.com/steveicarus/iverilog <http://github.com/steveicarus/iverilog>`_ | ||
page and use the "fork" button in the upper right corner. This will create | ||
a new repository that you can clone instead of the steveicarus/iverilog | ||
repository. You then use your local repository to create feature branches, | ||
then submit them for inclusion in the main repository as pull | ||
requests. Remember to `synchronize your fork | ||
<https://docs.github.com/en/github-ae@latest/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork>`_ | ||
periodically with the main repository. This will make sure your work is based | ||
on the latest upstream and avoid merge conflicts. | ||
|
||
Create your patch by first creating a branch that contains your commits: | ||
|
||
.. code-block:: console | ||
% git checkout -b my-github-id/branch-name | ||
We are encouraging using this scheme for naming your branches that are | ||
destined for pull requests. Use your github id in the branch name. So for | ||
example: | ||
|
||
.. code-block:: console | ||
% git checkout -b steveicarus/foo-feature | ||
Do your work in this branch, then when you are ready to create a pull request, | ||
first push the branch up to github: | ||
|
||
.. code-block:: console | ||
% git push -u origin my-github-id/branch-name | ||
Then go to github.com to create your pull request. `Create your pull request | ||
against the "master" branch of the upstream repository | ||
<https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork>`_, | ||
or the version branch that you are working on. Your pull reuqest will be run | ||
through continuous integration, and reviewed by one of the main | ||
authors. Feedback may be offered to your PR, and once accepted, an approved | ||
individual will merge it for you. Then you are done. | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,48 @@ | ||
|
||
Glossary | ||
======== | ||
|
||
Throughout Icarus Verilog descriptions and source code, I use a | ||
variety of terms and acronyms that might be specific to Icarus | ||
Verilog, have an Icarus Verilog specific meaning, or just aren't | ||
widely known. So here I define these terms. | ||
|
||
|
||
LRM - Language Reference Manual | ||
This is a generic acronym, but in the Verilog world we sometimes | ||
mean *the* language reference manual, the IEEE1364 standard. | ||
|
||
|
||
PLI - Programming Language Interface | ||
This is a C API into Verilog simulators that is defined by the | ||
IEEE1364. There are two major interfaces, sometimes called PLI 1 | ||
and PLI 2. PLI 2 is also often called VPI. | ||
|
||
|
||
UDP - User Defined Primitive | ||
These are objects that Verilog programmers define with the | ||
"primitive" keyword. They are truth-table based devices. The | ||
syntax for defining them is described in the LRM. | ||
|
||
|
||
VPI - Verilog Procedural Interface | ||
This is the C API that is defined by the Verilog standard, and | ||
that Icarus Verilog partially implements. See also PLI. | ||
|
||
|
||
VVM - Verilog Virtual Machine | ||
This is the Icarus Verilog runtime that works with the code | ||
generator that generates C++. | ||
|
||
|
||
VVP - Verilog Virtual Processor | ||
This is the Icarus Verilog runtime that reads in custom code in a | ||
form that I call "VVP Assembly". | ||
|
||
LPM - Library of Parameterized Modules | ||
LPM (Library of Parameterized Modules) is EIS-IS standard 103-A. It is | ||
a standard library of abstract devices that are designed to be close | ||
enough to the target hardware to be easily translated, yet abstract | ||
enough to support a variety of target technologies without excessive | ||
constraints. Icarus Verilog uses LPM internally to represent idealized | ||
hardware, especially when doing target neutral synthesis. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,34 @@ | ||
|
||
Cadence PLI1 Modules | ||
==================== | ||
|
||
With the cadpli module, Icarus Verilog is able to load PLI1 | ||
applications that were compiled and linked to be dynamic loaded by | ||
Verilog-XL or NC-Verilog. This allows Icarus Verilog users to run | ||
third-party modules that were compiled to interface with XL or | ||
NC. Obviously, this only works on the operating system that the PLI | ||
application was compiled to run on. For example, a Linux module can | ||
only be loaded and run under Linux. | ||
|
||
Icarus Verilog uses an interface module, the "cadpli" module, to | ||
connect the worlds. This module is installed with Icarus Verilog, and | ||
is invoked by the usual -m flag to iverilog or vvp. This module in | ||
turn scans the extended arguments, looking for +cadpli= arguments. The | ||
latter specify the share object and bootstrap function for running the | ||
module. For example, to run the module product.so, that has the | ||
bootstrap function "my_boot":: | ||
|
||
vvp -mcadpli a.out -cadpli=./product.so:my_boot | ||
|
||
The "-mcadpli" argument causes vvp to load the cadpli.vpl library | ||
module. This activates the -cadpli= argument interpreter. The | ||
-cadpli=<module>:<boot_func> argument, then, causes vvp, through the | ||
cadpli module, to load the loadable PLI application, invoke the | ||
my_boot function to get a veriusertfs table, and scan that table to | ||
register the system tasks and functions exported by that object. The | ||
format of the -cadpli= extended argument is essentially the same as | ||
the +loadpli1= argument to Verilog-XL. | ||
|
||
The integration from this point is seamless. The PLI application | ||
hardly knows that it is being invoked by Icarus Verilog instead of | ||
Verilog-XL, so operates as it would otherwise. |
Oops, something went wrong.