Debugger
[GridLAB-D Core]

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


Defines

#define _MAX_PATH   PATH_MAX

Typedefs

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

Enumerations

enum  BREAKPOINTTYPE {
  BP_MODULE, BP_CLASS, BP_OBJECT, BP_PASS,
  BP_RANK, BP_TIME, BP_CLOCK, BP_ERROR
}
enum  DEBUGCMD { DBG_QUIT, DBG_RUN, DBG_NEXT }

Functions

void debug_notify_error (void)
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)
 The function executes the next debug command provided by the user or read from a file.
void exec_sigint (int sig)
 The exec_sigint() function is called whenever a SIGINT signal is caught by the main application.

Variables

int iteration_counter
FILE * load_fp
 the file from which commands are read (see script)
int load_from_file = 0
const PASSCONFIG passtype []
int siglist [] = {SIGINT, SIGFPE, SIGSEGV}
int stop_now = 0
 flag indicating the the debugger needs to be activated

Enumeration Type Documentation

enum BREAKPOINTTYPE

Enumerator:
BP_MODULE 
BP_CLASS 
BP_OBJECT 
BP_PASS 
BP_RANK 
BP_TIME 
BP_CLOCK 
BP_ERROR 

Definition at line 304 of file debug.c.

enum DEBUGCMD

Enumerator:
DBG_QUIT 
DBG_RUN 
DBG_NEXT 

Definition at line 303 of file debug.c.

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 917 of file debug.c.

References convert_from_timestamp(), FMT_INT64, s_object_list::name, object_dump(), object_property_to_string(), output_debug(), and output_raw().

Referenced by exec_start().

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

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 393 of file debug.c.

References _MAX_PATH, BP_CLASS, BP_CLOCK, BP_ERROR, BP_MODULE, BP_OBJECT, BP_PASS, BP_RANK, BP_TIME, class_get_class_from_classname(), s_object_list::clock, convert_from_object(), convert_from_timestamp(), convert_to_object(), convert_to_timestamp(), DBG_NEXT, DBG_QUIT, DBG_RUN, debug_notify_error(), exec_sigint(), s_object_list::flags, FMT_INT64, int64, iteration_counter, max, module_find(), s_object_list::name, s_class_list::name, s_object_list::next, notify_error, object_find_name(), object_get_first(), s_object_list::oclass, OF_HASPLC, OF_LOCKED, output_debug(), output_error(), output_message(), output_notify_error(), output_verbose(), s_object_list::parent, s_class_list::passconfig, passtype, PC_BOTTOMUP, PC_POSTTOPDOWN, PC_PRETOPDOWN, s_object_list::rank, siglist, strnicmp, and TS_NEVER.

void exec_sigint ( int  sig  ) 

The exec_sigint() 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 activited before the beginning of the next sync call is made.

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

Definition at line 264 of file debug.c.

References output_debug(), and output_error().

Referenced by exec_debug_cmd(), and exec_start().

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