guide.erb in ruby-vpi-21.0.0

- old
+ new

@@ -3,53 +3,37 @@
   require 'lib/ruby-vpi'
 
   # local variables for this document
   mailing_list_url  = 'http://rubyforge.org/mailman/listinfo/ruby-vpi-discuss'
   mailing_list_link = link(mailing_list_url, "project mailing list")
-  download_url      = 'http://rubyforge.org/frs/?group_id=1339'
-  source_repo_url   = File.join(RubyVPI::Project[:website], 'src')
-  feed_url          = File.join(RubyVPI::Project[:website], 'news.xml')
 
+  pkg_url = File.join(RubyVPI::Project[:website], 'pkg')
+  src_url = File.join(RubyVPI::Project[:website], 'src')
+  ann_url = File.join(RubyVPI::Project[:website], 'ann')
+  dev_url = File.join(RubyVPI::Project[:website], 'dev')
+  log_url = File.join(RubyVPI::Project[:website], 'log')
+
   # parameters for the HTML format
   $title   = "Ruby-VPI #{RubyVPI::Project[:version]} user guide"
-  $authors = { 'Suraj N. Kurapati' => 'http://snk.tuxfamily.org' }
-  $feeds   = { feed_url => :rss }
+  $authors = { 'Suraj N. Kurapati' => 'http://snk.rubyforge.org' }
+  $feeds   = { ann_url => :rss }
+%>
 
-  # parameters for Gerbil
-  $unindent = '  '
+<% header_inside_below do %>
+  "Release notes and project news":<%= log_url %> &mdash; "Subscribe !images/feed-icon-28x28.png!":<%= ann_url %>
 
-  class String
-    def indent aDepthOrNode
-      amt =
-        if aDepthOrNode.is_a? Node
-          aDepthOrNode.depth + 1
-        else
-          aDepthOrNode
-        end
+  "Downloads":<%= pkg_url %> - obtain the newest release package.
 
-      gsub(/^/, $unindent * amt).strip
-    end
-  end
-%>
+  "Talks":http://ruby-vpi.rubyforge.org/talks/ - archive of presentations and seminars.
 
-<% header_inside_below do %>
-  <div style="text-align: left; margin-top: 2em">
+  "Papers":http://ruby-vpi.rubyforge.org/papers/ - archive of research and publications.
 
-  * "News feed":<%= feed_url %>
-    - project news and release announcements.
-  * "Download area":<%= download_url %>
-    - place to obtain release packages.
-  * "Mailing list":<%= mailing_list_url %>
-    - ask questions, get help, and discuss.
-  * "Reference":api/
-    - API documentation for source code.
-  * "Talks":http://ruby-vpi.rubyforge.org/talks/
-    - archive of presentations and seminars.
-  * "Papers":http://ruby-vpi.rubyforge.org/papers/
-    - archive of research and publications.
+  "Mailing list":<%= mailing_list_url %> - ask questions, get help, and discuss.
 
-  </div>
+  "Reference":api/index.html - API documentation for source code.
+
+  "Developer feed":<%= dev_url %> - news about repository commits.
 <% end %>
 
 <% chapter "Introduction" do %>
   Ruby-VPI is a library that provides the entire "IEEE 1364-2005 Verilog VPI":http://ieeexplore.ieee.org/xpl/standardstoc.jsp?isnumber=33945 interface to "Ruby":http://www.ruby-lang.org scripts. It also serves as *platform for unit testing*, rapid *prototyping*, and systems *integration* of Verilog modules through Ruby:
   * Create complex Verilog test benches easily and wholly in Ruby.
@@ -198,11 +182,11 @@
       Ruby-VPI is known to work with the following simulators. However, you should be able to use it with any Verilog simulator that supports VPI.
 
       |_. Simulator |_. Notes |
       | "Synopsys VCS":http://www.synopsys.com/products/simulation/simulation.html | Any version that supports the <tt>-load</tt> option is acceptable. |
       | "Mentor Modelsim":http://www.model.com | Any version that supports the <tt>-pli</tt> option is acceptable. |
-      | "Cadence NC-Sim":http://www.cadence.com/products/functional_ver/nc-verilog/ | Any version that supports the <tt>+loadvpi</tt> option is acceptable. |
+      | "Cadence NC-Sim":http://www.cadence.com/products/functional_ver/nc-verilog/ | Any version that supports the <tt>+loadvpi</tt> option is acceptable for Ruby-VPI versions 20.0.0 or older.  Version 21.0.0 of Ruby-VPI <%= xref "problem.ncsim", "does not work with Cadence NC-Sim" %>. |
       | "GPL Cver":http://www.pragmatic-c.com/gpl-cver/ | Version 2.11a or newer is acceptable. |
       | "Icarus Verilog":http://www.geda.seul.org/tools/icarus/index.html | Version 0.8 is _mostly_ acceptable because you *will not* be able to <%= xref "vpi.handles.relatives", "access child handles through method calls" %>. The reason for this limitation is explained in <%= xref 'problems.ivl.vpi_handle_by_name.absolute-paths' %>. |
     <% end %>
 
     <% paragraph "Compilers" do %>
@@ -213,11 +197,10 @@
       | "Ruby":http://www.ruby-lang.org/en/downloads/ | Version 1.8 or newer, including header and linkable object files for building extensions, is required. You can install Ruby by following "these instructions":http://www.ruby-lang.org/en/downloads/. |
     <% end %>
 
     <% paragraph "Libraries" do %>
       |_. Library |_. Notes |
