RubyGems - ruby-vpi - Versions diffs - 11.1.0 → 11.1.1 - Mend

ruby-vpi 11.1.0 → 11.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (292) hide show

data/Rakefile +8 -37
data/bin/generate_test_tpl/bench.v +1 -1
data/doc/{src/LICENSE → LICENSE} +0 -0
data/doc/Rakefile +39 -14
data/doc/common.css +144 -0
data/doc/common.tpl +49 -0
data/doc/figures/figures.dia +1589 -0
data/doc/history.erb +18 -0
data/doc/history.html +1726 -0
data/doc/history.rb +14 -0
data/doc/history.yml +686 -0
data/doc/images/{COPYING → LICENSE} +0 -0
data/doc/intro.inc +48 -0
data/doc/lib/doc_format.rb +62 -0
data/doc/lib/doc_proxy.rb +160 -0
data/doc/lib/erb_content.rb +67 -0
data/doc/lib/erb_proxy.rb +48 -0
data/doc/manual.erb +768 -0
data/doc/manual.html +2107 -0
data/doc/manual.rb +5 -0
data/{MEMO → doc/memo.erb} +0 -0
data/{memo.part.html → doc/memo.html} +38 -5
data/doc/readme.erb +36 -0
data/doc/readme.html +171 -0
data/index.html +1 -0
data/lib/ruby-vpi/float.rb +52 -0
data/lib/ruby-vpi/rspec.rb +6 -1
data/lib/ruby-vpi/verilog_parser.rb +4 -5
data/ref/c/annotated.html +1 -6
data/ref/c/common_8h.html +1 -1
data/ref/c/files.html +1 -3
data/ref/c/functions.html +24 -44
data/ref/c/functions_vars.html +24 -44
data/ref/c/globals.html +5 -211
data/ref/c/globals_0x63.html +32 -49
data/ref/c/globals_0x65.html +3 -10
data/ref/c/globals_0x66.html +3 -20
data/ref/c/globals_0x70.html +19 -26
data/ref/c/globals_0x72.html +4 -15
data/ref/c/globals_0x73.html +13 -199
data/ref/c/globals_0x74.html +2 -9
data/ref/c/globals_0x76.html +415 -426
data/ref/c/globals_0x78.html +3 -10
data/ref/c/globals_defs.html +30 -35
data/ref/c/globals_defs_0x65.html +2 -7
data/ref/c/globals_defs_0x70.html +3 -8
data/ref/c/globals_defs_0x76.html +413 -420
data/ref/c/globals_defs_0x78.html +2 -7
data/ref/c/globals_enum.html +1 -1
data/ref/c/globals_eval.html +1 -1
data/ref/c/globals_func.html +14 -173
data/ref/c/globals_type.html +26 -29
data/ref/c/globals_vars.html +4 -88
data/ref/c/index.html +1 -1
data/ref/c/relay_8c.html +1 -1
data/ref/c/relay_8h.html +1 -1
data/ref/c/structrelay____RubyOptions____def.html +1 -1
data/ref/c/structt__cb__data.html +6 -23
data/ref/c/structt__vpi__delay.html +3 -20
data/ref/c/structt__vpi__error__info.html +3 -71
data/ref/c/structt__vpi__strengthval.html +3 -3
data/ref/c/structt__vpi__systf__data.html +12 -46
data/ref/c/structt__vpi__time.html +3 -3
data/ref/c/structt__vpi__value.html +3 -113
data/ref/c/structt__vpi__vecval.html +3 -3
data/ref/c/structt__vpi__vlog__info.html +3 -54
data/ref/c/swig_8c.html +2 -2
data/ref/c/swig_8h.html +1 -1
data/ref/c/verilog_8h.html +1 -1
data/ref/c/vlog_8c.html +1 -1
data/ref/c/vlog_8h.html +1 -1
data/ref/c/vpi__user_8h.html +16 -16
data/ref/ruby/classes/ERB.html +5 -5
data/ref/ruby/classes/ERB.src/{M000034.html → M000036.html} +0 -0
data/ref/ruby/classes/FileUtils.html +10 -10
data/ref/ruby/classes/FileUtils.src/{M000081.html → M000083.html} +0 -0
data/ref/ruby/classes/FileUtils.src/{M000082.html → M000084.html} +0 -0
data/ref/ruby/classes/Float.html +140 -0
data/ref/ruby/classes/Float.src/M000031.html +19 -0
data/ref/ruby/classes/RDoc.html +5 -5
data/ref/ruby/classes/RDoc.src/{M000095.html → M000097.html} +0 -0
data/ref/ruby/classes/RubyVpi.html +10 -10
data/ref/ruby/classes/RubyVpi.src/{M000083.html → M000085.html} +0 -0
data/ref/ruby/classes/RubyVpi.src/{M000084.html → M000086.html} +0 -0
data/ref/ruby/classes/String.html +33 -10
data/ref/ruby/classes/String.src/M000033.html +28 -5
data/ref/ruby/classes/String.src/M000034.html +18 -0
data/ref/ruby/classes/String.src/M000035.html +36 -0
data/ref/ruby/classes/Template.html +5 -5
data/ref/ruby/classes/Template.src/{M000031.html → M000032.html} +0 -0
data/ref/ruby/classes/VerilogParser/Module.src/M000006.html +9 -8
data/ref/ruby/classes/VerilogParser/Module/Parameter.src/M000011.html +5 -7
data/ref/ruby/classes/VerilogParser/Module/Port.src/M000007.html +7 -7
data/ref/ruby/classes/VerilogParser/Module/Port.src/M000008.html +4 -4
data/ref/ruby/classes/VerilogParser/Module/Port.src/M000009.html +4 -4
data/ref/ruby/classes/VerilogParser/Module/Port.src/M000010.html +4 -4
data/ref/ruby/classes/Vpi/Handle.html +46 -46
data/ref/ruby/classes/Vpi/Handle.src/M000087.html +5 -9
data/ref/ruby/classes/Vpi/Handle.src/M000088.html +5 -31
data/ref/ruby/classes/Vpi/Handle.src/M000089.html +9 -74
data/ref/ruby/classes/Vpi/Handle.src/M000090.html +31 -17
data/ref/ruby/classes/Vpi/Handle.src/M000091.html +74 -11
data/ref/ruby/classes/Vpi/Handle.src/M000092.html +30 -0
data/ref/ruby/classes/Vpi/Handle.src/M000093.html +11 -55
data/ref/ruby/classes/Vpi/Handle.src/M000095.html +68 -0
data/ref/ruby/classes/Vpi/Handle/Property.html +5 -5
data/ref/ruby/classes/Vpi/Handle/Property.src/{M000094.html → M000096.html} +0 -0
data/ref/ruby/classes/XX/Document.html +45 -45
data/ref/ruby/classes/XX/Document.src/M000074.html +9 -7
data/ref/ruby/classes/XX/Document.src/M000075.html +7 -7
data/ref/ruby/classes/XX/Document.src/M000076.html +7 -9
data/ref/ruby/classes/XX/Document.src/M000077.html +7 -8
data/ref/ruby/classes/XX/Document.src/M000078.html +9 -8
data/ref/ruby/classes/XX/Document.src/M000079.html +8 -21
data/ref/ruby/classes/XX/Document.src/M000080.html +8 -85
data/ref/ruby/classes/XX/Document.src/M000081.html +34 -0
data/ref/ruby/classes/XX/Document.src/M000082.html +98 -0
data/ref/ruby/classes/XX/HTML4.html +5 -5
data/ref/ruby/classes/XX/HTML4.src/{M000036.html → M000038.html} +0 -0
data/ref/ruby/classes/XX/HTML4/Strict.html +5 -5
data/ref/ruby/classes/XX/HTML4/Strict.src/{M000038.html → M000040.html} +0 -0
data/ref/ruby/classes/XX/HTML4/Transitional.html +5 -5
data/ref/ruby/classes/XX/HTML4/Transitional.src/{M000037.html → M000039.html} +0 -0
data/ref/ruby/classes/XX/Markup.html +5 -5
data/ref/ruby/classes/XX/Markup.src/{M000043.html → M000045.html} +0 -0
data/ref/ruby/classes/XX/Markup/ClassMethods.html +40 -40
data/ref/ruby/classes/XX/Markup/ClassMethods.src/M000046.html +9 -12
data/ref/ruby/classes/XX/Markup/ClassMethods.src/M000047.html +7 -7
data/ref/ruby/classes/XX/Markup/ClassMethods.src/M000048.html +12 -14
data/ref/ruby/classes/XX/Markup/ClassMethods.src/M000049.html +7 -7
data/ref/ruby/classes/XX/Markup/ClassMethods.src/M000050.html +14 -14
data/ref/ruby/classes/XX/Markup/ClassMethods.src/M000051.html +7 -9
data/ref/ruby/classes/XX/Markup/ClassMethods.src/M000052.html +27 -0
data/ref/ruby/classes/XX/Markup/ClassMethods.src/M000053.html +22 -0
data/ref/ruby/classes/XX/Markup/InstanceMethods.html +100 -100
data/ref/ruby/classes/XX/Markup/InstanceMethods.src/M000054.html +43 -18
data/ref/ruby/classes/XX/Markup/InstanceMethods.src/M000055.html +20 -35
data/ref/ruby/classes/XX/Markup/InstanceMethods.src/M000056.html +18 -7
data/ref/ruby/classes/XX/Markup/InstanceMethods.src/M000057.html +35 -18
data/ref/ruby/classes/XX/Markup/InstanceMethods.src/M000058.html +7 -19
data/ref/ruby/classes/XX/Markup/InstanceMethods.src/M000059.html +18 -19
data/ref/ruby/classes/XX/Markup/InstanceMethods.src/M000060.html +19 -15
data/ref/ruby/classes/XX/Markup/InstanceMethods.src/M000061.html +19 -10
data/ref/ruby/classes/XX/Markup/InstanceMethods.src/M000062.html +15 -13
data/ref/ruby/classes/XX/Markup/InstanceMethods.src/M000063.html +10 -7
data/ref/ruby/classes/XX/Markup/InstanceMethods.src/M000064.html +13 -7
data/ref/ruby/classes/XX/Markup/InstanceMethods.src/M000065.html +7 -7
data/ref/ruby/classes/XX/Markup/InstanceMethods.src/M000066.html +7 -7
data/ref/ruby/classes/XX/Markup/InstanceMethods.src/M000067.html +7 -7
data/ref/ruby/classes/XX/Markup/InstanceMethods.src/M000068.html +7 -8
data/ref/ruby/classes/XX/Markup/InstanceMethods.src/M000069.html +7 -7
data/ref/ruby/classes/XX/Markup/InstanceMethods.src/M000070.html +8 -7
data/ref/ruby/classes/XX/Markup/InstanceMethods.src/M000071.html +7 -7
data/ref/ruby/classes/XX/Markup/InstanceMethods.src/M000072.html +20 -0
data/ref/ruby/classes/XX/Markup/InstanceMethods.src/M000073.html +20 -0
data/ref/ruby/classes/XX/XHTML.html +5 -5
data/ref/ruby/classes/XX/XHTML.src/{M000039.html → M000041.html} +0 -0
data/ref/ruby/classes/XX/XHTML/Strict.html +5 -5
data/ref/ruby/classes/XX/XHTML/Strict.src/{M000041.html → M000043.html} +0 -0
data/ref/ruby/classes/XX/XHTML/Transitional.html +5 -5
data/ref/ruby/classes/XX/XHTML/Transitional.src/{M000040.html → M000042.html} +0 -0
data/ref/ruby/classes/XX/XML.html +5 -5
data/ref/ruby/classes/XX/XML.src/{M000035.html → M000037.html} +0 -0
data/ref/ruby/classes/XX/XMLish.html +5 -5
data/ref/ruby/classes/XX/XMLish.src/{M000042.html → M000044.html} +0 -0
data/ref/ruby/created.rid +1 -1
data/ref/ruby/files/lib/ruby-vpi/float_rb.html +101 -0
data/ref/ruby/files/lib/ruby-vpi/rspec_rb.html +1 -1
data/ref/ruby/files/lib/ruby-vpi/runner_rb.html +1 -1
data/ref/ruby/files/lib/ruby-vpi/verilog_parser_rb.html +1 -1
data/ref/ruby/fr_class_index.html +1 -0
data/ref/ruby/fr_file_index.html +1 -0
data/ref/ruby/fr_method_index.html +69 -67
data/samp/counter/counter.v +4 -4
data/samp/counter/counter_rspec_spec.rb +4 -8
data/samp/counter/counter_xunit_spec.rb +4 -8
metadata +112 -196
data/HEADER +0 -97
data/HISTORY +0 -687
data/README +0 -23
data/doc/background.html +0 -3
data/doc/background.methodology.html +0 -3
data/doc/background.organization.html +0 -10
data/doc/background.running-tests.html +0 -3
data/doc/background.terminology.html +0 -3
data/doc/gfdl-0.html +0 -18
data/doc/gfdl-1.html +0 -70
data/doc/gfdl-10.html +0 -15
data/doc/gfdl-2.html +0 -13
data/doc/gfdl-3.html +0 -31
data/doc/gfdl-4.html +0 -75
data/doc/gfdl-5.html +0 -20
data/doc/gfdl-6.html +0 -12
data/doc/gfdl-7.html +0 -16
data/doc/gfdl-8.html +0 -17
data/doc/gfdl-9.html +0 -9
data/doc/gfdl-addendum.html +0 -25
data/doc/gfdl.html +0 -11
data/doc/glossary.html +0 -3
data/doc/hacking.html +0 -3
data/doc/hacking.release-packages.html +0 -7
data/doc/images/ChangeLog +0 -27
data/doc/images/blank.png +0 -0
data/doc/images/callouts/1.png +0 -0
data/doc/images/callouts/10.png +0 -0
data/doc/images/callouts/11.png +0 -0
data/doc/images/callouts/12.png +0 -0
data/doc/images/callouts/13.png +0 -0
data/doc/images/callouts/14.png +0 -0
data/doc/images/callouts/15.png +0 -0
data/doc/images/callouts/2.png +0 -0
data/doc/images/callouts/3.png +0 -0
data/doc/images/callouts/4.png +0 -0
data/doc/images/callouts/5.png +0 -0
data/doc/images/callouts/6.png +0 -0
data/doc/images/callouts/7.png +0 -0
data/doc/images/callouts/8.png +0 -0
data/doc/images/callouts/9.png +0 -0
data/doc/images/callouts/ChangeLog +0 -15
data/doc/images/copyright +0 -55
data/doc/images/draft.png +0 -0
data/doc/images/toc-blank.png +0 -0
data/doc/images/toc-minus.png +0 -0
data/doc/images/toc-plus.png +0 -0
data/doc/index.html +0 -4
data/doc/introduction.html +0 -3
data/doc/introduction.license.html +0 -3
data/doc/introduction.manifest.html +0 -3
data/doc/introduction.related-works.html +0 -3
data/doc/introduction.resources.html +0 -3
data/doc/manual.txt +0 -1852
data/doc/problem.ivl.html +0 -18
data/doc/problems.html +0 -3
data/doc/problems.ruby.html +0 -3
data/doc/problems.vsim.html +0 -3
data/doc/setup.html +0 -3
data/doc/setup.installation.html +0 -9
data/doc/setup.maintenance.html +0 -3
data/doc/setup.reqs.html +0 -3
data/doc/src/figures.dia +0 -0
data/doc/src/license.xml +0 -446
data/doc/src/manual.xml +0 -1824
data/doc/src/manual.xsl +0 -23
data/doc/src/shared.dtd +0 -62
data/doc/styles/manual.css +0 -91
data/doc/usage.examples.html +0 -3
data/doc/usage.html +0 -3
data/doc/usage.tools.html +0 -9
data/doc/usage.tutorial.html +0 -189
data/header.html +0 -95
data/header.part.html +0 -95
data/history.html +0 -1442
data/history.part.html +0 -1346
data/memo.html +0 -211
data/readme.html +0 -138
data/readme.part.html +0 -42
data/ref/c/globals_0x62.html +0 -62
data/ref/c/globals_0x67.html +0 -64
data/ref/c/globals_0x69.html +0 -62
data/ref/c/globals_0x6c.html +0 -64
data/ref/c/globals_0x6d.html +0 -62
data/ref/c/globals_0x6e.html +0 -63
data/ref/c/globals_0x75.html +0 -63
data/ref/c/globals_defs_0x6c.html +0 -57
data/ref/c/globals_defs_0x6e.html +0 -56
data/ref/c/globals_defs_0x72.html +0 -57
data/ref/c/globals_defs_0x73.html +0 -164
data/ref/c/globals_defs_0x75.html +0 -56
data/ref/c/globals_func_0x66.html +0 -62
data/ref/c/globals_func_0x67.html +0 -55
data/ref/c/globals_func_0x69.html +0 -53
data/ref/c/globals_func_0x70.html +0 -53
data/ref/c/globals_func_0x72.html +0 -57
data/ref/c/globals_func_0x73.html +0 -114
data/ref/c/globals_func_0x76.html +0 -57
data/ref/c/structswig__cast__info.html +0 -98
data/ref/c/structswig__class.html +0 -115
data/ref/c/structswig__module__info.html +0 -132
data/ref/c/structswig__type__info.html +0 -132
data/ref/c/swig__vpi_8h.html +0 -8739
data/ref/c/swig__wrap_8cin.html +0 -11556
data/ref/c/unions__vpi__value__value.html +0 -166
data/ref/ruby/classes/String.src/M000032.html +0 -41
data/ref/ruby/classes/Vpi/Handle.src/M000085.html +0 -18
data/ref/ruby/classes/Vpi/Handle.src/M000086.html +0 -18
data/ref/ruby/classes/XX/Document.src/M000072.html +0 -22
data/ref/ruby/classes/XX/Document.src/M000073.html +0 -20
data/ref/ruby/classes/XX/Markup/ClassMethods.src/M000044.html +0 -22
data/ref/ruby/classes/XX/Markup/ClassMethods.src/M000045.html +0 -20
data/ref/ruby/classes/XX/Markup/InstanceMethods.src/M000052.html +0 -56
data/ref/ruby/classes/XX/Markup/InstanceMethods.src/M000053.html +0 -33
data/style.css +0 -47

