luke
/
iverilog
mirror of https://github.com/steveicarus/iverilog.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
iverilog/usage/vpi.html

527 lines
32 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html>
<html lang="en" data-accent-color="violet" data-content_root="../">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Using VPI - Icarus Verilog documentation</title><link rel="shortcut icon" href="../_static/favicon.ico"/><link rel="index" title="Index" href="../genindex.html" /><link rel="search" title="Search" href="../search.html" /><link rel="next" title="Icarus Verilog Extensions" href="icarus_verilog_extensions.html" /><link rel="prev" title="Viewing Waveforms" href="waveform_viewer.html" /><script>
function setColorMode(t){let e=document.documentElement;e.setAttribute("data-color-mode",t);let a=window.matchMedia&&window.matchMedia("(prefers-color-scheme: dark)").matches,s=t;"auto"===t&&(s=a?"dark":"light"),"light"===s?(e.classList.remove("dark"),e.classList.add("light")):(e.classList.remove("light"),e.classList.add("dark"))}
setColorMode(localStorage._theme||"auto");
</script><link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=ad592e98" />
<link rel="stylesheet" type="text/css" href="../_static/shibuya.css?v=44020203" />
<link media="print" rel="stylesheet" type="text/css" href="../_static/print.css?v=20ff2c19" />
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet">
<style>
:root {
--sy-f-text: "Inter", var(--sy-f-sys), var(--sy-f-cjk), sans-serif;
--sy-f-heading: "Inter", var(--sy-f-sys), var(--sy-f-cjk), sans-serif;
}
</style>
<meta property="og:type" content="website"/><meta property="og:title" content="Using VPI"/>
<meta name="twitter:card" content="summary"/>
</head>
<body><div class="sy-head">
<div class="sy-head-blur"></div>
<div class="sy-head-inner sy-container mx-auto">
<a class="sy-head-brand" href="../index.html">
<strong>Icarus Verilog</strong>
</a>
<div class="sy-head-nav" id="head-nav">
<nav class="sy-head-links"></nav>
<div class="sy-head-extra flex items-center print:hidden"><form class="searchbox flex items-center" action="../search.html" method="get">
<input type="text" name="q" placeholder="Search" />
<kbd>/</kbd>
</form><div class="sy-head-socials">
<a href="https://github.com/steveicarus/iverilog" aria-label="GitHub">
<iconify-icon icon="simple-icons:github"></iconify-icon>
</a></div></div>
</div>
<div class="sy-head-actions flex items-center shrink-0 print:hidden"><button class="js-theme theme-switch flex items-center"
data-aria-auto="Switch to light color mode"
data-aria-light="Switch to dark color mode"
data-aria-dark="Switch to auto color mode">
<i class="i-lucide theme-icon"></i>
</button><button class="md:hidden flex items-center js-menu" aria-label="Menu" type="button" aria-controls="head-nav" aria-expanded="false">
<div class="hamburger">
<span class="hamburger_1"></span>
<span class="hamburger_2"></span>
<span class="hamburger_3"></span>
</div>
</button>
</div>
</div>
</div>
<div class="sy-page sy-container flex mx-auto">
<aside id="lside" class="sy-lside md:w-72 md:shrink-0 print:hidden">
<div class="sy-lside-inner md:sticky">
<div class="sy-scrollbar p-6">
<div class="globaltoc" data-expand-depth="0"><p class="caption" role="heading" aria-level="3"><span class="caption-text">Contents:</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../releases/index.html">Icarus Verilog Release Notes</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../releases/v13-0-release-note.html">🎉 Release V13.0</a></li>
<li class="toctree-l2"><a class="reference internal" href="../releases/v13-0-release-note.html#major-changes-in-v13">🔄 Major Changes in V13</a></li>
</ul>
</li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html">Icarus Verilog Usage</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="installation.html">Installation Guide</a></li>
<li class="toctree-l2"><a class="reference internal" href="getting_started.html">Getting Started With Icarus Verilog</a></li>
<li class="toctree-l2"><a class="reference internal" href="simulation.html">Simulation Using Icarus Verilog</a></li>
<li class="toctree-l2"><a class="reference internal" href="command_line_flags.html">iverilog Command Line Flags</a></li>
<li class="toctree-l2"><a class="reference internal" href="command_files.html">Command File Format</a></li>
<li class="toctree-l2"><a class="reference internal" href="verilog_attributes.html">Verilog Attributes</a></li>
<li class="toctree-l2"><a class="reference internal" href="ivlpp_flags.html">IVLPP - IVL Preprocessor</a></li>
<li class="toctree-l2"><a class="reference internal" href="vvp_flags.html">VVP Command Line Flags</a></li>
<li class="toctree-l2"><a class="reference internal" href="vvp_debug.html">VVP Interactive Mode</a></li>
<li class="toctree-l2"><a class="reference internal" href="vvp_library.html">VVP as a library</a></li>
<li class="toctree-l2"><a class="reference internal" href="vhdlpp_flags.html">vhdlpp Command Line Flags</a></li>
<li class="toctree-l2"><a class="reference internal" href="waveform_viewer.html">Viewing Waveforms</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">Using VPI</a></li>
<li class="toctree-l2"><a class="reference internal" href="icarus_verilog_extensions.html">Icarus Verilog Extensions</a></li>
<li class="toctree-l2"><a class="reference internal" href="icarus_verilog_quirks.html">Icarus Verilog Quirks</a></li>
<li class="toctree-l2"><a class="reference internal" href="reporting_issues.html">Reporting Issues</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../targets/index.html">The Icarus Verilog Targets</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../targets/tgt-vvp.html">The vvp Code Generator (-tvvp)</a></li>
<li class="toctree-l2"><a class="reference internal" href="../targets/tgt-stub.html">The stub Code Generator (-tstub)</a></li>
<li class="toctree-l2"><a class="reference internal" href="../targets/tgt-null.html">The null Code Generator (-tnull)</a></li>
<li class="toctree-l2"><a class="reference internal" href="../targets/tgt-vhdl.html">The VHDL Code Generator (-tvhdl)</a></li>
<li class="toctree-l2"><a class="reference internal" href="../targets/tgt-vlog95.html">The Verilog ‘95 Code Generator (-tvlog95)</a></li>
<li class="toctree-l2"><a class="reference internal" href="../targets/tgt-pcb.html">The PCB Code Generator (-tpcb)</a></li>
<li class="toctree-l2"><a class="reference internal" href="../targets/tgt-fpga.html">The FPGA Code Generator (-tfpga)</a></li>
<li class="toctree-l2"><a class="reference internal" href="../targets/tgt-pal.html">The PAL Code Generator (-tpal)</a></li>
<li class="toctree-l2"><a class="reference internal" href="../targets/tgt-sizer.html">The sizer Code Analyzer (-tsizer)</a></li>
<li class="toctree-l2"><a class="reference internal" href="../targets/tgt-verilog.html">The Verilog Code Generator (-tverilog)</a></li>
<li class="toctree-l2"><a class="reference internal" href="../targets/tgt-blif.html">The BLIF Code Generator (-tblif)</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../developer/index.html">Icarus Verilog Developer Support</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../developer/getting_started.html">Getting Started as a Contributor</a></li>
<li class="toctree-l2"><a class="reference internal" href="../developer/regression_tests.html">The Regression Test Suite</a></li>
<li class="toctree-l2"><a class="reference internal" href="../developer/version_stamps.html">Files With Version Information</a></li>
<li class="toctree-l2"><a class="reference internal" href="../developer/guide/index.html">Developer Guide</a><ul>
<li class="toctree-l3"><a class="reference internal" href="../developer/guide/ivl/index.html">IVL - The Core Compiler</a><ul>
<li class="toctree-l4"><a class="reference internal" href="../developer/guide/ivl/netlist.html">Netlist Format</a></li>
<li class="toctree-l4"><a class="reference internal" href="../developer/guide/ivl/attributes.html">Icarus Verilog Attributes</a></li>
<li class="toctree-l4"><a class="reference internal" href="../developer/guide/ivl/ivl_target.html">Loadable Target API (ivl_target)</a></li>
<li class="toctree-l4"><a class="reference internal" href="../developer/guide/ivl/lpm.html">What Is LPM</a></li>
<li class="toctree-l4"><a class="reference internal" href="../developer/guide/ivl/t-dll.html">Loadable Targets</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="../developer/guide/vvp/index.html">VVP - Verilog Virtual Processor</a><ul>
<li class="toctree-l4"><a class="reference internal" href="../developer/guide/vvp/vvp.html">VVP Simulation Engine</a></li>
<li class="toctree-l4"><a class="reference internal" href="../developer/guide/vvp/opcodes.html">Executable Instruction Opcodes</a></li>
<li class="toctree-l4"><a class="reference internal" href="../developer/guide/vvp/vpi.html">VPI Within VVP</a></li>
<li class="toctree-l4"><a class="reference internal" href="../developer/guide/vvp/vthread.html">Thread Details</a></li>
<li class="toctree-l4"><a class="reference internal" href="../developer/guide/vvp/debug.html">Debug Aids For VVP</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="../developer/guide/tgt-vvp/tgt-vvp.html">The VVP Target</a></li>
<li class="toctree-l3"><a class="reference internal" href="../developer/guide/vpi/index.html">VPI in Icarus Verilog</a><ul>
<li class="toctree-l4"><a class="reference internal" href="../developer/guide/vpi/vpi.html">VPI Modules in Icarus Verilog</a></li>
<li class="toctree-l4"><a class="reference internal" href="../developer/guide/vpi/va_math.html">Verilog-A math library</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="../developer/guide/cadpli/cadpli.html">Cadence PLI1 Modules</a></li>
<li class="toctree-l3"><a class="reference internal" href="../developer/guide/misc/index.html">Miscellaneous</a><ul>
<li class="toctree-l4"><a class="reference internal" href="../developer/guide/misc/ieee1364-notes.html">IEEE1364 Notes</a></li>
<li class="toctree-l4"><a class="reference internal" href="../developer/guide/misc/swift.html">Swift Model Support (Preliminary)</a></li>
<li class="toctree-l4"><a class="reference internal" href="../developer/guide/misc/xilinx-hint.html">Xilinx Hint</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../developer/glossary.html">Glossary</a></li>
</ul>
</li>
</ul>
</div>
</div>
</div>
</aside>
<div class="lside-overlay js-menu" role="button" aria-label="Close left sidebar" aria-controls="lside" aria-expanded="false"></div>
<aside id="rside" class="sy-rside pb-3 w-64 shrink-0 order-last">
<button class="rside-close js-menu xl:hidden" aria-label="Close Table of Contents" type="button" aria-controls="rside" aria-expanded="false">
<i class="i-lucide close"></i>
</button>
<div class="sy-scrollbar sy-rside-inner px-6 xl:top-16 xl:sticky xl:pl-0 pt-6 pb-4"><div class="localtoc"><h3>On this page</h3><ul>
<li><a class="reference internal" href="#how-it-works">How It Works</a></li>
<li><a class="reference internal" href="#compiling-vpi-modules">Compiling VPI Modules</a></li>
<li><a class="reference internal" href="#a-worked-example">A Worked Example</a></li>
<li><a class="reference internal" href="#system-function-return-types">System Function Return Types</a></li>
<li><a class="reference internal" href="#cadence-pli-modules">Cadence PLI Modules</a></li>
<li><a class="reference internal" href="#other-references">Other References</a></li>
</ul>
</div><a class="js-repo-stats repo-stats flex items-center" href="https://github.com/steveicarus/iverilog"
data-type="github" data-user="steveicarus" data-repo="iverilog">
<span class="w-8 flex items-center justify-around shrink-0 text-3xl">
<iconify-icon icon="simple-icons:github"></iconify-icon>
</span>
<span class="flex-grow px-2 break-all">
<span>iverilog</span>
<span class="flex text-sm repo-stats-count">
<span class="flex items-center pr-3">
<iconify-icon icon="lucide:star"></iconify-icon>
<strong class="js-repo-stars ml-1">0</strong>
</span>
<span class="flex items-center">
<iconify-icon icon="lucide:git-fork"></iconify-icon>
<strong class="js-repo-forks ml-1">0</strong>
</span>
</span>
</span>
</a><div class="edit-this-page">
<a href="https://github.com/steveicarus/iverilog/blob/master/Documentation/usage/vpi.rst">Edit this page</a>
</div><div id="ethical-ad-placement" data-ea-publisher="readthedocs"></div></div>
</aside>
<div class="rside-overlay js-menu" role="button" aria-label="Close Table of Contents" aria-controls="rside" aria-expanded="false"></div>
<main class="sy-main w-full max-sm:max-w-full print:pt-6">
<div class="sy-breadcrumbs" role="navigation">
<div class="sy-breadcrumbs-inner flex items-center">
<div class="md:hidden mr-3">
<button class="js-menu" aria-label="Menu" type="button" aria-controls="lside" aria-expanded="false">
<i class="i-lucide menu"></i>
</button>
</div>
<ol class="flex-1" itemscope itemtype="https://schema.org/BreadcrumbList"><li itemprop="itemListElement" itemscope itemtype="https://schema.org/ListItem">
<a itemprop="item" href="../index.html"><span itemprop="name">Icarus Verilog</span></a>
<span>/</span>
<meta itemprop="position" content="1" />
</li><li itemprop="itemListElement" itemscope itemtype="https://schema.org/ListItem">
<a itemprop="item" href="index.html"><span itemprop="name">Icarus Verilog Usage</span></a>
<span>/</span>
<meta itemprop="position" content="2" />
</li><li itemprop="itemListElement" itemscope itemtype="https://schema.org/ListItem">
<strong itemprop="name">Using VPI</strong>
<meta itemprop="position" content="3" />
</li></ol>
<div class="xl:hidden ml-1">
<button class="js-menu" aria-label="Show table of contents" type="button" aria-controls="rside"
aria-expanded="false">
<i class="i-lucide outdent"></i>
</button>
</div>
</div>
</div><div class="flex flex-col break-words justify-between">
<div class="relative min-w-0 max-w-6xl px-6 pb-6 pt-8 xl:px-12">
<div class="copy-page-wrapper relative pb-4 lg:absolute lg:top-8 lg:right-6 xl:right-12">
<div id="copy-page-trigger">
<button
type="button"
class="js-copy px-3 py-1 inline-flex items-center gap-1"
data-url="https://raw.githubusercontent.com/steveicarus/iverilog/refs/heads/master/Documentation/usage/vpi.rst.txt"
>
<i class="i-lucide" data-icon="copy"></i>
<span>Copy page</span>
</button>
<button class="js-menu px-2 py-1" type="button" aria-label="More actions"
aria-haspopup="menu" aria-expanded="false" aria-controls="copy-page-content">
<i class="i-lucide chevron-down"></i>
</button>
</div>
<div id="copy-page-content" role="menu" aria-orientation="vertical" aria-hidden="true">
<div role="presentation">
<div class="flex flex-col" role="group">
<button class="js-copy" type="button" role="menuitem"
data-url="https://raw.githubusercontent.com/steveicarus/iverilog/refs/heads/master/Documentation/usage/vpi.rst.txt">
<span class="iconify-icon">
<i class="i-lucide" data-icon="copy"></i>
</span>
<span>Copy page</span>
</button>
<a role="menuitem" href="https://raw.githubusercontent.com/steveicarus/iverilog/refs/heads/master/Documentation/usage/vpi.rst.txt" target="_blank" rel="nofollow"><iconify-icon icon="bi:code-slash"></iconify-icon>
<span>View Source</span></a><a role="menuitem" href="https://chatgpt.com/?hints=search&q=Read%20https%3A//raw.githubusercontent.com/steveicarus/iverilog/refs/heads/master/Documentation/usage/vpi.rst.txt%20so%20I%20can%20ask%20questions%20about%20it." target="_blank" rel="nofollow">
<iconify-icon icon="bi:openai"></iconify-icon>
<span>Open in ChatGPT</span>
</a><a role="menuitem" href="https://claude.ai/new?q=Read%20https%3A//raw.githubusercontent.com/steveicarus/iverilog/refs/heads/master/Documentation/usage/vpi.rst.txt%20so%20I%20can%20ask%20questions%20about%20it." target="_blank" rel="nofollow">
<iconify-icon icon="bi:claude"></iconify-icon>
<span>Open in Claude</span>
</a></div>
</div>
</div>
</div><article class="yue" role="main">
<section id="using-vpi">
<h1>Using VPI<a class="headerlink" href="#using-vpi" title="Link to this heading"></a></h1>
<p>Icarus Verilog implements a portion of the PLI 2.0 API to Verilog. This allows
programmers to write C code that interfaces with Verilog simulations to
perform tasks otherwise impractical with straight Verilog. Many Verilog
designers, especially those who only use Verilog as a synthesis tool, can
safely ignore the entire matter of the PLI (and this chapter) but the designer
who wishes to interface a simulation with the outside world cannot escape VPI.</p>
<p>The rest of this article assumes some knowledge of C programming, Verilog PLI,
and of the compiler on your system. In most cases, Icarus Verilog assumes the
GNU Compilation System is the compiler you are using, so tips and instructions
that follow reflect that. If you are not a C programmer, or are not planning
any VPI modules, you can skip this entire article. There are references at the
bottom for information about more general topics.</p>
<section id="how-it-works">
<h2>How It Works<a class="headerlink" href="#how-it-works" title="Link to this heading"></a></h2>
<p>The VPI modules are compiled loadable object code that the runtime loads at
the user’s request. The user commands vvp to locate and load modules with the
“-m” switch. For example, to load the “sample.vpi” module:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span><span data-line="1">% vvp -msample foo.vvp
</span></pre></div>
</div>
<p>The vvp run-time loads the modules first, before executing any of the
simulation, or even before compiling the vvp code. Part of the loading
includes invoking initialization routines. These routines register with the
run-time all the system tasks and functions that the module implements. Once
this is done, the run time loader can match names of the called system tasks
of the design with the implementations in the VPI modules.</p>
<p>(There is a special module, the system.vpi module, that is always loaded to
provide the core system tasks.)</p>
<p>The simulator run time (The “vvp” program) gets a handle on a freshly loaded
module by looking for the symbol “vlog_startup_routines” in the loaded
module. This table, provided by the module author and compiled into the
module, is a null terminated table of function pointers. The simulator calls
each of the functions in the table in order. The following simple C definition
defines a sample table:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span><span data-line="1">void (*vlog_startup_routines[])(void) = {
</span><span data-line="2"> hello_register,
</span><span data-line="3"> 0
</span><span data-line="4">};
</span></pre></div>
</div>
<p>Note that the “vlog_startup_routines” table is an array of function pointers,
with the last pointer a 0 to mark the end. The programmer can organize the
module to include many startup functions in this table, if desired.</p>
<p>The job of the startup functions that are collected in the startup table is to
declare the system tasks and functions that the module provides. A module may
implement as many tasks/functions as desired, so a module can legitimately be
called a library of system tasks and functions.</p>
</section>
<section id="compiling-vpi-modules">
<h2>Compiling VPI Modules<a class="headerlink" href="#compiling-vpi-modules" title="Link to this heading"></a></h2>
<p>To compile and link a VPI module for use with Icarus Verilog, you must compile
all the source files of a module as if you were compiling for a DLL or shared
object. With gcc under Linux, this means compiling with the “-fpic” flag. The
module is then linked together with the vpi library like so:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span><span data-line="1">% gcc -c -fpic hello.c
</span><span data-line="2">% gcc -shared -o hello.vpi hello.o -lvpi
</span></pre></div>
</div>
<p>This assumes that the “vpi_user.h header file and the libvpi.a library file
are installed on your system so that gcc may find them. This is normally the
case under Linux and UNIX systems. An easier, the preferred method that works
on all supported systems is to use the single command:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span><span data-line="1">% iverilog-vpi hello.c
</span></pre></div>
</div>
<p>The “iverilog-vpi” command takes as command arguments the source files for
your VPI module, compiles them with proper compiler flags, and links them into
a vpi module with any system specific libraries and linker flags that are
required. This simple command makes the “hello.vpi” module with minimum fuss.</p>
</section>
<section id="a-worked-example">
<h2>A Worked Example<a class="headerlink" href="#a-worked-example" title="Link to this heading"></a></h2>
<p>Let us try a complete, working example. Place the C code that follows into the
file hello.c:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span><span data-line="1"># include &lt;vpi_user.h&gt;
</span><span data-line="2">
</span><span data-line="3">static int hello_compiletf(char*user_data)
</span><span data-line="4">{
</span><span data-line="5"> (void)user_data; // Avoid a warning since user_data is not used.
</span><span data-line="6"> return 0;
</span><span data-line="7">}
</span><span data-line="8">
</span><span data-line="9">static int hello_calltf(char*user_data)
</span><span data-line="10">{
</span><span data-line="11"> (void)user_data; // Avoid a warning since user_data is not used.
</span><span data-line="12"> vpi_printf(&quot;Hello, World!\n&quot;);
</span><span data-line="13"> return 0;
</span><span data-line="14">}
</span><span data-line="15">
</span><span data-line="16">void hello_register(void)
</span><span data-line="17">{
</span><span data-line="18"> s_vpi_systf_data tf_data;
</span><span data-line="19">
</span><span data-line="20"> tf_data.type = vpiSysTask;
</span><span data-line="21"> tf_data.tfname = &quot;$hello&quot;;
</span><span data-line="22"> tf_data.calltf = hello_calltf;
</span><span data-line="23"> tf_data.compiletf = hello_compiletf;
</span><span data-line="24"> tf_data.sizetf = 0;
</span><span data-line="25"> tf_data.user_data = 0;
</span><span data-line="26"> vpi_register_systf(&amp;tf_data);
</span><span data-line="27">}
</span><span data-line="28">
</span><span data-line="29">void (*vlog_startup_routines[])(void) = {
</span><span data-line="30"> hello_register,
</span><span data-line="31"> 0
</span><span data-line="32">};
</span></pre></div>
</div>
<p>and place the Verilog code that follows into hello.v:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span><span data-line="1">module main;
</span><span data-line="2"> initial $hello;
</span><span data-line="3">endmodule
</span></pre></div>
</div>
<p>Next, compile and execute the code with these steps:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span><span data-line="1">% iverilog-vpi hello.c
</span><span data-line="2">% iverilog -ohello.vvp hello.v
</span><span data-line="3">% vvp -M. -mhello hello.vvp
</span><span data-line="4">Hello, World!
</span></pre></div>
</div>
<p>The compile and link in this example are conveniently combined into the
“iverilog-vpi” command. The “iverilog” command then compiles the “hello.v”
Verilog source file to the “hello.vvp” program. Next, the “vvp” command
demonstrates the use of the “-M” and “-m” flags to specify a vpi module search
directory and vpi module name. Specifically, they tell the “vvp” command where
to find the module we just compiled.</p>
<p>The “vvp” command, when executed as above, loads the “hello.vpi” module that
it finds in the current working directory. When the module is loaded, the
vlog_startup_routines table is scanned, and the “hello_register” function is
executed. The “hello_register” function in turn tells “vvp” about the system
tasks that are included in this module.</p>
<p>After the modules are all loaded, the “hello.vvp” design file is loaded and
its call to the “$hello” system task is matched up to the version declared by
the module. While “vvp” compiles the “hello.vvp” source, any calls to “$hello”
are referred to the “compiletf” function. This function is called at compile
time and can be used to check parameters to system tasks or function. It can
be left empty like this, or left out completely. The “compiletf” function can
help performance by collecting parameter checks in compile time, so they do
not need to be done each time the system task is run, thus potentially saving
execution time overall.</p>
<p>When the run-time executes the call to the hello system task, the
“hello_calltf” function is invoked in the loaded module, and thus the output
is generated. The “calltf” function is called at run time when the Verilog
code actually executes the system task. This is where the active code of the
task belongs.</p>
</section>
<section id="system-function-return-types">
<h2>System Function Return Types<a class="headerlink" href="#system-function-return-types" title="Link to this heading"></a></h2>
<p>Icarus Verilog supports system functions as well as system tasks, but there is
a complication. Notice how the module that you compile is only loaded by the
“vvp” program. This is mostly not an issue, but elaboration of expressions
needs to keep track of types, so the main compiler needs to know the return
type of functions.</p>
<p>Starting with Icarus Verilog v11, the solution is quite simple. The names and
locations of the user’s VPI modules can be passed to the compiler via the
“iverilog” -m and -L flags and the IVERILOG_VPI_MODULE_PATH environment
variable. The compiler will load and analyse the specified modules to
automatically determine any function return types. The compiler will also
automatically pass the names and locations of the specified modules to the
“vvp” program, so that they don’t need to be specified again on the “vvp”
command line.</p>
<p>For Icarus Verilog versions prior to v11, the solution requires that the
developer of a module include the table in a form that the compiler can
read. The System Function Table file carries this information. A simple
example looks like this:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span><span data-line="1"># Example sft declarations of some common functions
</span><span data-line="2">$random vpiSysFuncInt
</span><span data-line="3">$bitstoreal vpiSysFuncReal
</span><span data-line="4">$realtobits vpiSysFuncSized 64 unsigned
</span></pre></div>
</div>
<p>This demonstrates the format of the file and support types. Each line contains
a comment (starts with “#”) or a type declaration for a single function. The
declaration starts with the name of the system function (including the leading
“$”) and ends with the type. The supported types are:</p>
<ul class="simple">
<li><p>vpiSysFuncInt</p></li>
<li><p>vpiSysFuncReal</p></li>
<li><p>vpiSysFuncSized &lt;wid&gt; &lt;signed|unsigned&gt;</p></li>
</ul>
<p>Any functions that do not have an explicit type declaration in an SFT file are
implicitly taken to be “vpiSysFuncSized 32 unsigned”.</p>
<p>The module author provides, along with the “.vpi” file that is the module, a
“.sft” that declares all the function return types. For example, if the file
is named “example.sft”, pass it to the “iverilog” command line or in the
command file exactly as if it were an ordinary source file.</p>
</section>
<section id="cadence-pli-modules">
<h2>Cadence PLI Modules<a class="headerlink" href="#cadence-pli-modules" title="Link to this heading"></a></h2>
<p>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. In addition, a 64-bit
version of vvp can only load 64-bit PLI1 applications, etc.</p>
<p>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”:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span><span data-line="1">% vvp -mcadpli a.out -cadpli=./product.so:my_boot
</span></pre></div>
</div>
<p>The “-mcadpli” argument causes vvp to load the cadpli.vpl library module. This
activates the -cadpli= argument interpreter. The -cadpli=&lt;module&gt;:&lt;boot_func&gt;
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.</p>
<p>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.</p>
</section>
<section id="other-references">
<h2>Other References<a class="headerlink" href="#other-references" title="Link to this heading"></a></h2>
<p>Since the above only explains how to get PLI/VPI working with Icarus Verilog,
here are some references to material to help with the common aspects of
PLI/VPI.</p>
<ul class="simple">
<li><p>Principles of Verilog PLI by Swapnajit Mittra. ISBN 0-7923-8477-6</p></li>
<li><p>The Verilog PLI Handbook by Stuart Sutherland. ISBN 0-7923-8489-X</p></li>
</ul>
</section>
</section>
</article><button class="back-to-top" type="button">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
<path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8v12z"></path>
</svg>
<span>Back to top</span>
</button><div class="navigation flex print:hidden"><div class="navigation-prev">
<a href="waveform_viewer.html">
<i class="i-lucide chevron-left"></i>
<div class="page-info">
<span>Previous</span><div class="title">Viewing Waveforms</div></div>
</a>
</div><div class="navigation-next">
<a href="icarus_verilog_extensions.html">
<div class="page-info">
<span>Next</span>
<div class="title">Icarus Verilog Extensions</div>
</div>
<i class="i-lucide chevron-right"></i>
</a>
</div></div></div>
</div>
</main>
</div>
<footer class="sy-foot">
<div class="sy-foot-inner sy-container mx-auto">
<div class="sy-foot-reserved md:flex justify-between items-center">
<div class="sy-foot-copyright"><p>2024-2026, Stephen Williams</p>
<p>
Made with
<a href="https://www.sphinx-doc.org/">Sphinx</a> and
<a href="https://shibuya.lepture.com">Shibuya theme</a>.
</p>
</div>
<div class="sy-foot-socials">
<a href="https://github.com/steveicarus/iverilog" aria-label="GitHub">
<iconify-icon icon="simple-icons:github"></iconify-icon>
</a></div>
</div>
</div>
</footer>
<script src="../_static/documentation_options.js?v=5929fcd5"></script>
<script src="../_static/doctools.js?v=9bcbadda"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="../_static/shibuya.js?v=cac61aee"></script></body>
</html>
Reference in New Issue View Git Blame Copy Permalink