Preparing the System for Symbolic Debugging

Compiling for Debugging

In order to use all the debugging features in the XRAY Debugger, you need to generate symbolic debugging information when you compile components. This information is stored in the object files and describes the data type of each variable or function and the correspondence between source line numbers and addresses in the executable code.

How you enable debugging in components will depend on which release of ChorusOS 4.0 you have. The binary release of ChorusOS 4.0 includes the source code for the BSP, driver and example components. These you will compile in what is known as an imake build environment because the imake tool is used to create the Makefiles for these components.

The source release of ChorusOS 4.0 includes everything in the binary release plus source code for system components, such as the kernel and the operating system. These components are built in an mkmk build environment where the tool mkmk is used to build Makefiles. For more details see ChorusOS 4.0 Production Guide.

Enabling Debugging for Components Built with imake

To build all your components with symbolic debugging information turned on:

• Edit the Paths file located in the root of your build directory, created after you run the configure command, and add the following line to the end:

  FREMOTEDEB=ON

Other ways can be used to selectively build your components with symbolic debugging information. These are presented below.

To enable symbolic debugging throughout the component directory and its sub-directories:

1. Edit the Project.tmpl file located in the root of the component source directory, and add the following line to the end:

   DEBUG=$(DEBUG_ON)

2. Change directory to the root of your build directory and remove all the object files and executables:

   % make clean

3. Rebuild the local Makefile:

   % make Makefile

4. Rebuild the sub-directory Makefiles:

   % make Makefiles

5. Finally, rebuild the component:

   % make

To enable symbolic debugging in selected component directories:

1. Edit the Imakefile within each desired component source directory, and add the following line to the end:

   DEBUG=$(DEBUG_ON)

2. Change directory to the root of your build directory and remove all the object files and executables:

   % make clean

3. Rebuild the local Makefile:

   % make Makefile

4. Finally, rebuild the component:

   % make

If you prefer not to modify the Imakefile or Project.tmpl files, there is an alternative way of enabling debugging. You can pass the debug option within the make command itself:

• Change to your build directory and remove all the object files and executables:

  % make clean

  Rebuild the component with symbolic debugging enabled:

  % make MAKE="make DEBUG=-gdwarf-2"

• You can also create a DEBUG environment variable. If you use the C shell:

  % setenv DEBUG -gdwarf-2

  If you use the Bourne shell:

  $ DEBUG=-gdwarf-2 $ export DEBUG

  Now call make with the -e option to import environment variables:

  % make -e

Once a component has been compiled in debug mode, rebuild and reboot the system image.

Enabling Debugging for Components Built with mkmk

To enable symbolic debugging for system components:

1. Change to your build directory and remove all the object files and executables:

   % make clean

2. Create a mkmk build definition file:

   % echo 'FREMOTEDEB=ON' > filename.df

   filename can be a name of your choice.

3. Rebuild the system component:

   % make makemk

Configuring the Debug Agent

The DebugAgent is activated by enabling the DEBUG_SYSTEM feature with the configurator(1CC) command:

% configurator -set DEBUG_SYSTEM=true

The DEBUG_SYSTEM feature is set to true by default.

When the DebugAgent is activated, communications on the serial line are performed in binary mode.

The DebugAgent has eight tunable options that you can configure with ews or configurator. The following three tunables control the behavior of the DebugAgent when it is enabled (DEBUG_SYSTEM=true):

• dbg.agent.startup specifies the behavior of the DebugAgent when the DebugServer attempts to connect to the target. Possible values are stop or resume. In stop mode the system will wait indefinitely until the DebugServer connects to the DebugAgent. In resume mode the system will wait for no more than one second. In both cases, the DebugAgent will issue the prompt DebugAgent: trying to sync with DebugServer... over the serial line and sound a beep. If the DebugServer does not connect, the system will continue booting and console operations will be performed raw, without any processing by the DebugAgent, on the serial line.

• dbg.agent.exceptmode specifies the behavior of the DebugAgent when an exception is raised before the DebugServer has connected. Possible values are catch or forward. In catch mode the DebugAgent catches all exceptions and blocks the target until a DebugServer has connected and resumed the execution of the target. In forward mode the DebugAgent forwards all exceptions directly to the kernel-installed handlers.

• dbg.agent.consolemode specifies the operating mode of the system console. Possible values are sync or async. In sync mode the target is blocked until each message has been transmitted to the host for output and acknowledged. In async mode, console output is buffered and transmitted to the host periodically, either when the buffer is full or on each timer interrupt, whichever occurs first.

The following five tunables control the serial line used by the DebugAgent.

• dbg.agent.device specifies the serial device used by the DebugAgent. Possible values are COM1, COM2, COM3, or COM4. COM1 refers to communication port 1 (COM 1) on a PC, or the first serial line on other boards. COM2 refers to communication port 2 (COM 2) on a PC, or the second serial line on other boards, and so on.

• dbg.agent.baud specifies the baud rate of the serial line. Possible values are: 115200, 57600, 38400, 19200, 9600, 4800, 2400, or 1200.

• dbg.agent.parity specifies the parity of the serial line. Possible values are none, even, or odd.

• dbg.agent.databits specifies the number of data bits. The only possible value is 8.

• dbg.agent.stopbits specifies the number of stop bits. Possible values are 1 or 2.

When the DebugAgent is not active (DEBUG_SYSTEM=false), the serial line is used by the system debugging console, and the five tunables control the serial device and speed.