Debugger

Detailed Description

The debugger supports two methods of interrupting the simulation.

Breakpoints halt the simulator and start the debugger whenever a situation arises that matches the breakpoint criterion. For example, a breakpoint on the bottom-up pass will stop the simulation every time an object sync is called during a bottom-up pass.

Watchpoints are different from breakpoints in that the debugger is only stopped when the value being watched changes. For example, a breakpoint on node:12 voltage would only stop the simulation when that value is changed. In contrast, a breakpoint on node:12 would stop each time node:12 is sync'd.

While the debugger is running help will print a list of all the available commands.

Getting started

To start the debugger you must include the --debug option on the command-line. Note that while the debugger is running, the system will only operate in single-threaded mode.

Each time the debugger stops to prompt for input, it displays the current simulation time and simulator status. The status include which pass is currently running (see PASSCONFIG), which rank is being processed, which object is about to be updated, and which iteration is being run (if the time has not advanced yet).

	DEBUG: time 2000-01-01 00:00:00 PST
	DEBUG: pass BOTTOMUP, rank 0, object link:14, iteration 1
	GLD>

Debugging commands may be abbreviated to the extent that they are unambiguous. For example b may be used instead of break, but wa must be used for watch to distinguish it from where.

Listing objects

To obtain a list of objects loaded, you may use the list command:

	GLD> list
	A-b---    2 INIT                     node:0           ROOT
	A-b---    1 INIT                     node:1           node:0
	A-b---    1 INIT                     node:2           node:0
	A-b---    1 INIT                     node:3           node:0
	A-b---    0 INIT                     link:4           node:1
	A-b---    0 INIT                     link:5           node:2
	A-b---    0 INIT                     link:6           node:2
	A-b---    0 INIT                     link:7           node:3
	A-b---    0 INIT                     link:8           node:3	
	GLD>

You may limit the list to only the object of a particular class:

	GLD> list node
	A-b---    2 INIT                     node:0           ROOT
	A-b---    1 INIT                     node:1           node:0
	A-b---    1 INIT                     node:2           node:0
	A-b---    1 INIT                     node:3           node:0
	GLD>

The first column contains flags indicating the status of the object. In the first character:

The second field is the object's rank.

The third field is the object's internal clock (or INIT) if the object has not yet been sync'd.

The fourth field is the name (class:id) of the object.

The fifth field is the name of the object's parent (or ROOT) if is has none.

debug_print

To inspect the properties of an object, you can use the print command. With no option, the current object is printed:

	GLD> print
	DEBUG: object link:5 {
			parent = node:2
			rank = 0;
			clock = 0 (0);
			complex Y = +10-1j;
			complex I = +0+0j;
			double B = +0;
			object from = node:0;
			object to = node:2;
	}
	GLD>

When an object name (class:id) is provided, that object is printed:

	GLD> print node:0
	DEBUG: object node:0 {
			root object
			rank = 2;
			clock = 0 (0);
			latitude = 49N12'34.0";
			longitude = 121W15'48.3";
			complex V = +1-0d;
			complex S = +0+0j;
			double G = +0;
			double B = +0;
			double Qmax_MVAR = +0;
			double Qmin_MVAR = +0;
			enumeration type = 3;
			int16 bus_id = 0;
			char32 name = Feeder;
			int16 flow_area_num = 1;
			complex Vobs = +0+0d;
			double Vstdev = +0;
	}
	GLD>

Scripting commands

