From 06c819849f5df8b70173723d5eaaacf263e03922 Mon Sep 17 00:00:00 2001 From: Stephen Williams Date: Sun, 11 Dec 2022 12:12:24 -0800 Subject: [PATCH] vvp: Document the vvp interactive debug mode Vvp has an interactive debug mode that few seem to be aware of. Document that mode. --- Documentation/usage/index.rst | 1 + Documentation/usage/vvp_debug.rst | 148 ++++++++++++++++++++++++++++++ Documentation/usage/vvp_flags.rst | 5 + 3 files changed, 154 insertions(+) create mode 100644 Documentation/usage/vvp_debug.rst diff --git a/Documentation/usage/index.rst b/Documentation/usage/index.rst index e6a5eeda4..7ce70e403 100644 --- a/Documentation/usage/index.rst +++ b/Documentation/usage/index.rst @@ -16,6 +16,7 @@ Icarus Verilog. verilog_attributes vvp_flags gtkwave + vvp_debug vpi ivl_target reporting_issues diff --git a/Documentation/usage/vvp_debug.rst b/Documentation/usage/vvp_debug.rst new file mode 100644 index 000000000..450ad13d7 --- /dev/null +++ b/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. diff --git a/Documentation/usage/vvp_flags.rst b/Documentation/usage/vvp_flags.rst index f39f21b69..482aab064 100644 --- a/Documentation/usage/vvp_flags.rst +++ b/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