| Chapter 15. Debugging | ||
|---|---|---|
 | Part III. Command-line Usage |  |
Table of Contents
As much as it pains the developers of Covered to admit, there will be times when a user of Covered will encounter a problem in the resimulation process or will experience a performance issue during certain runs and will want to investigate the issue a bit themselves before posting a bug report. There may also be people out there who just might want to learn more about how Covered operates "under the hood". For those people whom I have just mentioned, this section is for you.
The brute force method of understanding Covered's internals is to generate verbose debug output using the global "-D" option to any of Covered's commands. The user of this method should take care to note that using this option may generate an extremely large amount of output and will definitely cause Covered's runtime performance to degrade considerably. If this option is used, its output should probably be redirected to a file for post-processing purposes. It should be noted that the verbose debug output is most useful for the developer's of Covered and is not meant to be of much help to the normal user.
Because generating verbose debug output can have a tremendous degradation in performance when it is even compiled,
Covered requires the user to specify an option to the configuration/build process to enable this feature. To enable
verbose debug outputting, simply specify the --enable-debug option to the configure
script. This will cause Covered to compile in verbose debug output support and enable the use of the -D global option.
![[Note]](img/note.gif) | Note |
|---|---|
If the user has not specified the --enable-debug option to the configuration script but proceeds to specify the -D global option, Covered will emit a warning message that it is unable to output verbose debug information due to the lack of the --enable-debug option being specified. It will then proceed to ignore the -D option. |
As an alternative to simply outputting the verbose debug output from Covered, the score command comes equipped with its own interactive debugging mechanism called the CLI (Command-Line Interface). This interface is a command-line driven utility that starts at the beginning of the resimulation. Its purpose is to allow the user to step through simulation execution and view the contents of signals, time, scopes, code and internal thread queues for the purposes of debugging and/or understanding Covered. This utility works much in the same way as simulator CLIs and the GDB debugging utility.
Because interactive command-line debugging has a small performance penalty when compiled in and is closely associated with
the verbose debug output option, Covered requires the user to specify an option to the configuation/build process to enable
this feature. To enable the CLI, simply specify the --enable-debug option to the configure
script. This will cause Covered to compile in CLI capabilities and enable the user of the -cli score command option.
To allow the score command to use the CLI for interactive resimulation, simply specify the
-cli [filename] option to the score command. If filename is
specified to this option, the contents of this file will be parsed and executed once the score command has reached the
resimulation process. The contents of this file are a series of CLI commands (one command per line) in ASCII format and can be
automatically produced with the "savehist" CLI command (see below). This feature allows a user to quickly save off
the CLI commands made during one score run and reuse them in a subsequent score run without having to remember and manually input
the same commands.
Once the -cli option is invoked, Covered will run the score command until it gets to the beginning of the resimulation process. At this time, if the optional filename is specified, it will parse the contents of this file and execute the CLI commands found there until all commands are executed. If filename was not specified, a prompt will be displayed and the resimulation execution will halt until the user has specified otherwise via command-line options. After entering a command-line option, simply press return to invoke that command. In the event that the command was a step, next or continue option, resimulation will resume until it reaches the next stop point.
During resimulation, if the -cli option is specified to the score command, the user may stop simulation at any time by hitting Ctrl-C. This will stop the simulation and display a CLI prompt where the user may continue to interact with the simulation.
The following is a list of all of the CLI options available to the user:
Table 15.1. CLI Command-line Options
| Option | Description |
|---|---|
| step [num] | Advances to the next statement if num is not specified; otherwise, advances num statements before returning to the CLI prompt. |
| next [num] | Advances to the next timestep if num is not specified; otherwise, advances num timesteps before returning to the CLI prompt. |
| goto time num | Simulates to the given timestep (or the next timestep after the given value if the timestep is not executed) specified by num. |
| goto line [filename:]num | Simulates until the specified line is the next line to be executed. If filename is specified, the line specified by num within that file is the line to stop on. If filename if not specified, the current filename is used. |
| goto expr name bool_op value | Simulates until the given expression is evaluated to true where name is the name of a signal in the design to evaluate, bool_op is a boolean operation (i.e., ==, !=, ===, !==, <, <=, >, >=), and value is a legal Verilog value (i.e., 30, 4'h0, etc.). |
| run | Runs the simulation to completion. |
| continue | Continues running the simulation to completion. |
| thread active | Displays the current state of the internal active simulation queue. This queue consists of process threads that will be executed in the current timestep. |
| thread delayed | Displays the current state of the internal delayed simulation queue. This queue consists of process threads that will be executed at a later time as dictated by a delay statement. |
| thread waiting | Displays the current state of the internal waiting simulation queue. This queue consists of process threads that are not active or delayed but may be activated by a value change in one of the signals in its expression tree. |
| thread all | Displays the current state of all process threads in the simulator. |
| current | Displays the current scope, block, filename and line number of the statement that is about to be executed in the active queue. |
| time | Displays the current simulation time. |
| signal name | Displays the current value of the given net/variable. |
| expr num | Displays the given expression and its current value where num is the ID of the expression to output. |
| debug [less | more | off] | Specifies the amount of debug information that is output during simulation. The value of 'less' only outputs the current statement that is being executed (along with line number). The value of 'more' outputs verbose output that is really only useful for the developer's of Covered. The value of 'off' turns off all debug output during simulation. If 'less', 'more', or 'off' is not specified, displays the current debug mode. |
| list [num] | Lists the contents of the file where the current statement is to be executed. If num is specified, outputs the given number of lines; otherwise, outputs 10 lines. |
| savehist filename | Saves the current history to the specified file. |
| history [(num | all)] | Displays the last 10 lines of command-line history. If 'all' is specified, the entire history contents will be displayed. If num is specified, the last num commands will be displayed. |
| !num | Executes the command at the num position in history. |
| !! | Executes the last valid command. |
| help | Displays the available command-line options. |
| quit | Ends simulation immediately. |
The built-in source code profiling facility allows the user to run any Covered command and understand performance metrics about the internal Covered source code, such as how many times a given function was called, how much wall-clock time was spent executing a given function, how many times a function allocated and deallocated memory from the heap, etc. This information can be useful in understanding where performance bottlenecks are during a given Covered command run. This feature does not provide the end-user any useful information about the design that they are testing.
Because internal source code profiling is not a function of obtaining Verilog code coverage and adds a performance
penalty for being compiled in and used, Covered requires the user to specify an option to the configuration/build
process to enable this feature. To enable internal source code profiling, simply specify the
--enable-profiling option to the configure script. This will cause Covered to
compile in profiling capabilities and enable the use of the -P global option.
| Note |
|---|---|
If the user has not specified the --enable-profiling option to the configuration script but proceeds to specify the -P global option, Covered will emit a warning message that it is unable to do profiling due to the lack of the --enable-profiling option being specified. It will then proceed to ignore the -P option. |
Once Covered has had profiling functionality configured and built into it, the user may optionally enable profiling for any
command by specifying the -P [filename] global option. If
the -P option is specified without a filename associated with it, the profiling report generated from the command run will
be output to a file called "covered.prof" in the same directory where Covered was run. If a filename is associated with the
-P option, the contents of the profiling report will be output to that file.
| Note |
|---|---|
The specified filename can be anything except "score", "merge" or "report" as this name will be interpreted by Covered's command-line parser to indicate the type of command being run. If one of these command keywords are specified after the -P option, it is assumed that the user has not specified a filename and the contents of the profiling report will be sent to the default file of "covered.prof". |
After a command has been run with the global -P option specified, a report file will contain several profiling statistics, including the following:
The amount of time spent running the entire command
The number of times each executed function was called
The total amount of wall clock time spent executing each function
The average amount of time spent executing each function
The number of times each function allocated heap memory
The number of times each function deallocated heap memory
In addition to providing this information on a per function basis, the profiling report also provides the information in three different sections with each function ordered from most to least by the following statistic columns:
The number of times each executed function was called
The total amount of wall clock time spent executing each function
The average amount of time spent executing each function
By ordering this information, it will help the users and developers determine where the performance bottlenecks in execution are for a given command run.
| |  | |
| Chapter 14. Reading the Report |  | Part IV. Graphical User Interface |