Using SparcWorks Debugger with Objectime 5.1

Toolset

This technote describes what you need to do to your environment in order to use the SparcWorks Debugger.

Anyone interested in using the SparcWorks Debugger for source debugging in SimulationRTS or with Target Observability.

ObjecTime 5.1

Refer to ObjecTime 5.1 C++ Guide "Using External C++ Debuggers" p.173 for introduction.

Two files must be added to your Objectime working directory:

.objectime.debugger.commands
sparcw_Debugger_Script

Create the '.objectime.debugger.commands' text file with the following contents:

attach "OT_DEBUG -p 0"
break on line "list .cc; stop at 0;"
break on func "OT_BREAK "
continue "cont"
directory ""
debugger "sh ./sparcw_Debugger_Script OT_BREAK OT_DEBUG"

Create the 'sparcw_Debugger_Script' text file with the following contents:

 # Copyright (c) 1991-1997 ObjecTime Limited.  All rights reserved.
 # Unpublished--rights reserved under all copyright laws including
 # Copyright Laws of the United States.
 #
 # ObjecTime (and logo) is a registered trademark of ObjecTime Limited.
 #
 # "ObjecTime" shall mean the ObjecTime, SimulationRTS (InternalRTS),
 # EmulationRTS and TargetRTS (MicroRTS) computer programs.
 #
 # The placing of the copyright notices on ObjecTime source code is not
 # intended to mean that they are published works, but are included in the
 # event of inadvertent publication. The source code of ObjecTime contains
 # trade secrets and other valuable confidential information of ObjecTime
 # Limited. ObjecTime Limited and its licensors retain ownership to
 # ObjecTime in both source and object code format, and related documentation
 # and all rights therein including copyrights, patents and trade secrets.
 #
 #                        Restricted Rights Legend
 #
 # With respect to any copies of the ObjecTime software and related
 # documentation provided to any U.S. Government department or agency, use,
 # duplication, or disclosure by the Government is subject to restrictions
 # as set forth in subparagraphs (a) through (d) of the Commercial Computer
 # Software-Restricted Rights clause FAR 52.227-19 and its successors. For
 # units of the Department of Defense (DoD), the license for this software is
 # subject to the "Restricted Rights" as that term is defined in the DFAR
 # 252.227-7013 (c) (1) (ii), Rights in Technical Data and Computer Software,
 # and its successors. Unpublished -- rights reserved under the Copyright
 # Laws of the United States.
 #
 #                        ObjecTime Limited
 #                        340 March Road
 #                        Kanata, Ontario K2K 2E4
 #                        Canada
 #
 # Unless otherwise agreed to in writing, use of ObjecTime is governed by
 # the Development License Agreement provided with the product.

 # SparcWorks Debugger Invocation Script  V2.0
 #

 script_name=$1
 exec_name=$2
 break_search_string=$3
 debug_search_string=$4
 exec_dir_name=`dirname $exec_name`
 exec_base_name=`basename $exec_name`

 script_dir=`dirname $script_name`
 new_break_script=$script_dir/.ot_break_script

 # Get the process pid to be debugged
 debug_pid=`grep $debug_search_string $script_name | awk '{print $3}'`

 # The TargetRTS runs the executable out of the model directory, while
 # the SimulationRTS runs it out of the top level actor directory.
 # check which case we have here

 cd $exec_dir_name

 if [ -d ./C++ ]
 then
 ###     TargetRTS environment
 ###    prefix_string "-I./C++/"
    include_dir=`grep $break_search_string $script_name | awk '{print "-I./C++/"$2}'`
 else
 ###     Simulation environment
 ###    prefix_string "-I../"
    include_dir=`grep $break_search_string $script_name | awk '{print "-I../"$2}'`
 fi
 # STOP command 1 (see tech note description).  If you use this command,
 # ensure that STOP command 2 below is commented out.
 grep $break_search_string $script_name| awk '{print "stop in "$2"::"$3}' > $new_break_script
 # STOP command 2: (see tech note description).  If you use this command,
 # ensure that STOP command 1 above is commented out.
 #grep $break_search_string $script_name| awk '{print "stop inmember "$3}' > $new_break_script
 grep cont $script_name >> $new_break_script
 debugger -c "source $new_break_script" $include_dir $exec_base_name $debug_pid

Important Notes:

The commands in the script are shell commands. These may require modification for your environment.

Application may run past user's breakpoints BEFORE the debugger has had a chance to attach itself to the running application process. A way to avoid this is to put a 'sleep' statement in the application's toplevel initialization transition to cause it to pause (10 seconds is ample). The 'sleep' prototype is in unistd.h which may need including in the environment.

We provide this example on an 'as is' basis. If it does not work in customer's environment, it is up to customers to modify the scripts as required.

With SimulationRTS, resetting or closing the RTS from the toolset will not kill the debugger. The user must exit the debugger manually after the reset/close.

Using this example with SimulationRTS or Target Observability, resetting or closing the RTS from the toolset will not kill the debugger nor the application being debugged. After reset/close, the user must use the "kill" debugger command to kill the application process being debugged and then exit out of the debugger. Warning: failure to kill the application may result in the application 'hanging' the next time it is run. This is because the application may still be communicating with the rtsController intermediary process (for Target Observability) or with the toolset (for SimulationRTS).

The -I option passed to the debugger for indicating source code search paths contains a path for every break point set. As a result, there can be duplicate path specified.

There are two SPARCworks debugger commands that can be used for setting the break point:

STOP command 1 (stop in ::):

Use this command to stop in an actor class scoped transition. In our experience, in order for the SPARCsworks debugger to recognize the actor being in scope upon attaching to the process, a call to sleep() for about 5 seconds is required in the initialize transition of the top level actor. If you use this command, ensure that the STOP command 2 in the script is commented out.

STOP command 2 (stop inmember ):

Use this command to stop in any member function with the name of the mangled actor transition name. Transition functions for an actor are mangled with a unique number, so transitions of the same name in an actor are actually given different names at code generation time. Transition functions for different actors can have the same name, e.g. usually the initialize transition function for all actors end up with the name transition1_initialize, as it is often the first transition added. Using this command can result in the debugger displaying the wrong source code file (based on the search path given to the debugger via -I) because there is a possibility that there is more than one member function with the same. If you use this command, ensure that the STOP command 1 in the script is commented out.

None