[m-dev.] for review: new debugger command set (part 1 of 4)

[Tyson Dowd]

On 01-Oct-1998, Zoltan Somogyi <zs at cs.mu.OZ.AU> wrote:
> 
> Estimated hours taken: 220
> 
> This checkin has several major purposes, set out in the sections below,
> all connected with the implementation of the new debugger command set.
> 
> DOCUMENT NEW DEBUG COMMAND SET
> 
> doc/user_guide.texi:
> 	Add a new section on the debugger. The description of the commands
> 	is complete, but some of the background sections, and the section
> 	about how to build debuggable executables, are not yet done.
> 
> 	Update the documentation of the tracing options.
> 
> doc/generate_mdb_doc:
> 	A new shell script that automatically converts some of the new
> 	sections of the user guide into the online documentation of the
> 	debugger.
> 
> doc/mdb_categories:
> 	The fixed initial part of the online documentation.
> 
> doc/mdbrc.in:
> 	A debugger command script that reads in the online documentation
> 	and then defines some standard aliases.
> 
> doc/Mmakefile:
> 	Add rules for creating mdb_doc, the file that is the online
> 	documentation of the debugger, and for installing it together
> 	with mdbrc.
> 
> Mmake.common.in:
> 	Define INSTALL_DOC_DIR for doc/Mmakefile.
> 
> configure.in:
> 	Define the variable that scripts/mdb.in and doc/mdbrc.in use to find
> 	the right files, and get configure to perform the substitutions.
> 
> configure.in:
> scripts/mdb:
> scripts/mdb.in:
> 	Replace mdb with mdb.in. Mdb is now created during configuration
> 	from mdb.in, filling in the name of the file that contains the default
> 	debugger initialization commands.
> 
> util/info_to_mdb.c:
> 	A program that does most of the work involved in automatically
> 	converting user guide sections into online documentation.
> 	(This couldn't easily be written in sh, because sh's read
> 	command has no notion of pushback.)
> 
> util/Mmakefile:
> 	Add info_to_mdb to the list of targets.
> 
> tools/bootcheck:
> 	Make sure that the tests in tests/debugger are executed with an
> 	initialization setup that is equivalent to what users will see
> 	by default.
> 
> REORGANIZE TRACING OPTIONS
> 
> compiler/globals.m:
> compiler/handle_options.m:
> compiler/options.m:
> compiler/trace.m:
> 	Reorganize the handling of trace levels around the new options
> 	--trace-internal, --trace-redo, and --trace-return.
> 
> compiler/*.m:
> 	Use the new ways of getting at trace levels.
> 
> SUPPORT RETRY
> 
> compiler/trace.m:
> 	After every call to MR_trace(), emit code that checks whether it
> 	should jump away, and if yes, performs the jump. This is used to
> 	implement retry. (The debugger cannot execute the jump itself
> 	because it is in the wrong C stack frame.)
> 
> compiler/llds.m:
> compiler/continuation_info.m:
> compiler/stack_layout.m:
> 	Modify the data structures that record information about live
> 	value at program points, to record the identity of each variable.
> 	This is necessary for the implementation of the restart command,
> 	since we do not want to confuse two distinct variables just because
> 	they have the same name. For example, a variable whose name is X
> 	and number is 5 is now recorded in the name array as "5:X".
> 
> 	Clean up the data structure a bit, so that we don't have to store
> 	dummy names for values that are not variables.
> 
> compiler/*.m:
> 	Minor changes to conform to the data structure changes.
> 
> runtime/mercury_stack_layout.h:
> 	Redefine an existing macro to strip away the initial number: prefix
> 	from the "name" of a variable (keeping its original function on
> 	changed data), and add a new one to access the raw unstripped data.
> 
> runtime/mercury_init.h:
> runtime/mercury_wrapper.h:
> 	Update the prototype of MR_trace_{fake,real}, and the type of the
> 	global that points to them.
> 
> USE FIXED STACK SLOTS FOR TRACE INFO
> 
> compiler/code_gen.m:
> compiler/code_info.m:
> compiler/live_vars.m:
> compiler/trace.m:
> 	If execution tracing is enabled, reserve the first few stack slots
> 	to hold the event number of the call event, the call number, the
> 	call depth, the redo layout structure address (if generating redo
> 	events) and the from_full flag at the time of call (if we are doing
> 	shallow tracing). By allocating the first four of these to fixed stack
> 	slots, the debugger knows where to look for them without having
> 	to be told. It finds out the location of the fifth, if needed,
> 	from a new slot in the proc layout structure. (It is not possible
> 	to allocate all five to fixed stack slots without wasting stack space
> 	in some cases.)
> 
> compiler/trace.m:
> 	Remove from the call to MR_trace the parameters that are now in fixed
> 	stack slots, since MR_trace can now look them up itself.
> 
> compiler/continuation_info.m:
> compiler/stack_layout.m:
> 	Add an extra field to the proc_layout_info. If the module is shallow
> 	traced, this field says which stack slot holds the saved value of
> 	MR_from_full. If it is not shallow traced, this field says that
> 	there is no such stack slot.
> 
> runtime/mercury_stack_layout.h:
> 	Add macros for accessing the fixed stack slots holding the event
> 	number of the call event, the call number, the call depth, and,
> 	at a redo event, the redo layout structure address.
> 
> 	Support the new field in proc layouts that gives the location of the
> 	from-full flag (if any).
> 
> runtime/mercury_trace_base.[ch]:
> trace/mercury_trace.[ch]:
> 	Remove the call number and call depth arguments from MR_trace
> 	and its avatars, since this info is now in fixed stack slots
> 	in every procedure that can call MR_trace. This should reduce
> 	the size of the executable significantly, since there are lots
> 	of calls to MR_trace.
> 
> runtime/mercury_init.h:
> runtime/mercury_wrapper.h:
> 	Update the prototype of MR_trace_{fake,real}, and the type of the
> 	global that points to them.
> 
> START NUMBERING FRAMEVARS FROM ONE
> 
> compiler/code_info.m:
> compiler/live_vars.m:
> compiler/llds_out.m:
> compiler/trace.m:
> 	Start numbering framevars from 1 internally to the compiler;
> 	the runtime already starts from 1. This simplifies several tasks.
> 
> ADD REDO EVENTS
> 
> compiler/trace.m:
> compiler/code_gen.m:
> 	Before the code that executes "succeed()", emit code to push a
> 	a temp nondet frame whose redoip points to a label in the runtime
> 	that calls MR_trace for a REDO event and then fails, provided
> 	--trace-redo is set.
> 
> compiler/llds.m:
> 	Add a new code address constant, do_trace_redo_fail, which stands
> 	for the address in the trace system to which calls MR_trace for
> 	the redo event and then fails.
> 
> compiler/trace.m:
> compiler/llds_out.m:
> 	Provided we are doing redo tracing, fill in the slot that holds
> 	the layout information for the REDO event.
> 
> compiler/*.m:
> 	Minor changes to conform to handle the new code address constant.
> 
> browser/debugger_interface.m:
> 	Add redo to trace_port_type.
> 
> runtime/mercury_trace_base.[ch]:
> 	Add a C module containing the code that calls MR_trace for REDO
> 	events.
> 
> ENSURE THAT INPUT ARGUMENTS ARE ALWAYS VISIBLE
> 
> compiler/trace.m:
> 	When generating the set of live variables at internal ports,
> 	the variables that are in the pre-death set of the goal into which
> 	we are entering may not be available. However, the variables in the
> 	pre-death set that are also in the resume vars set will be available,
> 	so now include info about them in the layout structure for the event.
> 	Since with tracing the non-clobbered input args are in all resume vars
> 	sets, this ensures that these input args will be available from all
> 	internal events.
> 
> compiler/code_info.m:
> 	Export a previously internal predicate (current_resume_point_vars)
> 	to make this possible.
> 
> BUG FIX: WANT RETURN LAYOUTS
> 
> compiler/globals.m:
> compiler/call_gen.m:
> compiler/code_info.m:
> compiler/mercury_compile.m:
> 	Add a new pred globals__want_return_layouts, which says whether the
> 	compiler should generate layout structures for call returns. This pred
> 	centralizes the several previous copies of the test. One of those
> 	copies (the one in call_gen) was faulty, leading to a bug: in the
> 	presence of execution tracing but the absence of accurate gc,
> 	information about the variables that are live at the call return
> 	wasn't being gathered properly.
> 
> BUG FIX: #include mercury_trace_base.h
> 
> compiler/llds_out.m:
> 	#include mercury_trace_base.h, not mercury_trace.h, since now
> 	mercury_trace_base.h defines everything directly accessible from
> 	modules compiled with tracing.
> 
> RECAST MERCURY_TRACE_UTIL AS MERCURY_LAYOUT_UTIL
> 
> runtime/mercury_trace_util.[ch]:
> runtime/mercury_layout_util.[ch]:
> 	Rename this module from trace_util to layout_util, since it is also
> 	used by the native garbage collector. Remove "trace" from the names
> 	of functions.
> 
> 	Get rid of the global variable MR_saved_regs, and instead thread
> 	a pointer to this data structure through the relevant functions
> 	as an extra argument.
> 
> 	Add a lot more documentation in the header file.
> 
> 	Add an extra function, MR_get_register_number, for use by retry.
> 
> runtime/Mmakefile:
> 	Reflect the module rename.
> 
> runtime/*.c:
> 	Refer to the new module.
> 
> DELETE EASY-TO-MISUSE MACROS
> 
> runtime/mercury_stacks.h:
> 	Delete the based_framevar and based_detstackvar macros, since their
> 	use can lead to off-by-one errors, and the saved_framevar and
> 	saved_detstackvar macros, since they are no longer used.
> 
> runtime/*.c
> 	Update any references to any macros removed from mercury_stacks.h.
> 
> MISC RUNTIME CHANGES
> 
> runtime/mercury_trace_base.[ch]:
> trace/mercury_trace*.[ch]:
> 	Make typedef'd names conform to the naming convention.
> 
> 	Make MR_trace_call_{seqno,depth} consistently Unsigned, rather than
> 	sometimes Word and sometimes Unsigned.
> 
> FIX BUG: MAKE THE DEBUGGER PRINT TO STDOUT, NOT THE CURRENT STREAM
> 
> library/io.m:
> 	Export to C code the predicates that return the identities of stdin,
> 	stdout and stderr, as well as io__print/[34].
> 
> runtime/mercury_init.h:
> 	Add extern declarations for the C functions now exported from io.m.
> 
> runtime/mercury_wrapper.[ch]:
> 	Add new global variables to hold the addresses of these C functions.
> 
> runtime/mercury_layout_util.c:
> 	Use indirect calls through these global variables to print Mercury
> 	values, instead of lower-level code.
> 
> util/mkinit.c:
> 	Assign the addresses of the functions exported from io.m to the
> 	global variables defined in mercury_wrapper.h.
> 
> IMPLEMENT NEW DEBUGGER COMMAND SET
> 
> runtime/mercury_stack_trace.[ch]:
> 	Factor out the code that prints the id of a procedure into a function
> 	of its own, so that it can also be used from the debugger, ensuring
> 	appearance commonality.
> 
> 	Add more documentation in the header file.
> 
> trace/mercury_trace_internal.c:
> 	Implement the proposed command set. Command names are now words,
> 	and several commands now have options allowing the user to override
> 	the default print level or strictness of the command, or the
> 	invocation conditions or action of a break point. Allows control
> 	over command echoing and the scrolling of sequences of event reports.
> 	Supports aliases, command file sourcing etc. Implements the retry
> 	command, using the info in the fixed stack slots.
> 
> trace/mercury_trace.[ch]:
> 	Extend the trace controls to support the new functionalities
> 	required by the new debugger language, which are print levels,
> 	variable-strictness commands, a more flexible finish command,
> 	and the retry command.
> 
> 	Pass the command structure to MR_trace_event_report, since
> 	the user can now forcibly terminate the scrolling of reports.
> 
> trace/mercury_trace_alias.[ch]:
> 	New module to manage aliases for the debugger.
> 
> trace/mercury_trace_spy.[ch]:
> 	New module to manage break points. The test of whether an event
> 	matches a break point is now much more efficient than before.
> 	The new module also allows several breakpoints with different
> 	actions and different invocation conditions (e.g. all ports,
> 	entry port, interface ports or specific (possibly internal) port)
> 	to be defined on the same procedure.
> 
> trace/mercury_trace_tables.[ch]:
> 	New module to manage a table of the debuggable modules, in which
> 	each such module is linked to the list of the layouts of all the
> 	procedures defined in that module. This information allows the
> 	debugger to turn the name of a predicate/function (possibly together
> 	with its arity and mode number) into the procedure layout structure
> 	required by the spy point module. Eventually it may also be useful
> 	in supplying lists of identifiers for command line completion.
> 
> 	Modules for which no stack layout information is available will
> 	not be included in the table, since do_init_modules will not
> 	register any labels for them in the label table.
> 
> trace/mercury_macros.h:
> 	A new file holding macros that can be useful in more than one module.
> 
> trace/Mmakefile:
> 	Mention the new files.
> 
> ADD TRACE DEPTH HISTOGRAMS
> 
> runtime/mercury_conf_param.h:
> 	Document MR_TRACE_HISTOGRAM.
> 
> runtime/mercury_trace_base.[ch]:
> 	Define the data structures for the histogram, and print the histogram
> 	when a traced program exits if MR_TRACE_HISTOGRAM is set.
> 
> trace/mercury_trace.[ch]:
> 	If MR_TRACE_HISTOGRAM is defined, record a count of the number of
> 	events at each depth. This information can help us evaluate space-time
> 	tradeoffs.
> 
> FACTOR OUT SHELL CODE HANDLING GRADE IMPLICATIONS
> 
> scripts/final_grade_options.sh-subr:
> 	A new file to contain any code that implements implications between
> 	grade flags; currently implements the implication debug -> use trail.
> 
> scripts/mgnuc.in:
> scripts/ml.in:
> 	Replace the code that is now in final_grade_options.sh-subr with
> 	an inclusion of final_grade_options.sh-subr.
> 
> configure.in:
> 	Handle final_grade_options.sh-subr as {init,parse}_grade_options.sh-subr
> 	are handled.
> 
> SIMPLIFY THE MAINTAINANCE OF CONSISTENCY BETWEEN DEBUGGER CODE AND DOCUMENTATION
> 
> doc/Mmakefile:
> 	Add rules for creating mdb_command_list, a C code fragment
> 	that can included manually in trace/mercury_trace_internal.c
> 	to supply the list of valid commands, and mdb_command_test.inp,
> 	which is a list of invalid invocations of debugger commands,
> 	which tests whether the help message for such invocations
> 	can be located as expected.
> 
> doc/generate_mdb_command_list:
> doc/generate_mdb_command_test:
> 	Awk scripts to create mdb_command_list and mdb_command_test.inp
> 	respectively from mdb_doc.
> 
> tools/bootcheck:
> 	Copy mdb_command_test.inp from doc to tests/debugger.
> 
> tests/debugger/Mmakefile:
> 	Add a new test that checks whether we get an internal error, unable
> 	to locate the right help node, for each invalid command invocation in
> 	mdb_command_test.inp.
> 
> UPDATE TEST CASES
> 
> tests/debugger/Mmakefile:
> 	Reenable queens. Conform to the new set of options.
> 
> tests/debugger/*.inp:
> tests/debugger/*.exp:
> 	Update the inputs and expected outputs of the debugger test cases
> 	to use the new command set and output formats.
> 
> Zoltan.
> 


> @@ -68,16 +68,27 @@
> USE FIXED STACK SLOTS FOR TRACE INFO
>  	% layouts).
>  :- pred trace__fail_vars(module_info::in, proc_info::in, set(var)::out) is det.
>  
> -	% Reserve the stack slots for the call number, call depth and
> -	% (for interface tracing) for the flag that says whether this call
> -	% should be traced. Return our (abstract) struct that says which
> -	% slots these are, so that it can be made part of the code generator
> -	% state.
> -:- pred trace__setup(trace_level::in, trace_info::out,
> +	% Return the number of slots reserved for tracing information.
> +	% If there are N slots, the reserved slots will be 1 through N.
> +:- pred trace__reserved_slots(proc_info::in, globals::in, int::out) is det.
> +
> +	% Reserve the non-fixed stack slots needed for tracing.
> +	% The fixed slots for the event number, call number, call depth and
> +	% (for trace levels that specify redo events) the stack layout of
> +	% the redo event are reserved in live_vars.m; this predicate reserved

s/reserved/reserves

> +	% only the slots that do not need to be in fixed slots. At the moment
> +	% the only such slot is the flag that says whether this call should be
> +	% traced, which is required only for shallow tracing.
> +	%
> +	% The predicate returns the number of this slot if it is used,
> +	% an abstract struct that represents the tracing-specific part

s/an/and an


Apart from this, I am happy with the compiler directory changes.


-- 
Those who would give up essential liberty to purchase a little temporary
safety deserve neither liberty nor safety.     - Benjamin Franklin

Tyson Dowd   <tyson at tyse.net>   http://tyse.net