data/doc/images/blank.png DELETED Viewed

Binary file

data/doc/images/callouts/1.png DELETED Viewed

Binary file

data/doc/images/callouts/10.png DELETED Viewed

Binary file

data/doc/images/callouts/11.png DELETED Viewed

Binary file

data/doc/images/callouts/12.png DELETED Viewed

Binary file

data/doc/images/callouts/13.png DELETED Viewed

Binary file

data/doc/images/callouts/14.png DELETED Viewed

Binary file

data/doc/images/callouts/15.png DELETED Viewed

Binary file

data/doc/images/callouts/2.png DELETED Viewed

Binary file

data/doc/images/callouts/3.png DELETED Viewed

Binary file

data/doc/images/callouts/4.png DELETED Viewed

Binary file

data/doc/images/callouts/5.png DELETED Viewed

Binary file

data/doc/images/callouts/6.png DELETED Viewed

Binary file

data/doc/images/callouts/7.png DELETED Viewed

Binary file

data/doc/images/callouts/8.png DELETED Viewed

Binary file

data/doc/images/callouts/9.png DELETED Viewed

Binary file

data/doc/images/callouts/ChangeLog DELETED Viewed

@@ -1,15 +0,0 @@
-2002-05-17  Norman Walsh <nwalsh@users.sourceforge.net>
-	* 11.gif, 11.png, 12.gif, 12.png, 13.gif, 13.png, 14.gif, 14.png, 15.gif, 15.png:
-	New file.
-2002-01-28  Norman Walsh <nwalsh@users.sourceforge.net>
-	* 1.gif, 10.gif, 2.gif, 3.gif, 4.gif, 5.gif, 6.gif, 7.gif, 8.gif, 9.gif:
-	New file.
-2001-04-02  Norman Walsh <nwalsh@users.sourceforge.net>
-	* 1.png, 10.png, 2.png, 3.png, 4.png, 5.png, 6.png, 7.png, 8.png, 9.png:
-	New file.

data/doc/images/copyright DELETED Viewed

@@ -1,55 +0,0 @@
-This package was debianized by Mark Johnson <mrj@debian.org> on
-Mon, 11 Oct 2004 18:37:39 -0400
-It was downloaded from the Sourceforge mirror:
- <http://umn.dl.sourceforge.net/sourceforge/docbook/>
-Upstream Author: Norman Walsh <ndw@nwalsh.com> and other docbook developers at
-the Sourceforge DocBook Open Repository
-Copyright
----------
-Copyright (C) 1999, 2000, 2001 Norman Walsh
-Permission is hereby granted, free of charge, to any person
-obtaining a copy of this software and associated documentation
-files (the ``Software''), 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:
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
-Except as contained in this notice, the names of individuals
-credited with contribution to this software shall not be used in
-advertising or otherwise to promote the sale, use or other
-dealings in this Software without prior written authorization
-from the individuals in question.
-Any stylesheet derived from this Software that is publically
-distributed will be identified with a different name and the
-version strings in any derived Software will be changed so that
-no possibility of confusion between the derived package and this
-Software will exist.
-Warranty
---------
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
-OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-NONINFRINGEMENT.  IN NO EVENT SHALL NORMAN WALSH OR ANY OTHER
-CONTRIBUTOR BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
-WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
-FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
-OTHER DEALINGS IN THE SOFTWARE.
-Contacting the Author
----------------------
-These stylesheets are maintained by Norman Walsh, <ndw@nwalsh.com>.

data/doc/images/draft.png DELETED Viewed

Binary file

data/doc/images/toc-blank.png DELETED Viewed

Binary file

data/doc/images/toc-minus.png DELETED Viewed

Binary file

data/doc/images/toc-plus.png DELETED Viewed

Binary file

data/doc/index.html DELETED Viewed

