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

ruby-vpi 11.1.0 → 11.1.1

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.