ruby-vpi 13.0.0 → 14.0.0

data/doc/manual.doc

@@ -1,19 +1,21 @@
-<div class="cover-page">
-
 h1. Ruby-VPI user manual
 
-Suraj N. Kurapati
+This manual was last updated on <%= Time.now %>.
+
+It is meant to be read in conjunction with the "reference documentation for Ruby-VPI":../ref/ruby/index.html. In addition, if you are new to "the Ruby language":http://www.ruby-lang.org, you are encouraged to "explore its documentation":http://www.ruby-lang.org/en/documentation/ alongside this manual.
 
-<%= Time.now %>
+You can give feedback about this manual and, in general, any aspect of the Ruby-VPI project on the "project forums":http://rubyforge.org/forum/?group_id=1339.
 
-</div>
+_Happy reading!_
 
 
 h2(#terms). Terms
 
+Copyright (c) 2006 Suraj N. Kurapati.
+
 Permission is granted to copy, distribute and/or modify this document under the terms of the "GNU Free Documentation License":http://www.gnu.org/copyleft/fdl.html, Version 1.1 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 the file named "LICENSE":./LICENSE.
 
-Admonition and navigation graphics are Copyright (c) 2005, 2006 "Tango Desktop Project":http://tango.freedesktop.org. They are licensed under "these terms":./images/LICENSE.
+The admonition and navigation graphics used in this manual are Copyright (c) 2005, 2006 "Tango Desktop Project":http://tango.freedesktop.org and are licensed under "these terms":./images/LICENSE.
 
 
 h1(#intro). Introduction
@@ -46,8 +48,6 @@ The following projects utilize the archaic *tf* and *acc* PLI interfaces, which
 
 h1(#background). Background
 
-Ruby-VPI is a "bench":#glossary.bench which lets you "test":#glossary.test Verilog modules using the Ruby language.
-
 
 h2(#background.methodology). Methodology
 
@@ -79,132 +79,33 @@ As <xref #fig..organization> shows, a "test":#glossary.test is composed of a "be
 
 To extend the "analogy of an electronics laboratory":#background.vocab, the _bench_ acts as the laboratory bench which provides measurement and manipulation tools. The _design_ acts as the electronic component being verified by the engineer. And the _specification_ acts as the engineer who measures, manipulates, and verifies the electronic component.
 
-
-h3(#background.org.vpi). Interface to VPI
-
 <% figure "Detailed organization of a test", "#fig..organization.detail" do %>
 !figures/organization_detailed.png!
 <% end %>
 
-In <xref #fig..organization.detail>, 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.
-
-bq. 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.
+Now, let us take a more detailed look at this organization, as illustrated in <xref #fig..organization.detail>.
 
-<code lang="c">
-void foo(va_list ap) {
-  va_list *p = &ap;
-}
-</code>
-
-
-h4(#background.org.vpi.util). VPI utility layer
-
-From a user's perspective, the VPI utility layer (see <xref #fig..organization.detail>) greatly enhances the ability to interact with "handles":#glossary.handle. 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 that module would be handles to that module's 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 @Vpi::Handle.get_value@ and @Vpi::Handle.put_value@ methods.
+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 use VPI.
 
 
-<% figure "Parts of speech for accessing a handle's VPI properties" do %>
-|_. Operation |_. _ |_. Property |_. _ |_. Accessor |_. Addendum |
-|\2. optional       | required   |\3. optional                   |
-
-* *Operation* suggests a method that should be invoked in the context of the Property parameter. All "methods in the Enumerable module":http://www.ruby-doc.org/core/classes/Enumerable.html are available as operations.
-
-* *Property* suggests a VPI property that should be accessed. The "vpi" prefix, which is common to all VPI properties, can be omitted if you wish. For example, the VPI property "vpiFullName" is considered equivalent to "fullName" and "FullName", but not equivalent "full_name".
+h2(#background.relay). Ruby/Verilog interaction
 
-* *Accessor* suggests a VPI function that should be used in order 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":../ref/ruby/classes/Vpi/Handle/Property.html of the @Property.resolve@ method for details).
+In a typical VPI application written in C, the _Verilog simulator_ is in charge. Verilog code temporarily transfers control to C by invoking C functions, which return control to Verilog when they finish.
 
-* *Addendum* suggests that the specified VPI property should be queried as a boolean value when it is a question mark (?). This suggestion is the same as specifying "b" for the Accessor parameter. Also, when this parameter is an equal sign (=), it suggests that the specified VPI property should be written to.
-<% end %>
+In contrast, Ruby-VPI puts the _specification_ in charge. The specification temporarily transfers control to the Verilog simulator by invoking the @Vpi::advance_time@ method, which returns control to the specification when it finishes. This process is illustrated in <xref#fig..ruby_relay>.
 
-<% table "Possible accessors and their implications" do %>
-|_. 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@ |
-<% end %>
+Ruby-VPI's approach is the same as any software testing framework, where the _specification_ drives the design under test. Whereas, the typical VPI & C approach is literally _backwards_ because the design under test drives the specification.
 
-<% example "Examples of accessing a handle's VPI properties" do %>
-|_/2. Ruby expression |_\6. Parts of speech |_/2. Description |
-||_. Operation |_. _ |_. Property |_. _ |_. Accessor |_. Addendum ||
-| @handle.vpiIntVal@ | &nbsp; | &nbsp; | vpiIntVal | &nbsp; |  &nbsp; | &nbsp; |/4. These expressions access the logic value of the handle's vpiIntVal property. |
-| @handle.vpiIntVal_l@ | &nbsp; | &nbsp; | vpiIntVal | _ | l | &nbsp; |
-| @handle.intVal@ | &nbsp; | &nbsp; | intVal | &nbsp; | &nbsp; | &nbsp; |
-| @handle.intVal_l@ | &nbsp; | &nbsp; | intVal | _ | l | &nbsp; |
-| @handle.vpiIntVal = 15@ | &nbsp; | &nbsp; | vpiIntVal | &nbsp; | &nbsp; | = |/4. These expressions assign the number 15 to the logic value of the handle's vpiIntVal property. |
-| @handle.vpiIntVal_l = 15@ | &nbsp; | &nbsp; | vpiIntVal | _ | l | = |
-| @handle.intVal = 15@ | &nbsp; | &nbsp; | intVal | &nbsp; | &nbsp; | = |
-| @handle.intVal_l = 15@ | &nbsp; | &nbsp; | intVal | _ | l | = |
-| @handle.vpiType@ | &nbsp; | &nbsp; | vpiType | &nbsp; | &nbsp; | &nbsp; |/4. These expressions access the integer value of the handle's vpiType property. |
-| @handle.vpiType_i@ | &nbsp; | &nbsp; | vpiType | _ | i | &nbsp; |
-| @handle.type@ | &nbsp; | &nbsp; | type | &nbsp; | &nbsp; | &nbsp; |
-| @handle.type_i@ | &nbsp; | &nbsp; | type | _ | i | &nbsp; |
-| @handle.vpiProtected@ | &nbsp; | &nbsp; | vpiProtected | &nbsp; | &nbsp; | &nbsp; |/6. These expressions access the boolean value of the handle's vpiProtected property. |
-| @handle.vpiProtected_b@ | &nbsp; | &nbsp; | vpiProtected | _ | b | &nbsp; |
-| @handle.vpiProtected?@ | &nbsp; | &nbsp; | vpiProtected | &nbsp; | &nbsp; | ? |
-| @handle.protected@ | &nbsp; | &nbsp; | protected | &nbsp; | &nbsp; | &nbsp; |
-| @handle.protected_b@ | &nbsp; | &nbsp; | protected | _ | b | &nbsp; |
-| @handle.protected?@ | &nbsp; | &nbsp; | protected | &nbsp; | &nbsp; | ? |
-| @handle.vpiFullName@ | &nbsp; | &nbsp; | vpiFullName | &nbsp; | &nbsp; | &nbsp; |/4. These expressions access the string value of the handle's vpiFullName property. |
-| @handle.vpiFullName_s@ | &nbsp; | &nbsp; | vpiFullName | _ | s | &nbsp; |
-| @handle.fullName@ | &nbsp; | &nbsp; | fullName | &nbsp; | &nbsp; | &nbsp; |
-| @handle.fullName_s@ | &nbsp; | &nbsp; | fullName | _ | s | &nbsp; |
-| @handle.vpiParent@ | &nbsp; | &nbsp; | vpiParent | &nbsp; | &nbsp; | &nbsp; |/4. These expressions access the handle value of the handle's vpiParent property. |
-| @handle.vpiParent_h@ | &nbsp; | &nbsp; | vpiParent | _ | h | &nbsp; |
-| @handle.parent@ | &nbsp; | &nbsp; | parent | &nbsp; | &nbsp; | &nbsp; |
-| @handle.parent_h@ | &nbsp; | &nbsp; | parent | _ | h | &nbsp; |
-| <code>handle.each_vpiNet {|net| puts net.fullName}</code> | each | _ | vpiNet | &nbsp; | &nbsp; | &nbsp; |/2. These expressions print the full name of each vpiNet object associated with the handle. |
-| <code>handle.each_net {|net| puts net.fullName}</code> | each | _ | net | &nbsp; | &nbsp; | &nbsp; |
-| <code>handle.all_vpiReg? {|reg| reg.size == 1}</code> | all? | _ | vpiReg | &nbsp; | &nbsp; | &nbsp; |/2. These expressions check if all registers associated with the handle are capable of storing only one bit. |
-| <code>handle.all_reg? {|reg| reg.size == 1}</code> | all? | _ | reg | &nbsp; | &nbsp; | &nbsp; |
-| <code>handle.select_vpiNet {|net| net.x?}</code> | select | _ | VpiNet | &nbsp; | &nbsp; | &nbsp; |/2. These expressions return a list of nets whose logic value is unknown or "don't care" (x).|
-| <code>handle.select_net {|net| net.x?}</code> | select | _ | net | &nbsp; | &nbsp; | &nbsp; |
-<% end %>
-
-
-h2(#background.running-tests). Running a test
-
-Unlike an engineer who can verify an electronic component in real-time, the Verilog simulator and the Ruby interpreter (see <xref #fig..organization.detail>) take turns working with "handles":#glossary.handle when a "test":#glossary.test is run. In particular, they take turns manipulating the Verilog "design":#glossary.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.
-
-
-h3(#background.running-tests.init). Initialization
-
-A "test":#glossary.test is first initialized before it is "executed":#background.running-tests.exec. This process is illustrated by <xref #fig..ruby_init>.
-
-<% figure "Initialization of a test", "#fig..ruby_init" do %>
-!figures/ruby_init.png!
-
-# 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 running <pre>ruby -w</pre> at a command-prompt.
-# The Verilog simulator is paused and the Ruby interpreter is initialized with the arguments of the @$ruby_init;@ system task/function.
-# When the Ruby interpreter invokes the @Vpi::relay_verilog@ method, it is paused and the Verilog simulator is given control.
-<% end %>
-
-
-h3(#background.running-tests.exec). Execution
-
-After a "test":#glossary.test is "initialized":#background.running-tests.init, it is executed such that the design is verified against the "specification":#glossary.specification. This process is illustrated by <xref #fig..ruby_relay>.
-
-<% figure "Execution of a test", "#fig..ruby_relay" do %>
+<% figure "Interaction between Ruby and Verilog", "#fig..ruby_relay" do %>
 !figures/ruby_relay.png!
 
-# The Verilog simulator transfers control to the Ruby interpreter by invoking the @$ruby_relay;@ system task/function.
-# The Verilog simulator is paused and the Ruby interpreter is given control.
-# When the Ruby interpreter invokes the @Vpi::relay_verilog@ method, it is paused and the Verilog simulator is given control.
+# The current simulation time is _X_.
+# The specification invokes the @Vpi::advance_time@ method with parameter _Y_, which specifies the number of simulation time steps to be simulated.
+# The Verilog simulator is now in control (temporarily).
+# The current simulation time has _not_ changed; it is still _X_.
+# The Verilog simulator simulates _Y_ simulation time steps.
+# The current simulation time is now _X + Y_.
+# The Verilog simulator returns control back to the specification.
 <% end %>
 
 
@@ -242,7 +143,6 @@ The following software is necessary in order to use Ruby-VPI.
 Write a "support request":http://rubyforge.org/tracker/?group_id=1339 for your simulator, while providing a sample transcript of the commands you use to run a test with your simulator, and we will add support for your simulator in the next release!
 <% end %>
 
-
 * *make*
   - any distribution should be acceptable.
 
@@ -320,6 +220,329 @@ Learn more about using and manipulating RubyGems in "the RubyGems user manual":h
 
 h1(#usage). Usage
 
+
+h2(#usage.vpi). VPI in Ruby
+
+The _entire_ IEEE Std 1364-2005 VPI interface is available in Ruby, but with one minor difference: the names of all VPI types, structures, and constants become _capitalized_ because Ruby requires that the names of constants begin with a capital letter.
+
+For example, the @s_vpi_value@ structure becomes the @S_vpi_value@ class in Ruby. Likewise, the @vpiIntVal@ constant becomes the @VpiIntVal@ constant in Ruby.
+
+Note that this capitalization rule does *not* apply to VPI functions; their names remain _unchanged_ in Ruby.
+
+
+h3(#usage.vpi.handles). Handles
+
+A _handle_ is a reference to an object, such as a module, register, wire, and so on, inside the Verilog simulation. In short, handles allow you to inspect and manipulate the design under test and its components.
+
+<% note do %>
+Handles are instances of the @Vpi::Handle@ class (see "reference documentation":../ref/ruby/classes/Vpi/Handle.html for details) in Ruby-VPI.
+<% end %>
+
+Handles have various _properties_, which provide different kinds of information (see the "Kind of value accessed" column in <xref #tbl..accessors>) about the underlying Verilog object represented by a handle. These properties are accessed through various functions, which are listed in the "VPI functions used to access the value" column in <xref #tbl..accessors>.
+
+Handles are typically obtained through the @vpi_handle_by_name@ and @vpi_handle@ functions. These functions are hierarchical in nature, because they allow you to obtain new handles that are related to existing handles. For example, to obtain a handle to a register inside a module, you would typically write: @some_reg = vpi_handle(VpiReg, some_handle)@.
+
+
+p(title). Shortcuts for productivity
+
+Given a handle, Ruby-VPI allows you to access (1) its relatives and (2) its properties by simply invoking its methods.
+
+If a handle's relative happens to have the same name as one of the handle's properties, then the relative is given preference. However, if  you _really_ need to access a handle's property in such a situation, then you can use the @Vpi::Handle.get_value@ and @Vpi::Handle.put_value@ methods.
+
+
+h4. Accessing a handle's relatives
+
+To access a handle's relative (a handle related to it), simply invoke the relative's name as a method on the handle.
+
+For example, to access the @reset@ signal of the @counter@ module shown in <xref #fig..counter.v_decl>, you would write the following:
+
+<code>
+counter_module = vpi_handle_by_name("counter", nil)
+
+reset_signal = counter_module.reset # <== shortcut!
+</code>
+
+In this code, the shortcut is that you simply wrote @counter_module.reset@ instead of having to write @vpi_handle_by_name("reset", counter_module)@.
+
+
+h4. Accessing a handle's properties
+
+To access a handle's properties, invoke the proprty name, using the following format, as a method on the handle. <xref ex..properties> shows how this naming format is used.
+
+<% figure "Method naming format for accessing a handle's properties" do %>
+|_. Operation |_. _ |_. Property |_. _ |_. Accessor |_. Addendum |
+|\2. optional       | required   |\3. optional                   |
+
+* *Operation* suggests a method that should be invoked in the context of the Property parameter. All "methods in the Enumerable module":http://www.ruby-doc.org/core/classes/Enumerable.html are valid _operations_.
+
+* *Property* suggests a VPI property that should be accessed. The "vpi" prefix, which is common to all VPI properties, can be omitted if you wish. For example, the VPI property "vpiFullName" is considered equivalent to "fullName" and "FullName", but not equivalent "full_name".
+
+* *Accessor* suggests a VPI function that should be used in order to access the VPI property. When this parameter is not specified, Ruby-VPI will attempt to _guess_ the value of this parameter.
+
+  <xref #tbl..accessors> shows a list of valid accessors and how they affect the access to a property.
+
+* *Addendum* suggests that the specified VPI property should be queried as a boolean value when it is a question mark @?@. This suggestion is the same as specifying @b@ for the Accessor parameter.
+
+  Also, when this parameter is an equal sign @=@, it suggests that the specified VPI property should be written to.
+<% end %>
+
+<% table "Possible accessors and their implications", "tbl..accessors" do %>
+|_. 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@ |
+<% end %>
+
+<% example "Examples of accessing a handle's properties", "ex..properties" do %>
+|_/2. Ruby expression |_\6. Parts of speech |_/2. Description |
+||_. Operation |_. _ |_. Property |_. _ |_. Accessor |_. Addendum ||
+| @handle.vpiIntVal@ | &nbsp; | &nbsp; | vpiIntVal | &nbsp; |  &nbsp; | &nbsp; |/4. These expressions access the logic value of the handle's vpiIntVal property. |
+| @handle.vpiIntVal_l@ | &nbsp; | &nbsp; | vpiIntVal | _ | l | &nbsp; |
+| @handle.intVal@ | &nbsp; | &nbsp; | intVal | &nbsp; | &nbsp; | &nbsp; |
+| @handle.intVal_l@ | &nbsp; | &nbsp; | intVal | _ | l | &nbsp; |
+| @handle.vpiIntVal = 15@ | &nbsp; | &nbsp; | vpiIntVal | &nbsp; | &nbsp; | = |/4. These expressions assign the number 15 to the logic value of the handle's vpiIntVal property. |
+| @handle.vpiIntVal_l = 15@ | &nbsp; | &nbsp; | vpiIntVal | _ | l | = |
+| @handle.intVal = 15@ | &nbsp; | &nbsp; | intVal | &nbsp; | &nbsp; | = |
+| @handle.intVal_l = 15@ | &nbsp; | &nbsp; | intVal | _ | l | = |
+| @handle.vpiType@ | &nbsp; | &nbsp; | vpiType | &nbsp; | &nbsp; | &nbsp; |/4. These expressions access the integer value of the handle's vpiType property. |
+| @handle.vpiType_i@ | &nbsp; | &nbsp; | vpiType | _ | i | &nbsp; |
+| @handle.type@ | &nbsp; | &nbsp; | type | &nbsp; | &nbsp; | &nbsp; |
+| @handle.type_i@ | &nbsp; | &nbsp; | type | _ | i | &nbsp; |
+| @handle.vpiProtected@ | &nbsp; | &nbsp; | vpiProtected | &nbsp; | &nbsp; | &nbsp; |/6. These expressions access the boolean value of the handle's vpiProtected property. |
+| @handle.vpiProtected_b@ | &nbsp; | &nbsp; | vpiProtected | _ | b | &nbsp; |
+| @handle.vpiProtected?@ | &nbsp; | &nbsp; | vpiProtected | &nbsp; | &nbsp; | ? |
+| @handle.protected@ | &nbsp; | &nbsp; | protected | &nbsp; | &nbsp; | &nbsp; |
+| @handle.protected_b@ | &nbsp; | &nbsp; | protected | _ | b | &nbsp; |
+| @handle.protected?@ | &nbsp; | &nbsp; | protected | &nbsp; | &nbsp; | ? |
+| @handle.vpiFullName@ | &nbsp; | &nbsp; | vpiFullName | &nbsp; | &nbsp; | &nbsp; |/4. These expressions access the string value of the handle's vpiFullName property. |
+| @handle.vpiFullName_s@ | &nbsp; | &nbsp; | vpiFullName | _ | s | &nbsp; |
+| @handle.fullName@ | &nbsp; | &nbsp; | fullName | &nbsp; | &nbsp; | &nbsp; |
+| @handle.fullName_s@ | &nbsp; | &nbsp; | fullName | _ | s | &nbsp; |
+| @handle.vpiParent@ | &nbsp; | &nbsp; | vpiParent | &nbsp; | &nbsp; | &nbsp; |/4. These expressions access the handle value of the handle's vpiParent property. |
+| @handle.vpiParent_h@ | &nbsp; | &nbsp; | vpiParent | _ | h | &nbsp; |
+| @handle.parent@ | &nbsp; | &nbsp; | parent | &nbsp; | &nbsp; | &nbsp; |
+| @handle.parent_h@ | &nbsp; | &nbsp; | parent | _ | h | &nbsp; |
+| <code>handle.each_vpiNet {|net| puts net.fullName}</code> | each | _ | vpiNet | &nbsp; | &nbsp; | &nbsp; |/2. These expressions print the full name of each vpiNet object associated with the handle. |
+| <code>handle.each_net {|net| puts net.fullName}</code> | each | _ | net | &nbsp; | &nbsp; | &nbsp; |
+| <code>handle.all_vpiReg? {|reg| reg.size == 1}</code> | all? | _ | vpiReg | &nbsp; | &nbsp; | &nbsp; |/2. These expressions check if all registers associated with the handle are capable of storing only one bit. |
+| <code>handle.all_reg? {|reg| reg.size == 1}</code> | all? | _ | reg | &nbsp; | &nbsp; | &nbsp; |
+| <code>handle.select_vpiNet {|net| net.x?}</code> | select | _ | VpiNet | &nbsp; | &nbsp; | &nbsp; |/2. These expressions return a list of nets whose logic value is unknown or "don't care" (x).|
+| <code>handle.select_net {|net| net.x?}</code> | select | _ | net | &nbsp; | &nbsp; | &nbsp; |
+<% end %>
+
+
+h3(#usage.vpi.callbacks). Callbacks
+
+A _callback_ is a mechanism that makes the Verilog simuluator execute a block of code, which is known as a "callback handler", when some prescribed event occurs in the simulation. They are set up using the @vpi_register_cb@ function and torn down using the @vpi_remove_cb@ function.
+
+<% example "Using a callback for value change notification", "ex..callback" do %>
+This example shows how to use a callback for notification of changes in a handle's @VpiIntVal@ property. When you no longer need this callback, you can tear it down using @vpi_remove_cb(cb_handle)@.
+
+In this example, the handle being monitored is the @Counter.count@ signal from <xref#fig..counter.v_decl>.
+
+<code>
+cb_time           = S_vpi_time.new
+cb_time.type      = VpiSimTime
+cb_time.low       = 0
+cb_time.high      = 0
+
+cb_value          = S_vpi_value.new
+cb_value.format   = VpiIntVal
+
+cb_data           = S_cb_data.new
+cb_data.reason    = CbValueChange
+cb_data.obj       = Counter.count
+cb_data.time      = cb_time
+cb_data.value     = cb_value
+cb_data.index     = 0
+
+cb_handle = vpi_register_cb(cb_data) do |data|
+
+  time = (data.time.high << 32) | data.time.low
+  count = data.value.value.integer
+
+  puts "hello from callback! time=#{time} count=#{count}"
+
+end
+</code>
+
+To see this code in action, append it to the <tt>counter_rspec_spec.rb</tt> and <tt>counter_xunit_spec.rb</tt> files, which are provided in <xref#usage.examples> and discussed in <xref#usage.tutorial.specification>.
+<% end %>
+
+<% figure "Output from <xref#ex..callback>" do %>
+Shown below is the output from running the "counter_rspec test":#usage.tutorial after appending the code shown in <xref#ex..callback> to the <tt>counter_rspec_spec.rb</tt> file.
+
+<pre>
+$ rake -f counter_rspec_runner.rake cver
+
+(in /home/sun/src/ruby-vpi/samp/counter)
+cver +loadvpi=/home/sun/src/ruby-vpi/lib/ruby-vpi/../../obj/ruby-vpi.cver.so:vlog_startup_routines_bootstrap counter.v counter_rspec_bench.v
+GPLCVER_2.11a of 07/05/05 (Linux-elf).
+Copyright (c) 1991-2005 Pragmatic C Software Corp.
+  All Rights reserved.  Licensed under the GNU General Public License (GPL).
+  See the 'COPYING' file for details.  NO WARRANTY provided.
+Today is Sat Dec 30 09:24:09 2006.
+Compiling source file "counter.v"
+Compiling source file "counter_rspec_bench.v"
+Highest level modules:
+counter_rspec_bench
+
+
+A resetted counter's value
+hello from callback! time=1 count=0
+- should be zero
+hello from callback! time=5 count=1
+hello from callback! time=7 count=2
+hello from callback! time=9 count=3
+hello from callback! time=11 count=4
+hello from callback! time=13 count=5
+hello from callback! time=15 count=6
+hello from callback! time=17 count=7
+hello from callback! time=19 count=8
+hello from callback! time=21 count=9
+hello from callback! time=23 count=10
+hello from callback! time=25 count=11
+hello from callback! time=27 count=12
+hello from callback! time=29 count=13
+hello from callback! time=31 count=14
+hello from callback! time=33 count=15
+hello from callback! time=35 count=16
+hello from callback! time=37 count=17
+hello from callback! time=39 count=18
+hello from callback! time=41 count=19
+hello from callback! time=43 count=20
+hello from callback! time=45 count=21
+hello from callback! time=47 count=22
+hello from callback! time=49 count=23
+hello from callback! time=51 count=24
+hello from callback! time=53 count=25
+hello from callback! time=55 count=26
+hello from callback! time=57 count=27
+hello from callback! time=59 count=28
+hello from callback! time=61 count=29
+hello from callback! time=63 count=30
+hello from callback! time=65 count=31
+hello from callback! time=67 count=0
+- should increment by one count upon each rising clock edge
+
+A counter with the maximum value
+hello from callback! time=71 count=1
+hello from callback! time=73 count=2
+hello from callback! time=75 count=3
+hello from callback! time=77 count=4
+hello from callback! time=79 count=5
+hello from callback! time=81 count=6
+hello from callback! time=83 count=7
+hello from callback! time=85 count=8
+hello from callback! time=87 count=9
+hello from callback! time=89 count=10
+hello from callback! time=91 count=11
+hello from callback! time=93 count=12
+hello from callback! time=95 count=13
+hello from callback! time=97 count=14
+hello from callback! time=99 count=15
+hello from callback! time=101 count=16
+hello from callback! time=103 count=17
+hello from callback! time=105 count=18
+hello from callback! time=107 count=19
+hello from callback! time=109 count=20
+hello from callback! time=111 count=21
+hello from callback! time=113 count=22
+hello from callback! time=115 count=23
+hello from callback! time=117 count=24
+hello from callback! time=119 count=25
+hello from callback! time=121 count=26
+hello from callback! time=123 count=27
+hello from callback! time=125 count=28
+hello from callback! time=127 count=29
+hello from callback! time=129 count=30
+hello from callback! time=131 count=31
+hello from callback! time=133 count=0
+- should overflow upon increment
+
+Finished in 0.042328 seconds
+
+3 specifications, 0 failures
+</pre>
+<% end %>
+
+
+h2(#usage.debugger). Debugging
+
+The "ruby-debug project":http://www.datanoise.com/articles/category/ruby-debug serves as the interactive debugger for Ruby-VPI.
+
+# Enable the debugger by activating the @DEBUG@ environment variable (see <xref #usage.test-runner> for details).
+# Put the @debugger@ command in your code -- anywhere you wish to activate an interactive debugging session. These commands are automatically ignored when the debugger is disabled; so you can safely leave them in your code, if you wish.
+
+
+h3(#usage.debugger.init). Advanced initialization
+
+By default, Ruby-VPI enables the debugger by invoking the @Debugger.start@ method. If you wish to perform more advanced initialization, such as having the debugger accept remote network connections for interfacing with a remote debugging session or perhaps with an IDE (see "the ruby-debug documentation":http://www.datanoise.com/articles/category/ruby-debug for details), then:
+
+# Deactivate the @DEBUG@ environment variable.
+# Put your own code, which initializes the debugger, above the @RubyVpi.init_bench@ line in your generated <tt>spec.rb</tt> file.
+
+
+h2(#usage.test-runner). Test runner
+
+A test runner is a file, generated by the "automated test generator":#usage.tools.generate-test, whose name ends with <tt>.rake</tt>. It helps you run generated tests -- you can think of it as a _makefile_ if you are familiar with C programming in a UNIX environment.
+
+<% example "Seeing what a test runner can do" do %>
+When you invoke a test runner without any arguments, it will show you a list of available tasks:
+<pre>$ rake -f some_test_runner.rake
+
+<%= `rake -f ../samp/counter/counter_rspec_runner.rake` %></pre>
+<% end %>
+
+<% tip "Running multiple tests at once." do %>
+Create a file named <tt>Rakefile</tt> containing the following line.
+
+bq. @require 'ruby-vpi/runner_proxy'@
+
+Now you can invoke all test runners in the current directory simply by executing <pre>rake cver</pre> (where _cver_ denotes the "GPL Cver simulator":#setup.reqs).
+<% end %>
+
+
+h3(#usage.test-runner.env-vars). Environment variables
+
+Test runners support the following _environment_ variables, which allow you to easily change the behavior of the test runner.
+
+* @COVERAGE@ enables code coverage analysis and generation of code coverage reports.
+* @DEBUG@ enables the "interactive debugger":#usage.debugger in its "post-mortem debugging mode":http://www.datanoise.com/articles/2006/12/20/post-mortem-debugging.
+* @PROTOTYPE@ enables the Ruby prototype for the design under test.
+
+To activate these variables, simply assign a non-empty value to them. For example, @DEBUG=1@ and @DEBUG=yes@ and @DEBUG=foo_bar_baz@ all activate the @DEBUG@ variable.
+
+To deactivate these variables, simply assign an _empty_ value to them, *unset* them in your shell, or do not specify them as command-line arguments to rake. For example, both @DEBUG=@ dectivates the @DEBUG@ variable.
+
+In addition, you can specify variable assignments as arguments to the *rake* command. For example, <pre>rake DEBUG=1</pre> is equivalent to <pre>
+$ DEBUG=1
+$ export DEBUG
+$ rake
+</pre> in Bourne shell or <pre>
+% setenv DEBUG 1
+% rake
+</pre> in C shell.
+
+<% example "Running a test with environment variables" do %>
+
+Here we enable the prototype and code coverage analysis:
+<pre>rake -f some_test_runner.rake PROTOTYPE=1 COVERAGE=1</pre>
+
+Here we _disable_ the prototype and enable the code coverage analysis. Note that both of these invocations are equivalent:
+<pre>rake -f some_test_runner.rake PROTOTYPE= COVERAGE=1</pre>
+<pre>rake -f some_test_runner.rake COVERAGE=1</pre>
+<% end %>
+
+
+h2(#usage.examples). Sample tests
+
+The <tt>samp</tt> directory contains several sample tests which illustrate how Ruby-VPI can be used. Each sample has an associated <tt>Rakefile</tt> which simplifies the process of running it. Therefore, simply navigate into an example directory and run the <pre>rake</pre> command to get started.
+
+
 h2(#usage.tools). Tools
 
 The <tt>bin</tt> directory contains various utilities which ease the process of writing tests. Each tool provides help and usage information invoked with the <tt>--help</tt> option.
@@ -586,80 +809,6 @@ Finished in 0.006766 seconds.
 In these examples, 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 simulator":#setup.reqs, denoted by _cver_, is used to run the simulation.
 
 
-h2(#usage.test-runner). Test runner
-
-A test runner is a file, generated by the "automated test generator":#usage.tools.generate-test, whose name ends with <tt>.rake</tt>. It helps you run generated tests -- you can think of it as a _makefile_ if you are familiar with C programming in a UNIX environment.
-
-<% example "Seeing what a test runner can do" do %>
-When you invoke a test runner without any arguments, it will show you a list of available tasks:
-<pre>$ rake -f some_test_runner.rake
-
-<%= `rake -f ../samp/counter/counter_rspec_runner.rake` %></pre>
-<% end %>
-
-<% tip "Running multiple tests at once." do %>
-Create a file named <tt>Rakefile</tt> containing the following line.
-
-bq. @require 'ruby-vpi/runner_proxy'@
-
-Now you can invoke all test runners in the current directory simply by executing <pre>rake cver</pre> (where _cver_ denotes the "GPL Cver simulator":#setup.reqs).
-<% end %>
-
-
-h3(#usage.test-runner.env-vars). Environment variables
-
-Test runners support the following _environment_ variables, which allow you to easily change the behavior of the test runner.
-
-* @COVERAGE@ enables code coverage analysis and generation of code coverage reports.
-* @DEBUG@ enables the "interactive debugger":#usage.debugger in its "post-mortem debugging mode":http://www.datanoise.com/articles/2006/12/20/post-mortem-debugging.
-* @PROTOTYPE@ enables the Ruby prototype for the design under test.
-
-To activate these variables, simply assign a non-empty value to them. For example, @DEBUG=1@ and @DEBUG=yes@ and @DEBUG=foo_bar_baz@ all activate the @DEBUG@ variable.
-
-To deactivate these variables, simply assign an _empty_ value to them, *unset* them in your shell, or do not specify them as command-line arguments to rake. For example, both @DEBUG=@ dectivates the @DEBUG@ variable.
-
-In addition, you can specify variable assignments as arguments to the *rake* command. For example, <pre>rake DEBUG=1</pre> is equivalent to <pre>
-$ DEBUG=1
-$ export DEBUG
-$ rake
-</pre> in Bourne shell or <pre>
-% setenv DEBUG 1
-% rake
-</pre> in C shell.
-
-<% example "Running a test with environment variables" do %>
-
-Here we enable the prototype and code coverage analysis:
-<pre>rake -f some_test_runner.rake PROTOTYPE=1 COVERAGE=1</pre>
-
-Here we _disable_ the prototype and enable the code coverage analysis. Note that both of these invocations are equivalent:
-<pre>rake -f some_test_runner.rake PROTOTYPE= COVERAGE=1</pre>
-<pre>rake -f some_test_runner.rake COVERAGE=1</pre>
-<% end %>
-
-
-h2(#usage.debugger). Interactive debugger
-
-The "ruby-debug project":http://www.datanoise.com/articles/category/ruby-debug serves as the interactive debugger for Ruby-VPI.
-
-# Enable the debugger by activating the @DEBUG@ environment variable (see <xref #usage.test-runner> for details).
-# Put the @debugger@ command in your code -- anywhere you wish to activate an interactive debugging session. These commands are automatically ignored when the debugger is disabled; so you can safely leave them in your code, if you wish.
-
-
-h3(#usage.debugger.init). Advanced initialization
-
-By default, Ruby-VPI enables the debugger by invoking the @Debugger.start@ method. If you wish to perform more advanced initialization, such as having the debugger accept remote network connections for interfacing with a remote debugging session or perhaps with an IDE (see "the ruby-debug documentation":http://www.datanoise.com/articles/category/ruby-debug for details), then:
-
-# Deactivate the @DEBUG@ environment variable.
-# Put your own code, which initializes the debugger, above the @RubyVpi.init_bench@ line in your generated <tt>spec.rb</tt> file.
-
-
-
-h2(#usage.examples). Sample tests
-
-The <tt>samp</tt> directory contains several sample tests which illustrate how Ruby-VPI can be used. Each sample has an associated <tt>Rakefile</tt> which simplifies the process of running it. Therefore, simply navigate into an example directory and run the <pre>rake</pre> command to get started.
-
-
 h1(#hacking). Hacking
 
 h2(#hacking.release-packages). Building release packages