ruby-vpi 7.0.0

data/doc/txt/manual.txt

@@ -0,0 +1,1657 @@
+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. 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. Usage
+
+    Requirements
+    Installation and maintenance
+    Tools
+
+        Automated test generation
+        Verilog to Ruby conversion
+
+    Examples
+    Tutorial
+
+        Start with a design
+        Generate a test
+        Specify your expectations
+        Implement the prototype
+        Verify the prototype
+        Implement the design
+        Verify the design
+
+4. 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
+3.1. Declaration of a simple up-counter with synchronous reset
+3.2. Generating a test with specification in RSpec format
+3.3. Generating a test with specification in unit test format
+3.4. Specification implemented in RSpec format
+3.5. Specification implemented in unit test format
+3.6. Ruby prototype of our Verilog design
+3.7. Running a test with specification in RSpec format
+3.8. Running a test with specification in unit test format
+3.9. Implementation of a simple up-counter with synchronous reset
+3.10. Running a test with specification in RSpec format
+3.11. Running a test with specification in unit test 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
+4.1. Part of a bench which instantiates a Verilog design
+4.2. Bad design with unconnected registers
+4.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 libraries, written in the Ruby language, for use by
+    specifications.
+
+tpl
+
+    This directory contains templates used by tests.
+
+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 = ≈
+    }
+
+
+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 its VPI properties.
+
+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
+    SWIG::TYPE_p_unsigned_int#method_missing 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.     │
+│                     │         │ │            │ │        │        │            │
+├─────────────────────┼─────────┼─┼────────────┼─┼────────┼────────┼────────────┤
+│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. Usage
+
+Table of Contents
+
+Requirements
+Installation and maintenance
+Tools
+
+    Automated test generation
+    Verilog to Ruby conversion
+
+Examples
+Tutorial
+
+    Start with a design
+    Generate a test
+    Specify your expectations
+    Implement the prototype
+    Verify the prototype
+    Implement the design
+    Verify the design
+
+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
+
+        Version X-2005.06 or newer is acceptable.
+
+    Mentor Modelsim
+
+        Version 6.1b or newer 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.
+
+Installation and maintenance
+
+Once you have satisfied the necessary requirements, you can install Ruby-VPI by
+running the command gem install ruby-vpi. Likewise, 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.
+
+You can learn more about using and manipulating RubyGems in the RubyGems user
+manual.
+
+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 generate_test.rb tool can be used to automatically generate tests from
+Verilog 2001 module declarations (see the section called “Generate a test”).
+You can try it by running the command generate_test.rb --help.
+
+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.
+
+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.
+
+Tutorial
+
+Procedure 3.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. Implement the prototype of the design in Ruby.
+
+ 5. 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 3.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.
+
+[Important] Before we continue…
+            Save the source code shown in Figure 3.1, “Declaration of a simple
+            up-counter with synchronous reset” into a file named counter.v.
+
+Figure 3.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
+
+Generate a test
+
+Now that we have a design to verify, let us generate a test for it using the
+automated test generator tool. This tool allows us to implement our
+specification in either RSpec, unit test, or our very own format. Each format
+represents a different software development methodology: RSpec represents BDD,
+unit testing represents TDD, and our own format can represent another
+methodology.
+
+[Note] Note
+       In this tutorial, we will see how to implement our specification in both
+       RSpec and unit test formats.
+
+Once we have decided how we want to implement our specification, we can proceed
+to generate a test for our design. Figure 3.2, “Generating a test with
+specification in RSpec format” and Figure 3.3, “Generating a test with
+specification in unit test format” illustrate this process. Here, the test
+generation tool produces a test composed of the following parts:
+
+Runner
+
+    Written in Rake, this file builds and runs the test bench.
+
+Bench
+
+    Written in Verilog and Ruby, these files define the testing environment.
+
+Design
+
+    Written in Ruby, this file provides an interface to the design under test.
+
+Prototype
+
+    Written in Ruby, this file defines a prototype of the design under test.
+
+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 to incorporate those changes into the test without diverting
+your focus from the specification.
+
+Figure 3.2. Generating a test with specification in RSpec format
+
+$ generate_test.rb counter.v --rspec --name rspecTest
+Using name `rspecTest' for generated test.
+Using RSpec specification format.
+
+Parsed module: counter
+- Generated runner:           counter_rspecTest_runner.rake
+- Generated bench:            counter_rspecTest_bench.v
+- Generated bench:            counter_rspecTest_bench.rb
+- Generated design:           counter_rspecTest_design.rb
+- Generated prototype:        counter_rspecTest_proto.rb
+- Generated specification:    counter_rspecTest_spec.rb
+
+Figure 3.3. Generating a test with specification in unit test format
+
+$ generate_test.rb counter.v --unit --name unitTest
+Using name `unitTest' for generated test.
+Using UnitTest specification format.
+
+Parsed module: counter
+- Generated runner:           counter_unitTest_runner.rake
+- Generated bench:            counter_unitTest_bench.v
+- Generated bench:            counter_unitTest_bench.rb
+- Generated design:           counter_unitTest_design.rb
+- Generated prototype:        counter_unitTest_proto.rb
+- Generated specification:    counter_unitTest_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 3.4, “Specification implemented
+in RSpec format” and Figure 3.5, “Specification implemented in unit test
+format” illustrate this process. Note the striking similarities between our
+expectations and their implementation.
+
+[Important] Before we continue…
+              ● Append the following code to the files named
+                counter_rspecTest_design.rb and counter_unitTest_design.rb.
+
+                class Counter
+                  def reset!
+                    @reset.intVal = 1
+                    relay_verilog # advance the clock
+                    @reset.intVal = 0
+                  end
+                end
+
+              ● Replace the contents of the file named
+                counter_rspecTest_spec.rb with the source code shown in
+                Figure 3.4, “Specification implemented in RSpec format”.
+
+              ● Replace the contents of the file named counter_unitTest_spec.rb
+                with the source code shown in Figure 3.5, “Specification
+                implemented in unit test format”.
+
+Figure 3.4. Specification implemented in RSpec format
+
+LIMIT = 2 ** Counter::Size  # lowest upper bound of counter's value
+MAX = LIMIT - 1             # maximum allowed value for a counter
+
+include Vpi
+
+context "A resetted counter's value" do
+  setup do
+    @design = Counter.new
+    @design.reset!
+  end
+
+  specify "should be zero" do
+    @design.count.intVal.should_equal 0
+  end
+
+  specify "should increment by one count upon each rising clock edge" do
+    LIMIT.times do |i|
+      @design.count.intVal.should_equal i
+      relay_verilog # advance the clock
+    end
+  end
+end
+
+context "A counter with the maximum value" do
+  setup do
+    @design = Counter.new
+    @design.reset!
+
+    # increment the counter to maximum value
+    MAX.times do relay_verilog end
+    @design.count.intVal.should_equal MAX
+  end
+
+  specify "should overflow upon increment" do
+    relay_verilog # increment the counter
+    @design.count.intVal.should_equal 0
+  end
+end
+
+Figure 3.5. Specification implemented in unit test format
+
+LIMIT = 2 ** Counter::Size  # lowest upper bound of counter's value
+MAX = LIMIT - 1             # maximum allowed value for a counter
+
+class ResettedCounterValue < Test::Unit::TestCase
+  include Vpi
+
+  def setup
+    @design = Counter.new
+    @design.reset!
+  end
+
+  def test_zero
+    assert_equal 0, @design.count.intVal
+  end
+
+  def test_increment
+    LIMIT.times do |i|
+      assert_equal i, @design.count.intVal
+      relay_verilog # advance the clock
+    end
+  end
+end
+
+class MaximumCounterValue < Test::Unit::TestCase
+  include Vpi
+
+  def setup
+    @design = Counter.new
+    @design.reset!
+
+    # increment the counter to maximum value
+    MAX.times do relay_verilog end
+    assert_equal MAX, @design.count.intVal
+  end
+
+  def test_overflow
+    relay_verilog # increment the counter
+    assert_equal 0, @design.count.intVal
+  end
+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 3.6, “Ruby prototype of our
+Verilog design” shows the completed prototype for our design.
+
+[Important] Before we continue…
+            Replace the contents of the files named counter_rspecTest_proto.rb
+            and counter_unitTest_proto.rb with the source code shown in
+            Figure 3.6, “Ruby prototype of our Verilog design”.
+
+Figure 3.6. Ruby prototype of our Verilog design
+
+class CounterProto < Counter
+  def simulate!
+    if @reset.intVal == 1
+      @count.intVal = 0
+    else
+      @count.intVal += 1
+    end
+  end
+end
+
+Verify the prototype
+
+Now that we have implemented our prototype, we are ready to verify it against
+our specification by running the test. Figure 3.7, “Running a test with
+specification in RSpec format” and Figure 3.8, “Running a test with
+specification in unit test format” illustrate this process.
+
+Here, the PROTO environment variable is set—any value is fine—before running
+the test in order to replace the design with the prototype in the simulation.
+Otherwise, our design will be verified—instead of our prototype—against our
+specification. Furthermore, the manner in which the PROTO environment variable
+is set in these figures follows the syntax of the GNU BASH shell. If you use a
+different shell, you may have to use different syntax, or a different command
+altogether, in order to set this variable. Finally, the Icarus Verilog
+simulator, denoted by ivl, is used to simulate our design.
+
+Figure 3.7. Running a test with specification in RSpec format
+
+$ export PROTO=1
+$ rake -f counter_rspecTest_runner.rake ivl
+counter_rspecTest: 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 3.8. Running a test with specification in unit test format
+
+$ export PROTO=1
+$ rake -f counter_unitTest_runner.rake ivl
+counter_unitTest: verifying prototype instead of design
+
+Loaded suite counter_unitTest_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 into Verilog. Figure 3.9, “Implementation of a simple up-counter
+with synchronous reset” illustrates the result of this process.
+
+[Important] Before we continue…
+            Replace the contents of the file named counter.v with the source
+            code shown in Figure 3.9, “Implementation of a simple up-counter
+            with synchronous reset”.
+
+Figure 3.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
+
+Verify the design
+
+Now that we have implemented our design, we are ready to verify it against our
+specification by running the test. Figure 3.10, “Running a test with
+specification in RSpec format” and Figure 3.11, “Running a test with
+specification in unit test format” illustrate this process.
+
+Here, the PROTO environment variable is unset before the test is run in order
+to prevent the design from being replaced by the prototype. Otherwise, our
+prototype will be verified—instead of our design—against our specification.
+Furthermore, the manner in which the PROTO environment variable is unset in
+these figures follows the syntax of the GNU BASH shell. If you use a different
+shell, you may have to use different syntax, or a different command altogether,
+in order to set this variable. Finally, the Icarus Verilog simulator, denoted
+by ivl, is used to simulate our design.
+
+Figure 3.10. Running a test with specification in RSpec format
+
+$ unset PROTO
+$ rake -f counter_rspecTest_runner.rake ivl
+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 3.11. Running a test with specification in unit test format
+
+$ unset PROTO
+$ rake -f counter_unitTest_runner.rake ivl
+Loaded suite counter_unitTest_bench
+Started
+...
+Finished in 0.006766 seconds.
+
+3 tests, 35 assertions, 0 failures, 0 errors
+
+Chapter 4. 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 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.
+
+For example, consider Example 4.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 4.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 4.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 4.3, “Fixed design with wired registers” where the register is
+connected to a wire, or Example 4.1, “Part of a bench which instantiates a
+Verilog design” where the register is connected to a module instantiation.
+
+Example 4.2. Bad design with unconnected registers
+
+Here the clk_reg register is not connected to anything.
+
+module TestFoo;
+  reg clk_reg;
+endmodule
+
+Example 4.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.
+
+H
+
+Handle
+
+    An object in a Verilog simulation.
+
+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 collection of expectations that must be satisfied by a design when
+    subjected to certain conditions.
+
+T
+
+TDD
+
+    Test Driven Development.
+
+    See Also BDD.
+
+Test
+
+    The act of verifying a design against a specification in a bench.
+
+    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.
+