The metamodel debugger mgdb
is a wrapper around the Gnu
debugger, gdb
. It allows the user to run a SystemC
simulation of a metamodel in the debugger, and to set breakpoints
directly in the metamodel (.mmm
) source code, and to track
execution in that source code instead of the generated C++ code from
which the executable is compiled.
A graphical version mddd
uses ddd
, which is
itself a graphical wrapper
around gdb
.
An important limitation deserves mentioning early on: Because there is
not a one-to-one correspondence between lines of code in a
.mmm
file and in its corresponding .cpp
file,
the gdb
commands step
and next
will not work in any useful way. Instead, the user must stop execution
using breakpoints and the special commands provided by mgdb
.
mgdb
uses gdb
and several standard Unix utilities,
which all must be on the user's PATH. The programs that must be on the
user's PATH are
gdb
ddd
(for mddd
)
sh
sed
awk
sort
The user must have write access to the directory /tmp
, since
the program writes temporary files there.
To compile metamodel code to create a SystemC simulation, the user
ordinarily runs the script $METRO/bin/systemc
with the
source code file names as arguments. To compile for debugging, simply
add the command-line option, "-mmdebug" to the $METRO/bin/systemc
command, before the file names. For example:
$METRO/bin/systemc -mmdebug -top myPkg.myNetlist Foo.mmm Blah.mmmThis adds extra information to the generated C++ code, including "
#line
"
preprocessor directives that relate each executable C++ code line to a
line in the corresponding metamodel (.mmm
) file.
To run the debugger, execute the command:
$METRO/bin/mgdb run.xor
$METRO/bin/mddd run.xwhere
run.x
is the name of the executable file generated by
$METRO/bin/systemc
.
Running either command with an initial argument of -h
displays a simple usage message and quits.
The first source file to be shown by the list
command (or in
the source code window under mddd
) on startup will not be a
metamodel source file, but some underlying C++ code. To display a
.mmm
file of interest, use the list
command
with an argument of the file name and a line number. For example:
> list architecture.mmm:1Breakpoints can be set in the currently listed file using just the line number:
> break 10or in another file by preceding the line number with the file name and a colon:
> break behavior.mmm:7
The debugger accepts all of gdb
's command-line options, although
many of them don't make sense for debugging metamodel code. The
-x init_file
option can be useful for automatically
executing a stored set of commands on startup.
If the file mgdb.ini
exists in the user's current directory
on startup, and is readable, that file will be assumed to contain startup
commands and will automatically be executed before any other files listed
with -x
options.
Because mgdb
uses gdb
's logging feature to gather
information that it needs into temporary files, the user cannot use
gdb
's logging features to save or redirect output.
See the description of the delog
command, below. If you find
that your commands produce no output, try the delog
command to
restore normal function.
The gdb
commands "next
" and "step
"
do not work in any useful way, since they execute the next command in the
.cpp
code, which may have little to do with the next command
in the .mmm
code. The only reliable way to know where one
is in the .mmm
source code is to set a breakpoint and use
"continue
" (or "run
" to start the program from
the beginning).
The following are special commands provided by mgdb
:
pnext
will stop when the thread of execution
changes from one process to another, just before the first metamodel
statement to be executed by the newly swapped-in process.
pname
will echo the name of the current process thread.
mwhere
will list the metamodel file names and
line numbers where each process is currently stopped, along with other
status information about each process.
mgdb
commands execute gdb
commands to
gather information, or to set or clear breakpoints. These internally-used
gdb
commands produce copious output which is of no interest
to the user, and so mgdb
uses logging commands to hide
it from the user.
If a segmentation fault or bus error should occur while output is hidden, it will continue to be hidden, which can be very confusing to the user. (If a where command produces no output, this is what has happened.)
The command delog
displays the most recently hidden output
and stops hiding it.