ChorusOS 5.0 Debugging Guide

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 host name on which the debug server is running.
Optionally, the slot number for the debug server RPC service.

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:

Break the build_dir/build-NUCLEUS/conf/mkimage/layout_typedef.xml symbolic link accessed by chserver and replace it with a copy of the file to which it points.
Copy the conf and image directories to the host where chserver will run, then use chadmin to set the path of the layout.xml file. You will need to do this each time the system image is regenerated.

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:

The name of the target.
The serial device used to communicate with the target.
Configuration parameters for the serial device (baud rate and parity) .
The architecture type of the target (for example, x86, PPC, SPARC) .
The absolute path of the layout.xml image layout file generated by mkimage.

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:

The name of the serial device on the host.
The path of the layout.xml file generated by mkimage (the path of this file is printed by mkimage when a system image is built).

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

$ 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.