@@ -1,4 +0,0 @@
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Ruby-VPI user manual</title><link rel="stylesheet" href="styles/manual.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.68.1" /><meta name="description" content="This manual explains how to use Ruby-VPI. A plain-text version of this manual is also available. Finally, you can find the newest version of this manual at the Ruby-VPI website." /><link rel="start" href="index.html" title="Ruby-VPI user manual" /><link rel="next" href="introduction.html" title="Chapter 1. Introduction" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center"><span class="application">Ruby-VPI</span> user manual</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="introduction.html"><img src="images/next.png" alt="Next" /></a></td></tr></table><hr /></div><div class="book" lang="en" xml:lang="en"><div class="titlepage"><div><div><h1 class="title"><a id="id2472603"></a><span class="application">Ruby-VPI</span> user manual</h1></div><div><p class="copyright">Copyright © 2006 Suraj N. Kurapati</p></div><div><p class="copyright">Copyright © 2005, 2006 <a href="http://tango.freedesktop.org" target="_top">Tango Desktop Project</a> <em><span class="remark">for admonition and navigation graphics released under <a href="images/COPYING" target="_top">this license</a>.</span></em></p></div><div><p class="copyright">Copyright © 1999, 2000, 2001 Norman Walsh <em><span class="remark">for DocBook graphics released under <a href="images/copyright" target="_top">this license</a>.</span></em></p></div><div><div class="legalnotice"><a id="id2516394"></a><p>Permission is granted to copy, distribute and/or modify this document under the terms of the <span class="acronym">GNU</span> Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "<span class="acronym">GNU</span> Free Documentation License".</p></div></div><div><div class="abstract"><p class="title"><b>Abstract</b></p><p>This manual explains how to use <span class="application">Ruby-VPI</span>. A <a href="manual.txt" target="_top">plain-text version of this manual</a> is also available. Finally, you can find the newest version of this manual at the <a href="http://ruby-vpi.rubyforge.org" target="_top"><span class="application">Ruby-VPI</span> website</a>.</p></div></div></div><hr /></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="chapter"><a href="introduction.html">1. Introduction</a></span></dt><dd><dl><dt><span class="section"><a href="introduction.license.html">License</a></span></dt><dt><span class="section"><a href="introduction.manifest.html">Manifest</a></span></dt><dt><span class="section"><a href="introduction.resources.html">Resources</a></span></dt><dt><span class="section"><a href="introduction.related-works.html">Related works</a></span></dt><dd><dl><dt><span class="section"><a href="introduction.related-works.html#introduction.related-works.pli">Ye olde PLI</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="background.html">2. Background</a></span></dt><dd><dl><dt><span class="section"><a href="background.methodology.html">Methodology</a></span></dt><dt><span class="section"><a href="background.terminology.html">Terminology</a></span></dt><dt><span class="section"><a href="background.organization.html">Organization</a></span></dt><dd><dl><dt><span class="section"><a href="background.organization.html#organization.vpi">Interface to <span class="acronym">VPI</span></a></span></dt></dl></dd><dt><span class="section"><a href="background.running-tests.html">Running a test</a></span></dt><dd><dl><dt><span class="section"><a href="background.running-tests.html#background.running-tests.init">Initialization</a></span></dt><dt><span class="section"><a href="background.running-tests.html#background.running-tests.exec">Execution</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="setup.html">3. Setup</a></span></dt><dd><dl><dt><span class="section"><a href="setup.reqs.html">Requirements</a></span></dt><dd><dl><dt><span class="section"><a href="setup.reqs.html#setup.reqs.optional">Recommendations</a></span></dt></dl></dd><dt><span class="section"><a href="setup.installation.html">Installation</a></span></dt><dd><dl><dt><span class="section"><a href="setup.installation.html#setup.installation.windows">Installing on Windows</a></span></dt></dl></dd><dt><span class="section"><a href="setup.maintenance.html">Maintenance</a></span></dt></dl></dd><dt><span class="chapter"><a href="usage.html">4. Usage</a></span></dt><dd><dl><dt><span class="section"><a href="usage.tools.html">Tools</a></span></dt><dd><dl><dt><span class="section"><a href="usage.tools.html#usage.tools.generate-test">Automated test generation</a></span></dt><dt><span class="section"><a href="usage.tools.html#usage.tools.verilog-ruby-conv">Verilog to Ruby conversion</a></span></dt></dl></dd><dt><span class="section"><a href="usage.tutorial.html">Tutorial</a></span></dt><dd><dl><dt><span class="section"><a href="usage.tutorial.html#usage.tutorial.declare-design">Start with a design</a></span></dt><dt><span class="section"><a href="usage.tutorial.html#usage.tutorial.generate-test">Generate a test</a></span></dt><dt><span class="section"><a href="usage.tutorial.html#usage.tutorial.specification">Specify your expectations</a></span></dt><dt><span class="section"><a href="usage.tutorial.html#usage.tutorial.implement-proto">Implement the prototype</a></span></dt><dt><span class="section"><a href="usage.tutorial.html#usage.tutorial.test-proto">Verify the prototype</a></span></dt><dt><span class="section"><a href="usage.tutorial.html#usage.tutorial.implement-design">Implement the design</a></span></dt><dt><span class="section"><a href="usage.tutorial.html#usage.tutorial.test-design">Verify the design</a></span></dt></dl></dd><dt><span class="section"><a href="usage.examples.html">Examples</a></span></dt></dl></dd><dt><span class="chapter"><a href="hacking.html">5. Hacking</a></span></dt><dd><dl><dt><span class="section"><a href="hacking.release-packages.html">Building release packages</a></span></dt></dl></dd><dt><span class="chapter"><a href="problems.html">6. Known problems</a></span></dt><dd><dl><dt><span class="section"><a href="problems.ruby.html">Ruby</a></span></dt><dd><dl><dt><span class="section"><a href="problems.ruby.html#problems.ruby.SystemStackError">SystemStackError</a></span></dt><dt><span class="section"><a href="problems.ruby.html#problems.ruby.xUnit">test/unit</a></span></dt></dl></dd><dt><span class="section"><a href="problem.ivl.html">Icarus Verilog</a></span></dt><dd><dl><dt><span class="section"><a href="problem.ivl.html#problems.ivl.vpi_handle_by_name">vpi_handle_by_name</a></span></dt><dt><span class="section"><a href="problem.ivl.html#problems.ivl.vpi_reset">Vpi::reset</a></span></dt></dl></dd><dt><span class="section"><a href="problems.vsim.html">Mentor Modelsim</a></span></dt><dd><dl><dt><span class="section"><a href="problems.vsim.html#problems.vsim.ruby_run">ruby_run()</a></span></dt></dl></dd></dl></dd><dt><span class="glossary"><a href="glossary.html">Glossary</a></span></dt><dt><span class="appendix"><a href="gfdl.html">A. GNU Free Documentation License</a></span></dt><dd><dl><dt><span class="section"><a href="gfdl-0.html">PREAMBLE</a></span></dt><dt><span class="section"><a href="gfdl-1.html">APPLICABILITY AND DEFINITIONS</a></span></dt><dt><span class="section"><a href="gfdl-2.html">VERBATIM COPYING</a></span></dt><dt><span class="section"><a href="gfdl-3.html">COPYING IN QUANTITY</a></span></dt><dt><span class="section"><a href="gfdl-4.html">MODIFICATIONS</a></span></dt><dt><span class="section"><a href="gfdl-5.html">COMBINING DOCUMENTS</a></span></dt><dt><span class="section"><a href="gfdl-6.html">COLLECTIONS OF DOCUMENTS</a></span></dt><dt><span class="section"><a href="gfdl-7.html">AGGREGATION WITH INDEPENDENT WORKS</a></span></dt><dt><span class="section"><a href="gfdl-8.html">TRANSLATION</a></span></dt><dt><span class="section"><a href="gfdl-9.html">TERMINATION</a></span></dt><dt><span class="section"><a href="gfdl-10.html">FUTURE REVISIONS OF THIS LICENSE</a></span></dt><dt><span class="section"><a href="gfdl-addendum.html">ADDENDUM: How to use this License for
-  your documents</a></span></dt></dl></dd></dl></div><div class="list-of-figures"><p><b>List of Figures</b></p><dl><dt>2.1. <a href="background.organization.html#fig..organization">Overall organization of a test</a></dt><dt>2.2. <a href="background.organization.html#fig..organization.detail">Detailed organization of a test</a></dt><dt>2.3. <a href="background.running-tests.html#fig..ruby_init">Initialization of a test</a></dt><dt>2.4. <a href="background.running-tests.html#fig..ruby_relay">Execution of a test</a></dt><dt>4.1. <a href="usage.tutorial.html#fig..counter.v_decl">Declaration of a simple up-counter with synchronous reset</a></dt><dt>4.2. <a href="usage.tutorial.html#fig..generate-test.rspec">Generating a test with specification in rSpec format</a></dt><dt>4.3. <a href="usage.tutorial.html#fig..generate-test.unit-test">Generating a test with specification in xUnit format</a></dt><dt>4.4. <a href="usage.tutorial.html#fig..counter_rspec_spec.rb">Specification implemented in rSpec format</a></dt><dt>4.5. <a href="usage.tutorial.html#fig..counter_xunit_spec.rb">Specification implemented in xUnit format</a></dt><dt>4.6. <a href="usage.tutorial.html#fig..counter_proto.rb">Ruby prototype of our Verilog design</a></dt><dt>4.7. <a href="usage.tutorial.html#fig..test-proto.rspec">Running a test with specification in rSpec format</a></dt><dt>4.8. <a href="usage.tutorial.html#fig..test-proto.unit-test">Running a test with specification in xUnit format</a></dt><dt>4.9. <a href="usage.tutorial.html#fig..counter.v_impl">Implementation of a simple up-counter with synchronous reset</a></dt><dt>4.10. <a href="usage.tutorial.html#fig..test-design.rspec">Running a test with specification in rSpec format</a></dt><dt>4.11. <a href="usage.tutorial.html#fig..test-design.unit-test">Running a test with specification in xUnit format</a></dt></dl></div><div class="list-of-tables"><p><b>List of Tables</b></p><dl><dt>2.1. <a href="background.organization.html#table..handle-property-accessor-naming-format">Naming format for accessing a handle's <span class="acronym">VPI</span> properties</a></dt><dt>2.2. <a href="background.organization.html#id2488103">Possible accessors and their implications</a></dt></dl></div><div class="list-of-examples"><p><b>List of Examples</b></p><dl><dt>2.1. <a href="background.organization.html#ex..handle-property-accessor-naming-format">Accessing a handle's <span class="acronym">VPI</span> properties</a></dt><dt>6.1. <a href="problem.ivl.html#ex..TestFoo">Part of a bench which instantiates a Verilog design</a></dt><dt>6.2. <a href="problem.ivl.html#ex..TestFoo_bad">Bad design with unconnected registers</a></dt><dt>6.3. <a href="problem.ivl.html#ex..TestFoo_fix">Fixed design with wired registers</a></dt></dl></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="introduction.html"><img src="images/next.png" alt="Next" /></a></td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"> </td><td width="40%" align="right" valign="top"> Chapter 1. Introduction</td></tr></table></div></body></html>

data/doc/introduction.html DELETED Viewed

@@ -1,3 +0,0 @@
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 1. Introduction</title><link rel="stylesheet" href="styles/manual.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.68.1" /><link rel="start" href="index.html" title="Ruby-VPI user manual" /><link rel="up" href="index.html" title="Ruby-VPI user manual" /><link rel="prev" href="index.html" title="Ruby-VPI user manual" /><link rel="next" href="introduction.license.html" title="License" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 1. Introduction</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="index.html"><img src="images/prev.png" alt="Prev" /></a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="introduction.license.html"><img src="images/next.png" alt="Next" /></a></td></tr></table><hr /></div><div class="chapter" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="introduction"></a>Chapter 1. Introduction</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="introduction.license.html">License</a></span></dt><dt><span class="section"><a href="introduction.manifest.html">Manifest</a></span></dt><dt><span class="section"><a href="introduction.resources.html">Resources</a></span></dt><dt><span class="section"><a href="introduction.related-works.html">Related works</a></span></dt><dd><dl><dt><span class="section"><a href="introduction.related-works.html#introduction.related-works.pli">Ye olde PLI</a></span></dt></dl></dd></dl></div><p><span class="application">Ruby-VPI</span> is a <a href="http://www.ruby-lang.org/en/20020101.html" target="_top">Ruby</a> interface to <a href="http://en.wikipedia.org/wiki/Verilog" target="_top"><span class="acronym">VPI</span></a>. It lets you create complex Verilog test benches easily and wholly in Ruby.</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="index.html"><img src="images/prev.png" alt="Prev" /></a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="introduction.license.html"><img src="images/next.png" alt="Next" /></a></td></tr><tr><td width="40%" align="left" valign="top"><span class="application">Ruby-VPI</span> user manual </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home" /></a></td><td width="40%" align="right" valign="top"> License</td></tr></table></div></body></html>

data/doc/introduction.license.html DELETED Viewed

@@ -1,3 +0,0 @@
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>License</title><link rel="stylesheet" href="styles/manual.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.68.1" /><link rel="start" href="index.html" title="Ruby-VPI user manual" /><link rel="up" href="introduction.html" title="Chapter 1. Introduction" /><link rel="prev" href="introduction.html" title="Chapter 1. Introduction" /><link rel="next" href="introduction.manifest.html" title="Manifest" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">License</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="introduction.html"><img src="images/prev.png" alt="Prev" /></a> </td><th width="60%" align="center">Chapter 1. Introduction</th><td width="20%" align="right"> <a accesskey="n" href="introduction.manifest.html"><img src="images/next.png" alt="Next" /></a></td></tr></table><hr /></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="introduction.license"></a>License</h2></div></div></div><p><span class="application">Ruby-VPI</span> is <a href="http://en.wikipedia.org/wiki/Free_software" target="_top">free software</a>; you can redistribute it and/or modify it under the terms of the <a href="http://www.gnu.org/copyleft/gpl.html" target="_top"><span class="acronym">GNU</span> General Public License</a> as published by the <a href="http://www.fsf.org" target="_top">Free Software Foundation</a>; either version 2 of the License, or (at your option) any later version.</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="introduction.html"><img src="images/prev.png" alt="Prev" /></a> </td><td width="20%" align="center"><a accesskey="u" href="introduction.html"><img src="images/up.png" alt="Up" /></a></td><td width="40%" align="right"> <a accesskey="n" href="introduction.manifest.html"><img src="images/next.png" alt="Next" /></a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 1. Introduction </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home" /></a></td><td width="40%" align="right" valign="top"> Manifest</td></tr></table></div></body></html>

data/doc/introduction.manifest.html DELETED Viewed

@@ -1,3 +0,0 @@
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Manifest</title><link rel="stylesheet" href="styles/manual.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.68.1" /><link rel="start" href="index.html" title="Ruby-VPI user manual" /><link rel="up" href="introduction.html" title="Chapter 1. Introduction" /><link rel="prev" href="introduction.license.html" title="License" /><link rel="next" href="introduction.resources.html" title="Resources" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Manifest</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="introduction.license.html"><img src="images/prev.png" alt="Prev" /></a> </td><th width="60%" align="center">Chapter 1. Introduction</th><td width="20%" align="right"> <a accesskey="n" href="introduction.resources.html"><img src="images/next.png" alt="Next" /></a></td></tr></table><hr /></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="introduction.manifest"></a>Manifest</h2></div></div></div><p>When you extract a <span class="application">Ruby-VPI</span> release package, the following is what you would expect to find.</p><div class="variablelist"><dl><dt><span class="term"><code class="filename">doc</code></span></dt><dd><p>This directory contains user documentation in various formats.</p></dd><dt><span class="term"><code class="filename">ref</code></span></dt><dd><p>This directory contains reference <span class="acronym">API</span> documentation in <span class="acronym">HTML</span> format.</p></dd><dt><span class="term"><code class="filename">ext</code></span></dt><dd><p>This directory contains source code, written in the C language, for the <a href="background.organization.html" title="Organization">core of <span class="application">Ruby-VPI</span></a>.</p></dd><dt><span class="term"><code class="filename">lib</code></span></dt><dd><p>This directory contains Ruby libraries provided by <span class="application">Ruby-VPI</span>.</p></dd><dt><span class="term"><code class="filename">bin</code></span></dt><dd><p>This directory contains various tools. See <a href="usage.tools.html" title="Tools">the section called “Tools”</a> for more information.</p></dd><dt><span class="term"><code class="filename">samp</code></span></dt><dd><p>This directory contains example tests. See <a href="usage.examples.html" title="Examples">the section called “Examples”</a> for more information.</p></dd></dl></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="introduction.license.html"><img src="images/prev.png" alt="Prev" /></a> </td><td width="20%" align="center"><a accesskey="u" href="introduction.html"><img src="images/up.png" alt="Up" /></a></td><td width="40%" align="right"> <a accesskey="n" href="introduction.resources.html"><img src="images/next.png" alt="Next" /></a></td></tr><tr><td width="40%" align="left" valign="top">License </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home" /></a></td><td width="40%" align="right" valign="top"> Resources</td></tr></table></div></body></html>

data/doc/introduction.related-works.html DELETED Viewed

@@ -1,3 +0,0 @@
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Related works</title><link rel="stylesheet" href="styles/manual.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.68.1" /><link rel="start" href="index.html" title="Ruby-VPI user manual" /><link rel="up" href="introduction.html" title="Chapter 1. Introduction" /><link rel="prev" href="introduction.resources.html" title="Resources" /><link rel="next" href="background.html" title="Chapter 2. Background" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Related works</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="introduction.resources.html"><img src="images/prev.png" alt="Prev" /></a> </td><th width="60%" align="center">Chapter 1. Introduction</th><td width="20%" align="right"> <a accesskey="n" href="background.html"><img src="images/next.png" alt="Next" /></a></td></tr></table><hr /></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="introduction.related-works"></a>Related works</h2></div></div></div><p>You may wish to consider the following projects, which are similar to <span class="application">Ruby-VPI</span>.</p><div class="variablelist"><dl><dt><span class="term"><a href="http://rhdl.rubyforge.org" target="_top">RHDL</a></span></dt><dd><p>Hardware description and verification language based on Ruby.</p></dd><dt><span class="term"><a href="http://myhdl.jandecaluwe.com" target="_top">MyHDL</a></span></dt><dd><p>Hardware description and verification language based on Python, which features conversion to Verilog and co-simulation.</p></dd><dt><span class="term"><a href="http://jove.sourceforge.net" target="_top">JOVE</a></span></dt><dd><p>Java interface to <span class="acronym">VPI</span>.</p></dd><dt><span class="term"><a href="http://embedded.eecs.berkeley.edu/Alumni/pinhong/scriptEDA/" target="_top">ScriptEDA</a></span></dt><dd><p>Perl, Python, and Tcl interface to <span class="acronym">VPI</span>.</p></dd></dl></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="introduction.related-works.pli"></a>Ye olde PLI</h3></div></div></div><p>The following projects utilize the archaic <span class="acronym">tf</span> and <span class="abbrev">acc</span> PLI interfaces, which have been officially deprecated in IEEE Std 1364-2005.</p><div class="variablelist"><dl><dt><span class="term"><a href="http://www.nelsim.com" target="_top">ScriptSim</a></span></dt><dd><p>Perl, Python, and Tcl/Tk interface to PLI.</p></dd><dt><span class="term"><a href="http://www.veripool.com/verilog-pli.html" target="_top">Verilog::Pli</a></span></dt><dd><p>Perl interface to PLI.</p></dd><dt><span class="term"><a href="http://www.time-rover.com/jpli/" target="_top">JPLI</a></span></dt><dd><p>Java interface to PLI.</p></dd></dl></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="introduction.resources.html"><img src="images/prev.png" alt="Prev" /></a> </td><td width="20%" align="center"><a accesskey="u" href="introduction.html"><img src="images/up.png" alt="Up" /></a></td><td width="40%" align="right"> <a accesskey="n" href="background.html"><img src="images/next.png" alt="Next" /></a></td></tr><tr><td width="40%" align="left" valign="top">Resources </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home" /></a></td><td width="40%" align="right" valign="top"> Chapter 2. Background</td></tr></table></div></body></html>

data/doc/introduction.resources.html DELETED Viewed

@@ -1,3 +0,0 @@
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Resources</title><link rel="stylesheet" href="styles/manual.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.68.1" /><link rel="start" href="index.html" title="Ruby-VPI user manual" /><link rel="up" href="introduction.html" title="Chapter 1. Introduction" /><link rel="prev" href="introduction.manifest.html" title="Manifest" /><link rel="next" href="introduction.related-works.html" title="Related works" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Resources</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="introduction.manifest.html"><img src="images/prev.png" alt="Prev" /></a> </td><th width="60%" align="center">Chapter 1. Introduction</th><td width="20%" align="right"> <a accesskey="n" href="introduction.related-works.html"><img src="images/next.png" alt="Next" /></a></td></tr></table><hr /></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="introduction.resources"></a>Resources</h2></div></div></div><div class="variablelist"><dl><dt><span class="term"><a href="http://rubyforge.org/projects/ruby-vpi" target="_top">Project</a></span></dt><dd><p>Access project facilities, hosted generously by <a href="http://rubyforge.org" target="_top">RubyForge</a>.</p></dd><dt><span class="term"><a href="http://rubyforge.org/tracker/?group_id=1339" target="_top">Tracker</a></span></dt><dd><p>Report problems, contribute patches, and more.</p></dd><dt><span class="term"><a href="http://rubyforge.org/frs/?group_id=1339" target="_top">Releases</a></span></dt><dd><p>Download the newest release of <span class="application">Ruby-VPI</span>.</p></dd><dt><span class="term"><a href="http://ruby-vpi.rubyforge.org/src/ruby-vpi" target="_top">Sources</a></span></dt><dd><p>Browse or access the source code repository.</p></dd><dt><span class="term"><a href="http://rubyforge.org/forum/?group_id=1339" target="_top">Forums</a></span></dt><dd><p>Ask for help, give feedback, or discuss.</p></dd></dl></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="introduction.manifest.html"><img src="images/prev.png" alt="Prev" /></a> </td><td width="20%" align="center"><a accesskey="u" href="introduction.html"><img src="images/up.png" alt="Up" /></a></td><td width="40%" align="right"> <a accesskey="n" href="introduction.related-works.html"><img src="images/next.png" alt="Next" /></a></td></tr><tr><td width="40%" align="left" valign="top">Manifest </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home" /></a></td><td width="40%" align="right" valign="top"> Related works</td></tr></table></div></body></html>

data/doc/manual.txt DELETED Viewed