You can run a script containing debug commands using the script command:

	GLD> sys copy con: test.scr
	wa node:0
	run
	^Z
			1 file(s) copied.
	GLD> script test.scr
	DEBUG: resuming simulation, Ctrl-C interrupts
	DEBUG: watchpoint 0 stopped on object node:0
	DEBUG: object node:0 {
			root object
			rank = 2;
			clock = 2000-01-01 00:00:00 PST (946713600);
			latitude = 49N12'34.0";
			longitude = 121W15'48.3";
			complex V = +1-0d;
			complex S = +0.522519+0.0522519j;
			double G = +0;
			double B = +0;
			double Qmax_MVAR = +0;
			double Qmin_MVAR = +0;
			enumeration type = 3;
			int16 bus_id = 0;
			char32 name = Feeder;
			int16 flow_area_num = 1;
			complex Vobs = +0+0d;
			double Vstdev = +0;
	}

	DEBUG: watchpoint 1 stopped on object node:0
	DEBUG: object node:0 {
			root object
			rank = 2;
			clock = 2000-01-01 00:00:00 PST (946713600);
			latitude = 49N12'34.0";
			longitude = 121W15'48.3";
			complex V = +1-0d;
			complex S = +0.522519+0.0522519j;
			double G = +0;
			double B = +0;
			double Qmax_MVAR = +0;
			double Qmin_MVAR = +0;
			enumeration type = 3;
			int16 bus_id = 0;
			char32 name = Feeder;
			int16 flow_area_num = 1;
			complex Vobs = +0+0d;
			double Vstdev = +0;
	}

	DEBUG: time 2000-01-01 00:00:00 PST
	DEBUG: pass BOTTOMUP, rank 2, object node:0, iteration 5
	GLD>
strsignal


Typedefs

typedef struct s_breakpoint BREAKPOINT
 the structure for a breakpoint entry
typedef struct s_watchpoint WATCHPOINT
 the structure for a watchpoint entry

Functions

int exec_debug (struct sync_data *data, int pass, int index, OBJECT *obj)
 This is the main debugger processing loop.
DEBUGCMD exec_debug_cmd (struct sync_data *data, int pass, int index, OBJECT *obj)
 flag whether commands are being read from a script file (see load_fp)
void exec_sighandler (int sig)
 The exec_sighandler() function is called whenever a SIGINT signal is caught by the main application.

Variables

FILE * load_fp
 the file from which commands are read (see script)
int stop_now = 0
 flag indicating that main loop needs to be step (and debugger activated if allowed)

Function Documentation

int exec_debug ( struct sync_data *  data,
int  pass,
int  index,
OBJECT *  obj 
)

This is the main debugger processing loop.

Parameters:
data  the current sync status of the mail loop
pass  the current pass on the main loop
index  the rank index
obj  the current object being processed

Definition at line 1273 of file debug.c.

References convert_from_timestamp(), exec_debug_cmd(), FMT_INT64, int64, object_dump(), object_name(), object_sync(), output_debug(), output_error(), output_raw(), and output_verbose().

Referenced by exec_start().

DEBUGCMD exec_debug_cmd ( struct sync_data *  data,
int  pass,
int  index,
OBJECT *  obj 
)

flag whether commands are being read from a script file (see load_fp)

The function executes the next debug command provided by the user or read from a file

Parameters:
data  the current sync status of the mail loop
pass  the current pass on the main loop
index  the rank index
obj  the current object being processed

Definition at line 483 of file debug.c.

References class_get_class_from_classname(), convert_from_timestamp(), convert_to_object(), convert_to_timestamp(), exec_sighandler(), find_first(), find_next(), find_objects(), FMT_INT64, global_getnext(), global_getvar(), global_setvar(), int64, max, module_load(), object_dump(), object_find_name(), object_get_first(), object_get_property(), object_namespace(), object_select_namespace(), object_set_value_by_name(), output_debug(), output_error(), output_message(), output_verbose(), PC_BOTTOMUP, PC_POSTTOPDOWN, PC_PRETOPDOWN, and strnicmp.

Referenced by exec_debug().

void exec_sighandler ( int  sig  ) 

The exec_sighandler() function is called whenever a SIGINT signal is caught by the main application.

When global_debug_mode is 0, this causes the main simulation loop to halt. When global_debug_mode is non-zero, it causes the debugger to be activated before the beginning of the next sync call is made.

Parameters:
sig  the signal number, see <signal.h>

Definition at line 281 of file debug.c.

References output_debug(), and output_error().

Referenced by exec_debug_cmd(), and exec_start().

GridLAB-DTM Version 2.0
An open-source project initiated by the US Department of Energy