test

ChorusOS 5.0 Debugging Guide

Chapter 3 Debugging ChorusOS Systems

This chapter describes how to debug ChorusOS systems with the GDB debugger and the Insight GUI. The chapter includes the following:

System Debugging Architecture

This section describes the system debugging architecture and illustrates how the various components work together. The system debugging architecture includes:

The first two components run on the host. The debug agent runs on the target and communicates with the ChorusOS debug server through a serial connection. The architecture is illustrated in Figure 3-1.

Figure 3-1 System Debugging Architecture

Graphic

A debug server can manage several targets (with different architectures) at the same time.

System debugging enables you to debug the microkernel, the system drivers, the BSP, and those supervisor actors that cannot be debugged with application debugging, such as the C_OS.

Setting Up a Debugging Session

The following steps guide you through setting up your first system debugging session:

  1. Connect a serial cable between the host and the target.

  2. Prepare the system for symbolic debugging. See "Enabling Symbolic Debugging" for information on how to do this.

  3. Start and configure the ChorusOS debug server chserver. See "Starting the Debug Server" for more information.

  4. Register the target with chadmin, the ChorusOS debug server administration tool. See "Registering a Target".

  5. Configure and start the GDB debugging tool for ChorusOS.

Note -

GDB performs the system console function during system debugging. However, you can also use the standalone chconsole tool. If the debug server is not connected to a target, you can still view the system console using the tip or cu commands (but cannot debug). See the tip(1) and cu(1C) man pages for more information.

For subsequent debugging sessions, you need only perform the following steps:

  1. Start the ChorusOS debug server chserver, if it is not already running.

  2. Start the GDB debugging tool for ChorusOS systems.

Starting and Configuring the ChorusOS Debug Server

The ChorusOS debug server chserver communicates with the target through a serial cable connection and must be run on the host to which the target is connected.

Assigning Debug Server Slot Numbers

The debug server is a Sun RPC server that is registered with the rpcbind server. When you require more than one debug server to run on the same host, associate a unique slot number with each of them so that individual debug servers can be identified. If only one debug server is started on a given host, it is not necessary to allocate a slot number; 0 is used by default.

Use the debug server environment variable CHSERVER_HOST to assign a slot number to a debug server.

Debug Server Environment Variable

The debug server and all other tools based on the ChorusOS system Debug Library use the optional environment variable CHSERVER_HOST to indicate:

The format of the environment string is: host[:slot-id], as shown in the following example:


$ setenv CHSERVER_HOST jeriko
$ setenv CHSERVER_HOST concerto:3

Starting the Debug Server

On the host to which your target or targets are connected, type the following:


$ chserver

This starts the debug server as a background process. An empty configuration file called dbg_config.xml is copied into your home directory the first time you run the debug server.

If you have defined a slot number n and have not set the environment variable, you can start the debug server by typing:


$ chserver -slot n

If the CHSERVER_HOST environment variable is set, it must contain the correct host name, otherwise the debug server will not operate correctly.

A complete description of the debug server is provided in the chserver(1CC) man page.

If chserver is run on a different host from the one on which the system image was built (particularly on a shared file system with a different view of the build directory) it will not be able to access the necessary source files during system debugging. The symbolic link created on one host may not be valid for another because of the relative file references in the layout.xml file. There are two solutions to this problem:

Debug Server Configuration File

Configuration information about targets is kept in a configuration file that the debug server reads every time it is run. For each target, the configuration file contains:

When a new target is registered, the configuration file is modified. (See "Registering a Target" for details of how to do this). A sample configuration file is shown below.

Example 3-1 Sample Debug Server Configuration File

<!-- ChorusOS debug server configuration file -->
<!-- Generated by ChorusOS debug server v1.0 -->
<package>
  <object name="target_name" type="target_type">
    <set param="pathmap" value=""/>
    <set param="layout_file" 
        value="build_dir/image/bmon/chorus/layout.xml"/>
    <set param="get_image_desc_cmd" 
        value="chgetlayout -stamp $(image_stamp)  $(abs_layout_file)"/>
    <set param="archive_file" value=""/>
    <set param="activate" value="1"/>
    <object name="backends" type="BackendList">
      <object name="log:bkpts:cache:log:serial" type="SerialBackend">
        <set param="device" value="/dev/term/a"/>
        <set param="baud" value="9600"/>
        <set param="parity" value="none"/>
        <set param="debug_mode" value="1"/>
        <set param="reboot_cmd" value=""/>
        <set param="reboot_wait" value="5"/>
        <set param="connect_timeout" value="120000"/>
        <set param="sync_retry_delay" value="5000"/>
      </object>
    </object>
  </object>
