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.
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:
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)
Change directory to the root of your build directory and remove all the object files and executables:
% make clean |
Rebuild the local Makefile:
% make Makefile |
Rebuild the sub-directory Makefiles:
% make Makefiles |
Finally, rebuild the component:
% make |
To enable symbolic debugging in selected component directories:
Edit the Imakefile within each desired component source directory, and add the following line to the end:
DEBUG=$(DEBUG_ON)
Change directory to the root of your build directory and remove all the object files and executables:
% make clean |
Rebuild the local Makefile:
% make Makefile |
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.
To enable symbolic debugging for system components:
Change to your build directory and remove all the object files and executables:
% make clean |
Create a mkmk build definition file:
% echo 'FREMOTEDEB=ON' > filename.df |
filename can be a name of your choice.
Rebuild the system component:
% make makemk |
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.