doc/guide.erb in ruby-vpi-21.0.0 vs doc/guide.erb in ruby-vpi-21.1.0

- old
+ new

@@ -14,30 +14,34 @@ # parameters for the HTML format $title = "Ruby-VPI #{RubyVPI::Project[:version]} user guide" $authors = { 'Suraj N. Kurapati' => 'http://snk.rubyforge.org' } $feeds = { ann_url => :rss } + + intro_paragraph = <<-EOS.strip + Ruby-VPI is a library that lets "Ruby":http://www.ruby-lang.org programs access the entire "IEEE 1364-2005 Verilog VPI":http://ieeexplore.ieee.org/xpl/standardstoc.jsp?isnumber=33945 interface supported by "major Verilog simulators":#setup.reqs.sim today. It also serves as *platform for unit testing*, rapid *prototyping*, and systems *integration* of Verilog modules through Ruby + EOS %> -<% header_inside_below do %> - "Release notes and project news":<%= log_url %> &mdash; "Subscribe !images/feed-icon-28x28.png!":<%= ann_url %> +<% abstract do %> + <%= intro_paragraph %>. - "Downloads":<%= pkg_url %> - obtain the newest release package. + p=. <%= xref 'Introduction', '< Continue reading... >' %> - "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. - - "Reference":api/index.html - API documentation for source code. - - "Developer feed":<%= dev_url %> - news about repository commits. + <% paragraph "Resources" do %> + * "Releases":<%= log_url %> - release notes and project news. "!images/feed-icon-28x28.png(RSS feed)!":<%= ann_url %> + * "Downloads":<%= pkg_url %> - obtain the newest release package. + * "Source code":<%= src_url %> - obtain via "Darcs 2":http://darcs.net or browse online. + * "Reference":api/index.html - API documentation for source code. "!images/feed-icon-28x28.png(RSS feed)!":<%= dev_url %> + * "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. + <% end %> <% 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: + <%= intro_paragraph %>: * Create complex Verilog test benches easily and wholly in Ruby. * Apply agile software development practices to develop hardware. * Perform "specification-driven functional verification":http://ruby-vpi.rubyforge.org/papers/masters_thesis.html ("PDF version":http://ruby-vpi.rubyforge.org/papers/masters_thesis.pdf). Ruby-VPI is *open source software* (see <%= xref "License" %>) so feel free to contribute your improvements and discuss your ideas in the <%= mailing_list_link %>. See <%= xref "Hacking" %> for details. @@ -77,58 +81,59 @@ * Uses "rcov":http://eigenclass.org/hiki.rb?rcov for test <%= xref 'usage.runner.env-vars', "coverage analysis and report generation" %>. <% end %> <% end %> <% section "License" do %> - <%= h(File.read('LICENSE')).gsub(/^Copyright.*$/, '\&<br/>') %> + <%=h File.read('LICENSE').gsub(/^Copyright.*$/, "\\&\n").para_join %> <% end %> <% section "Appetizers" do %> Here is a tiny sampling of code to whet your appetite. See <%= xref 'usage.tutorial', "the tutorial" %> for more samples. * Assign the value 2^2048^ to a register: <code> - # NOTE: these are all equivalent + # these statements are equivalent your_register.intVal = 2 ** 2048 your_register.put_value 2 ** 2048 </code> * Check if all nets in a module are at high impedance: <code> your_module.all_net? { |your_net| your_net.z? } - # or, alternatively: + # or: your_nets = your_module.net_a your_nets.all? { |net| net.z? } </code> * See a register's path, width, and location (file & line number): <code> - # NOTE: these are all equivalent - puts your_register + + # or: + p :path => your_register.fullName p :width => your_register.size p :file => your_register.fileName p :line => your_register.lineNo </code> * Access the first five elements in a memory: <code> - # NOTE: these are all equivalent + # these statements are equivalent your_memory.memoryWord_a.first(5) your_memory.memoryWord_a[0..4] your_memory.memoryWord_a[0...5] your_memory.memoryWord_a[0, 5] </code> * Clear a memory by filling it with zeroes: <code> - # NOTE: these are all equivalent + # these statements are equivalent your_memory.each_memoryWord { |w| w.f! } your_memory.each_memoryWord { |w| w.vpi0! } your_memory.each_memoryWord { |w| w.intVal = 0 } your_memory.each_memoryWord { |w| w.put_value 0 } @@ -180,21 +185,21 @@ <% paragraph "Verilog simulator", 'setup.reqs.sim' do %> 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 | + | "GPL Cver":http://www.pragmatic-c.com/gpl-cver/ (recommended) | Version 2.11a or newer is acceptable. | | "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 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' %>. | + | "Mentor Modelsim":http://www.model.com | Any version that supports the <tt>-pli</tt> option is acceptable. See <%= xref "problem.vsim" %> if you are using Modelsim version 6.2g. | + | "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. See <%= xref "problem.ncsim" %> for details. | + | "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" %>. See <%= xref 'problems.ivl.vpi_handle_by_name.absolute-paths' %> for details. | <% end %> <% paragraph "Compilers" do %> |_. Software |_. Notes | | "make":http://en.wikipedia.org/wiki/Make | Any flavor or distribution should be acceptable. | - | C compiler | the "GNU Compiler Collection (GCC)":http://www.gnu.org/software/gcc/ is preferred, but any C compiler should be acceptable. | + | C compiler | the "GCC(GNU Compiler Collection)":http://www.gnu.org/software/gcc/ is preferred, but any C compiler should be acceptable. | | "SWIG":http://www.swig.org/download.html | Version 1.3.29 or newer is required. | | "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 %> @@ -223,20 +228,24 @@ You can tune your installation of Ruby-VPI for maximum performance by adding your C compiler's optimization flag to the @CFLAGS@ environment variable _before_ you run the installation command (shown below). For example, if your C compiler is GCC, then you can set @CFLAGS@ to <tt>-O9</tt> for maximum optimization. <% end %> 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 + <pre> + gem install ruby-vpi + ruby-vpi -v + </pre> 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 + <pre> + rake build + ruby bin/ruby-vpi -v + </pre> If the installation was successful, then you will see output like this: <pre><%=h `ruby bin/ruby-vpi -v` %></pre> Otherwise, you can ask for help in the <%= mailing_list_link %>. @@ -256,15 +265,15 @@ <% end %> <% section "Maintenance", "setup.maintenance" do %> You can upgrade to the latest release of Ruby-VPI by running the following command: - gem update ruby-vpi + pre. gem update ruby-vpi You can uninstall Ruby-VPI by running the following command: - gem uninstall ruby-vpi + pre. gem uninstall ruby-vpi Learn more about using RubyGems in "the RubyGems user guide":http://www.rubygems.org. <% end %> <% section "Manifest", "setup.manifest" do %> @@ -371,11 +380,11 @@ the Verilog objects you want and proceed as usual. * <tt>loader.rb</tt> ** The user-defined Ruby script which loads the test. - Note that because the user-defined Ruby script (<tt>loader.rb</tt> among the files above) decides what files to load, you are free to organize your tests however you like. As a result, the files presented above are a mere _convention_ that you can _choose_ to follow rather than being forced to follow. + Note that because the user-defined Ruby script (<tt>loader.rb</tt> among the files above) decides what files to load, you are free to organize your tests however you like. As a result, the files presented above are a mere convention that you can _choose_ to follow. <% end %> <% end %> <% section "Interacting with the Verilog simulator", "overview.relay" do %> 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. @@ -488,11 +497,11 @@ | a | array | @vpi_iterate@ | <% end %> <% table "Examples of accessing a handle's properties", "ex:properties" do %> |_/2. Ruby expression |_\6. Method naming format |_/2. Description | - ||_. Operation |_. _ |_. Property |_. _ |_. Accessor |_. Addendum || + |_. Operation |_. _ |_. Property |_. _ |_. Accessor |_. Addendum | | @handle.vpiIntVal@ | &nbsp; | &nbsp; | vpiIntVal | &nbsp; | &nbsp; | &nbsp; |/4. Obtain 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. Assign the integer 15 to the _logic value_ of the handle's @VpiIntVal@ property. | @@ -571,14 +580,14 @@ First, *all processes execute in the _same_ time step*. That is, we only advance the _entire_ simulation to the next time step when _all_ processes are finished with the current time step. In this manner, we avoid race conditions where a process advances the entire simulation to a future time step but the other processes still think they are executing in the original time step (because they were not notified of the advancement). Second, *all processes see the _same_ input* (the state of the simulation database at the start of the current time step) while executing in a time step. That is, when a process modifies the simulation database, say, by changing the logic value of a register, the modification only takes effect at the _end_ of the current time step. In this manner, we avoid race conditions where one process modifies the simulation midflight but some/all of other processes are unaware of that modification (because they were not notified of its occurence). - Note that these constraints are automatically enforced "under the hood", so to speak, by Ruby-VPI. As a user, you need not do anything extra to implement or support these constraints; they are already taken care of. + Note that these constraints are automatically enforced by Ruby-VPI. As a user, you need not do anything extra to implement or support these constraints. <% caution "Assignments inside processes are non-blocking" do %> - As a result of the constraints described above, all assignments inside processes are treated like Verilog's non-blocking assignments. Think about it: blocking assignments allow a process to make changes to simulation values (possibly) before other processes read those values. Since the second constraint makes all processes see the same input while they are executing, it is impossible to support blocking assignments inside processes. + As a result of the constraints described above, all assignments inside processes are treated like Verilog's *non-blocking assignments*. Think about it: blocking assignments allow a process to make changes to simulation values (possibly) before other processes read those values. Since the second constraint forces all processes to see the _same_ input while they are executing, it is impossible to support blocking assignments inside processes. <% end %> <% section "Creating a concurrent process" do %> You can create a concurrent proceess by passing a block of code to the @process@ method. Once the process finishes executing this block of code, it will disappear automatically. This behavior mimics the "initial" blocks of the Verilog language. @@ -588,11 +597,11 @@ Suppose you have the following Verilog code: <code lang="verilog"> always @(posedge clock1 and negedge clock2) begin foo <= foo + 1; - bar = bar + 5; + bar = bar + 5; // treated as NON-blocking in prototype end </code> In Ruby-VPI, this code would be written as: @@ -706,13 +715,15 @@ <% example "Running a test with environment variables" do %> Below, we enable the prototype and code coverage analysis: <pre>rake -f your_test_runner.rake PROTOTYPE=1 COVERAGE=1</pre> Below, we _disable_ the prototype and enable the code coverage analysis. These invocations are equivalent if the @PROTOTYPE@ environment variable is unset. - <pre>rake -f your_test_runner.rake PROTOTYPE=0 COVERAGE=1</pre> - <pre>rake -f your_test_runner.rake PROTOTYPE= COVERAGE=1</pre> - <pre>rake -f your_test_runner.rake COVERAGE=1</pre> + <pre> + rake -f your_test_runner.rake PROTOTYPE=0 COVERAGE=1 + rake -f your_test_runner.rake PROTOTYPE= COVERAGE=1 + rake -f your_test_runner.rake COVERAGE=1 + </pre> <% end %> <% end %> <% end %> <% section "Tools", "usage.tools" do %> @@ -979,26 +990,25 @@ After successfully building from source (see <%= xref "hacking.build" %>), set the @RUBYLIB@ environment variable to the path where you checked out the source code _plus_ the <tt>lib/</tt> directory. For example, if you checked out the source code into <tt>/home/foo/ruby-vpi/</tt> then you would set the value of the @RUBYLIB@ environment variable to <tt>/home/foo/ruby-vpi/lib/</tt>. Afterwards, any Ruby-VPI tests you run will use the checked-out source code directly. <% end %> + <% section "Editing this guide", "hacking.guide" do %> + The <tt>doc/guide.erb</tt> file contains the source code of this guide. You must install "Gerbil":http://gerbil.rubyforge.org before you can run the <pre>rake doc</pre> command to automatically generate the HTML documentation you are currently viewing. + <% end %> + <% section "Building release packages", "hacking.release-packages" do %> In addition to the <%= xref "setup.reqs", "normal requirements" %> you need the following software to build release packages: - * "RedCloth":http://rubyforge.org/projects/redcloth/ - * "CodeRay":http://rubyforge.org/projects/coderay/ + * "Gerbil":http://gerbil.rubyforge.org - extensible document generator Once you have satisfied these requirements, you can run the following command to build the release packages: <pre>rake release</pre> For more build options, see below: <pre>$ rake -T <%=h `rake -T` %></pre> <% end %> - - <% section "Editing this guide", "hacking.guide" do %> - The <tt>doc/guide.erb</tt> file contains the source code of this guide. You must install "Gerbil":http://gerbil.rubyforge.org before you can run the <pre>rake doc</pre> command to automatically generate the HTML documentation you are currently viewing. - <% end %> <% end %> <% chapter "Known problems", "problems" do %> This chapter presents known problems and possible solutions. @@ -1054,10 +1064,44 @@ 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). + <% paragraph "Problem" do %> + Using RubyVPI 21.0.0 (or a newer version) to test a real Verilog module (as opposed to a <%= xref "usage.prototyping", "Ruby prototype of a Verilog module" %>) with the 64-bit Cadence NC-Verilog 05.83-s003 causes the simulator to crash. + <% end %> + + <% paragraph "Solution" do %> + Use RubyVPI 20.0.0 or an older version. + <% end %> + + <% paragraph "Discussion" do %> + The problem is most likely an interaction issue with Ruby's threads implementation because *ncsim* worked fine with the "POSIX threads (pthreads)":http://en.wikipedia.org/wiki/Pthreads based Ruby-VPI 20.0.0. + <% end %> + <% end %> + + <% section "Mentor Modelsim", "problem.vsim" do %> + <% paragraph "Problem" do %> + The <%= xref "fig:RSpec/counter_spec.rb", "example RSpec-based up-counter test" %> sometimes fails randomly when run under the 64-bit Mentor Modelsim 6.2g. + <% end %> + + <% paragraph "Solution" do %> + By adding a zero-delay null statement at the beginning of the edge-triggered always block in <%= xref "fig:counter.v_impl", "the Verilog source code for the up-counter" %>, the problem goes away and the test always passes: + + <code lang="verilog"> + always @(posedge clock) begin + #0; // zero-delay null statement + + /* rest of the code */ + end + </code> + <% end %> + + <% paragraph "Discussion" do %> + I think the problem is a faulty implementation of the cbAfterDelay callback in Modelsim 6.2g, where the callback sometimes takes you to the _middle_ of a time-step (after some events in the time-step have already been executed) rather than taking you to the _top_ of a time-step (before any events in that time-step have been executed). + + See http://rubyforge.org/pipermail/ruby-vpi-discuss/2007-October/000083.html + <% end %> <% end %> <% end %> <% chapter "Glossary", "glossary" do %> <% section "Test", "glossary.test" do %> \ No newline at end of file