@@ -1,1852 +0,0 @@
-Ruby-VPI user manual
-Copyright   2006 Suraj N. Kurapati
-Copyright   2005, 2006 Tango Desktop Project for admonition and navigation
-graphics released under this license.
-Copyright   1999, 2000, 2001 Norman Walsh for DocBook graphics released under
-this license.
-Permission is granted to copy, distribute and/or modify this document under the
-terms of the GNU Free Documentation License, Version 1.2 or any later version
-published by the Free Software Foundation; with no Invariant Sections, no
-Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included
-in the section entitled "GNU Free Documentation License".
-Abstract
-This manual explains how to use Ruby-VPI. A plain-text version of this manual
-is also available. Finally, you can find the newest version of this manual at
-the Ruby-VPI website.
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-Table of Contents
-1. Introduction
-    License
-    Manifest
-    Resources
-    Related works
-        Ye olde PLI
-2. Background
-    Methodology
-    Terminology
-    Organization
-        Interface to VPI
-    Running a test
-        Initialization
-        Execution
-3. Setup
-    Requirements
-        Recommendations
-    Installation
-        Installing on Windows
-    Maintenance
-4. Usage
-    Tools
-        Automated test generation
-        Verilog to Ruby conversion
-    Tutorial
-        Start with a design
-        Generate a test
-        Specify your expectations
-        Implement the prototype
-        Verify the prototype
-        Implement the design
-        Verify the design
-    Examples
-5. Hacking
-    Building release packages
-6. Known problems
-    Ruby
-        SystemStackError
-        test/unit
-    Icarus Verilog
-        vpi_handle_by_name
-        Vpi::reset
-    Mentor Modelsim
-        ruby_run()
-Glossary
-A. GNU Free Documentation License
-    PREAMBLE
-    APPLICABILITY AND DEFINITIONS
-    VERBATIM COPYING
-    COPYING IN QUANTITY
-    MODIFICATIONS
-    COMBINING DOCUMENTS
-    COLLECTIONS OF DOCUMENTS
-    AGGREGATION WITH INDEPENDENT WORKS
-    TRANSLATION
-    TERMINATION
-    FUTURE REVISIONS OF THIS LICENSE
-    ADDENDUM: How to use this License for your documents
-List of Figures
-2.1. Overall organization of a test
-2.2. Detailed organization of a test
-2.3. Initialization of a test
-2.4. Execution of a test
-4.1. Declaration of a simple up-counter with synchronous reset
-4.2. Generating a test with specification in rSpec format
-4.3. Generating a test with specification in xUnit format
-4.4. Specification implemented in rSpec format
-4.5. Specification implemented in xUnit format
-4.6. Ruby prototype of our Verilog design
-4.7. Running a test with specification in rSpec format
-4.8. Running a test with specification in xUnit format
-4.9. Implementation of a simple up-counter with synchronous reset
-4.10. Running a test with specification in rSpec format
-4.11. Running a test with specification in xUnit format
-List of Tables
-2.1. Naming format for accessing a handle's VPI properties
-2.2. Possible accessors and their implications
-List of Examples
-2.1. Accessing a handle's VPI properties
-6.1. Part of a bench which instantiates a Verilog design
-6.2. Bad design with unconnected registers
-6.3. Fixed design with wired registers
-Chapter 1. Introduction
-Table of Contents
-License
-Manifest
-Resources
-Related works
-    Ye olde PLI
-Ruby-VPI is a Ruby interface to VPI. It lets you create complex Verilog test
-benches easily and wholly in Ruby.
-License
-Ruby-VPI is free software; you can redistribute it and/or modify it under the
-terms of the GNU General Public License as published by the Free Software
-Foundation; either version 2 of the License, or (at your option) any later
-version.
-Manifest
-When you extract a Ruby-VPI release package, the following is what you would
-expect to find.
-doc
-    This directory contains user documentation in various formats.
-ref
-    This directory contains reference API documentation in HTML format.
-ext
-    This directory contains source code, written in the C language, for the
-    core of Ruby-VPI.
-lib
-    This directory contains Ruby libraries provided by Ruby-VPI.
-bin
-    This directory contains various tools. See the section called “Tools” for
-    more information.
-samp
-    This directory contains example tests. See the section called “Examples”
-    for more information.
-Resources
-Project
-    Access project facilities, hosted generously by RubyForge.
-Tracker
-    Report problems, contribute patches, and more.
-Releases
-    Download the newest release of Ruby-VPI.
-Sources
-    Browse or access the source code repository.
-Forums
-    Ask for help, give feedback, or discuss.
-Related works
-You may wish to consider the following projects, which are similar to Ruby-VPI.
-RHDL
-    Hardware description and verification language based on Ruby.
-MyHDL
-    Hardware description and verification language based on Python, which
-    features conversion to Verilog and co-simulation.
-JOVE
-    Java interface to VPI.
-ScriptEDA
-    Perl, Python, and Tcl interface to VPI.
-Ye olde PLI
-The following projects utilize the archaic tf and acc PLI interfaces, which
-have been officially deprecated in IEEE Std 1364-2005.
-ScriptSim
-    Perl, Python, and Tcl/Tk interface to PLI.
-Verilog::Pli
-    Perl interface to PLI.
-JPLI
-    Java interface to PLI.
-Chapter 2. Background
-Table of Contents
-Methodology
-Terminology
-Organization
-    Interface to VPI
-Running a test
-    Initialization
-    Execution
-Ruby-VPI is a Bench which lets you Test Verilog modules using the Ruby
-language.
-Methodology
-Ruby-VPI presents an open-ended interface to VPI. Thus, you can use any
-methodology you wish when writing tests. However, BDD is emphasized in this
-project because it greatly simplifies thinking about how to verify a design.
-Terminology
-[Tip] Tip
-      Have a look at the Glossary for definitions of terms used in this manual.
-As a newcomer into the world of Verilog, I often heard the term test bench: “I
-ran the test bench, but it didn't work!” or “Are you crazy?!! You still haven't
-written the test bench? o_O”, for example. I flipped through my textbook and
-surfed the Internet for a definition of the term, but it was to no avail.
-Instead, both resources nonchalantly employed the term throughout their being,
-as if mocking my ignorance of what seems to be universal knowledge.
-Defeated, I turned to my inner faculties to determine the answer. “Let's see,
-the term test bench has the word test—so it has something to do with
-testing—and it has the word bench—so maybe it's referring to a table where the
-testing should occur”. This reasoning grew increasingly familiar as my mind
-rummaged through towering stores of obsolescence and ultimately revealed
-dreaded memories of sleepless anguish: debugging electronics in the robotics
-laboratory.
-“Aha!”, I exclaimed hesitantly, trying to dismiss the past. The term has its
-roots in the testing of electronic devices, where an engineer would sit at a
-bench in an electronics laboratory and verify that an electronic component
-satisfies some criteria. The bench would be furnished with tools of measurement
-and manipulation—such as oscilloscopes, voltmeters, soldering irons, and so
-on—which help the engineer to verify the electronic component or locate the
-sources of defects in the component.
-Alright, now I remember what a laboratory bench is, but how does that compare
-with the term test bench? Surely they cannot have the same meaning, because it
-doesn't make sense to run a laboratory bench or to write one. Thus, to avoid
-propagating such confusion into this manual, I have attempted to clarify the
-terminology by simplifying and reintroducing it in a new light.
-Organization
-Figure 2.1. Overall organization of a test
-Overall organization of a test
-As Figure 2.1, “Overall organization of a test” shows, a test is composed of a
-bench, a design, and a specification. To extend the analogy of an electronics
-laboratory, the first acts as the laboratory bench which provides measurement
-and manipulation tools. The second acts as the electronic component being
-verified by the engineer. And the third acts as the engineer who measures,
-manipulates, and verifies the electronic component.
-Interface to VPI
-Figure 2.2. Detailed organization of a test
-Detailed organization of a test
-In Figure 2.2, “Detailed organization of a test”, Ruby-VPI acts as the bench, a
-Verilog simulator encapsulates the design, and a Ruby interpreter encapsulates
-the specification. Notice that Ruby-VPI encapsulates all communication between
-the Ruby interpreter and VPI. This allows the specification, or any Ruby
-program in general, to access VPI using nothing more than the Ruby language!
-Thus, Ruby-VPI removes the burden of having to write C programs in order to
-access VPI.
-Furthermore, Ruby-VPI presents the entire IEEE Std 1364-2005 VPI interface to
-the Ruby interpreter, but with the following minor changes.
-  ● The first letter in the name of every function, type, structure, and
-    constant becomes capitalized.
-    For example, the s_vpi_value structure in C becomes the S_vpi_value class
-    in Ruby. Likewise, the vpiIntVal constant in C becomes the VpiIntVal
-    constant in Ruby.
-  ● The VPI functions vpi_vprintf and vpi_mcd_vprintf are not made accessible
-    to Ruby. However, this isn't a big problem because you can use Ruby's
-    printf method instead.
-    The reason for this limitation is that some C compilers have trouble with
-    pointers to the va_list type. For these compilers, the second line in the
-    code shown below causes a “type mismatch” error.
-    void foo(va_list ap) {
-      va_list *p = &ap;
-    }
-VPI utility layer
-From a user's perspective, the VPI utility layer greatly enhances the ability
-to interact with handles. One simply invokes a handle's methods, which are
-carefully named in the following manner, to access either (1) its children or
-(2) its VPI properties.
-The children of a handle are simply the handles that are immediately contained
-within it in. For example, suppose that you had a Verilog module that contains
-some registers. The children, of a handle to the module, would be handles to
-the registers.
-In the event that a child handle has the same name as a VPI property, the child
-is given priority. However, you can always access VPI properties explicitly via
-the get_value and put_value methods.
-Table 2.1. Naming format for accessing a handle's VPI properties
-┌─────────┬─┬────────┬─┬────────┬────────┐
-│Operation│_│Property│_│Accessor│Addendum│
-├─────────┴─┼────────┼─┴────────┼────────┤
-│optional   │required│optional  │optional│
-└───────────┴────────┴──────────┴────────┘
-Operation
-    This parameter suggests a method that should be invoked in the context of
-    the Property parameter.
-Property
-    This parameter suggests which VPI property should be accessed. The first
-    letter of this parameter's value should be lower case, and the vpi
-    prefix—common to all VPI properties—can be omitted.
-    For example, the VPI property vpiFullName is considered equivalent to
-    fullName but not equivalent to either FullName or full_name.
-Accessor
-    This parameter suggests which VPI function should be used to access the VPI
-    property. When this parameter is not specified, the VPI utility layer will
-    attempt to guess the value of this parameter (see the source code of the
-    Property.resolve method for details).
-    Table 2.2. Possible accessors and their implications
-    ┌────────┬──────────────────────┬──────────────────────────────────────┐
-    │Accessor│Kind of value accessed│VPI functions used to access the value│
-    ├────────┼──────────────────────┼──────────────────────────────────────┤
-    │d       │delay                 │vpi_get_delays, vpi_put_delays        │
-    ├────────┼──────────────────────┼──────────────────────────────────────┤
-    │l       │logic                 │vpi_get_value, vpi_put_value          │
-    ├────────┼──────────────────────┼──────────────────────────────────────┤
-    │i       │integer               │vpi_get                               │
-    ├────────┼──────────────────────┼──────────────────────────────────────┤
-    │b       │boolean               │vpi_get                               │
-    ├────────┼──────────────────────┼──────────────────────────────────────┤
-    │s       │string                │vpi_get_str                           │
-    ├────────┼──────────────────────┼──────────────────────────────────────┤
-    │h       │handle                │vpi_handle                            │
-    └────────┴──────────────────────┴──────────────────────────────────────┘
-Addendum
-    When this parameter is a question mark (?), it suggests that the specified
-    VPI property should be queried as a boolean value. This produces the same
-    effect as specifying b for the Accessor parameter.
-    When this parameter is an equal sign (=), it suggests that the specified
-    VPI property should be written to.
-Example 2.1. Accessing a handle's VPI properties
-┌─────────────────────┬────────────────────────────────────────────┬────────────┐
-│                     │               Naming format                │            │
-│   Ruby expression   ├─────────┬─┬────────────┬─┬────────┬────────┤Description │
-│                     │Operation│_│  Property  │_│Accessor│Addendum│            │
-├─────────────────────┼─────────┼─┼────────────┼─┼────────┼────────┼────────────┤
-│                     │         │ │            │ │        │        │These       │
-│handle.each_vpiNet {|│         │ │            │ │        │        │expressions │
-│net| puts            │each     │_│vpiNet      │ │        │        │print the   │
-│net.fullName}        │         │ │            │ │        │        │full name of│
-│                     │         │ │            │ │        │        │each vpiNet │
-├─────────────────────┼─────────┼─┼────────────┼─┼────────┼────────┤object      │
-│                     │         │ │            │ │        │        │associated  │
-│handle.each_net {|net│each     │_│net         │ │        │        │with the    │
-│| puts net.fullName} │         │ │            │ │        │        │handle.     │
-│                     │         │ │            │ │        │        │            │
-├─────────────────────┼─────────┼─┼────────────┼─┼────────┼────────┼────────────┤
-│                     │         │ │            │ │        │        │These       │
-│handle.all_reg? {|reg│         │ │            │ │        │        │expressions │
-│| reg.size == 1}     │all?     │_│vpiReg      │ │        │        │check if all│
-│                     │         │ │            │ │        │        │registers   │
-│                     │         │ │            │ │        │        │associated  │
-├─────────────────────┼─────────┼─┼────────────┼─┼────────┼────────┤with the    │
-│                     │         │ │            │ │        │        │handle are  │
-│handle.all_reg? {|reg│         │ │            │ │        │        │capable of  │
-│| reg.size == 1}     │all?     │_│reg         │ │        │        │storing only│
-│                     │         │ │            │ │        │        │one bit.    │
-│                     │         │ │            │ │        │        │            │
-├─────────────────────┼─────────┼─┼────────────┼─┼────────┼────────┼────────────┤
-│handle.select_vpiNet │select   │_│vpiReg      │ │        │        │            │
-│{|net| net.x?}       │         │ │            │ │        │        │            │
-├─────────────────────┼─────────┼─┼────────────┼─┼────────┼────────┤            │
-│handle.select_net {| │select   │_│net         │ │        │        │These       │
-│net| net.x?}         │         │ │            │ │        │        │expressions │
-├─────────────────────┼─────────┼─┼────────────┼─┼────────┼────────┤return a    │
-│handle.select(VpiNet)│select   │_│            │ │        │        │list of nets│
-│{|net| net.x?}       │         │ │            │ │        │        │whose logic │
-├─────────────────────┼─────────┼─┼────────────┼─┼────────┼────────┤value is    │
-│handle.select        │         │ │            │ │        │        │“don't      │
-│(:VpiNet) {|net|     │select   │_│            │ │        │        │care”.      │
-│net.x?}              │         │ │            │ │        │        │            │
-├─────────────────────┼─────────┼─┼────────────┼─┼────────┼────────┤            │
-│handle.select(:net)  │select   │_│            │ │        │        │            │
-│{|net| net.x?}       │         │ │            │ │        │        │            │
-├─────────────────────┼─────────┼─┼────────────┼─┼────────┼────────┼────────────┤
-│handle.vpiIntVal     │         │ │vpiIntVal   │ │        │        │            │
-│                     │         │ │            │ │        │        │These       │
-├─────────────────────┼─────────┼─┼────────────┼─┼────────┼────────┤expressions │
-│handle.vpiIntVal_l   │         │ │vpiIntVal   │_│l       │        │access the  │
-│                     │         │ │            │ │        │        │logic value │
-├─────────────────────┼─────────┼─┼────────────┼─┼────────┼────────┤of the      │
-│handle.intVal        │         │ │intVal      │ │        │        │handle's    │
-│                     │         │ │            │ │        │        │vpiIntVal   │
-├─────────────────────┼─────────┼─┼────────────┼─┼────────┼────────┤property.   │
-│handle.intVal_l      │         │ │intVal      │_│l       │        │            │
-│                     │         │ │            │ │        │        │            │
-├─────────────────────┼─────────┼─┼────────────┼─┼────────┼────────┼────────────┤
-│handle.vpiIntVal = 15│         │ │vpiIntVal   │ │        │=       │            │
-│                     │         │ │            │ │        │        │These       │
-├─────────────────────┼─────────┼─┼────────────┼─┼────────┼────────┤expressions │
-│handle.vpiIntVal_l = │         │ │            │ │        │        │assign the  │
-│15                   │         │ │vpiIntVal   │_│l       │=       │number 15 to│
-│                     │         │ │            │ │        │        │the logic   │
-├─────────────────────┼─────────┼─┼────────────┼─┼────────┼────────┤value of the│
-│handle.intVal = 15   │         │ │intVal      │ │        │=       │handle's    │
-│                     │         │ │            │ │        │        │vpiIntVal   │
-├─────────────────────┼─────────┼─┼────────────┼─┼────────┼────────┤property.   │
-│handle.intVal_l = 15 │         │ │intVal      │_│l       │=       │            │
-│                     │         │ │            │ │        │        │            │
-├─────────────────────┼─────────┼─┼────────────┼─┼────────┼────────┼────────────┤
-│handle.vpiType       │         │ │vpiType     │ │        │        │            │
-│                     │         │ │            │ │        │        │These       │
-├─────────────────────┼─────────┼─┼────────────┼─┼────────┼────────┤expressions │
-│handle.vpiType_i     │         │ │vpiType     │_│i       │        │access the  │
-│                     │         │ │            │ │        │        │integer     │
-├─────────────────────┼─────────┼─┼────────────┼─┼────────┼────────┤value of the│
-│handle.type          │         │ │type        │ │        │        │handle's    │
-│                     │         │ │            │ │        │        │vpiType     │
-├─────────────────────┼─────────┼─┼────────────┼─┼────────┼────────┤property.   │
-│handle.type_i        │         │ │type        │_│i       │        │            │
-│                     │         │ │            │ │        │        │            │
-├─────────────────────┼─────────┼─┼────────────┼─┼────────┼────────┼────────────┤
-│handle.vpiProtected  │         │ │vpiProtected│ │        │        │            │
-├─────────────────────┼─────────┼─┼────────────┼─┼────────┼────────┤These       │
-│handle.vpiProtected_b│         │ │vpiProtected│_│b       │        │expressions │
-├─────────────────────┼─────────┼─┼────────────┼─┼────────┼────────┤access the  │
-│handle.vpiProtected? │         │ │vpiProtected│ │        │?       │boolean     │
-├─────────────────────┼─────────┼─┼────────────┼─┼────────┼────────┤value of the│
-│handle.protected     │         │ │protected   │ │        │        │handle's    │
-├─────────────────────┼─────────┼─┼────────────┼─┼────────┼────────┤vpiProtected│
-│handle.protected_b   │         │ │protected   │_│b       │        │property.   │
-├─────────────────────┼─────────┼─┼────────────┼─┼────────┼────────┤            │
-│handle.protected?    │         │ │protected   │ │        │?       │            │
-├─────────────────────┼─────────┼─┼────────────┼─┼────────┼────────┼────────────┤
-│handle.vpiFullName   │         │ │vpiFullName │ │        │        │            │
-│                     │         │ │            │ │        │        │These       │
-├─────────────────────┼─────────┼─┼────────────┼─┼────────┼────────┤expressions │
-│handle.vpiFullName_s │         │ │vpiFullName │_│s       │        │access the  │
-│                     │         │ │            │ │        │        │string value│
-├─────────────────────┼─────────┼─┼────────────┼─┼────────┼────────┤of the      │
-│handle.fullName      │         │ │fullName    │ │        │        │handle's    │
-│                     │         │ │            │ │        │        │vpiFullName │
-├─────────────────────┼─────────┼─┼────────────┼─┼────────┼────────┤property.   │
-│handle.fullName_s    │         │ │fullName    │_│s       │        │            │
-│                     │         │ │            │ │        │        │            │
-├─────────────────────┼─────────┼─┼────────────┼─┼────────┼────────┼────────────┤
-│handle.vpiParent     │         │ │vpiParent   │ │        │        │            │
-│                     │         │ │            │ │        │        │These       │
-├─────────────────────┼─────────┼─┼────────────┼─┼────────┼────────┤expressions │
-│handle.vpiParent_h   │         │ │vpiParent   │_│h       │        │access the  │
-│                     │         │ │            │ │        │        │handle value│
-├─────────────────────┼─────────┼─┼────────────┼─┼────────┼────────┤of the      │
-│handle.parent        │         │ │parent      │ │        │        │handle's    │
-│                     │         │ │            │ │        │        │vpiParent   │
-├─────────────────────┼─────────┼─┼────────────┼─┼────────┼────────┤property.   │
-│handle.parent_h      │         │ │parent      │_│h       │        │            │
-│                     │         │ │            │ │        │        │            │
-└─────────────────────┴─────────┴─┴────────────┴─┴────────┴────────┴────────────┘
-Running a test
-Unlike an engineer who can verify an electronic component in real-time, the
-Verilog simulator and the Ruby interpreter (see Figure 2.2, “Detailed
-organization of a test”) take turns working with objects in a simulation when a
-test is run. In particular, they take turns manipulating the design and
-transfer control to each other when appropriate.
-The situation is similar to a pair of friends playing catch. One friend throws
-a ball to the other, and the other throws it back. Either is able to inspect
-and modify the ball, but only when it is in hand.
-Initialization
-A test is first initialized before it is executed. Figure 2.3, “Initialization
-of a test” illustrates the initialization process described below.
-Figure 2.3. Initialization of a test
-Initialization of a test
-Procedure 2.1. Initialization of a test
- 1. The Verilog simulator initializes the Ruby interpreter by invoking the
-    $ruby_init; system task/function, whose parameters represent the
-    command-line invocation of the Ruby interpreter. For example, one would
-    specify $ruby_init("ruby", "-w"); in Verilog to achieve the same effect as
-    specifying ruby -w at a command-prompt.
- 2. The Verilog simulator is paused and the Ruby interpreter is initialized
-    with the arguments of the $ruby_init; system task/function.
- 3. When the Ruby interpreter invokes the Vpi::relay_verilog method, it is
-    paused and the Verilog simulator is given control.
-Execution
-After a test is initialized, it is executed such that the design is verified
-against the specification. Figure 2.4, “Execution of a test” illustrates the
-execution process described below.
-Figure 2.4. Execution of a test
-Execution of a test
-Procedure 2.2. Execution of a test
- 1. The Verilog simulator transfers control to the Ruby interpreter by invoking
-    the $ruby_relay; system task/function.
- 2. The Verilog simulator is paused and the Ruby interpreter is given control.
- 3. When the Ruby interpreter invokes the Vpi::relay_verilog method, it is
-    paused and the Verilog simulator is given control.
-Chapter 3. Setup
-Table of Contents
-Requirements
-    Recommendations
-Installation
-    Installing on Windows
-Maintenance
-Requirements
-The following software is necessary in order to use Ruby-VPI.
-Verilog simulator
-    Ruby-VPI is known to work with the following simulators. Nevertheless, you
-    should be able to use it with any Verilog simulator that supports VPI.
-    Icarus Verilog
-        Version 0.8 or newer is acceptable.
-    GPL Cver
-        Version 2.11a or newer is acceptable.
-    Synopsys VCS
-        Any version that supports the -load option is acceptable.
-    Mentor Modelsim
-        Any version that supports the -pli option is acceptable.
-make
-    GNU make is preferred but any distribution of make should be acceptable.
-C compiler
-    GNU Compiler Collection (GCC) is preferred but any C compiler should be
-    acceptable.
-POSIX threads (pthreads)
-    Header and linkable object files, and operating system support for this
-    library are necessary.
-Ruby
-    Version 1.8 or newer, including header and linkable object files for
-    building extensions, is necessary. You can install Ruby by following these
-    instructions.
-RubyGems
-    Any recent version should be acceptable. You can install RubyGems by
-    following these instructions.
-Recommendations
-The following software may make your interactions with Ruby-VPI more pleasant.
-Text merging tool
-    An interactive text merging tool can greatly simplify the process of
-    transferring wanted changes from one file to another. In particular, such
-    tools are especially beneficial when using the automated test generator. A
-    handful of the currently available open-source text merging tools are
-    listed below.
-    kdiff3
-        A graphical, three-way merging tool for KDE.
-    meld
-        A graphical, three-way merging tool for GNOME.
-    tkdiff
-        A graphical, two-way merging tool that uses the cross-platform Tk
-        windowing toolkit.
-    xxdiff
-        A graphical, three-way merging tool.
-    imediff2
-        A textual, fullscreen two-way merging tool. This tool is useful when
-        you are working remotely via SSH.
-Installation
-Once you have satisfied the necessary requirements, you can install Ruby-VPI by
-running the command gem install ruby-vpi. RubyGems will install Ruby-VPI into
-the system gem directory, whose path can be determined by running the command
-gem env gemdir. Within this directory, there is a "gems" subdirectory which
-contains the Ruby-VPI installation, as illustrated below.
-$ gem env gemdir
-/usr/lib/ruby/gems/1.8
-$ ls -d /usr/lib/ruby/gems/1.8/gems/ruby-vpi-*
-/usr/lib/ruby/gems/1.8/gems/ruby-vpi-7.0.0/
-Installing on Windows
- 1. Install Cygwin, the Linux-like environment for Windows.
- 2. Search for object files whose names end with .so, .o, or .dll in your
-    Verilog simulator's installation directory.
- 3. Determine which object files, among those found in the previous step,
-    contain symbols whose names begin with _vpi^[1] by running the command for
-    x in *.{o,so,dll}; do nm $x | grep -q '[Tt] _vpi' > /dev/null && echo $x;
-    done in Cygwin.
-    [Tip] Tip
-          If you are using Mentor Modelsim, the desired object file can be
-          found at a path similar to C:\Modeltech\win32\libvsim.dll.
-    [Tip] Tip
-          If you are using GPL Cver, the desired object file can be found at a
-          path similar to C:\gplcver\objs\v_vpi.o.
- 4. Assign the path of the object file (determined in the previous step) to the
-    LDFLAGS environment variable. For example, if the object file's path is /
-    foo/bar/vpi.so, then you would run the command export LDFLAGS=/foo/bar/
-    vpi.so in Cygwin.
- 5. You may now install Ruby-VPI by running the command gem install ruby-vpi in
-    Cygwin.
-Maintenance
-You can uninstall Ruby-VPI by running the command gem uninstall ruby-vpi.
-Furthermore, you can upgrade to the latest release of Ruby-VPI by running the
-command gem update ruby-vpi. Finally, you can learn more about using and
-manipulating RubyGems in the RubyGems user manual.
-━━━━━━━━━━━━━━
-^[1] Because Ruby-VPI makes use of the VPI C-language interface, it links to
-symbols whose names begin with _vpi. It is possible for these symbols to be
-undefined when Ruby-VPI is compiled under GNU/Linux and similar operating
-systems. In contrast, one cannot compile a shared object file with references
-to undefined symbols under Windows. Thus, we must find a Verilog simulator's
-shared object file, which contains definitions of all VPI symbols, and give
-this file to the linker when compiling Ruby-VPI.
-Chapter 4. Usage
-Table of Contents
-Tools
-    Automated test generation
-    Verilog to Ruby conversion
-Tutorial
-    Start with a design
-    Generate a test
-    Specify your expectations
-    Implement the prototype
-    Verify the prototype
-    Implement the design
-    Verify the design
-Examples
-Tools
-The bin directory contains various utilities which ease the process of writing
-tests. Each tool provides help and usage information invoked with the --help
-option.
-Automated test generation
-The automated test generator (generate_test.rb) generates tests from Verilog
-2001 module declarations, as demonstrated in the section called “Generate a
-test”. A generated test is composed of the following parts:
-Runner
-    Written in Rake, this file builds and runs the test.
-Bench
-    Written in Verilog and Ruby, these files define the testing environment.
-Design
-    Written in Ruby, this file provides an interface to the design being
-    verified.
-Prototype
-    Written in Ruby, this file defines a prototype of the design being
-    verified.
-Specification
-    Written in Ruby, this file verifies the design.
-The reason for dividing a single test into these parts is mainly to decouple
-the design from the specification. This allows you to focus on writing the
-specification while the remainder is automatically generated by the tool. For
-example, when the interface of a Verilog module changes, you would simply
-re-run this tool and incorporate those changes (using a text merging tool) into
-the test without diverting your focus from the specification.
-[Tip] Using kdiff3 with the automated test generator
-      Create a file named merge2 with the content below, make it executable,
-      and put it somewhere accessible by your PATH environment variable. Next,
-      update the MERGER environment variable by executing export MERGER=merge2.
-      #!/bin/sh
-      # args: old file, new file
-      kdiff3 --auto --merge --output "$2" "$@" 2>/dev/null
-      From now on, kdiff3 will be invoked to help you transfer your changes
-      between generated files. When you are finished transferring changes,
-      simply issue the "save the file" command and terminate kdiff3. Or, if you
-      do not want to transfer any changes, simply terminate kdiff3.
-Verilog to Ruby conversion
-The header_to_ruby.rb tool can be used to convert Verilog header files into
-Ruby. You can try it by running the command header_to_ruby.rb --help.
-Tutorial
-Procedure 4.1. Typical way of using Ruby-VPI
- 1. Declare the design, which is a Verilog module, using Verilog 2001 syntax.
- 2. Generate a test for the design using the automated test generator tool.
- 3. Identify your expectations for the design and implement them in the
-    specification.
- 4. (Optional) Implement the prototype of the design in Ruby.
- 5. (Optional) Verify the prototype against the specification.
- 6. Implement the design in Verilog once the prototype has been verified.
- 7. Verify the design against the specification.
-Start with a design
-First, we need a Design to verify. In this tutorial, Figure 4.1, “Declaration
-of a simple up-counter with synchronous reset” will serve as our design. Its
-interface is composed of the following parts:
-Size
-    This parameter defines the number of bits used to represent the counter's
-    value.
-clock
-    Each positive edge of this signal causes the count register to increment.
-reset
-    Assertion of this signal causes the count register to become zero.
-count
-    This register contains the counter's value.
-Figure 4.1. Declaration of a simple up-counter with synchronous reset
-module counter #(parameter Size = 5) (
-  input clock,
-  input reset,
-  output reg [Size - 1 : 0] count
-);
-endmodule
-[Important] Before we continue…
-            Save the source code shown in Figure 4.1, “Declaration of a simple
-            up-counter with synchronous reset” into a file named counter.v.
-Generate a test
-Now that we have a Design to verify, let us generate a Test for it using the
-automated test generator. This tool allows us to implement our Specification in
-either rSpec, xUnit, or our very own format. Each format represents a different
-software development methodology: rSpec represents BDD, xUnit represents TDD,
-and our own format can represent another methodology. Both rSpec and xUnit are
-presented in this tutorial.
-Once we have decided how we want to implement our specification, we can proceed
-to generate a test for our design. Figure 4.2, “Generating a test with
-specification in rSpec format” and Figure 4.3, “Generating a test with
-specification in xUnit format” illustrate this process.
-Figure 4.2. Generating a test with specification in rSpec format
-$ generate_test.rb counter.v --rspec --name rspec
-    name  rspec
-  format  rSpec
-  module  counter
-  create  counter_rspec_runner.rake
-  create  counter_rspec_bench.v
-  create  counter_rspec_bench.rb
-  create  counter_rspec_design.rb
-  create  counter_rspec_proto.rb
-  create  counter_rspec_spec.rb
-Figure 4.3. Generating a test with specification in xUnit format
-$ generate_test.rb counter.v --xunit --name xunit
-    name  xunit
-  format  xUnit
-  module  counter
-  create  counter_xunit_runner.rake
-  create  counter_xunit_bench.v
-  create  counter_xunit_bench.rb
-  create  counter_xunit_design.rb
-  create  counter_xunit_proto.rb
-  create  counter_xunit_spec.rb
-Specify your expectations
-So far, the test generation tool has created a basic foundation for our Test.
-Now we must build upon this foundation by identifying our Expectations of the
-Design. That is, how do we expect the design to behave under certain
-conditions?
-The following is a reasonable set of expectations for our simple counter:
-  ● A resetted counter's value should be zero.
-  ● A resetted counter's value should increment by one count upon each rising
-    clock edge.
-  ● A counter with the maximum value should overflow upon increment.
-Now that we have identified a set of expectations for our design, we are ready
-to implement them in our specification. Figure 4.4, “Specification implemented
-in rSpec format” and Figure 4.5, “Specification implemented in xUnit format”
-illustrate this process. Note the striking similarities between our
-expectations and their implementation.
-Figure 4.4. Specification implemented in rSpec format
-# lowest upper bound of counter's value
-LIMIT = 2 ** Counter.Size.intVal
-# maximum allowed value for a counter
-MAX = LIMIT - 1
-context "A resetted counter's value" do
-  setup do
-    Counter.reset!
-  end
-  specify "should be zero" do
-    Counter.count.intVal.should_equal 0
-  end
-  specify "should increment by one count upon each rising clock edge" do
-    LIMIT.times do |i|
-      Counter.count.intVal.should_equal i
-      relay_verilog # advance the clock
-    end
-  end
-end
-context "A counter with the maximum value" do
-  setup do
-    Counter.reset!
-    # increment the counter to maximum value
-    MAX.times do relay_verilog end
-    Counter.count.intVal.should_equal MAX
-  end
-  specify "should overflow upon increment" do
-    relay_verilog # increment the counter
-    Counter.count.intVal.should_equal 0
-  end
-end
-Figure 4.5. Specification implemented in xUnit format
-# lowest upper bound of counter's value
-LIMIT = 2 ** Counter.Size.intVal
-# maximum allowed value for a counter
-MAX = LIMIT - 1
-class ResettedCounterValue < Test::Unit::TestCase
-  def setup
-    Counter.reset!
-  end
-  def test_zero
-    assert_equal 0, Counter.count.intVal
-  end
-  def test_increment
-    LIMIT.times do |i|
-      assert_equal i, Counter.count.intVal
-      relay_verilog # advance the clock
-    end
-  end
-end
-class MaximumCounterValue < Test::Unit::TestCase
-  def setup
-    Counter.reset!
-    # increment the counter to maximum value
-    MAX.times do relay_verilog end
-    assert_equal MAX, Counter.count.intVal
-  end
-  def test_overflow
-    relay_verilog # increment the counter
-    assert_equal 0, Counter.count.intVal
-  end
-end
-[Important] Before we continue…
-              ● Replace the contents of the file named counter_rspec_spec.rb
-                with the source code shown in Figure 4.4, “Specification
-                implemented in rSpec format”.
-              ● Replace the contents of the file named counter_xunit_spec.rb
-                with the source code shown in Figure 4.5, “Specification
-                implemented in xUnit format”.
-              ● Replace the contents of the files named counter_rspec_design.rb
-                and counter_xunit_design.rb with the following code. This code
-                defines the reset! method which resets our Verilog design.
-                def Counter.reset!
-                  reset.intVal = 1
-                  relay_verilog # advance the clock
-                  reset.intVal = 0
-                end
-Implement the prototype
-Now that we have a Specification against which to verify our Design, let us
-build a prototype of our design. By doing so, we exercise our specification,
-experience potential problems that may arise when we later implement our design
-in Verilog, and gain confidence in our work. Figure 4.6, “Ruby prototype of our
-Verilog design” shows the completed prototype for our design.
-Figure 4.6. Ruby prototype of our Verilog design
-def Counter.simulate!
-  if reset.intVal == 1
-    count.intVal = 0
-  else
-    count.intVal += 1
-  end
-end
-[Important] Before we continue…
-            Replace the contents of the files named counter_rspec_proto.rb and
-            counter_xunit_proto.rb with the source code shown in Figure 4.6,
-            “Ruby prototype of our Verilog design”.
-Verify the prototype
-Now that we have implemented our prototype, we are ready to verify it against
-our Specification by running the Test. Figure 4.7, “Running a test with
-specification in rSpec format” and Figure 4.8, “Running a test with
-specification in xUnit format” illustrate this process.
-[Tip] Reuse your past efforts!
-      The same specification can be used to verify both prototype and design.
-Here, the PROTOTYPE environment variable is assigned a non-empty value while
-running the test, so that, instead of our design, our prototype is verified
-against our specification. You can also assign a value to PROTOTYPE before
-running the test, by using your shell's export or setenv command. Finally, the
-Icarus Verilog simulator, denoted by cver, is used to run the simulation.
-[Tip] What can the test runner do?
-      If you invoke the test runner (1) without any arguments or (2) with the
-      -T option, it will show you a list of tasks that it can perform for you.
-Figure 4.7. Running a test with specification in rSpec format
-$ rake -f counter_rspec_runner.rake cver PROTOTYPE=1
-counter_rspec: verifying prototype instead of design
-A resetted counter's value
-- should be zero
-- should increment by one count upon each rising clock edge
-A counter with the maximum value
-- should overflow upon increment
-Finished in 0.018199 seconds
-3 specifications, 0 failures
-Figure 4.8. Running a test with specification in xUnit format
-$ rake -f counter_xunit_runner.rake cver PROTOTYPE=1
-counter_xunit: verifying prototype instead of design
-Loaded suite counter_xunit_bench
-Started
-...
-Finished in 0.040668 seconds.
-3 tests, 35 assertions, 0 failures, 0 errors
-Implement the design
-Now that we have implemented and verified our prototype, we are ready to
-implement our Design. This is often quite simple because we translate existing
-code from Ruby (our prototype) into Verilog (our design). Figure 4.9,
-“Implementation of a simple up-counter with synchronous reset” illustrates the
-result of this process. Once again, note the striking similarities between the
-implementation of our prototype and design.
-Figure 4.9. Implementation of a simple up-counter with synchronous reset
-module counter #(parameter Size = 5) (
-  input clock,
-  input reset,
-  output reg [Size - 1 : 0] count
-);
-  always @(posedge clock) begin
-    if (reset)
-      count <= 0;
-    else
-      count <= count + 1;
-  end
-endmodule
-[Important] Before we continue…
-            Replace the contents of the file named counter.v with the source
-            code shown in Figure 4.9, “Implementation of a simple up-counter
-            with synchronous reset”.
-Verify the design
-Now that we have implemented our Design, we are ready to verify it against our
-Specification by running the Test. Figure 4.10, “Running a test with
-specification in rSpec format” and Figure 4.11, “Running a test with
-specification in xUnit format” illustrate this process.
-Here, the PROTOTYPE environment variable is not specified while running the
-test, so that our design, instead of our prototype, is verified against our
-specification. You can also achieve this effect by assigning an empty value to
-PROTOTYPE, or by using your shell's unset command. Finally, the GPL Cver
-Verilog simulator, denoted by cver, is used to run the simulation.
-[Tip] Running multiple tests
-      Create a file named Rakefile containing the following line.
-      require 'ruby-vpi/runner_proxy'
-      Now you can invoke all test runners in the current directory simply by
-      executing rake cver (where cver denotes the GPL Cver simulator).
-Figure 4.10. Running a test with specification in rSpec format
-$ rake -f counter_rspec_runner.rake cver
-A resetted counter's value
-- should be zero
-- should increment by one count upon each rising clock edge
-A counter with the maximum value
-- should overflow upon increment
-Finished in 0.005628 seconds
-3 specifications, 0 failures
-Figure 4.11. Running a test with specification in xUnit format
-$ rake -f counter_xunit_runner.rake cver
-Loaded suite counter_xunit_bench
-Started
-...
-Finished in 0.006766 seconds.
-3 tests, 35 assertions, 0 failures, 0 errors
-Examples
-The samp directory contains several example tests which illustrate how Ruby-VPI
-can be used. Each example has an associated Rakefile which simplifies the
-process of running it. Therefore, simply navigate into an example directory and
-run the command rake to get started.
-Also, some example specifications make use of BDD through the rSpec library.
-See the the section called “Methodology” for a discussion of rSpec.
-Chapter 5. Hacking
-Table of Contents
-Building release packages
-Building release packages
-In addition to the "normal requirements":./doc/usage.requirements.html, you
-need the following software to build release packages:
-DocBook-XML
-xsltproc
-xmlto
-RedCloth
-SWIG
-Once you have satisfied these requirements, you can run rake release to build
-the release packages. Also, see the output of rake -T for more build options.
-Chapter 6. Known problems
-Table of Contents
-Ruby
-    SystemStackError
-    test/unit
-Icarus Verilog
-    vpi_handle_by_name
-    Vpi::reset
-Mentor Modelsim
-    ruby_run()
-This chapter presents known problems and possible solutions. In addition,
-previously solved problems have been retained for historical reference.
-Ruby
-SystemStackError
-[Note] Problem solved
-       This problem was fixed in release 2.0.0 (2006-04-17). If it still
-       occurs, then please report it.
-If a “stack level too deep (SystemStackError)” error occurs during the
-simulation, then increase the system-resource limit for stack-size by running
-the command ulimit -s unlimited before starting the simulation.
-test/unit
-[Note] Problem solved
-       This problem was fixed in release 2.0.0 (2006-04-17). If it still
-       occurs, then please report it.
-If your specification employs Ruby's unit testing framework, then you will
-encounter the error: “[BUG] cross-thread violation on rb_gc()”.
-Icarus Verilog
-vpi_handle_by_name
-Give full paths to Verilog objects
-In version 0.8 and snapshot 20061009 of Icarus Verilog, the vpi_handle_by_name
-function requires an absolute path (including the name of the bench which
-instantiates the design) to a Verilog object. In addition, vpi_handle_by_name
-is unable to retrieve the handle for a module parameter.
-For example, consider Example 6.1, “Part of a bench which instantiates a
-Verilog design”. Here, one needs to specify TestFoo.my_foo.clk instead of
-my_foo.clk in order to access the clk input of the my_foo module instance.
-Example 6.1. Part of a bench which instantiates a Verilog design
-module TestFoo;
-  reg clk_reg;
-  Foo my_foo(.clk(clk_reg));
-endmodule
-Registers must be connected
-In version 0.8 of Icarus Verilog, if you want to access a register in a design,
-then it must be connected to something (either assigned to a wire or passed as
-a parameter to a module instantiation). Otherwise, you will get a nil value as
-the result of vpi_handle_by_name method.
-For example, suppose you wanted to access the clk_reg register, from the bench
-shown in Example 6.2, “Bad design with unconnected registers”. If you execute
-the statement clk_reg = vpi_handle_by_name("TestFoo.clk_reg", nil) in a
-specification, then you will discover that the vpi_handle_by_name method
-returns nil instead of a handle to the clk_reg register.
-The solution is to change the design such that it appears like the one shown in
-Example 6.3, “Fixed design with wired registers” where the register is
-connected to a wire, or Example 6.1, “Part of a bench which instantiates a
-Verilog design” where the register is connected to a module instantiation.
-Example 6.2. Bad design with unconnected registers
-Here the clk_reg register is not connected to anything.
-module TestFoo;
-  reg clk_reg;
-endmodule
-Example 6.3. Fixed design with wired registers
-Here the clk_reg register is connected to the clk_wire wire.
-module TestFoo;
-  reg clk_reg;
-  wire clk_wire;
-  assign clk_wire = clk_reg;
-endmodule
-Vpi::reset
-[Caution] Deprecated method
-          The vpi_control method was removed in release 3.0.0 (2006-04-23) of
-          Ruby-VPI, and is deprecated. Please use Vpi::vpi_control(VpiReset)
-          instead.
-In version 0.8 of Icarus Verilog, the vpi_control(vpiReset) VPI function causes
-an assertion to fail inside the simulator. As a result, the simulation
-terminates and a core dump is produced.
-Mentor Modelsim
-ruby_run()
-[Note] Problem solved
-       This problem was fixed in release 2.0.0 (2006-04-17). If it still
-       occurs, then please report it.
-Version 6.1b of Mentor Modelsim doesn't play nicely with either an embedded
-Ruby interpreter or POSIX threads in a PLI application. When Ruby-VPI invokes
-the ruby_run function (which starts the Ruby interpreter), the simulator
-terminates immediately with an exit status of 0.
-Glossary
-B
-Bench
-    An environment in which a Design is verified against a Specification.
-    Often, it is used to emulate conditions in which the design will be
-    eventually deployed.
-BDD
-    Behavior driven development.
-    A software development methodology which emphasizes thinking in terms of
-    behavior when designing, implementing, and verifying software. See the
-    official wiki for more information.
-    See Also TDD, rSpec.
-D
-Design
-    An idea or entity that is verified against a Specification in order to
-    ensure correctness or soundness of its being. In other words, it is the
-    thing being checked: does it work or not?
-E
-Expectation
-    The desired response to some stimulus.
-H
-Handle
-    An object in a Verilog simulation. For example, a handle can represent a
-    wire, register, module, if-statement, expression, and so on.
-R
-Rake
-            Rake is a build tool, written in Ruby, using Ruby as a
-            build language. Rake is similar to make in scope and
-            purpose.
-                                                           --Rake documentation
-    See the Rake website for more information.
-rSpec
-    Ruby framework for BDD. See the rSpec website and rSpec tutorial for more
-    information.
-    See Also BDD.
-S
-Specification
-    A set of Expectations which define the desired behavior of a Design when it
-    is subjected to certain conditions.
-T
-TDD
-    Test Driven Development.
-    See Also BDD.
-Test
-    Something that checks if a Design satisfies a Specification.
-    See Also Test bench.
-Test bench
-    An allusion to a bench in an electronics laboratory, or so it seems.
-    See Also Test.
-GNU Free Documentation License
-Version 1.2, November 2002
-Copyright © 2000,2001,2002 Free Software Foundation, Inc.
-Free Software Foundation, Inc.
- 51 Franklin St, Fifth Floor,
- Boston,
- MA
- 02110-1301
- USA
-Everyone is permitted to copy and distribute verbatim copies of this license
-document, but changing it is not allowed.
-Version 1.2, November 2002
-Table of Contents
-PREAMBLE
-APPLICABILITY AND DEFINITIONS
-VERBATIM COPYING
-COPYING IN QUANTITY
-MODIFICATIONS
-COMBINING DOCUMENTS
-COLLECTIONS OF DOCUMENTS
-AGGREGATION WITH INDEPENDENT WORKS
-TRANSLATION
-TERMINATION
-FUTURE REVISIONS OF THIS LICENSE
-ADDENDUM: How to use this License for your documents
-PREAMBLE
-The purpose of this License is to make a manual, textbook, or other functional
-and useful document "free" in the sense of freedom: to assure everyone the
-effective freedom to copy and redistribute it, with or without modifying it,
-either commercially or noncommercially. Secondarily, this License preserves for
-the author and publisher a way to get credit for their work, while not being
-considered responsible for modifications made by others.
-This License is a kind of "copyleft", which means that derivative works of the
-document must themselves be free in the same sense. It complements the GNU
-General Public License, which is a copyleft license designed for free software.
-We have designed this License in order to use it for manuals for free software,
-because free software needs free documentation: a free program should come with
-manuals providing the same freedoms that the software does. But this License is
-not limited to software manuals; it can be used for any textual work,
-regardless of subject matter or whether it is published as a printed book. We
-recommend this License principally for works whose purpose is instruction or
-reference.
-APPLICABILITY AND DEFINITIONS
-This License applies to any manual or other work, in any medium, that contains
-a notice placed by the copyright holder saying it can be distributed under the
-terms of this License. Such a notice grants a world-wide, royalty-free license,
-unlimited in duration, to use that work under the conditions stated herein. The
-"Document", below, refers to any such manual or work. Any member of the public
-is a licensee, and is addressed as "you". You accept the license if you copy,
-modify or distribute the work in a way requiring permission under copyright
-law.
-A "Modified Version" of the Document means any work containing the Document or
-a portion of it, either copied verbatim, or with modifications and/or
-translated into another language.
-A "Secondary Section" is a named appendix or a front-matter section of the
-Document that deals exclusively with the relationship of the publishers or
-authors of the Document to the Document's overall subject (or to related
-matters) and contains nothing that could fall directly within that overall
-subject. (Thus, if the Document is in part a textbook of mathematics, a
-Secondary Section may not explain any mathematics.) The relationship could be a
-matter of historical connection with the subject or with related matters, or of
-legal, commercial, philosophical, ethical or political position regarding them.
-The "Invariant Sections" are certain Secondary Sections whose titles are
-designated, as being those of Invariant Sections, in the notice that says that
-the Document is released under this License. If a section does not fit the
-above definition of Secondary then it is not allowed to be designated as
-Invariant. The Document may contain zero Invariant Sections. If the Document
-does not identify any Invariant Sections then there are none.
-The "Cover Texts" are certain short passages of text that are listed, as
-Front-Cover Texts or Back-Cover Texts, in the notice that says that the
-Document is released under this License. A Front-Cover Text may be at most 5
-words, and a Back-Cover Text may be at most 25 words.
-A "Transparent" copy of the Document means a machine-readable copy, represented
-in a format whose specification is available to the general public, that is
-suitable for revising the document straightforwardly with generic text editors
-or (for images composed of pixels) generic paint programs or (for drawings)
-some widely available drawing editor, and that is suitable for input to text
-formatters or for automatic translation to a variety of formats suitable for
-input to text formatters. A copy made in an otherwise Transparent file format
-whose markup, or absence of markup, has been arranged to thwart or discourage
-subsequent modification by readers is not Transparent. An image format is not
-Transparent if used for any substantial amount of text. A copy that is not
-"Transparent" is called "Opaque".
-Examples of suitable formats for Transparent copies include plain ASCII without
-markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly
-available DTD, and standard-conforming simple HTML, PostScript or PDF designed
-for human modification. Examples of transparent image formats include PNG, XCF
-and JPG. Opaque formats include proprietary formats that can be read and edited
-only by proprietary word processors, SGML or XML for which the DTD and/or
-processing tools are not generally available, and the machine-generated HTML,
-PostScript or PDF produced by some word processors for output purposes only.
-The "Title Page" means, for a printed book, the title page itself, plus such
-following pages as are needed to hold, legibly, the material this License
-requires to appear in the title page. For works in formats which do not have
-any title page as such, "Title Page" means the text near the most prominent
-appearance of the work's title, preceding the beginning of the body of the
-text.
-A section "Entitled XYZ" means a named subunit of the Document whose title
-either is precisely XYZ or contains XYZ in parentheses following text that
-translates XYZ in another language. (Here XYZ stands for a specific section
-name mentioned below, such as "Acknowledgements", "Dedications",
-"Endorsements", or "History".) To "Preserve the Title" of such a section when
-you modify the Document means that it remains a section "Entitled XYZ"
-according to this definition.
-The Document may include Warranty Disclaimers next to the notice which states
-that this License applies to the Document. These Warranty Disclaimers are
-considered to be included by reference in this License, but only as regards
-disclaiming warranties: any other implication that these Warranty Disclaimers
-may have is void and has no effect on the meaning of this License.
-VERBATIM COPYING
-You may copy and distribute the Document in any medium, either commercially or
-noncommercially, provided that this License, the copyright notices, and the
-license notice saying this License applies to the Document are reproduced in
-all copies, and that you add no other conditions whatsoever to those of this
-License. You may not use technical measures to obstruct or control the reading
-or further copying of the copies you make or distribute. However, you may
-accept compensation in exchange for copies. If you distribute a large enough
-number of copies you must also follow the conditions in section 3.
-You may also lend copies, under the same conditions stated above, and you may
-publicly display copies.
-COPYING IN QUANTITY
-If you publish printed copies (or copies in media that commonly have printed
-covers) of the Document, numbering more than 100, and the Document's license
-notice requires Cover Texts, you must enclose the copies in covers that carry,
-clearly and legibly, all these Cover Texts: Front-Cover Texts on the front
-cover, and Back-Cover Texts on the back cover. Both covers must also clearly
-and legibly identify you as the publisher of these copies. The front cover must
-present the full title with all words of the title equally prominent and
-visible. You may add other material on the covers in addition. Copying with
-changes limited to the covers, as long as they preserve the title of the
-Document and satisfy these conditions, can be treated as verbatim copying in
-other respects.
-If the required texts for either cover are too voluminous to fit legibly, you
-should put the first ones listed (as many as fit reasonably) on the actual
-cover, and continue the rest onto adjacent pages.
-If you publish or distribute Opaque copies of the Document numbering more than
-100, you must either include a machine-readable Transparent copy along with
-each Opaque copy, or state in or with each Opaque copy a computer-network
-location from which the general network-using public has access to download
-using public-standard network protocols a complete Transparent copy of the
-Document, free of added material. If you use the latter option, you must take
-reasonably prudent steps, when you begin distribution of Opaque copies in
-quantity, to ensure that this Transparent copy will remain thus accessible at
-the stated location until at least one year after the last time you distribute
-an Opaque copy (directly or through your agents or retailers) of that edition
-to the public.
-It is requested, but not required, that you contact the authors of the Document
-well before redistributing any large number of copies, to give them a chance to
-provide you with an updated version of the Document.
-MODIFICATIONS
-You may copy and distribute a Modified Version of the Document under the
-conditions of sections 2 and 3 above, provided that you release the Modified
-Version under precisely this License, with the Modified Version filling the
-role of the Document, thus licensing distribution and modification of the
-Modified Version to whoever possesses a copy of it. In addition, you must do
-these things in the Modified Version:
-GNU FDL Modification Conditions
- A. Use in the Title Page (and on the covers, if any) a title distinct from
-    that of the Document, and from those of previous versions (which should, if
-    there were any, be listed in the History section of the Document). You may
-    use the same title as a previous version if the original publisher of that
-    version gives permission.
- B. List on the Title Page, as authors, one or more persons or entities
-    responsible for authorship of the modifications in the Modified Version,
-    together with at least five of the principal authors of the Document (all
-    of its principal authors, if it has fewer than five), unless they release
-    you from this requirement.
- C. State on the Title page the name of the publisher of the Modified Version,
-    as the publisher.
- D. Preserve all the copyright notices of the Document.
- E. Add an appropriate copyright notice for your modifications adjacent to the
-    other copyright notices.
- F. Include, immediately after the copyright notices, a license notice giving
-    the public permission to use the Modified Version under the terms of this
-    License, in the form shown in the Addendum below.
- G. Preserve in that license notice the full lists of Invariant Sections and
-    required Cover Texts given in the Document's license notice.
- H. Include an unaltered copy of this License.
- I. Preserve the section Entitled "History", Preserve its Title, and add to it
-    an item stating at least the title, year, new authors, and publisher of the
-    Modified Version as given on the Title Page. If there is no section
-    Entitled "History" in the Document, create one stating the title, year,
-    authors, and publisher of the Document as given on its Title Page, then add
-    an item describing the Modified Version as stated in the previous sentence.
- J. Preserve the network location, if any, given in the Document for public
-    access to a Transparent copy of the Document, and likewise the network
-    locations given in the Document for previous versions it was based on.
-    These may be placed in the "History" section. You may omit a network
-    location for a work that was published at least four years before the
-    Document itself, or if the original publisher of the version it refers to
-    gives permission.
- K. For any section Entitled "Acknowledgements" or "Dedications", Preserve the
-    Title of the section, and preserve in the section all the substance and
-    tone of each of the contributor acknowledgements and/or dedications given
-    therein.
- L. Preserve all the Invariant Sections of the Document, unaltered in their
-    text and in their titles. Section numbers or the equivalent are not
-    considered part of the section titles.
- M. Delete any section Entitled "Endorsements". Such a section may not be
-    included in the Modified Version.
- N. Do not retitle any existing section to be Entitled "Endorsements" or to
-    conflict in title with any Invariant Section.
- O. Preserve any Warranty Disclaimers.
-If the Modified Version includes new front-matter sections or appendices that
-qualify as Secondary Sections and contain no material copied from the Document,
-you may at your option designate some or all of these sections as invariant. To
-do this, add their titles to the list of Invariant Sections in the Modified
-Version's license notice. These titles must be distinct from any other section
-titles.
-You may add a section Entitled "Endorsements", provided it contains nothing but
-endorsements of your Modified Version by various parties--for example,
-statements of peer review or that the text has been approved by an organization
-as the authoritative definition of a standard.
-You may add a passage of up to five words as a Front-Cover Text, and a passage
-of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts
-in the Modified Version. Only one passage of Front-Cover Text and one of
-Back-Cover Text may be added by (or through arrangements made by) any one
-entity. If the Document already includes a cover text for the same cover,
-previously added by you or by arrangement made by the same entity you are
-acting on behalf of, you may not add another; but you may replace the old one,
-on explicit permission from the previous publisher that added the old one.
-The author(s) and publisher(s) of the Document do not by this License give
-permission to use their names for publicity for or to assert or imply
-endorsement of any Modified Version.
-COMBINING DOCUMENTS
-You may combine the Document with other documents released under this License,
-under the terms defined in section 4 above for modified versions, provided that
-you include in the combination all of the Invariant Sections of all of the
-original documents, unmodified, and list them all as Invariant Sections of your
-combined work in its license notice, and that you preserve all their Warranty
-Disclaimers.
-The combined work need only contain one copy of this License, and multiple
-identical Invariant Sections may be replaced with a single copy. If there are
-multiple Invariant Sections with the same name but different contents, make the
-title of each such section unique by adding at the end of it, in parentheses,
-the name of the original author or publisher of that section if known, or else
-a unique number. Make the same adjustment to the section titles in the list of
-Invariant Sections in the license notice of the combined work.
-In the combination, you must combine any sections Entitled "History" in the
-various original documents, forming one section Entitled "History"; likewise
-combine any sections Entitled "Acknowledgements", and any sections Entitled
-"Dedications". You must delete all sections Entitled "Endorsements".
-COLLECTIONS OF DOCUMENTS
-You may make a collection consisting of the Document and other documents
-released under this License, and replace the individual copies of this License
-in the various documents with a single copy that is included in the collection,
-provided that you follow the rules of this License for verbatim copying of each
-of the documents in all other respects.
-You may extract a single document from such a collection, and distribute it
-individually under this License, provided you insert a copy of this License
-into the extracted document, and follow this License in all other respects
-regarding verbatim copying of that document.
-AGGREGATION WITH INDEPENDENT WORKS
-A compilation of the Document or its derivatives with other separate and
-independent documents or works, in or on a volume of a storage or distribution
-medium, is called an "aggregate" if the copyright resulting from the
-compilation is not used to limit the legal rights of the compilation's users
-beyond what the individual works permit. When the Document is included in an
-aggregate, this License does not apply to the other works in the aggregate
-which are not themselves derivative works of the Document.
-If the Cover Text requirement of section 3 is applicable to these copies of the
-Document, then if the Document is less than one half of the entire aggregate,
-the Document's Cover Texts may be placed on covers that bracket the Document
-within the aggregate, or the electronic equivalent of covers if the Document is
-in electronic form. Otherwise they must appear on printed covers that bracket
-the whole aggregate.
-TRANSLATION
-Translation is considered a kind of modification, so you may distribute
-translations of the Document under the terms of section 4. Replacing Invariant
-Sections with translations requires special permission from their copyright
-holders, but you may include translations of some or all Invariant Sections in
-addition to the original versions of these Invariant Sections. You may include
-a translation of this License, and all the license notices in the Document, and
-any Warranty Disclaimers, provided that you also include the original English
-version of this License and the original versions of those notices and
-disclaimers. In case of a disagreement between the translation and the original
-version of this License or a notice or disclaimer, the original version will
-prevail.
-If a section in the Document is Entitled "Acknowledgements", "Dedications", or
-"History", the requirement (section 4) to Preserve its Title (section 1) will
-typically require changing the actual title.
-TERMINATION
-You may not copy, modify, sublicense, or distribute the Document except as
-expressly provided for under this License. Any other attempt to copy, modify,
-sublicense or distribute the Document is void, and will automatically terminate
-your rights under this License. However, parties who have received copies, or
-rights, from you under this License will not have their licenses terminated so
-long as such parties remain in full compliance.
-FUTURE REVISIONS OF THIS LICENSE
-The Free Software Foundation may publish new, revised versions of the GNU Free
-Documentation License from time to time. Such new versions will be similar in
-spirit to the present version, but may differ in detail to address new problems
-or concerns. See http://www.gnu.org/copyleft/.
-Each version of the License is given a distinguishing version number. If the
-Document specifies that a particular numbered version of this License "or any
-later version" applies to it, you have the option of following the terms and
-conditions either of that specified version or of any later version that has
-been published (not as a draft) by the Free Software Foundation. If the
-Document does not specify a version number of this License, you may choose any
-version ever published (not as a draft) by the Free Software Foundation.
-ADDENDUM: How to use this License for your documents
-To use this License in a document you have written, include a copy of the
-License in the document and put the following copyright and license notices
-just after the title page:
-    Sample Invariant Sections list
-    Copyright (c) YEAR YOUR NAME. Permission is granted to copy, distribute and
-    /or modify this document under the terms of the GNU Free Documentation
-    License, Version 1.2 or any later version published by the Free Software
-    Foundation; with no Invariant Sections, no Front-Cover Texts, and no
-    Back-Cover Texts. A copy of the license is included in the section entitled
-    "GNU Free Documentation License".
-If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace
-the "with...Texts." line with this:
-    Sample Invariant Sections list
-    with the Invariant Sections being LIST THEIR TITLES, with the Front-Cover
-    Texts being LIST, and with the Back-Cover Texts being LIST.
-If you have Invariant Sections without Cover Texts, or some other combination
-of the three, merge those two alternatives to suit the situation.
-If your document contains nontrivial examples of program code, we recommend
-releasing these examples in parallel under your choice of free software
-license, such as the GNU General Public License, to permit their use in free
-software.