doc/manual.doc in ruby-vpi-18.0.2 vs doc/manual.doc in ruby-vpi-19.0.0

- old
+ new

@@ -1,21 +1,25 @@ <doc_proxy_include common.inc> -<% front_cover "Ruby-VPI #{version} user manual" do %> +<% front_cover "Ruby-VPI user manual" do %> h2(author). Suraj N. Kurapati h3(date). <%= Time.now.strftime("%d %B %Y") %> + p=. "Version <%= version %>":history.html#<%= version.to_html_anchor %> + <% paragraph "About this manual" do %> This manual is meant to be read in conjunction with the "reference documentation for Ruby-VPI":../ref/ruby/index.html. In addition, if you are new to "the Ruby language":http://www.ruby-lang.org, you are encouraged to "explore its documentation":http://www.ruby-lang.org/en/documentation/ as necessary. In this manual, you will notice that the numbers of chapters, sections, figures, admonitions, etc. are hyperlinks that take you back to the corresponding place in the table of contents. These links make it easy to navigate this manual, especially for users of text-only web browsers. In addition, this manual is distributed as one big HTML file so that you can easily search for a particular topic using nothing more than your web browser's built-in text search mechanism. This facilitates offline reading, where an Internet search engine is not available. - You can give feedback about this manual and, in general, any aspect of the Ruby-VPI project on the "project forums":<%= forumURL %>. Furthermore, you can <%= xref "hacking.manual", "edit this manual" %> and contribute your improvements to the "project patches":<%= trackerURL %>. Finally, you can find the newest version of this manual at the "Ruby-VPI project website":<%= projectURL %>. + Finally, this manual comes equipped with a stylesheet that makes it suitable for printing. In particular, users of the "Mozilla":http://mozilla.org family of web browsers will be pleasantly surprised to notice that all hyperlinks have been expanded to include their target URL next to the link text. So try using the "print preview" function of a graphical web browser to see how this manual will appear when printed. + + You can give feedback about this manual and, in general, any aspect of the Ruby-VPI project on the "project forums":<%= forumURL %>. Furthermore, you can <%= xref "hacking.manual", "edit this manual" %> yourself and contribute your improvements to the "project patches":<%= trackerURL %> tracker. Finally, you can find the newest version of this manual at the "Ruby-VPI project website":<%= projectURL %>. <% end %> <% paragraph "Legal notice" do %> This manual is distributed under <%= xref "intro.license", "the same license as Ruby-VPI" %>. @@ -34,11 +38,11 @@ * <tt>doc</tt> contains user documentation in various formats. * <tt>ref</tt> contains reference API documentation in HTML format. * <tt>ext</tt> contains source code, written in the C language, for the <%= xref "organization", "core of Ruby-VPI" %> * <tt>lib</tt> contains Ruby libraries provided by Ruby-VPI. * <tt>bin</tt> contains various tools. See <%= xref "usage.tools" %> for more information. - * <tt>samp</tt> contains example tests. See <%= xref "usage.examples" %> for more information. + * <tt>examples</tt> contains example tests. See <%= xref "usage.examples" %> for more information. <% end %> <% section "Requirements", "setup.reqs" do %> See <%= xref "intro.reqs" %> above. @@ -116,32 +120,10 @@ !figures/organization_detailed.png! <% end %> As <%= xref "fig:organization.detail" %> shows, Ruby-VPI is composed of two complementary parts: one interacts with VPI through the C language, while the other interacts with an executable specification written in the Ruby language. The former is complied during installation to produce dynamically loadable C libraries---each tailored to accommodate the quirks of its respective Verilog simulator. The latter is not compiled because Ruby programs are interpreted dynamically. - <% section "Ruby/Verilog interaction", "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. - - In contrast, Ruby-VPI puts the _specification_ in charge. The specification temporarily transfers control to the Verilog simulator by invoking the @advance_time@ method, which returns control to the specification when it finishes. This process is illustrated in <%= xref "fig:ruby_relay" %>. - - Ruby-VPI's approach is the same as any software testing framework, where the _specification_ drives the design under test. Whereas, the typical VPI & C approach is literally _backwards_ because the design under test drives the specification. - - <% figure "Interaction between Ruby and Verilog", "fig:ruby_relay" do %> - !figures/ruby_relay.png! - - # The current simulation time is _X_. - # The specification invokes the @Vpi::advance_time@ method with parameter _Y_, which specifies the number of simulation time steps to be simulated. - # The Verilog simulator is now in control (temporarily). - # The current simulation time has _not_ changed; it is still _X_. - # The Verilog simulator simulates _Y_ simulation time steps. - # The current simulation time is now _X + Y_. - # The Verilog simulator returns control back to the specification. - <% end %> - - Another means of transferring control from the specification to the Verilog simulator is the <%= xref "vpi.callbacks", "VPI callback" %>. - <% end %> - <% section "Tests", "organization.tests" do %> In Ruby-VPI, the process of functional verification is neatly packaged into self-contained, executable tests. As <%= xref "fig:organization" %> illustrates, a test is composed of a *bench*, a *design*, and a *specification*. <% figure "Organization of a test in Ruby-VPI", "fig:organization" do %> !figures/organization.png! @@ -151,42 +133,46 @@ *The design* is an instantiated Verilog module. To extend the analogy of the electronics laboratory, it corresponds to the electronic component that is verified by an engineer. *The specification* is a Ruby program. In the electronics laboratory analogy, it corresponds to the engineer who inspects, manipulates, and verifies the electronic component. In terms of specification-driven functional verification, it corresponds to the executable specification. <% end %> +<% end %> +<% chapter "Usage", "usage" do %> + <% 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. - <% section "VPI in Ruby" do %> - <% section "Deviations from the VPI standard" do %> - Ruby-VPI makes the entire IEEE Std 1364-2005 VPI interface available to Ruby, but with the following minor differences. + In contrast, Ruby-VPI puts the _specification_ in charge. The specification temporarily transfers control to the Verilog simulator by invoking the @advance_time@ method, which returns control to the specification after a given number of time steps. This process is illustrated in <%= xref "fig:ruby_relay" %>. You can also use the @wait@ method, which is just an alias to the @advance_time@ method, if you prefer. + Ruby-VPI's approach is the same as any software testing framework, where the _specification_ drives the design under test. Whereas, the typical VPI & C approach is literally _backwards_ because the design under test drives the specification. - <% section "Names are capitalized" do %> - The names of all VPI types, structures, and constants become _capitalized_ because Ruby requires that the names of constants begin with a capital letter. However, note that Ruby's capitalization rule does _not_ apply to VPI functions. + <% figure "Interaction between Ruby and Verilog", "fig:ruby_relay" do %> + !figures/ruby_relay.png! - 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. However, the @vpi_handle@ function remains as @vpi_handle@ in Ruby. - <% end %> + # The current simulation time is _X_. + # The specification invokes the @advance_time@ method with parameter _Y_, which specifies the number of simulation time steps to be simulated. + # The Verilog simulator is now in control (temporarily). + # The current simulation time has _not_ changed; it is still _X_. + # The Verilog simulator simulates _Y_ simulation time steps. + # The current simulation time is now _X + Y_. + # The Verilog simulator returns control back to the specification. + <% end %> + Another means of transferring control from the specification to the Verilog simulator is the <%= xref "vpi.callbacks", "VPI callback" %>. + <% end %> - <% 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: + <% section "VPI in Ruby", "vpi" do %> + Ruby-VPI provides the _entire_ IEEE Std 1364-2005 VPI interface to Ruby. This section will show you how to make use of it. - * 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. + <% note "Constants are capitalized in Ruby" do %> + In the remainder of this manual, you may be surprised to see that VPI constants such as @vpiIntVal@ are written with a captialized name, as @VpiIntVal@. The reason for this discrepancy is that in Ruby, the names of constants are capitalized. - * 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 = &ap; - } - </code> - <% end %> + However, keep in mind that Ruby-VPI provides all VPI constants in both (1) their original, uncapitalized form and (2) their capitalized Ruby form. You may use either version according to your preference; they are functionally equivalent. <% end %> <% section "Handles", "vpi.handles" do %> - A *handle* is a reference to an object (such as a module, register, wire, and so on) inside the Verilog simulation. Handles allows you to inspect and manipulate the design under test and its internal components. They are instances of the @Vpi::Handle@ class (see "reference documentation":../ref/ruby/classes/Vpi/Handle.html for details) in Ruby-VPI. + A *handle* is a reference to an object (such as a module, register, wire, and so on) inside the Verilog simulation. Handles allows you to inspect and manipulate the design under test and its internal components. They are instances of the @VPI::Handle@ class (see "reference documentation":../ref/ruby/classes/VPI/Handle.html for details) in Ruby-VPI. Handles have various *properties*, listed in the second column of <%= xref "tbl:accessors" %>, which provide different kinds of information about the underlying Verilog objects they represent. These properties are accessed through the VPI functions listed in the last column of <%= xref "tbl:accessors" %>. Handles are typically obtained through the @vpi_handle_by_name@ and @vpi_handle@ functions. These functions are hierarchical in nature, as they allow you to obtain new handles that are related to existing ones. For example, to obtain a handle to a register contained within a module, one would typically write: @your_reg = vpi_handle( VpiReg, your_handle )@ @@ -309,114 +295,172 @@ A _callback_ is a mechanism that makes the Verilog simuluator execute a block of code, which is known as a "callback handler", when some prescribed event occurs in the simulation. Callbacks are added using the @vpi_register_cb@ function and removed using the @vpi_remove_cb@ function. However, instead of storing the address of a C function in the @cb_rtn@ field of the @s_cb_data@ structure (as you would do in C) you pass a block of code to the @vpi_register_cb@ method in Ruby. This block will be executed whenever the callback occurs. <% example "Using a callback for value change notification", "ex:callback" do %> - 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)@. + 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@. In this example, the handle being monitored is the @Counter.count@ signal from <%= xref "fig:counter.v_decl" %>. <code> - cbTime = S_vpi_time.new - cbTime.type = VpiSimTime - cbTime.low = 0 - cbTime.high = 0 + time = S_vpi_time.new + time.type = VpiSimTime + time.low = 0 + time.high = 0 - cbValue = S_vpi_value.new - cbValue.format = VpiIntVal + value = S_vpi_value.new + value.format = VpiIntVal - cbData = S_cb_data.new - cbData.reason = CbValueChange - cbData.obj = Counter.count - cbData.time = cbTime - cbData.value = cbValue - cbData.index = 0 + alarm = S_cb_data.new + alarm.reason = CbValueChange + alarm.obj = Counter.count + alarm.time = time + alarm.value = value + alarm.index = 0 - cbHandle = vpi_register_cb(cbData) do |data| - time = (data.time.high << 32) | data.time.low - count = data.value.value.integer + vpi_register_cb( alarm ) do |info| + time = info.time.integer + count = info.value.value.integer puts "hello from callback! time=#{time} count=#{count}" end </code> Append this code to the <tt>RSpec/counter_spec.rb</tt> file (provided in <%= xref "usage.examples" %> and discussed in <%= xref "usage.tutorial.specification" %>) and run the <%= xref "usage.tutorial", "counter_RSpec test" %> <% end %> <% end %> <% end %> -<% end %> -<% chapter "Usage", "usage" do %> + <% section "Concurrency", "usage.concurrency" do %> + Ruby-VPI provides a concurrency model that allows you to run blocks of code in parallel. These blocks of code are known as _concurrent processes_ and they represent the same idea as "initial", "always", and "forever" blocks do in Verilog. + + Ruby-VPI's concurrency model imposes two important constraints, which are inspired by "GPGPU and fragment/vertex shader programming":http://en.wikipedia.org/wiki/GPGPU, in order to avoid race conditions and to make parallel programming simpler. + + 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. + + <% paragraph "Creating a concurrent process" do %> + You can create a concurrent proceess by passing a block of code to the @process@ method. + + You can also create concurrent processes that loop forever using the @always@ and @forever@ methods, which mimic the "always" and "forever" blocks, respectively, of the Verilog language. However, due to the constraints of the concurrency model (see above), there is one limitation: all assignments are treated like Verilog's non-blocking assignments. + + <% example 'An edge-triggered "always" block' do %> + Suppose you have the following Verilog code: + + <code lang="verilog"> + always @(posedge clock1 and negedge clock2) begin + foo <= foo + 1; + bar = bar + 5; + end + </code> + + In Ruby-VPI, this code would be written as: + + <code> + always do + wait until clock.posedge? and clock2.negedge? + + foo.intVal += 1 + bar.intVal += 5 # this is a NON-blocking assignment! + end + </code> + <% end %> + + <% example 'A change-triggered (combinational) "always" block' do %> + Suppose you have the following Verilog code: + + <code lang="verilog"> + always @(apple, banana, cherry, date) begin + $display("Yum! Fruits are good for health!"); + end + </code> + + In Ruby-VPI, this code would be written as: + + <code> + always do + wait until apple.change? or banana.change? and cherry.change? or date.change? + puts "Yum! Fruits are good for health!" + end + </code> + + Or, if you are lazy like I am, you can express the sensitivity list programatically: + + <code> + always do + wait until [apple, banana, cherry, date].any? {|x| x.change?} + puts "Yum! Fruits are good for health!" + end + </code> + <% end %> + <% end %> + <% end %> + <% section "Prototyping", "usage.prototyping" do %> 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. - The prototyping process is completely transparent: there is absolutely no difference, in the eyes of your executable specification, between a real Verilog design or its Ruby prototype. + The prototyping process is completely transparent: there is absolutely no difference, in the eyes of your executable specification, between a real Verilog design or its Ruby prototype. In addition, the prototyping process is completely standard-based: Ruby prototypes emulate the behavior of real Verilog designs using _nothing more_ than the VPI itself. - In addition, the prototyping process is completely standard-based: Ruby prototypes emulate the behavior of real Verilog designs using _nothing more_ than the VPI itself. - For example, compare the Verilog design shown in <%= xref "fig:counter.v_impl" %> with its Ruby prototype shown in figure <%= xref "fig:counter_proto.rb" %>. The prototype uses only VPI to (1) detect changes in its inputs and (2) manipulate its outputs accordingly. In addition, notice how well the prototype's syntax reflects the intended behavior of the Verilog design. This similarity facilitates rapid translation of a prototype from Ruby into Verilog later in the design process. - <% paragraph "Getting started" do %> - To create a prototype, + <% paragraph "Creating a prototype" do %> # Start with a <%= xref "usage.tutorial.declare-design", "Verilog module declaration" %> for your design. # <%= xref "usage.tutorial.generate-test", "Generate a test" %> using that module declaration. # <%= xref "usage.tutorial.implement-proto", "Implement the prototype" %> in the generated <tt>proto.rb</tt> file. # <%= xref "usage.tutorial.test-proto", "Verify the prototype" %> against its specification. Once you are satisfied with your prototype, you can proceed to <%= xref "usage.tutorial.implement-design", "implement your design in Verilog" %>. 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 (see <%= xref "usage.test-runner" %> for details). + 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 (see <%= xref "usage.runner" %> for details). <% end %> - - <% section "How does prototyping work?" do %> - The @advance_time@ method normally transfers control from the executable specification to the Verilog simulator. However, when prototyping is enabled, Ruby-VPI redefines it so that the @feign!@ method (which is defined in a test's <tt>proto.rb</tt> file) is invoked on the design under test. The @feign!@ method artificially simulates the behavior of the real Verilog design. - - In this manner, control is kept within the Ruby interpreter when prototyping is enabled. An advantage of this approach is that it reduces the total execution time of a Ruby-VPI test by allowing Ruby's POSIX thread to commandeer the Verilog simulator's process. A disadvantage of this approach is that callbacks, which require the transfer of control to the Verilog simulator, must be ignored. - <% end %> <% end %> - <% section "Debugging", "usage.debugger" do %> + <% section "Interactive debugging", "usage.debugger" do %> 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 @DEBUGGER@ environment variable (see <%= xref "usage.test-runner" %> for details). + # Enable the debugger by activating the @DEBUGGER@ environment variable (see <%= xref "usage.runner" %> for details). # Put the @debugger@ command in your code -- anywhere you wish to activate an interactive debugging session. These commands are automatically ignored when the debugger is disabled; so you can safely leave them in your code, if you wish. <% section "Advanced initialization", "usage.debugger.init" do %> By default, Ruby-VPI enables the debugger by invoking the @Debugger.start@ method. If you wish to perform more advanced initialization, such as having the debugger accept remote network connections for interfacing with a remote debugging session or perhaps with an IDE (see "the ruby-debug documentation":http://www.datanoise.com/articles/category/ruby-debug for details), then: # Deactivate the @DEBUG@ environment variable. # Put your own code, which initializes the debugger, at the top of your test's <tt>spec.rb</tt> file. <% end %> <% end %> - <% section "Test runner", "usage.test-runner" do %> + <% section "Test runner", "usage.runner" do %> A test runner is a file, generated by the <%= xref "usage.tools.generate", "automated test generator" %> whose name ends with <tt>.rake</tt>. It helps you run generated tests -- you can think of it as a _makefile_ if you are familiar with C programming in a UNIX environment. When you invoke a test runner without any arguments, it will show you a list of available tasks: - <pre>$ rake -f your_test_runner.rake + <pre>% rake -f your_test_runner.rake - <%= `rake -f ../samp/counter/RSpec/counter_runner.rake` %></pre> + <%= `rake -f ../examples/counter/RSpec/counter_runner.rake` %></pre> - <% section "Environment variables", "usage.test-runner.env-vars" do %> + <% section "Environment variables", "usage.runner.env-vars" do %> Test runners support the following _environment_ variables, which allow you to easily change the behavior of the test runner. + * @PROTOTYPE@ enables the Ruby prototype for the design under test so that the prototype, rather than the real Verilog design, is verified by the specification. * @COVERAGE@ enables code coverage analysis and generation of code coverage reports. + * @PROFILER@ enables the "ruby-prof":http://ruby-prof.rubyforge.org Ruby code profiler, which collects statistics on the runtime usage of the source code. This data allows you to identify performance bottlenecks. * @DEBUGGER@ enables the <%= xref "usage.debugger", "interactive debugger" %> in its "post-mortem debugging mode":http://www.datanoise.com/articles/2006/12/20/post-mortem-debugging. - * @PROTOTYPE@ enables the Ruby prototype for the design under test so that the prototype, rather than the real Verilog design, is verified by the specification. - To activate these variables, simply assign the number 1 to them. For example, @DEBUG=1@ activates the @DEBUG@ variable. + To activate these variables, simply assign the number 1 to them. For example, @DEBUGGER=1@ activates the @DEBUGGER@ variable. - To deactivate these variables, simply assign a different value to them or *unset* them in your shell. For example, both @DEBUG=0@ and @DEBUG=@ dectivate the @DEBUG@ variable. + To deactivate these variables, simply assign a different value to them or *unset* them in your shell. For example, both @DEBUGGER=0@ and @DEBUGGER=@ dectivate the @DEBUGGER@ variable. <% paragraph "Variables as command-line arguments" do %> - You can specify variable assignments as arguments to the *rake* command. For example, <pre>rake DEBUG=1</pre> is equivalent to + You can specify variable assignments as arguments to the *rake* command. For example, <pre>rake DEBUGGER=1</pre> is equivalent to <pre> - DEBUG=1 - export DEBUG + DEBUGGER=1 + export DEBUGGER rake </pre> in Bourne shell or <pre> - setenv DEBUG 1 + setenv DEBUGGER 1 rake </pre> in C shell. <% end %> @@ -476,12 +520,12 @@ 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 ("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. + <% section "Example tests", "usage.examples" do %> + The <tt>examples</tt> directory ("browse it online":<%= codeURL %>/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 %> <% 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. @@ -523,13 +567,13 @@ * xUnit represents <%= xref "glossary.TDD", "TDD" %> * our own format can represent another methodology In this tutorial, you will see how both RSpec and xUnit formats are used. So let us make separate directories for both formats to avoid generated tests from overwriting each other: <pre> - $ mkdir RSpec xUnit - $ cp counter.v RSpec - $ cp counter.v xUnit + mkdir RSpec xUnit + cp counter.v RSpec + cp counter.v xUnit </pre> Once we have decided how we want to implement our specification, we can proceed to generate a test for our design. This process is illustrated by <%= xref "fig:generate-test.RSpec" %> and <%= xref "fig:generate-test.xUnit" %>. <% example "Generating a test with specification in RSpec format", "fig:generate-test.RSpec" do %> @@ -569,15 +613,15 @@ * 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 %> - <code><%= File.read '../samp/counter/RSpec/counter_spec.rb' %></code> + <code><%= File.read '../examples/counter/RSpec/counter_spec.rb' %></code> <% end %> <% example "Specification implemented in xUnit format", "fig:xUnit/counter_spec.rb" do %> - <code><%= File.read '../samp/counter/xUnit/counter_spec.rb' %></code> + <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" %>. @@ -586,21 +630,21 @@ <% 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 %> - <code><%= File.read '../samp/counter/RSpec/counter_proto.rb' %></code> + <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 %> <% section "Verify the prototype", "usage.tutorial.test-proto" do %> Now that we have implemented our prototype, we are ready to verify it against our specification by running the 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 the value 1 while running the test so that, instead of our design, our prototype is verified against our specification (see <%= xref "usage.test-runner.env-vars" %> for details). Also, the <%= xref "setup.reqs", "GPL Cver simulator" %> denoted by _cver_, is used to run the simulation. + In these examples, the @PROTOTYPE@ environment variable is assigned the value 1 while running the test so that, instead of our design, our prototype is verified against our specification (see <%= xref "usage.runner.env-vars" %> for details). Also, the <%= xref "setup.reqs", "GPL Cver simulator" %> denoted by _cver_, is used to run the simulation. <% example "Running a test with specification in RSpec format", "fig:test-proto.RSpec" do %> <pre> $ cd RSpec $ rake cver PROTOTYPE=1 @@ -638,11 +682,11 @@ <% 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 %> - <code lang="verilog"><%= File.read '../samp/counter/counter.v' %></code> + <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 %> @@ -681,30 +725,38 @@ <% end %> <% end %> <% end %> <% chapter "Hacking", "hacking" do %> - <% section "Getting the source code", "hacking.scm" do %> + <% section "Getting the latest source code", "hacking.scm" do %> Check out the source code using "Darcs":http://darcs.net from the project repository: darcs get http://ruby-vpi.rubyforge.org/src/ruby-vpi <% end %> + <% section "Installing without really installing" do %> + After you've obtained the latest source code (see <%= xref "hacking.scm" %>), you can use it immediately without having to build or install a Ruby-VPI gem. To do this, 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>. Henceforth, any Ruby-VPI tests you run will use the checked-out source code directly. + <% 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: - * "SWIG":http://www.swig.org/ * "RedCloth":http://rubyforge.org/projects/redcloth/ * "CodeRay":http://rubyforge.org/projects/coderay/ Once you have satisfied these requirements, you can run <pre>rake release</pre> to build the release packages. Also, see the output of <pre>rake -T</pre> for more build options. <% end %> <% section "Editing this manual", "hacking.manual" do %> The "doc" files inside the <tt>doc/</tt> directory are really _plain text_ files that contain the source code of this manual. You can edit these files and run the <pre>rake</pre> command to automatically generate the HTML documentation you are currently viewing. + + In addition, the <tt>doc/README</tt> file says: <blockquote><%= File.read 'README' %></blockquote> <% end %> <% end %> <% chapter "Known problems", "problems" do %> This chapter presents known problems and possible solutions. @@ -755,25 +807,12 @@ endmodule </code> <% end %> <% end %> - <% section "Vpi::reset", "problems.ivl.vpi_reset" do %> + <% 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 %> - 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 %>