The Calyx Interactive Debugger
The Calyx Interactive Debugger is a prototype debugging tool built on top of the [Calyx Interpreter][interp] which exposes a gdb-like interface for debugging Calyx programs.
If you are using
fud getting started with the debugger is easy.
Assuming you are trying to debug a program called
my_program.futil with data
my_program.futil.data, invoke the debugger with the following command:
fud e --to debugger -q my_program.futil -s verilog.data my_program.futil.data
This will open the target program in the interactive debugger. Note that
uses the quiet flag,
-q, here. This prevents the printing from the
from conflicting the debugger as both tools interact with standard out.
Advancing Program execution
The simplest way to advance the program is via the
step command which causes
time to advance by a clock tick. It also has a shortcode:
> step > s
The above snippet advances the program by two steps.
Another way to advance the program is via the
step-over command. Unlike the
step command, this command requires a second argument which is the name of the
group to advance over. The
step-over command then advances the program until
the given group is no longer running.
If you want to use the command to advance the program past a group
> step-over group_1
Note that the
step-over command will do nothing if the given group is not
> step-over other_group Group is not running >
Finally, the continue command will run the program until either a breakpoint is
hit or the program terminates. This command is used in conjunction with
breakpoints and watchpoints to provide more targeted inspection. It may also be
accessed with the shortcode
> continue Main component has finished executing. Debugger is now in inspection mode.
CIDR supports breakpoints on group definitions. This helps focus attention on suspect portions of the code.
Setting a breakpoint
Breakpoints may be set on the main component by simple specifying the group of interest.
> break group_1
This is identical to
> break main::group_1
For sub-components, the name of the sub-component must be included with the
double colon separating the group name. To break on the
do_mul group inside
> break pow::do_mul
To see a list of breakpoints:
> info break
This produces output like this:
> ib Current breakpoints: 1. main::group_1 enabled 2. pow::do_mul enabled
All breakpoints have a number associated with them and they may be managed with this number or the group name.
To enable or disable a breakpoint:
> disable group_1 2 > enable 1 pow::do_mul
Note that this is equivalent to:
> disable group_1 > disable 2 > enable 1 > enable pow::do_mul
To delete a breakpoint:
> delete 1 > del pow::do_mul
Deleted breakpoints will be entirely removed while disabled breakpoints will
remain until they are either enabled again or subsequently deleted. Disabled
breakpoints will not cause program execution to halt when
The display command dumps the full state of the main component without
formatting. Use the
print-state commands for targeted inspection
CIDR supports several different formatting codes which do the hard work of interpreting the data in human readable ways.
|binary||The default, a bit vector with the msb on the left|
|unsigned||\u||Unsigned bit-num formatting|
|signed||\s||Two's Complement formatting|
|unsigned fixedpoint||\u.N||For N >=1. Unsigned Fixed-point with N fractional bits. The remaining bits are for the integral component.|
|signed fixedpoint||\s.N||For N >=1. Signed Fixed-point with N fractional bits. The remaining bits are for the integral component.|
These commands allow inspecting instance state with optional formatting. Note
that this is different from breakpoints which operate on definitions. For example to print the ports of the
std_mul instance named
mul in the
pow_1 attached to the main component:
> print main.pow_1.mul
as with breakpoints, the leading
main may be elided:
> print pow_1.mul
This will print all the ports attached to this multiplier instance with binary formatting.
Formatting codes may be supplied as the first argument.
> print \u pow_1.mul
> print \u pow_1.mul.out
print-state command works in the same way as the
contents may be viewed via:
> print-state main.out_mem
> print-state out_mem
print-state supports formatting codes as an optional first
argument. So to view the contents of
out_mem with a signed interpretation:
> print-state \s out_mem
Watchpoints are like breakpoints but rather than stop the execution when they
are passed, they instead print out some information. Like breakpoints, they are
set on group definitions, such as
The general form of watchpoints looks like
watch [POSITION] GROUP with PRINT-COMMAND
GROUPis the group definition to be watched
PRINT-COMMANDis a full
print-statecommand to be run by the watchpoint
POSITION argument may either be
specifies whether the watchpoint should run when the group first becomes active
before) or when the group finishes running (
after). This defaults to
before if not set.
Watchpoint management is similar to breakpoints. However there may be multiple watchpoints for a single group definition, so deleting watchpoints via the group name will delete all the watchpoints associated with the group. Watchpoints do not currently have an enable/disable state.
To view all the watchpoint definitions:
> info watch ... > iw
To delete watchpoints:
> delete-watch 1 > del-watch main::group_1
Viewing the program counter
where command (alias
pc) displays the currently running portion of the
control tree including active subcomponents. This can be used to more easily
determine the currently active portion of the design as well as visualize how
much of the execution is occurring in parallel at any given point.
Exiting the debugger
help to see all commands. Use
exit to exit the debugger.