</package>

Stopping the debug server

To stop the debug server, use the chadmin tool:


$ chadmin -shutdown

Note -

Stopping the debug server is not advised because you can lose communication with the target.

Registering a Target

Before registering a target you must know:

You must also have chosen a name for the target (typically its host name).

Register the target by typing:


$ chadmin -add-serial-target target_name\
			-device device\
			-layout-file layout_file\
			-pathmap original_dir new_dir

In the preceding example, device is the serial device that you have identified and layout_file is the absolute path of the layout.xml file.

The -pathmap option enables you to set a translation pathmap. original_dir is the original directory that cannot be accessed by the debug server. new_dir is the new directory for the debug server to use (instead of the original one).

You only need to register a target once, as configuration information is saved in your dbg_config.xml file.

Note -

If you modify the dbg_config.xml file manually, without using chadmin, you must restart the debug server for changes to take effect.

When a target is activated, the debug server synchronizes with the debug agent and the debug agent switches to binary protocol mode. Use chconsole at this stage to access the system debugging console.

Updating Target Information

Use chadmin to update the information provided during the registration of the target.

The following example sets the baud rate to 38400 and sets the parity to none. It uses the device /dev/ttya for the target name:


$ chadmin -baud 38400 -parity none -device /dev/ttya target_name

Note -

Before the target updates, it is necessary to adjust certain tunables for the debug agent. See "Configuring the Debug Agent" for more information.

To specify a new layout.xml file because the path has changed, use the following command to inform the debug server of the new path:


$ chadmin -layout-file pathname/layout.xml target_name

When you change the mode in which the system image boots (using the BOOT_MODE global variable) or select a different system image configuration (using the SYSTEM global variable), the path to the layout.xml file changes.

For example, if you type:


$ configurator -set SYSTEM=kts

the path changes to build_dir/image/RAM/kts/layout.xml.

If you then type:


$ configurator -set SYSTEM=chorus

the path changes to build_dir/image/RAM/chorus/layout.xml.

Similarly, if you change the mode in which the system image boots by typing:


$ configurator -set BOOT_MODE=ROM

the path changes to build_dir/image/ROM/chorus/layout.xml.

Deactivating a Target

A target can be deactivated to disconnect the debug server from the debug agent and to release the serial device used by the debug server. When a target is deactivated, the debug agent switches to standalone mode. The chconsole can no longer be used because the debug server no longer reads the serial line. Instead, you must start the tip or cu tools to access the system debugging console.

A target can be temporarily removed (deactivated) with the command:


$ chadmin -deactivate target_name

When a target is deactivated, it is not removed from the debug server configuration file. It is therefore possible to reactivate it later.

Reactivating a Target

Before a target can be reactivated, stop any tip or cu tools which may be using the serial line.

A target is reactivated with the following command:


$ chadmin -activate target_name

Removing a Target

A target can be removed permanently by deactivating it (see "Deactivating a Target") then unregistering it with the following command:


$ chadmin -remove-target target_name

If you have deactivated the target properly, its configuration information will be deleted from the configuration file.

Configuring the Debug Agent

The debug agent is activated by enabling the DEBUG_SYSTEM feature with the configurator command as follows:


$ configurator -set DEBUG_SYSTEM=true
Note -

The DEBUG_SYSTEM feature is set to true by default.

When the debug agent is activated, communications on the serial line are performed in binary mode (if the debug server is attached) or in ASCII mode (if it is not).

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

The following five tunables control the serial line used by the debug agent:

Note -

When the debug agent 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.

Using the System Debugging Tools

This section describes the use of the Insight GUI and of GDB for debugging ChorusOS systems.

Starting Insight for System Debugging

Before starting Insight for system debugging, ensure that the debug agent is running on the target system and that the debug server is connected to it.

The name of the Insight executable differs according to the target platform and takes the form target-type-chorusos-gdb. Thus, depending on the platform, type one of the following to start Insight:

Note -

