doc/manual.doc in ruby-vpi-17.0.0 vs doc/manual.doc in ruby-vpi-18.0.0

- old
+ new

@@ -17,11 +17,11 @@ <% end %> <% paragraph "Legal notice" do %> This manual is distributed under <%= xref "intro.license", "the same license as Ruby-VPI" %>. - The admonition graphics used in this manual are Copyright 2005, 2006 "Tango Desktop Project":http://tango.freedesktop.org and are distributed under "these terms":./images/tango/LICENSE. + The admonition graphics used in this manual are Copyright 2005, 2006 "Tango Desktop Project":http://tango.freedesktop.org/Tango_Desktop_Project and are distributed under "these terms":./images/tango/LICENSE. <% end %> <% end %> <% chapter "Welcome", 'intro' do %> <doc_proxy_include intro.inc> @@ -70,15 +70,15 @@ <pre> $ gem env gemdir /usr/lib/ruby/gems/1.8 - $ ls -d /usr/lib/ruby/gems/1.8/gems/ruby-vpi* + $ ls -d `gem env gemdir`/gems/ruby-vpi* /usr/lib/ruby/gems/1.8/gems/ruby-vpi-7.0.0/ </pre> - <% note "Tuning for maximum performance" do %> + <% tip "Tuning for maximum performance" do %> 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 <pre>gem install -y ruby-vpi</pre> command. For example, if your C compiler is GCC, then you can set @CFLAGS@ to <tt>-O9</tt> for maximum optimization. <% end %> <% section "Installing on Windows", "setup.inst.windows" do %> After Ruby-VPI is compiled, it is linked to symbols whose names begin with <tt>_vpi</tt>. In GNU/Linux and similar operating systems, these symbols are allowed to be undefined. However, one "cannot compile a shared object file with references to undefined symbols in Windows":http://sourceware.org/ml/cygwin/2001-12/msg01293.html. @@ -168,11 +168,11 @@ <% section "@vprintf@ is @printf@" do %> The @vpi_vprintf@ and @vpi_mcd_vprintf@ VPI functions are aliased to @vpi_printf@ and @vpi_mcd_printf@ respectively because: - * Ruby represents "variable argument lists as arrays":http://www.rubycentral.com/book/tut_methods.html#UA instead of defining a special datatype, such as @va_list@, for them. + * Ruby represents "variable argument lists as arrays":http://phrogz.net/ProgrammingRuby/tut_methods.html#variablelengthargumentlists instead of defining a special datatype, such as @va_list@, for them. * 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> @@ -477,11 +477,11 @@ By converting Verilog header files into Ruby, your test can utilize the same @`define@ constants that are used in the Verilog design. <% end %> <% end %> <% section "Sample tests", "usage.examples" do %> - 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. + The <tt>samp</tt> directory ("browse it online":<%= codeURL %>/samp/) 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. <% end %> <% section "Tutorial", "usage.tutorial" do %> # <%= xref "usage.tutorial.declare-design", "Declare a design" %> using Verilog 2001 syntax. # <%= xref "usage.tutorial.generate-test", "Generate a test" %> for the design using the <%= xref "usage.tools.generate", "automated test generator" %> tool. @@ -579,11 +579,10 @@ <% 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" %>. - # Replace the contents of the files named <tt>RSpec/counter_design.rb</tt> and <tt>xUnit/counter_design.rb</tt> with the following code. <code><%= File.read '../samp/counter/RSpec/counter_design.rb' %></code> <% 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" %>. @@ -709,10 +708,12 @@ <% chapter "Known problems", "problems" do %> This chapter presents known problems and possible solutions. <% section "Icarus Verilog", "problem.ivl" do %> + The following sections describe problems that occur when Icarus Verilog is used with Ruby-VPI. + <% section "Give full paths to Verilog objects", "problems.ivl.vpi_handle_by_name.absolute-paths" do %> In version 0.8 and snapshot 20061009 of Icarus Verilog, the @vpi_handle_by_name@ function requires an _absolute_ path (including the name of the bench which instantiates the design) to a Verilog object. In addition, @vpi_handle_by_name@ always returns @nil@ when its second parameter is specified. For example, consider <%= xref "ex:TestFoo" %>. Here, one must write @vpi_handle_by_name("TestFoo.my_foo.clk", nil)@ instead of @vpi_handle_by_name("my_foo.clk", TestFoo)@ in order to access the @clk@ input of the @my_foo@ module instance. @@ -753,14 +754,27 @@ assign clk_wire = clk_reg; endmodule </code> <% end %> <% 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 "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. + <% section "Cadence NC-Sim", "problem.ncsim" do %> + The following sections describe problems that occur when Cadence NC-Sim (version 05.83-s003) is used with Ruby-VPI. + + <% section "Cannot force values onto handles", "problem.ncsim.vpiForceFlag" do %> + When you write to a handle's value using @vpi_put_value()@ with the @VpiForceFlag@ propagation parameter, it does not have any effect. As a result, the "register_file" sample test fails when you run it with NC-Sim. + + This might be a bug in NC-Sim itself: even though I specified the "+access+rwc" command-line option for NC-Sim, I'm thinking that the force/release capability is not really enabled. However, it's more likely that there's a bug in the "register_file" sample test. + + If you happen to know the solution, please tell me either on the project forums or via e-mail (see the LICENSE file for my e-mail address). Thanks. + <% end %> + <% end %> <% end %> <% chapter "Glossary", "glossary" do %> <% section "Test", "glossary.test" do %> @@ -790,10 +804,10 @@ <% end %> <% section "RSpec", "glossary.RSpec" do %> The <%= xref "glossary.BDD", "BDD" %> framework for Ruby. - See the "RSpec website":http://rspec.rubyforge.org and "tutorial":http://rspec.rubyforge.org/tutorials/index.html for more information. + See the "RSpec website":http://rspec.rubyforge.org and "tutorial":http://rspec.rubyforge.org/documentation/index.html for more information. <% end %> <% section "Test driven development", "glossary.TDD" do %> An "agile software development methodology":http://agilemanifesto.org/ which emphasizes (1) testing functionality before implementing it and (2) refactoring.