manual.doc in ruby-vpi-15.0.0

- old
+ new

@@ -225,11 +225,11 @@
 
 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.
+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.
@@ -265,11 +265,11 @@
 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.
+To access a handle's properties, invoke the property 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                   |
 
@@ -342,26 +342,26 @@
 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
+cbTime           = S_vpi_time.new
+cbTime.type      = VpiSimTime
+cbTime.low       = 0
+cbTime.high      = 0
 
-cb_value          = S_vpi_value.new
-cb_value.format   = VpiIntVal
+cbValue          = S_vpi_value.new
+cbValue.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
+cbData           = S_cb_data.new
+cbData.reason    = CbValueChange
+cbData.obj       = Counter.count
+cbData.time      = cbTime
+cbData.value     = cbValue
+cbData.index     = 0
 
-cb_handle = vpi_register_cb(cb_data) do |data|
+cbHandle = vpi_register_cb(cbData) do |data|
 
   time = (data.time.high << 32) | data.time.low
   count = data.value.value.integer
 
   puts "hello from callback! time=#{time} count=#{count}"
@@ -468,10 +468,25 @@
 3 specifications, 0 failures
 </pre>
 <% end %>
 
 
+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,
+# "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.
+
+Once you are satisfied with your prototype, you can proceed to "implement your design in Verilog":#usage.tutorial.implement-design. This process is often a simple translation your Ruby prototype into your Verilog. At the very least, your prototype serves as a reference while you are implementing your Verilog design.
+
+Once your design has been implemented in Verilog, you can use the _same_ specification, which was originally used to verify your prototype, to verify your Verilog design.
+
+
 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).
@@ -695,19 +710,11 @@
 h3(#usage.tutorial.implement-proto). Implement the prototype
 
 Now that we have a "specification":#glossary.specification against which to verify our "design":#glossary.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. The result of this proceess is illustrated by <xref #fig..counter_proto.rb>.
 
 <% example "Ruby prototype of our Verilog design", "#fig..counter_proto.rb" do %>
-<code>
-def Counter.simulate!
-  if reset.intVal == 1
-    count.intVal = 0
-  else
-    count.intVal += 1
-  end
-end
-</code>
+<code><%= File.read '../samp/counter/counter_rspec_proto.rb' %></code>
 <% end %>
 
 <% important "Before we continue..." do %>
 Replace the contents of the files named <tt>counter_rspec_proto.rb</tt> and <tt>counter_xunit_proto.rb</tt> with the source code shown in <xref #fig..counter_proto.rb>
 <% end %>
@@ -715,10 +722,12 @@
 
 h3(#usage.tutorial.test-proto). Verify the prototype
 
 Now that we have implemented our prototype, we are ready to verify it against our "specification":#glossary.specification by running the "test":#glossary.test. This process is illustrated by <xref #fig..test-proto.rspec> and <xref #fig..test-proto.unit-test>.
 
+In these examples, the @PROTOTYPE@ environment variable is assigned a non-empty value while running the test so that, instead of our design, our prototype is verified against our specification. You can also assign a value to @PROTOTYPE@ before running the test, by using your shell's *export* or *setenv* command. Finally, the "GPL Cver simulator":#setup.reqs, denoted by _cver_, is used to run the simulation.
+
 <% example "Running a test with specification in rSpec format", "#fig..test-proto.rspec" do %>
 <pre>
 $ rake -f counter_rspec_runner.rake cver PROTOTYPE=1
 
 Ruby-VPI: prototype has been enabled for test "counter_rspec"
@@ -749,12 +758,10 @@
 
 3 tests, 35 assertions, 0 failures, 0 errors
 </pre>
 <% end %>
 
-In these examples, the @PROTOTYPE@ environment variable is assigned a non-empty value while running the test so that, instead of our design, our prototype is verified against our specification. You can also assign a value to @PROTOTYPE@ before running the test, by using your shell's *export* or *setenv* command. Finally, the "GPL Cver simulator":#setup.reqs, denoted by _cver_, is used to run the simulation.
-
 <% tip "What can the test runner do?" do %>
 If you invoke the test runner (1) without any arguments or (2) with the <tt>--tasks</tt> option, it will show you a list of tasks that it can perform for you.
 <% end %>
 
 
@@ -774,10 +781,12 @@
 
 h3(#usage.tutorial.test-design). Verify the design
 
 Now that we have implemented our "design":#glossary.design, we are ready to verify it against our "specification":#glossary.specification by running the "test":#glossary.test. <xref #fig..test-design.rspec> and <xref #fig..test-design.unit-test> illustrate this process.
 
+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.
+
 <% example "Running a test with specification in rSpec format", "#fig..test-design.rspec" do %>
 <pre>
 $ rake -f counter_rspec_runner.rake cver
 
 A resetted counter's value
@@ -804,13 +813,11 @@
 
 3 tests, 35 assertions, 0 failures, 0 errors
 </pre>
 <% end %>
 
-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.
 
-
 h1(#hacking). Hacking
 
 h2(#hacking.release-packages). Building release packages
 
 In addition to the "normal requirements":#setup.reqs, you need the following software to build release packages:
@@ -901,10 +908,12 @@
 <% end %>
 
 
 h3(#problems.ivl.vpi_reset). Vpi::reset
 
-<div class="caution">The @vpi_control@ method was removed in release 3.0.0 (2006-04-23). Please use @Vpi::vpi_control(VpiReset)@ instead.</div>
+<% 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