By default, the Insight GUI is started when you start GDB.

To Connect to the Target

  1. Select File -> Target Settings.

  2. Select ChorusOS System Debug from the Target list.

  3. In the Target name field, type the target name, as registered in the debug server.

  4. In the Chserver host field, type the name of the host on which the debug server is running.

    If the chserver uses the default slot, type chserver_host_name.

    If the chserver does not use the default slot, type chserver_host_name:slot-id.

  5. Click OK to save the target settings.

  6. Select Run -> Connect to target.

Once you have connected to the target successfully, the symbols for all components of your system image are automatically loaded. The connection is complete when the message Successfully connected is displayed.

Note -

If you recompiled the microkernel from source after enabling symbolic debugging, the target stops executing and the line of code on which it stops is displayed in the Source Window when a successful connection is made.

Figure 3-2 Application Source Window

Graphic

Using the Run button or selecting Run -> Run will reboot your ChorusOS target. You can also reboot your target using the Run command in the View -> Console window.

Selecting Run -> Connect to target before setting your target causes the Target Selection window to be displayed automatically.

Starting GDB for System Debugging

Before starting GDB for system debugging, make sure that the debug agent is running on the target and that the debug server is connected to it.

The name of the GDB executable differs according to the target platform and takes the form target-type-chorusos-gdb. Thus, depending on the platform, type one of the following to start GDB:

Note -

By default, the Insight GUI is started when you start GDB. To start GDB without the Insight GUI, you must include the --nw option.

If GDB is not started on the same host as the debug server, and the CHSERVER_HOST is not set or is incorrectly set, set the host with the following command:


(chgdb) set chserver host_name [:slot-id]

where host_name is the name of the host on which the debug server is running and the optional slot-id is the occupied slot.

Connect to the target using the target chorusos target_name command, as indicated in the example below:


(chgdb) target chorusos target_name

When GDB is connected to the target, load the symbols for all the components of your system image as follows:


(chgdb) chload-symbols

Once you have started GDB and connected to the target successfully, the system is stopped, usually in the clock interrupt handler. The debugging session follows the standard GDB debugging process. For more information on this process, see Debugging with GDB.

Caution - Caution -

Using the run command at any point will reboot your ChorusOS system.

Insight GUI - ChorusOS System Debugging Specifics

Most of the Insight windows used in ChorusOS system debugging sessions are standard and information on their use is available in the standard Insight documentation. Some functionality has been added or customized for ChorusOS operating systems. These additions and customizations are described in the following sections.

Displaying ChorusOS DebugServer Objects

The ChorusOS DebugServers Objects window displays a list of ChorusOS entities (threads, actors, and regions). To view the DebugServers Objects window, select ChorusOS -> DebugServer Objects.

Figure 3-3 ChorusOS DebugServer Objects Window

Graphic

Use the buttons at the top of the window to execute predefined commands, or enter an argument for the Chls command and click Display.

System Debugging Commands

The following system debugging commands are available:

chload-symbols

Loads the symbols for the attached system.

chthread thread-id

Changes the current thread. This command is similar to thread thread-id but uses ChorusOS thread numbers. It does not accept the apply keyword.

chls args

Lists ChorusOS system objects. Refer to the chls(1CC) man page.

set chcontinue-on-exit on/off

Sets the resume target flag on exit. By default, the target resumes when GDB detaches from it. You can clear the target flag to keep the target stopped when GDB detaches.

set chdebug on/off

Enables or disables debug traces for maintenance.

set chserver host[:slot]

Sets the host name and slot number to connect to the debug server. The format of the argument is the same as the CHSERVER_HOST environment variable. This variable is set automatically, according to the CHSERVER_HOST environment variable. The host name indicates the host on which the debug server is running. The optional slot number represents the slot number used when the debug server was started.

set chthread-format arg

Defines the format of the template to be used by GDB when reporting information about a thread. The template uses the thread attributes defined by the debug server to insert variable information into the constructed name.

target chorusos machinename

Connects to the ChorusOS target for system debugging. The optional argument machinename is the name of the target as registered in the debug server. The command attempts to find a default active target registered in the debug server. If several targets are registered and active, you must specify the name of a target.

Note -

Additional commands may have been added after the release of this manual. To obtain a complete list of these commands, type:


$ ch

or


% set ch

and press the Tab key twice.