This section shows you how to start working with gdb as well as some of its most frequently used commands.

This page shows you the basic commands that you can use in gdb. When this page will help you to break the ice, this is no way a complete reference text for gdb. If you want to know more about it, please refer to the original manual by Richard M. Stallman and Roland H. Pesch.

gdb can be used to do mainly four different things. We will see each of them with examples.

1. gdb can start your program.
   To load an executable (say, simv) under gdb, all that you need to do is to give this command:
   $ gdb simv
(gdb)
   Once you are within gdb, as indicated by the (gdb) prompt, you can type other gdb commands.
   If you have a core file, you can load that too:
   $ gdb simv core
   Remember that, this will only load your executable under gdb - it will not run it. To run your executable, you should give the following command:
   $ gdb simv
(gdb)run +plusarg1 +plusarg2
where "+plusarg1" , "+plusarg2" etc. are examples of command line arguments that you would have used with simv.
2. gdb can stop your program on certain conditions that you specify.
   To stop your program at certain point, you must set up a "breakpoint". You do that by using the gdb command break.
   (gdb) break
break, without any other argument as above, sets a breakpoint on the next executable line. If you want to set a breakpoint in some other place, try one of the followings:
   (gdb) break function_name
(gdb) break file_name:function_name
(gdb) break line_number
(gdb) break file_name:line_number
   For example,
   (gdb) break "veriuser.c":45
   stops your program at the 45th line (or the next executable line) of the file "veriuser.c".
   You can even set a conditional breakpoint:
   (gdb) break "veriuser.c":45 if (i!=-5)
   Once you stop at a breakpoint, in order to continue again, you must give the c (continue) command:
   (gdb) c
   If you would rather like to step through your program, there are two commands: next executes the next program line stepping over any function calls in the line, whereas step executes the next program line stepping into any function calls in the line.
   (gdb) next
(gdb) step
   You can remove all breakpoints from a program by issuing d (delete) command:
   (gdb) d
   Or, if you want, you can remove any particular breakpoint by using the clear command. Its format is very similar to break itself. The following command clears the breakpoint at line 45 of the file veriuser.c.
   (gdb) clear "veriuser.c":45
3. gdb can help you to analyze what has happened inside the program when it has stopped.
   Once you reach a breakpoint, the next step is to examine some of the variables that you think might be behaving wrongly.You can check their values by giving a p (print) command. The following example checks the value of the variable i.
   (gdb) p i
   It is possible to print variable in a different file or function:
   (gdb) p "veriuser.c"::i
(gdb) p my_misctf::i
4. gdb allows you to change values of variables etc. in your program on the fly.
   Say, for example, that you find the value of i as 5, when you know it should have been -5. You can over-write the current value of i by the command set:
   (gdb) set i=-5

Once you are done, you can exit gdb by using the quit command.
(gdb) quit
gdb provides a nicely organized help menu:
(gdb) help

What about NC ?

You will need to run the debugger on the simulator executable, not on the ncverilog/ncxlmode wrapper. That means either using NC in "classic mode" (i.e. ncvlog/ncelab/ncsim) or attaching the debugger to the simulator process after the wrapper has started it (perhaps running the simulator in interactive mode to get it to stop while you obtain the process id for connecting to it).

If you are statically linking your PLI, you will obviously need to debug the statically linked executable. If you are dynamically linking the PLI, you may have to set the library path and make sure that the debugger does not reset it on you (e.g. it might execute your .cshrc)

You will need to tell the debugger to ignore SIGBUS. NC uses it internally in situations that are not errors and you don't want the simulator to stop and tell you about it. In dbx the command is "ignore SIGBUS". In gdb, it is "handle SIGBUS nostop noprint pass". Do not use the -REDMEM option to ncsim, since it causes ncsim to use SIGSEGV internally also.

You can then debug the testcase normally. You may see some unnamed routines in the stack traceback, which are the code generated from NC.