-      | "POSIX threads (pthreads)":http://en.wikipedia.org/wiki/Pthreads | Header and linkable object files, and operating system support for this library are necessary. |
       | "RubyGems":http://rubyforge.org/frs/?group_id=126 | Any recent version should be acceptable. You can install RubyGems by following "these instructions":http://www.rubygems.org/read/chapter/3. |
     <% end %>
   <% end %>
 
   <% section "Recommendations", "setup.recom" do %>
@@ -243,12 +226,12 @@
     Once your system has the <%= xref "setup.reqs", "necessary requirements" %>, you can install Ruby-VPI by running the following commands:
 
       gem install ruby-vpi
       ruby-vpi -v
 
-    Otherwise, follow these instructions:
-    # Download the newest <tt>tar.gz</tt> release package from "the project download area":<%= download_url %>.
+    Alternatively, if you do not wish to use RubyGems:
+    # Download the newest <tt>tar.gz</tt> release package from "the project download area":<%= pkg_url %>.
     # Extract the release package anywhere you want on your system.
     # Go inside the extracted directory and run the following commands:
 
       rake build
       ruby bin/ruby-vpi -v
@@ -862,28 +845,28 @@
       * 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. This process is illustrated by <%= xref "fig:RSpec/counter_spec.rb" %> and <%= xref "fig:xUnit/counter_spec.rb" %>.
 
-      <% example "Specification implemented in RSpec format", "fig:RSpec/counter_spec.rb" do |n| %>
-        <code><%= File.read('examples/counter/RSpec/counter_spec.rb').indent(n) %></code>
+      <% example "Specification implemented in RSpec format", "fig:RSpec/counter_spec.rb" do %>
+        <code><%= File.read('examples/counter/RSpec/counter_spec.rb') %></code>
       <% end %>
 
-      <% example "Specification implemented in xUnit format", "fig:xUnit/counter_spec.rb" do |n| %>
-        <code><%= File.read('examples/counter/xUnit/counter_spec.rb').indent(n) %></code>
+      <% example "Specification implemented in xUnit format", "fig:xUnit/counter_spec.rb" do %>
+        <code><%= File.read('examples/counter/xUnit/counter_spec.rb') %></code>
       <% end %>
 
       Before we continue,
       # Replace the contents of the file named <tt>RSpec/counter_spec.rb</tt> with the source code shown in <%= xref "fig:RSpec/counter_spec.rb" %>.
       # Replace the contents of the file named <tt>xUnit/counter_spec.rb</tt> with the source code shown in <%= xref "fig:xUnit/counter_spec.rb" %>.
     <% end %>
 
     <% section "Implement the prototype", "usage.tutorial.implement-proto" do %>
       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. 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 |n| %>
-        <code><%= File.read('examples/counter/RSpec/counter_proto.rb').indent(n) %></code>
+      <% example "Ruby prototype of our Verilog design", "fig:counter_proto.rb" do %>
+        <code><%= File.read('examples/counter/RSpec/counter_proto.rb') %></code>
       <% end %>
 
       Before we continue, replace the contents of the files named <tt>RSpec/counter_proto.rb</tt> and <tt>xUnit/counter_proto.rb</tt> with the source code shown in <%= xref "fig:counter_proto.rb" %>.
     <% end %>
 
@@ -928,12 +911,12 @@
     <% end %>
 
     <% section "Implement the design", "usage.tutorial.implement-design" do %>
       Now that we have implemented and verified our prototype, we are ready to implement our design This is often quite simple because we translate _existing_ code from Ruby (our prototype) into Verilog (our design). The result of this process is illustrated by <%= xref "fig:counter.v_impl" %>.
 
-      <% example "Implementation of a simple up-counter with synchronous reset", "fig:counter.v_impl" do |n| %>
-        <code lang="verilog"><%= File.read('examples/counter/counter.v').indent(n) %></code>
+      <% example "Implementation of a simple up-counter with synchronous reset", "fig:counter.v_impl" do %>
+        <code lang="verilog"><%= File.read('examples/counter/counter.v') %></code>
       <% end %>
 
       Before we continue, replace the contents of the files named <tt>RSpec/counter.v</tt> and <tt>xUnit/counter.v</tt> with the source code shown in <%= xref "fig:counter.v_impl" %>
     <% end %>
 
@@ -969,11 +952,11 @@
         </pre>
       <% end %>
     <% end %>
 
     <% section "More examples", "usage.examples" do %>
-      The <tt>examples</tt> directory ("browse it online":<%= source_repo_url %>/examples/) contains several example tests which illustrate how Ruby-VPI can be used. Each example 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.
+      The <tt>examples</tt> directory ("browse it online":<%= src_url %>/examples/) contains several example tests which illustrate how Ruby-VPI can be used. Each example 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.
     <% end %>
   <% end %>
 <% end %>
 
 <% chapter "Hacking", "hacking" do %>
@@ -1068,9 +1051,13 @@
     <% end %>
 
     <% section "VPI::reset", "problems.ivl.vpi_reset" do %>
       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.
     <% end %>
+  <% end %>
+
+  <% section "Cadence NC-Sim", "problem.ncsim" do %>
+    *ncsim* crashes with Ruby-VPI 21.0.0.  The problem is most likely an interaction issue with Ruby's threads implementation because *ncsim* worked fine with a "POSIX threads (pthreads)":http://en.wikipedia.org/wiki/Pthreads based implementation of Ruby-VPI (version 20.0.0).
   <% end %>
 <% end %>
 
 <% chapter "Glossary", "glossary" do %>
   <% section "Test", "glossary.test" do %>
\ No newline at end of file