doc/manual.doc in ruby-vpi-15.0.0 vs doc/manual.doc in ruby-vpi-15.0.1
- old
+ new
@@ -9,20 +9,20 @@
_Happy reading!_
h2(#terms). Terms
-Copyright (c) 2006 Suraj N. Kurapati.
+Copyright (c) 2006, 2007 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.
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
-<%= File.read 'intro.inc' %>
+<%= import 'intro.inc' %>
h2(#intro.license). License
Ruby-VPI is "free software":http://en.wikipedia.org/wiki/Free_software ; you can redistribute it and/or modify it under the terms of the "GNU General Public License":http://www.gnu.org/copyleft/gpl.html as published by the "Free Software Foundation":http://www.fsf.org ; either version 2 of the License, or (at your option) any later version.
@@ -54,11 +54,11 @@
Ruby-VPI presents an open-ended interface to VPI. Thus, you can use any methodology you wish when writing tests. However, being an agile language, Ruby makes it _very_ easy to use agile development practies such as "TDD":#glossary.TDD and "BDD":#glossary.BDD.
h2(#background.vocab). Terminology
-<% note do %>
+<% note "Glossary has definitions" do %>
Have a look at the "glossary":#glossary for definitions of terms used in this manual.
<% end %>
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?", for example. I poured through my textbook for a definition of the term, but it was to no avail. Instead, it nonchalantly employed the term _throughout_ its being, as if mocking my ignorance of what seems to be universal knowledge.
@@ -211,32 +211,49 @@
h2(#setup.maintenance). Maintenance
* You can uninstall Ruby-VPI by running the <pre>gem uninstall ruby-vpi</pre> command.
* You can upgrade to the latest release of Ruby-VPI by running the <pre>gem update ruby-vpi</pre> command.
-<% note do %>
Learn more about using and manipulating RubyGems in "the RubyGems user manual":http://www.rubygems.org.
-<% end %>
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.
+The _entire_ IEEE Std 1364-2005 VPI interface is available in Ruby, but with a few minor differences.
+p(title). Capitalize those names!
+
+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.
+<% note "No capitalization for VPI functions" do %>
+Ruby's capitalization rule does _not_ apply to VPI functions--their names remain unchanged in Ruby.
+<% end %>
+p(title). Use Ruby's @printf@
+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 third line of source code shown below causes a "type mismatch" error.
+
+<code lang="c">
+#include <stdarg.h>
+void foo(va_list ap) {
+ va_list *p = ≈
+}
+</code>
+
+
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 %>
+<% note "@Vpi::Handle@ heritage" 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>.
@@ -295,35 +312,35 @@
| 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 |
+|_/2. Ruby expression |_\6. Method naming format |_/2. Description |
||_. Operation |_. _ |_. Property |_. _ |_. Accessor |_. Addendum ||
-| @handle.vpiIntVal@ | | | vpiIntVal | | | |/4. These expressions access the logic value of the handle's vpiIntVal property. |
+| @handle.vpiIntVal@ | | | vpiIntVal | | | |/4. These expressions access the *logic value* of the handle's @VpiIntVal@ property. |
| @handle.vpiIntVal_l@ | | | vpiIntVal | _ | l | |
| @handle.intVal@ | | | intVal | | | |
| @handle.intVal_l@ | | | intVal | _ | l | |
-| @handle.vpiIntVal = 15@ | | | vpiIntVal | | | = |/4. These expressions assign the number 15 to the logic value of the handle's vpiIntVal property. |
+| @handle.vpiIntVal = 15@ | | | vpiIntVal | | | = |/4. These expressions assign the number 15 to the *logic value* of the handle's @VpiIntVal@ property. |
| @handle.vpiIntVal_l = 15@ | | | vpiIntVal | _ | l | = |
| @handle.intVal = 15@ | | | intVal | | | = |
| @handle.intVal_l = 15@ | | | intVal | _ | l | = |
-| @handle.vpiType@ | | | vpiType | | | |/4. These expressions access the integer value of the handle's vpiType property. |
+| @handle.vpiType@ | | | vpiType | | | |/4. These expressions access the *integer value* of the handle's @VpiType@ property. |
| @handle.vpiType_i@ | | | vpiType | _ | i | |
| @handle.type@ | | | type | | | |
| @handle.type_i@ | | | type | _ | i | |
-| @handle.vpiProtected@ | | | vpiProtected | | | |/6. These expressions access the boolean value of the handle's vpiProtected property. |
+| @handle.vpiProtected@ | | | vpiProtected | | | |/6. These expressions access the *boolean value* of the handle's @VpiProtected@ property. |
| @handle.vpiProtected_b@ | | | vpiProtected | _ | b | |
| @handle.vpiProtected?@ | | | vpiProtected | | | ? |
| @handle.protected@ | | | protected | | | |
| @handle.protected_b@ | | | protected | _ | b | |
| @handle.protected?@ | | | protected | | | ? |
-| @handle.vpiFullName@ | | | vpiFullName | | | |/4. These expressions access the string value of the handle's vpiFullName property. |
+| @handle.vpiFullName@ | | | vpiFullName | | | |/4. These expressions access the *string value* of the handle's @VpiFullName@ property. |
| @handle.vpiFullName_s@ | | | vpiFullName | _ | s | |
| @handle.fullName@ | | | fullName | | | |
| @handle.fullName_s@ | | | fullName | _ | s | |
-| @handle.vpiParent@ | | | vpiParent | | | |/4. These expressions access the handle value of the handle's vpiParent property. |
+| @handle.vpiParent@ | | | vpiParent | | | |/4. These expressions access the *handle value* of the handle's @VpiParent@ property. |
| @handle.vpiParent_h@ | | | vpiParent | _ | h | |
| @handle.parent@ | | | parent | | | |
| @handle.parent_h@ | | | parent | _ | h | |
| <code>handle.each_vpiNet {|net| puts net.fullName}</code> | each | _ | vpiNet | | | |/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 | | | |
@@ -367,16 +384,12 @@
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 %>
+Shown below is the result of appending this code to the <tt>counter_rspec_spec.rb</tt> file (provided in <xref#usage.examples> and discussed in <xref#usage.tutorial.specification>) and running the "counter_rspec test":#usage.tutorial.
-<% 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
@@ -472,11 +485,11 @@
h2(#usage.prototyping). Prototyping
Ruby-VPI enables you to rapidly prototype your designs in Ruby without having to do full-scale implementations in Verilog. This lets you explore and evaluate different design choices quickly.
-In order to create a prototype,
+To create a prototype,
# "Determine the *interface*":#usage.tutorial.declare-design (Verilog module declaration) of your design.
# "Generate a test":#usage.tutorial.generate-test for that interface.
# "Implement the prototype":#usage.tutorial.implement-proto in the generated <tt>proto.rb</tt> file.
# "Verify the prototype":#usage.tutorial.test-proto against its specification.
@@ -601,11 +614,11 @@
By converting Verilog header files into Ruby, your "test":#glossary.test can utilize the same @`define@ constants that are used in the Verilog "design":#glossary.design.
h2(#usage.tutorial). Tutorial
-# "Declare the design":#usage.tutorial.declare-design, which is a Verilog module, using Verilog 2001 syntax.
+# "Declare a design":#usage.tutorial.declare-design using Verilog 2001 syntax.
# "Generate a test":#usage.tutorial.generate-test for the design using the "automated test generator":#usage.tools.generate-test tool.
# "Identify your expectations":#usage.tutorial.specification for the design and implement them in the specification.
# (Optional) "Implement the prototype":#usage.tutorial.implement-proto of the design in Ruby.
# (Optional) "Verify the prototype":#usage.tutorial.test-proto against the specification.
# "Implement the design":#usage.tutorial.implement-design in Verilog once the prototype has been verified.
@@ -907,13 +920,9 @@
Here the @clk_reg@ register is connected to the @clk_wire@ wire.
<% end %>
h3(#problems.ivl.vpi_reset). Vpi::reset
-
-<% caution do %>
-The @vpi_control@ method was removed in release 3.0.0 (2006-04-23). Please use @Vpi::vpi_control(VpiReset)@ instead.
-<% end %>
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.
h2(#problems.vsim). Mentor Modelsim