This chapter describes debugging programs running on remote systems. A remote debugger consists of a server running on the target system and a client (the debugger) running on the host system. Once connected to the target system, you use Ladebug to debug your program in the same way you debug your programs running locally.
For a detailed description of writing a remote debugger server, see Appendix B.
The remote debugging environment consists the following components that interact through the remote debugger protocol:
The functionality available in a remote debugging session depends in part on which debugger server you are using. For Digital UNIX Version 4.0-6, this server is the server for the EB64 Alpha Evaluation Board (see Section 21.6) or Digital UNIX, or a server that you write for your own Alpha environment (see Appendix B).
The Ladebug server provided with Digital UNIX Version 4.0-6 (or later) is not compatible with versions of the debugger earlier than Version 4.0-6. (This incompatibility affects you only if you use remote debugging.) The incompatibility stems from a security enhancement introduced in Version 4.0-6: The server checks that a connect request is from a privileged port.
There are several cases in which you would use a remote debugger:
The target system may be an embedded system that cannot support a debugger. You also may be debugging a part of the target's software that has to work before you can support a local debugger. A remote debugger server (that is, the software) requires less and different support from the target's operating system (if one exists) than the support required by a local debugger.
The target system may not be able to run a local debugger and simultaneously run the program being debugged. The remote debugger server uses less resources (particularly memory) than a resident Ladebug debugger.
These sources are accessible from a host system from which you can remotely debug the target system.
A screen or keyboard interface may not exist because they are used by the program being debugged. Another possibility is that the target system's physical location is different from the user's.
On many interactive systems, it may be best to run a remote debugger. Alternatively, you may be able to run a local debugger that directs its input/output (I/O) to a screen on the remote system.
Remote debugging with Ladebug uses a client/server model. In this model, the host system, or client, initiates a connection to the target hardware and server software, which processes client requests.
Ladebug supports remote debugging in various client/server configurations. Figure 21-1 shows two configurations that use a single file system.
In configuration A, the client and server are implemented on a single machine which connects to a file system.
In configuration B, a host system client is connected to a remote server through TCP/IP. Both host and target systems share the same file system.
A host system client can also be connected to a remote server in a configuration that employs separate file systems, as shown in Figure 21-2.
-rfnoption with the remote file name and have a locally accessible binary with debugger information.
In configurations A, B, and C in Figure 21-1 and Figure 21-2, the user program resides on the target system. The host machine interacts with the target system in the following way:
Table 21-1 describes the client/server concepts for remote debugging. Section 21.4 describes the tasks for remote debugging.
|Is Ladebug debugger.||Is remote debugger server.|
|Runs on host system.||Runs on target hardware (for example, EB64 or Digital UNIX Alpha. )|
|Makes requests to server.||Controls the process being debugged.|
|Is responsible for all access to source files and symbol table.||Is not responsible.|
|Uses debug protocol; sends protocol commands to the server.||Uses debug protocol; receives protocol commands and sends responses.|
|Contains information about the process being debugged.||Contains information about the processes' environment.|
|Does not control processes.||Server controls a single process; server deamon controls multiple processes (messages to the server containing a server ID).|
This section describes general tasks to debug programs running on remote systems. The tasks include:
The server daemon must be running on the target system before you can remotely debug programs on that target. You can start the server daemon either from a system startup file or interactively from the command line.
hosts.equivfiles. On Digital UNIX machines,
rwprivileges only for the owner, with no privileges for the group and others.
For example, to start the server daemon interactively and output system messages to a log file, log in as superuser then start the server daemon as follows:
$ /usr/bin/ladebug-server > ladebug-server.log & Ladebug remote debug server deamon starting /usr/bin/ladebug-server : server is servdb.ptl.dss.com (184.108.40.206) ...
When you start Ladebug you also start the user program and connect to the server.
-rn command-line option, which specifies the
IP name or address of the machine on which the server deamon is
running and on which you want your user program to run. Specifying
this command-line option is the only difference between starting
Ladebug to debug a remote application and starting Ladebug to debug
a local one.
If you start Ladebug without specifying the process ID (
pid ) , it starts a debuggee process in the remote node
running the indicated image file. If you do not specify the user
name on the remote node (
-ru ) , it uses the local user
For example, if you are connecting to the target system
to debug the user program
and the file system is shared:
$ ladebug -rn servdb ~/work/test/hello Welcome to the Ladebug Debugger Version 3.0 ------------------ object file name: /usr/users/dss/work/test/hello machine name: servdb Reading symbolic information ...done
If you start Ladebug and specify a process ID, Ladebug connects to the process in the remote node running the process. If the specified process ID does not exist, the server returns an error and refuses connection.
-rfnoption with the
-rnoption. See Section 21.5 for detailed descriptions of all the remote debugging command-line options.
You debug a user program running on the target system the same way as you would a local program. Note the following differences:
reruncommands are disabled since you do not need to start the process.
quitcommand to a remote debugger session, it does not terminate the process running on the target system. To do this, you must use the
contcommand with a signal number is not supported.
The following example shows the result of running user program
~/work/test/hello on remote node
(ladebug) stop in main; run [#1: stop in main ]  stopped at [main:6 0x120001fa0] 6 (void) printf("Hello, world !\n"); (ladebug) cont Thread has finished executing (ladebug)
Note that the output of the program is not displayed after the
cont command. With remote debugging, the program
output is displayed on the target system. You can also redirect
the output of the application to a log file.
The same program run locally would look like this:
$ ladebug ~/work/test/hello Welcome to the Ladebug Debugger Version 3.0 ------------------ object file name: /usr/users/dss/work/test/hello Reading symbolic information ...done (ladebug) stop in main; run [#1: stop in main ] s stopped at [main:6 0x120001fa0] 6 (void) printf("Hello, world !\n"); (ladebug) cont Hello, world ! Thread has finished executing (ladebug)
quit command ends the remote debugger
session and automatically disconnects from the server.
quitcommand does not terminate the process running on the target system. Use the
killcommand to terminate a running process and end the remote debugger session.
Table 21-2 lists the Ladebug command-line options that support remote debugging.
||Specifies the internet node name or IP address of the machine on which the remote debugger server is running (that is, the node running the program to be debugged); optionally specifies the UDP port on which to connect the server. Either the node name or IP address is required; there is no default.|
| ||Specifies the process ID of the process to be debugged. When you specify this option, Ladebug debugs a running process rather than loading a new process.|
| || Specifies the file
name (or other identifier) of the image to be loaded on a remote
system. This option defaults to the local image file name and it is
passed to the remote system uninterpreted. Use only with
| || Connects to
a running remote process using the connect insist protocol message
instead of the connect protocol message. This option functions as
a request to the server to connect to the client, even if another
client is already connected. (The previously connected client is
disconnected.) Use only with with |
| ||Specifies the user name to be used on the remote system. The default is the local user name.|
 Depending on your shell, it may be necessary to enclose this option in quotes to prevent the shell from interpreting the punctuation characters in the parameter.
 Current remote debugger servers use UDP port 410 (the default); older releases might use UDP port 21511.
The following examples show how to use the remote debugger command- line options.
$ ladebug -rn 220.127.116.11 -ru brown program1
Connects to the server on the node with IP address
and asks the server to load a process called
program1. The local copy of the object file is also
program1. The user name on the remote node is
$ ladebug -rn EB64 -rfn '**process name A**' program3
Connects to the server on the node with IP name
and asks it to load the process called
A**'. The local object file is called
This section describes the steps you need to perform to debug remote processes running on the Evaluation Board Server . The procedures described in Section 21.6.1 through Section 21.6.3 describe the simplest procedure for using Ladebug with the Evaluation Board Server. Since Ladebug can be started at any monitor breakpoint (not only when the program is at its initial entry point), many variations are possible.
 The server includes the EB64, EB64+, and EB66 evaluation boards.
To build the executable file for remote debugging:
-goption to save symbolic information.
xis the load address for the executable file.
cstriputility to strip the
coffheader from the executable file. Keep the unstripped executable file.
To load the executable file and start the Ladebug server:
bootpserver for the Evaluation Board Server (for example, the EB64).
bootadrcommand on the monitor to set the boot address to the load address that was used when linking the executable file.
netloadcommand to load the stripped executable file across the ethernet.
LADBXcommand to start the Ladebug server.
After starting the server, to start the Ladebug debugger on the host system:
ladebug -rn <EB64> -pid 0 <exe>
In this command, <exe> is the file name of the unstripped executable file and <EB64> is the internet name or address of the Evaluation Board Server.
quitcommand closes Ladebug and returns the monitor to its command prompt. The state of the program you are debugging is not affected by this action.
The following conditions may arise when remote debugging using the Evaluation Board Server: