mgdb -- The Metamodel Debugger

  1. CONTENTS

    1. Introduction
    2. Requirements
    3. Compiling the metamodel for debugging
    4. Running the debugger
      1. Limitations, caveats
    5. Debugger commands
      1. pnext
      2. pname
      3. mwhere
      4. delog
  2. INTRODUCTION

    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.

  3. REQUIREMENTS

    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

    The user must have write access to the directory /tmp, since the program writes temporary files there.

  4. COMPILING THE METAMODEL FOR DEBUGGING

    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.mmm
    
    This 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.

  5. RUNNING THE DEBUGGER

    To run the debugger, execute the command:

            $METRO/bin/mgdb run.x
    
    or
            $METRO/bin/mddd run.x
    
    where 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:1
    
    Breakpoints can be set in the currently listed file using just the line number:
        > break 10
    
    or 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.

  6. LIMITATIONS and CAVEATS

    No logging

    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.

    Disappearing 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.

  7. DEBUGGER COMMANDS

    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
    The command 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
    The command pname will echo the name of the current process thread.
    mwhere
    The command mwhere will list the metamodel file names and line numbers where each process is currently stopped, along with other status information about each process.
    delog
    Most 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.