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.
-rfn option 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.
| Client | Server |
|---|---|
| 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.
.rhosts and the
hosts.equiv files. On Digital
UNIX machines, .rhosts must have rw
privileges 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 (11.18.49.164) ...
When you start Ladebug you also start the user program and connect to the server.
Use the -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
name.
For example, if you are connecting to the target system servdb
to debug the user program ~/work/test/hello
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.
-rfn option with the -rn option. 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:
run
and rerun commands are disabled since you
do not need to start the process.
quit command to a
remote debugger session, it does not terminate the process
running on the target system. To do this, you must use the
kill command.
cont command with a signal number is not
supported.
The following example shows the result of running user program
~/work/test/hello on remote node servdb:
(ladebug) stop in main; run
[#1: stop in main ]
[1] 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[1] stopped at [main:6 0x120001fa0]
6 (void) printf("Hello, world !\n");
(ladebug) cont
Hello, world !
Thread has finished executing
(ladebug)
The Ladebug quit command ends the remote debugger
session and automatically disconnects from the server.
quit command
does not terminate the process running on the target system. Use the
kill command to terminate a running process and end
the remote debugger session.
Table 21-2 lists the Ladebug command-line options that support remote debugging.
| Option/Qualifier | Meaning /Conditions |
|---|---|
-rn [1]
node_or_address [,udp_port [2]] |
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. |
-pid process_id | 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. |
-rfn [1]
arbitrary_string | 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 -
rn ; do not combine with -pid . |
-rinsist | 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 -rn and -
pid . |
-ru username
| Specifies the user name to be used on the remote system. The default is the local user name. |
|
[1] 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. [2] 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 1.2.3.4 -ru brown program1
Connects to the server on the node with IP address 1.2.3.4
and asks the server to load a process called
program1. The local copy of the object file is also
called program1. The user name on the remote node is
brown.
$ ladebug -rn EB64 -rfn '**process name A**' program3
Connects to the server on the node with IP name EB64
and asks it to load the process called '**process name
A**'. The local object file is called program3.
This section describes the steps you need to perform to debug remote processes running on the Evaluation Board Server [1]. 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.
[1] The server includes the EB64, EB64+, and EB66 evaluation boards.
To build the executable file for remote debugging:
-g
option to save symbolic information.
-N and
-Tx options, where x is the load
address for the executable file.
cstrip utility to strip the
coff header from the executable file. Keep the
unstripped executable file.
To load the executable file and start the Ladebug server:
bootp server for the
Evaluation Board Server (for example, the EB64).
bootadr command on the monitor
to set the boot address to the load address that was used when
linking the executable file.
netload command to load the stripped
executable file across the ethernet.
stop command.
go command.
LADBX command 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.
quit
command. The quit command 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: