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:

   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.
