test

ChorusOS 4.0 Introduction

Starting and Configuring the ChorusOS DebugServer

Identifying the Serial Device

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

To identify the serial device, look in the /etc/remote file. This file contains references to remote systems that you can access through your local serial line. For more details, see remote(4). The device is usually named /dev/ttya or /dev/ttyb and will be the same device used by the tip or cu tools. The device must be readable and writable by all users.

DebugServer Slot Numbers

The DebugServer 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, assign a unique slot number (in the range 0..65535) to 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 as 0 will be used by default.

If you decide to assign a slot number to your DebugServer, use the DebugServer environment variable CHSERVER_HOST.

DebugServer Environment Variable

The DebugServer, as well as all the other tools based on the Debug Library, uses the optional environment variable CHSERVER_HOST. This environment variable indicates:

The format of the environment string is host[:slot-id]. For example:


%  setenv CHSERVER_HOST  jeriko
%  setenv CHSERVER_HOST  concerto:3

DebugServer Configuration File

Configuration information about targets is held in a special file which the DebugServer reads every time you run it. For each target, the configuration file contains:

When a new target is registered, see "Registering a Target" for details of how to do this, the configuration file is modified.

Starting the DebugServer

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


% chserver

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

If you have defined a slot number n and not set the environment variable, you can start the DebugServer as follows:


% chserver -slot n

A complete description of the DebugServer is given in the chserver(1CC) man page.

Note -

If chserver is run on a different host to the one the system image was built on, particularly on a shared file system with a different view of the build directory, the tool will not be able to access the necessary source files during system debugging. This problem is NFS related, the symbolic link created on one host may not be valid for another, and is due to there being relative file references in the layout.xml file. There are two solutions to the problem:

Stopping the DebugServer

Stop the DebugServer by using the chadmin tool.


% chadmin -shutdown

Registering a Target

Before registering a target you need to know:

Now you can register the target by typing: 


% chadmin -add-serial-target name/
           -device device/
           -layout-file layout_file

name is the name of your target, device is the serial device that you have identified, and layout_file is the absolute path of the layout.xml file.

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

Updating Target Information

Use chadmin to update the information that you gave during the registration of your target.

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


% chadmin -baud 38400 -parity none -device /dev/ttya name

If you wish to specify a new layout.xml file because the path has changed (see note), use the following command to inform the DebugServer of the new path:


% chadmin -layout-file path/layout.xml name

Note -

When you change the mode of system image booting (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 will change.

For example, if you type:


% configurator -set SYSTEM=kts

The path will change to build_dir/image/RAM/kts/layout.xml.

If you then type:


% configurator -set SYSTEM=chorus

The path will change to build_dir/image/RAM/chorus/layout.xml.

Similarly, if you change the mode of system image booting:


% configurator -set BOOT_MODE=ROM

The path will change to build_dir/image/ROM/chorus/layout.xml.

Deactivating a Target

A target can be deactivated to disconnect the DebugServer from the DebugAgent and release the serial device used by the DebugServer. When a target is deactivated, the DebugAgent switches to a stand-alone mode. The chconsole must no longer be used as the DebugServer does not read the serial line any more. Instead, you must start the tip(1) or cu(1C) tools to gain access to the system debugging console.

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


% chadmin -deactivate name

name is the name of your target.

When a target is deactivated, it is not removed from the DebugServer configuration file so that it is possible to reactivate it later.

Reactivating a Target

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

The target is reactivated with this command:


% chadmin -activate name

name is the name of your target.

The DebugServer will synchronize with the DebugAgent and the DebugAgent will switch to a binary protocol mode. At this stage, you must use the chconsole to gain access to the system debugging console.

Removing a Target

A target may be permanently removed by first deactivating it (see "Deactivating a Target") then unregistering it with this command:


% chadmin -remove-target name

name is the name of your target.

Providing you have deactivated the target first, the target's configuration information will be deleted from the configuration file.