Merge pull request #803 from steveicarus/steveicarus/document-vvp-debugmode

vvp: Document the vvp interactive debug mode

Documentation/usage/index.rst

@@ -16,6 +16,7 @@ Icarus Verilog.
    verilog_attributes
    vvp_flags
    gtkwave
+   vvp_debug
    vpi
    ivl_target
    reporting_issues

Documentation/usage/vvp_debug.rst

@@ -0,0 +1,148 @@
+Vvp Interactive Mode
+====================
+
+The vvp command has an interactive debug mode, where you can stop the
+simulation and browse the current state of the simulation. There are
+a couple ways to enter the debug mode, but once in interactive debug
+mode, the usage is the same. Consider the example below:
+
+.. code-block:: verilog
+
+  module clock(output reg clock);
+    initial clock = 1'b1;
+    always #100 clock = !clock;
+  endmodule // clock
+
+  module main;
+
+    reg [2:0] foo;
+    wire	     clk;
+
+    clock foo_clock(clk);
+
+    always @(posedge clk)
+      foo <= foo + 1;
+
+    initial begin
+       foo = 3'b000;
+      #250 $stop;
+    end
+
+  endmodule
+
+In examples that follow, we will use the above sample program.
+
+Enter Interactive Mode
+----------------------
+
+The first and most common method is to put "$stop" system task
+calls in the simulation at the times where you want to simulation
+to break and enter interactive mode. The example above has a $stop,
+so the output looks like this::
+
+  ../foo.vl:25: $stop called at 250 (1s)
+  ** VVP Stop(0) **
+  ** Flushing output streams.
+  ** Current simulation time is 250 ticks.
+  >
+
+You can get some interactive help by using the "help" command::
+
+  > help
+  Commands can be from the following table of base commands,
+  or can be invocations of system tasks/functions.
+
+  cd       - Synonym for push.
+  cont     - Resume (continue) the simulation
+  finish   - Finish the simulation.
+  help     - Get help.
+  list     - List items in the current scope.
+  load     - Load a VPI module, a la vvp -m.
+  ls       - Shorthand for "list".
+  pop      - Pop one scope from the scope stack.
+  push     - Descend into the named scope.
+  step     - Single-step the scheduler for 1 event.
+  time     - Print the current simulation time.
+  trace    - Control statement tracing (on/off) when the code is instrumented.
+  where    - Show current scope, and scope hierarchy stack.
+
+  If the command name starts with a '$' character, it
+  is taken to be the name of a system task, and a call is
+  built up and executed. For example, "$display foo" will
+  call the function as $display(foo).
+
+You can also enter interactive mode at the terminal by interrupting the
+execution with a "^C" (Control-C) character. The vvp engine catches the
+terminal interrupt and drops you into the interactive prompt::
+
+  ^C** VVP Stop(0) **
+  ** Flushing output streams.
+  ** Current simulation time is 533928600 ticks.
+  > 
+
+This could be useful if you suspect that your simulation is stuck in
+an infinite loop and you want to rummage around and see what's going on.
+
+And finally, you can pass the "-s" command line flag to vvp to tell it
+to execute "$stop" at the beginning of the simulation, before any other
+events are executed. This may be useful as a way to manually set up some
+details about the simulation.
+
+Browsing the Design
+-------------------
+
+Now that you are in the interactive prompt, you can browse
+around the design::
+
+  > ls
+  2 items in this scope:
+  package : $unit
+  module  : main
+  > cd main
+  > ls
+  3 items in this scope:
+  reg     : foo[2:0]
+  module  : foo_clock
+  net     : clk
+  > where
+  module main
+  > $display foo
+  1
+  > cd foo_clock
+  > where
+  module foo_clock
+  module main
+  > ls
+  2 items in this scope:
+  port    : clock -- output
+  reg     : clock
+
+In the above example, the 'cd' and 'pop' commands descend into a scope
+or pop back up a scope level. The 'where' command shows the scope stack,
+and the 'ls' command lists the items present in the scope. With these
+commands, one can browse freely throughout the design scope hierarchy.
+
+It is also possible to call system tasks within the debug mode. The call
+to the "$display" function is an example of this. In general, any system
+task can be invoked, in the current context, with the objects that are
+included on the command line passed as arguments. The arguments can be
+variables or nets, and various kinds of literals::
+
+  > ls
+  2 items in this scope:
+  port    : clock -- output
+  reg     : clock
+  > $display "Hello, World! " 10 " " clock
+  Hello, World!          10 1
+
+This is a great way to call custom system tasks as well. And system task
+that vvp knows about can be invoked this way.
+
+Leave Interactive Mode
+----------------------
+
+After you are done probing around in the interactive mode, you can
+resume the simulation, or termimate execution. Resume the simulation
+with the "cont" command, and terminate the simulation with the
+"finish" command. The latter is the same as executing the
+"$finish" system task.

Documentation/usage/vvp_flags.rst

@@ -41,6 +41,11 @@ simulation.
   determine the return types of user-defined system functions. If specified at
   compile-time, there is no need to specify them again here.
 
+* -s
+
+  $stop right away, in the beginning of the simulation. This kicks the
+  vvp program into interactive debug mode.
+
 * -v
 
   Show verbose progress while setting up or cleaning up the runtime