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.
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.
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 host name where your DebugServer is running
optionally, the slot number for the DebugServer RPC service
The format of the environment string is host[:slot-id]. For example:
% setenv CHSERVER_HOST jeriko % setenv CHSERVER_HOST concerto:3 |
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:
The name of the target
The serial device used to communicate with the target
Configuration parameters for the serial device (baud rate, parity)
The architecture type of the target (i386, PPC, SPARC)
The absolute path of the layout.xml image layout file generated by mkimage
When a new target is registered, see "Registering a Target" for details of how to do this, the configuration file is modified.
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.
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:
Break the symbolic link with the file /build-NUCLEUS/conf/mkimage/layout_typedef.xml accessed by chserver.
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.
Stop the DebugServer by using the chadmin tool.
% chadmin -shutdown |
Before registering a target you need to know:
The name of the target
The name of the serial device
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)
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.
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 |
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.
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.
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.
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.