doc/readme.html in ruby-vpi-16.0.1 vs doc/readme.html in ruby-vpi-17.0.0

- old
+ new

@@ -6,101 +6,85 @@ <link rel="stylesheet" type="text/css" href="print.css" media="print" /> <link rel="alternate" type="application/rss+xml" href="http://ruby-vpi.rubyforge.org/doc/rss.xml" title="RSS feed for this project." /> <title>Ruby-VPI: Ruby interface to Verilog VPI</title> </head> <body> - <style type="text/css"> - body { - margin-left: 275px; - padding-right: 1em; - } + + <div id="body"><div style="float: right">Version 17.0.0</div> +<h1 style="padding-top: 0">Ruby-VPI</h1> - #resources { - position: absolute; - left: 0; - top: 0; - width: 200px; - padding: 1em; - - border: thin solid red; - border-left: none; - border-top: none; - background-color: snow; - } - - #resources li { - margin-top: 1em; - margin-left: -1em; - } - - #resources h2 { - display: none; - } -</style> - - <h1 style="margin-top: 0;"><a id="Ruby-VPI" href="#a-607628178">1</a> &nbsp; Ruby-VPI</h1> - - <p><a href="http://www.ruby-lang.org"><img src="images/ruby/logo-reflection.png" alt="Logo of the Ruby programming language" style="margin: 0; margin-left: 2em; float: right"/></a></p> <p>Ruby-VPI is a platform for unit testing, rapid prototyping, and systems integration of Verilog modules through the <a href="http://www.ruby-lang.org">Ruby programming language</a>. It lets you:</p> <ul> - <li>Access the <em>entire</em> <a href="http://ieeexplore.ieee.org/xpl/standardstoc.jsp?isnumber=33945"><span class="caps">IEEE 1364</span>-2005 Verilog <span class="caps">VPI</span></a> interface from Ruby.</li> + <li>Access the <em>entire</em> <a href="http://ieeexplore.ieee.org/xpl/standardstoc.jsp?isnumber=33945"><span class="caps">IEEE 1364</span>-2005 Verilog VPI</a> interface from Ruby.</li> <li>Create complex Verilog test benches easily and wholly in Ruby.</li> <li>Apply agile software development practices to develop hardware.</li> - <li>Perform <a href="http://ruby-vpi.rubyforge.org/papers/masters_thesis.html">specification-driven functional verification</a> (<a href="http://ruby-vpi.rubyforge.org/papers/masters_thesis.pdf"><span class="caps">PDF</span> version</a>).</li> + <li>Perform <a href="http://ruby-vpi.rubyforge.org/papers/masters_thesis.html">specification-driven functional verification</a> (<a href="http://ruby-vpi.rubyforge.org/papers/masters_thesis.pdf">PDF version</a>).</li> </ul> <p>Ruby-VPI is <a href="http://en.wikipedia.org/wiki/Open_source_software">open source software</a> released under <a href="#intro.license">this license</a>.</p> -<div id="resources"> + <p> + <hr style="display: none"/> - <h2><a id="Resources" href="#a-607629158">1.1</a> &nbsp; Resources</h2> + <div id="resources" class="section"> + <h1 class="title"> + <a href="#a-607522818">1</a> + &nbsp; - <p class="title">Records</p> + Resources + </h1> + + <div id="Records" class="paragraph"> + <p class="title">Records</p> + <a type="application/rss+xml" href="http://ruby-vpi.rubyforge.org/doc/rss.xml"><img src="images/feed-icon-28x28.png" alt="RSS feed for release notifications" style="float: right"/></a> - <p><a type="application/rss+xml" href="http://ruby-vpi.rubyforge.org/doc/rss.xml"><img src="images/feed-icon-28x28.png" alt="RSS feed for release notifications" style="float: right"/></a></p> - <ul> - <li><a href="history.html">What&#8217;s new?</a> - &#8211; a record of all release notes.</li> + <li><a href="history.html">What&#8217;s new</a> + &#8211; a history of all release notes.</li> <li><a href="memo.html">Plans</a> &#8211; pending tasks for future releases.</li> <li><a href="http://ruby-vpi.rubyforge.org/talks/">Talks</a> &#8211; materials from presentations and seminars.</li> <li><a href="http://ruby-vpi.rubyforge.org/papers/">Papers</a> &#8211; research publications.</li> + <li><a href="http://ruby-vpi.rubyforge.org/papers/masters_thesis.html#tth_sEc5.2">Motivation</a> + &#8211; why does Ruby-VPI exist?</li> </ul> + </div> + - - <p class="title">Documentation</p> - - + <div id="Documentation" class="paragraph"> + <p class="title">Documentation</p> + <ul> + <li><a href="manual.html">User manual</a> + &#8211; complete documentation for users. <em>Start here!</em> <ul> <li><a href="manual.html#usage.tutorial">Tutorial</a> &#8211; learn how to use Ruby-VPI quickly.</li> - <li><a href="manual.html">Manual</a> - &#8211; complete documentation for users. <em>Start here!</em></li> + </ul> + </li> <li><a href="../ref/">Reference</a> - &#8211; <span class="caps">API</span> documentation for Ruby libraries and C extension.</li> + &#8211; API documentation for Ruby libraries and C extension.</li> </ul> + </div> + - - <p class="title">Facilities</p> - - - <ul> + <div id="Facilities" class="paragraph"> + <p class="title">Facilities</p> + <ul> <li><a href="http://rubyforge.org/frs/?group_id=1339">Downloads</a> - &#8211; obtain release packages.</li> + &#8211; obtain release packages</li> <li><a href="http://ruby-vpi.rubyforge.org/src/ruby-vpi">Source code</a> &#8211; browse online or obtain with <a href="http://darcs.net">Darcs</a>.</li> <li><a href="http://rubyforge.org/forum/?group_id=1339">Forums</a> &#8211; discuss things and ask questions.</li> <li><a href="http://rubyforge.org/tracker/?group_id=1339">Bugs</a> @@ -110,31 +94,43 @@ <li><a href="http://rubyforge.org/tracker/?group_id=1339">Requests</a> &#8211; request new features or get support.</li> <li><a href="http://rubyforge.org/projects/ruby-vpi">Project portal</a> &#8211; hosted generously by <a href="http://rubyforge.org">RubyForge</a>.</li> </ul> + </div> + + </div> + </p> -</div> - <h2 ><a id="intro.features" href="#a-607630098">1.2</a> &nbsp; Features</h2> + <p> + <hr style="display: none"/> + <div id="intro.features" class="section"> + <h1 class="title"> + <a href="#a-607537108">2</a> - <p class="title">Portable</p> + &nbsp; + Features + </h1> - <ul> - <li>Supports the <em>entire</em> <a href="http://ieeexplore.ieee.org/xpl/standardstoc.jsp?isnumber=33945"><span class="caps">IEEE 1364</span>-2005 Verilog <span class="caps">VPI</span></a> standard.</li> + + <div id="Portable" class="paragraph"> + <p class="title">Portable</p> + <ul> + <li>Supports the <em>entire</em> <a href="http://ieeexplore.ieee.org/xpl/standardstoc.jsp?isnumber=33945"><span class="caps">IEEE 1364</span>-2005 Verilog VPI</a> standard.</li> <li>Works with all <a href="#intro.reqs">major Verilog simulators</a> available today.</li> <li>Compiled <em>just once</em> during <a href="manual.html#setup.installation">installation</a> and used forever!</li> </ul> + </div> + - - <p class="title">Agile</p> - - - <ul> + <div id="Agile" class="paragraph"> + <p class="title">Agile</p> + <ul> <li>Enables <a href="http://agilemanifesto.org/">agile practices</a> such as <ul> <li><a href="http://www.testdriven.com">test-driven</a> development</li> <li><a href="http://behaviour-driven.org">behavior-driven</a> development</li> <li><a href="manual.html#usage.tutorial.implement-proto">rapid prototyping</a> for design exploration</li> @@ -148,16 +144,16 @@ <li><a href="manual.html#usage.tutorial.specification">Specifications</a> are readable, portable, and <em>executable</em>.</li> <li>The <a href="manual.html#usage.tools.generate-test">automated test generator</a> helps you accomodate design changes with <em>minimal</em> effort.</li> <li>There is absolutely <em>no compiling</em>!</li> </ul></li> </ul> + </div> + - - <p class="title">Powerful</p> - - - <ul> + <div id="Powerful" class="paragraph"> + <p class="title">Powerful</p> + <ul> <li>Inherits the <a href="http://www.ruby-lang.org/en/about/">power and elegance</a> of Ruby: <ul> <li>Unlimited length integers</li> <li>Regular expressions</li> <li>Multi-threading</li> @@ -169,98 +165,98 @@ <ul> <li>Uses <a href="http://rubyforge.org/projects/ruby-debug/">ruby-debug</a> for <a href="manual.html#usage.debugger">interactive debugging</a>.</li> <li>Uses <a href="http://eigenclass.org/hiki.rb?rcov">rcov</a> for test <a href="manual.html#usage.test-runner.env-vars">coverage analysis and report generation</a>.</li> </ul> + </div> + + </div> + </p> - <h2 ><a id="intro.reqs" href="#a-607631128">1.3</a> &nbsp; Requirements</h2> + <p> + <hr style="display: none"/> - <p>The following software is necessary in order to use Ruby-VPI.</p> + <div id="intro.reqs" class="section"> + <h1 class="title"> + <a href="#a-607549738">3</a> + &nbsp; - <p class="title">Verilog simulator</p> + Requirements + </h1> + <p>The following software is necessary in order to use Ruby-VPI.</p> - <p>Ruby-VPI is known to work with the following simulators. However, you should be able to use it with any Verilog simulator that supports <span class="caps">VPI</span>.</p> + <p> + <div id="Verilog_simulator" class="paragraph"> + <p class="title">Verilog simulator</p> + Ruby-VPI is known to work with the following simulators. However, you should be able to use it with any Verilog simulator that supports VPI. - <ul> - <li><a href="http://www.synopsys.com/products/simulation/simulation.html">Synopsys <span class="caps">VCS</span></a> - &#8211; any version that supports the <tt>-load</tt> option is acceptable.</li> - </ul> - <ul> - <li><a href="http://www.model.com">Mentor Modelsim</a> + <li><a href="http://www.synopsys.com/products/simulation/simulation.html">Synopsys VCS</a> + &#8211; any version that supports the <tt>-load</tt> option is acceptable.</li> + <li><a href="http://www.model.com">Mentor Modelsim</a> &#8211; any version that supports the <tt>-pli</tt> option is acceptable.</li> - </ul> - - - <ul> - <li><a href="http://www.cadence.com/products/functional_ver/nc-verilog/">Cadence NC-Sim / NC-Verilog</a> + <li><a href="http://www.cadence.com/products/functional_ver/nc-verilog/">Cadence NC-Sim / NC-Verilog</a> &#8211; any version that supports the <tt>+loadvpi</tt> option is acceptable.</li> - </ul> - - - <ul> - <li><a href="http://www.pragmatic-c.com/gpl-cver/"><span class="caps">GPL</span> Cver</a> + <li><a href="http://www.pragmatic-c.com/gpl-cver/">GPL Cver</a> &#8211; version 2.11a or newer is acceptable.</li> + <li><a href="http://www.icarus.com/eda/Verilog/">Icarus Verilog</a> + &#8211; version 0.8 is <em>mostly</em> acceptable&#8212;you <strong>will not</strong> be able to <a href="manual.html#background.org.vpi.util">access child handles through method calls</a>. The reason for this limitation is explained <a href="manual.html#problems.ivl.vpi_handle_by_name.absolute-paths">in the user manual</a>.</li> </ul> + </div> + - - <ul> - <li><a href="http://www.icarus.com/eda/Verilog/">Icarus Verilog</a> - &#8211; version 0.8 is <em>mostly</em> acceptable&#8212;you <strong>will not</strong> be able to <a href="manual.html#background.org.vpi.util">access child handles through method calls</a>. The reason for this limitation is explained <a href="#problems.ivl.vpi_handle_by_name.absolute-paths">in the user manual</a>.</li> - </ul> - - - <p class="title">Compilers</p> - - - <ul> + <div id="Compilers" class="paragraph"> + <p class="title">Compilers</p> + <ul> <li><a href="http://en.wikipedia.org/wiki/Make">make</a> &#8211; any flavor should be acceptable.</li> - </ul> - - - <ul> - <li>C compiler - &#8211; the <a href="http://www.gnu.org/software/gcc/" title="GCC"><span class="caps">GNU</span> Compiler Collection</a> is preferred, but any C compiler should be acceptable.</li> - </ul> - - - <ul> - <li><a href="http://www.ruby-lang.org">Ruby</a> + <li>C compiler + &#8211; the <a href="http://www.gnu.org/software/gcc/" title="GCC">GNU Compiler Collection</a> is preferred, but any C compiler should be acceptable.</li> + <li><a href="http://www.ruby-lang.org">Ruby</a> &#8211; version 1.8 or newer, including header and linkable object files for building extensions, is necessary. You can install Ruby by following <a href="http://www.rubygarden.org/faq/section/show/3">these instructions</a>.</li> </ul> + </div> + - - <p class="title">Libraries</p> - - - <ul> - <li><a href="http://en.wikipedia.org/wiki/Pthreads" title="pthreads"><span class="caps">POSIX</span> threads</a> + <div id="Libraries" class="paragraph"> + <p class="title">Libraries</p> + <ul> + <li><a href="http://en.wikipedia.org/wiki/Pthreads" title="pthreads">POSIX threads</a> &#8211; header and linkable object files, and operating system support for this library are necessary.</li> + <li><a href="http://rubyforge.org/frs/?group_id=126">RubyGems</a> + &#8211; any recent version should be acceptable. You can install RubyGems by following <a href="http://www.rubygems.org/read/chapter/3">these instructions</a>.</li> </ul> + </div> + </p> + </div> + </p> - <ul> - <li><a href="http://rubyforge.org/frs/?group_id=126">RubyGems</a> - &#8211; any recent version should be acceptable. You can install RubyGems by following <a href="http://www.rubygems.org/read/chapter/3">these instructions</a>.</li> - </ul> + <p> + <hr style="display: none"/> - <h2 ><a id="intro.applications" href="#a-607632078">1.4</a> &nbsp; Applications</h2> + <div id="intro.applications" class="section"> + <h1 class="title"> + <a href="#a-607552458">4</a> + &nbsp; - <p>Examples of tasks that can be performed with Ruby-VPI are:</p> + Applications + </h1> + Examples of tasks that can be performed with Ruby-VPI are: + <ul> - <li>From the second edition of <a href="http://www.sutherland-hdl.com/publications.html"><em>The Verilog <span class="caps">PLI</span> Handbook</em></a>: + <li>From the second edition of <a href="http://www.sutherland-hdl.com/publications.html"><em>The Verilog PLI Handbook</em></a>: <ul> <li>C language bus-functional models</li> <li>Reading test vector files</li> <li>Delay calculation</li> <li>Custom output displays</li> @@ -282,108 +278,170 @@ <li>Interactive logic simulation</li> <li>Building a distributed simulation</li> </ul></li> </ul> + </div> + </p> - <h2 ><a id="intro.appetizers" href="#a-607633188">1.5</a> &nbsp; Appetizers</h2> + <p> + <hr style="display: none"/> - <p>Here is a tiny sampling of code to whet your appetite. See <a href="manual.html#usage.tutorial">the tutorial</a> for more samples.</p> + <div id="intro.appetizers" class="section"> + <h1 class="title"> + <a href="#a-607555198">5</a> + &nbsp; + Appetizers + </h1> + + <p>Here is a tiny sampling of code to whet your appetite. See <a href="manual.html#usage.tutorial">the tutorial</a> for more samples.</p> + + <ul> <li>Assign the value 2<sup>2048</sup> to a register:</li> </ul> <blockquote> - <p><code class="code">some_register.intVal = <span style="color:#00D; font-weight:bold">2</span> ** <span style="color:#00D; font-weight:bold">2048</span></code></p> + <p><code class="code">your_register.intVal = <span style="color:#00D; font-weight:bold">2</span> ** <span style="color:#00D; font-weight:bold">2048</span></code></p> </blockquote> <ul> <li>Check if all nets in a module are at high impedance:</li> </ul> <blockquote> - <p><code class="code">some_module.all_net? { |net| net.z? }</code></p> + <p><code class="code">your_module.all_net? { |net| net.z? }</code></p> </blockquote> <ul> <li>See a register&#8217;s path, width, and location (file &#38; line number):</li> </ul> <blockquote> - <p><code class="code">puts some_register</code></p> + <p><code class="code">puts your_register</code></p> </blockquote> <ul> - <li>Simulate fifteen clock cycles:</li> + <li>Access the first five elements in a memory:</li> </ul> <blockquote> - <p><code class="code"><span style="color:#00D; font-weight:bold">15</span>.times { simulate }</code></p> + <p><code class="code">your_memory.memoryWord_a[<span style="color:#00D; font-weight:bold">0</span>..<span style="color:#00D; font-weight:bold">4</span>]</code></p> </blockquote> - <h2 ><a id="intro.license" href="#a-607634248">1.6</a> &nbsp; License</h2> + <ul> + <li>Clear a memory by filling it with zeroes:</li> + </ul> - <p>Copyright&#169; 2006-2007 Suraj N. Kurapati</p> + <blockquote> + <p><code class="code">your_memory.each_memoryWord {|w| w.intVal = <span style="color:#00D; font-weight:bold">0</span>}</code></p> + </blockquote> + </div> + </p> - <p>Permission is hereby granted, free of charge, to any person obtaining a -copy of this software and associated documentation files (the &#8220;Software&#8221;), -to deal in the Software without restriction, including without limitation the -rights to use, copy, modify, merge, publish, distribute, sublicense, and/or -sell copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions:</p> + <p> + <hr style="display: none"/> - <p>All copies and portions of the Software (together the &#8220;Derivatives&#8221;) and -their corresponding machine-readable source code (the &#8220;Code&#8221;) must include the -above copyright notice and this permission notice. The Code must reflect all -modifications made to the Derivatives. The Derivatives must be distributed -either with the Code or, if the Code is obtainable for no more than the cost -of distribution plus a nominal fee, with information on how to obtain the Code.</p> + <div id="intro.license" class="section"> + <h1 class="title"> + <a href="#a-607558088">6</a> + &nbsp; - <p><span class="caps">THE SOFTWARE IS PROVIDED</span> &#8220;AS IS&#8221;, <span class="caps">WITHOUT WARRANTY OF ANY KIND</span>, EXPRESS OR -<span class="caps">IMPLIED</span>, INCLUDING <span class="caps">BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY</span>, -<span class="caps">FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT</span>. <span class="caps">IN NO EVENT SHALL</span> -<span class="caps">THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM</span>, DAMAGES <span class="caps">OR OTHER</span> -<span class="caps">LIABILITY</span>, WHETHER <span class="caps">IN AN ACTION OF CONTRACT</span>, TORT <span class="caps">OR OTHERWISE</span>, ARISING <span class="caps">FROM</span>, -<span class="caps">OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN</span> -<span class="caps">THE SOFTWARE</span>.</p> + License + </h1> + <p>Copyright 2006 Suraj N. Kurapati &lt;snk@gna.org&gt;</p> - <h2 ><a id="intro.related-works" href="#a-607635258">1.7</a> &nbsp; Related works</h2> + <p>Permission is hereby granted, free of charge, to any person obtaining a copy of +this software and associated documentation files (the &quot;Software&quot;), to deal in +the Software without restriction, including without limitation the rights to +use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of +the Software, and to permit persons to whom the Software is furnished to do so, +subject to the following conditions:</p> - <ul> - <li><a href="http://jove.sourceforge.net"><span class="caps">JOVE</span></a> is a Java interface to <span class="caps">VPI</span>.</li> - <li><a href="http://teal.sourceforge.net">Teal</a> is a C++ interface to <span class="caps">VPI</span>.</li> - <li><a href="http://embedded.eecs.berkeley.edu/Alumni/pinhong/scriptEDA/">ScriptEDA</a> is a Perl, Python, and Tcl interface to <span class="caps">VPI</span>.</li> - <li><a href="http://rhdl.rubyforge.org"><span class="caps">RHDL</span></a> is a hardware description and verification language based on Ruby.</li> + + <p>1. All modified and unmodified copies and substantial portions of the Software + (the &quot;Derivatives&quot;) and their corresponding machine-readable source code (the + &quot;Code&quot;) must include the above copyright notice and this permission notice.</p> + + + <p>2. Upon distribution, the Derivatives must be accompanied either by the Code or, + if the Code is obtainable for no more than the cost of distribution plus a + nominal fee, by information on how to obtain the Code.</p> + + + <p><span class="caps">THE SOFTWARE IS PROVIDED</span> &quot;AS IS&quot;, <span class="caps">WITHOUT WARRANTY OF ANY KIND</span>, EXPRESS OR +IMPLIED, INCLUDING <span class="caps">BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY</span>, FITNESS +<span class="caps">FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT</span>. IN <span class="caps">NO EVENT SHALL THE AUTHORS OR</span> +<span class="caps">COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM</span>, DAMAGES <span class="caps">OR OTHER LIABILITY</span>, WHETHER +<span class="caps">IN AN ACTION OF CONTRACT</span>, TORT <span class="caps">OR OTHERWISE</span>, ARISING FROM, OUT <span class="caps">OF OR IN</span> +<span class="caps">CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE</span>.</p> + + </div> + </p> + + + <p> + <hr style="display: none"/> + + <div id="intro.related-works" class="section"> + <h1 class="title"> + <a href="#a-607563868">7</a> + + &nbsp; + + Related works + </h1> + + <ul> + <li><a href="http://jove.sourceforge.net">JOVE</a> is a Java interface to VPI.</li> + <li><a href="http://teal.sourceforge.net">Teal</a> is a C++ interface to VPI.</li> + <li><a href="http://embedded.eecs.berkeley.edu/Alumni/pinhong/scriptEDA/">ScriptEDA</a> is a Perl, Python, and Tcl interface to VPI.</li> + <li><a href="http://rhdl.rubyforge.org">RHDL</a> is a hardware description and verification language based on Ruby.</li> <li><a href="http://myhdl.jandecaluwe.com">MyHDL</a> is a hardware description and verification language based on Python, which features conversion to Verilog and co-simulation.</li> </ul> - <h3 ><a id="intro.related-works.pli" href="#a-607636448">1.7.1</a> &nbsp; Ye olde <span class="caps">PLI</span></h3> + <p> + <hr style="display: none"/> + <div id="intro.related-works.pli" class="section"> + <h2 class="title"> + <a href="#a-607560688">7.1</a> - <p>The following projects utilize the archaic <strong>tf</strong> and <strong>acc</strong> PLI interfaces, which have been officially deprecated in <span class="caps">IEEE</span> Std 1364-2005.</p> + &nbsp; + Ye olde PLI + </h2> + The following projects utilize the archaic <strong>tf</strong> and <strong>acc</strong> PLI interfaces, which have been officially deprecated in IEEE Std 1364-2005. + + <ul> - <li><a href="http://www.nelsim.com">ScriptSim</a> is a Perl, Python, and Tcl/Tk interface to <span class="caps">PLI</span>.</li> - <li><a href="http://www.veripool.com/verilog-pli.html">Verilog::Pli</a> is a Perl interface to <span class="caps">PLI</span>.</li> - <li><a href="http://www.time-rover.com/jpli/"><span class="caps">JPLI</span></a> is a proprietary Java interface to <span class="caps">PLI</span>.</li> + <li><a href="http://www.nelsim.com">ScriptSim</a> is a Perl, Python, and Tcl/Tk interface to PLI.</li> + <li><a href="http://www.veripool.com/verilog-pli.html">Verilog::Pli</a> is a Perl interface to PLI.</li> </ul> - </body> + + </div> + </p> + + </div> + </p></div> + + </body> </html>