If you press MB3 while your mouse pointer rests in the Command Message View, a pop-up menu with the items in Table A-6 appears.

Table A-6 Message Region Pop-Up Menu

Menu Item	Description
Repeat Command [last command]	Reenters your last command.
Clear Command Line	Clears the command line.
Next	Steps to the next line by stepping over routine calls.
Continue	Resumes execution of the program.

A.4.4 Browse Source Pop-Up Menu

If you press MB3 while your mouse pointer rests in the Browse Source dialog box, a pop-up menu with the items in Table A-7 appears.

Table A-7 Source Browser Pop-Up Menu

Menu Item	Description
Expand	Expands the selected image or module to include its component modules or functions in the Source Browser display.
Collapse	Collapses an expanded image, module, or function display.
Set Breakpoint	Sets a breakpoint on the selected function.
Next	Steps to the next line by stepping over routine calls.
Continue	Resumes execution of the program.

A.4.5 Breakpoint View Pop-Up Menu

If you position your mouse pointer in the breakpoint list or annotation area of the Breakpoint View and press MB3, a pop-up menu with the items in Table A-8 appears.

Table A-8 Breakpoint View Pop-Up Menu

Menu Item	Description
Toggle	Toggles a selected breakpoint.
Set/Modify...	Provides the Set/Modify Breakpoint dialog box, which contains information about a selected breakpoint.
Delete	Deletes a selected breakpoint.
Next	Steps to the next line by stepping over routine calls.
Continue	Resumes execution of the program.

A.4.6 Monitor View and Local Variables View Pop-Up Menu

If you position your mouse pointer in the Monitor View or Local Variables View and press MB3, a pop-up menu with the items in Table A-9 appears.

Table A-9 Monitor View and Local Variables View Pop-Up Menu

Menu Item	Description
Monitor	When selected from the Monitor View, this menu item has no effect. When selected from the Local Variables View, inserts the selected expression in the monitor list of the Monitor View.
Expand	Expands a monitored aggregate to show its members.
Collapse	Collapses an expanded aggregate.
Typecast-->	Provides the list of type choices for modifying values.
Change Radix-->	Provides the list of radix choices for modifying values.
Next	Steps to the next line by stepping over routine calls.

A.4.7 Register View Pop-Up Menu

If you position your mouse pointer in the Register View and press MB3, a pop-up menu with the items in Table A-10 appears.

Table A-10 Register View Pop-Up Menu

Menu Item	Description
Next	Steps to the next line by stepping over routine calls.
Continue	Resumes execution of the program.

A.4.8 Instruction View Pop-Up Menu

If you position your mouse pointer in the Instruction View and press MB3, a pop-up menu with the items in Table A-11 appears.

Table A-11 Instruction View Pop-Up Menu

Menu Item	Description
Print [selection]	Evaluates the selected text and prints its value in the Command Message View.
Toggle Breakpoint	Toggles the breakpoint at your mouse pointer location.
Next	Steps to the next line by stepping over routine calls.
Continue	Resumes execution of the program.

The annotation area of the Instruction View contains the breakpoint toggles. If you press MB3 while your mouse pointer rests in the annotation area of the Instruction View, a pop-up menu with the items in Table A-12 appears.

Table A-12 Instruction View Annotation Area Pop-Up Menu

Menu Item	Description
Toggle Breakpoint	Toggles the breakpoint at your mouse pointer location.
Next	Steps to the next line by stepping over routine calls.
Continue	Resumes execution of the program.

This chapter introduces you to some of the features and differences of the Ladebug debugger when run as part of the DEC FUSE environment. FUSE is DIGITAL's software development environment (IDE) for UNIX workstations and servers. It integrates industry-standard UNIX tools with DIGITAL tools and other industry-leading CASE tools.

Features include:

• Support for the compile-edit-debug cycle of software development in an entry-level CASE 3GL tool environment.
• A user interface based on OSF/Motif.
• Support for application development in C, C++, FORTRAN, COBOL, and DEC Ada.
• Integration with the Common Desktop Environment (CDE).

Because FUSE works with source code from any supported language, it is a highly effective tool for maintenance or re-engineering, as well as new development. The software visualization provided by FUSE reduces the time needed to understand complex applications, which results in cost savings and fewer code errors.

For detailed information on FUSE, including prerequisite software and ordering information, see the DEC FUSE Software Product Description (SPD) and the DEC FUSE Handbook.

B.1 Starting and Configuring the Debugger Within the DEC FUSE Environment

Assuming you have DEC FUSE installed, there are three possible ways you can choose to start the debugger as part of the DEC FUSE environment:

• Use the command line.
  You can start the debugger from the command line using the following command:

  % fusedebug [ -Xt-Options ] [ filepath ]

  
  If DEC FUSE is not running, it starts automatically as a minimized icon.
  See the DEC FUSE Handbook and the specific reference pages for descriptions of the command syntax and options.

• If you have CDE installed, directly manipulate the DEC FUSE icons.
  DEC FUSE provides a DEC FUSE application group icon and icons for the individual tools that make up the DEC FUSE environment. To invoke the debugger:
  1. Double click on the Application Manager icon in the CDE Front Panel to display the application group icons.
  2. Double click on the DEC FUSE application group icon to display the icons in the DEC FUSE application group.
  3. Double click on the debugger icon to start the tool.
• Use the DEC FUSE Control Panel once DEC FUSE is running.
  To start the debugger from the DEC FUSE Control Panel (assumes DEC FUSE is already running), select Ladebug Debugger from the Tools menu in the Control Panel.
  DEC FUSE first lists the tool in the Control Panel display area. Then, the tool main window appears.

The DEC FUSE debugger Main Window is essentially the same as it appears in Ladebug with the exception of the following:

• Tools menu
  The Tools menu lets you start the other tools that are integrated within the DEC FUSE environment. You can also use this menu to configure and exit the debugger.
• Help menu differences
  DEC FUSE help is based on Bristol HyperHelp while Ladebug help is based on the OSF/Motif help widget.
• Quick help pane
  The quick help pane provides brief descriptions of menu items at the bottom of the DEC FUSE debugger Main Window.
• File:Exit Debugger was removed from the menu pulldown because you can use Exit Tool from the Tools menu.

When you start up the debugger, you specify an executable target. The debugger displays the source file for that target.

The debugger Source View is read-only. To edit a source file, you can access the editor either directly from the debugger or from the Tools menu.

If you want to edit the source file whose code is currently being displayed by the debugger, the quickest way is to choose Edit File from the Commands menu. This invokes your default DEC FUSE editor (FUSE Editor, Emacs, or vi). The editor displays the target's source code in its own window. As in the debugger Main Window, the source code in the editor window is centered where execution is currently paused.

When you then execute the program with the debugger, the Source View is updated in both the debugger and the editor.

You can use the DEC FUSE Editor and Emacs to set breakpoints. For further information, see the DEC FUSE Handbook.

This appendix describes how to write a Ladebug remote debugger server for an Alpha target (operating system or hardware platform). It describes the functionality required of the server and explains how this functionality is implemented in the Tru64 UNIX server and in the server included in the debugger monitors for the Alpha server evaluation boards. It also includes information about writing new Ladebug remote debugger servers.

C.1 Reasons for Using a Remote Debugger

The main reason for using a remote debugger is to debug software on a system that cannot run a fully functional debugger locally. Examples of when you might use a remote debugger are:

• When debugging an embedded system that does not include displays or keyboards.
• When porting an operating system. You cannot usually run a debugger locally on the target system until a substantial part of the operating system has been ported.
• When developing software to run on an operating system that does not support a fully functional local debugger.

Remote debuggers are useful simply for debugging software on systems that are remote from where you are working, although in this case there are often other alternatives (for example logging into the system across a network). Whether it is better to use remote debugging or one of these alternatives will often depend on the precise characteristics of the network and the debugger used.

C.2 Alternatives to Using a Remote Debugger

In most cases, the alternatives to using a remote debugger are either to put debugging code, such as print statements, in the software being debugged or to develop a simple local debugger for the target system.

Adding debugging code to the software increases the complexity of the software, hence causing additional bugs, and it is often difficult to determine what information will be needed to debug the software. A further problem is the debugging code can itself change the behavior of the software and as such normally has to be removed before the software is released.

Developing a local debugger can itself be a major task. Since such a debugger is normally a one-off development, you cannot normally justify including support for high level features (such as source level debugging). Even if this is possible, attempting to provide such facilities locally the target system will often not have the resources (memory, for example) required to run a high level debugger.

C.3 The Structure of a Remote Debugger

All remote debuggers consist of two parts:

• A client that runs on the user's local system (the host system)
• A server that runs on the system being debugged (the target system)

These communicate through a remote debugger protocol that runs over some communication mechanism such as a serial line or the Internet.

The client provides the user interface to the debugger and most of the intelligence of the debugger. For example, the client will normally do all translation between addresses and variable or function names.

The server makes available low level functions that allow the client to examine and control software running on the target system. For example, the server provides functions to read and modify the target system's memory. The client requests these functions, and receives responses, using the remote debugger protocol.

In general, a server is much simpler than a client and will require only minimal functionality from the target system on which it is running. This allows servers to be implemented for environments in which the functionality of a full workstation operating system is not available.

C.4 Types of Targets

Most target systems for remote debugging are of these two types:

• Targets on which the debuggees are applications running on top of an operating system such as Tru64 UNIX or VxWorks. A remote debugger server for such a target will normally communicate with the client using the operating system's networking interface (for example, sockets in Tru64 UNIX), and will normally use an operating system debugger interface (for example, the ptrace() function) to implement its debugger functions. The Tru64 UNIX server described in Section C.6.1 is an example of a server for such a target.
• Targets (typically special purpose embedded hardware) on which the debuggees are either stand alone programs or operating systems directly using the hardware. On such targets the server is typically incorporated in a ROM based debugger monitor that drives the network device directly. Such a server will perform its debugger functions by directly reading and writing memory. The Evaluation Board Server described in Section C.6.2 is an example of such a server.

Ladebug is a debugger running on Tru64 UNIX systems. It supports a wide range of languages including Ada, C, C++, COBOL, and Fortran. Besides providing local debugging on Tru64 UNIX systems, it supports remote debugging through the Ladebug remote debugger protocol. The same text and windows based interfaces are available for use with both local and remote debugging and almost all the commands that are available for local debugging are also available for remote debugging.

C.5.1 Target and Programming System Requirements

Ladebug servers must be able to:

• Set and clear breakpoints in the program being debugged (the debuggee).
• Read from and write to the debuggee's memory and registers.
• Find out when the debuggee reaches a breakpoint and read the debuggee's memory and registers when it is at a breakpoint.
• Stop a running debuggee when it is not at a breakpoint.

  Note Servers can be implemented on targets without this feature. However, without this feature, the Ladebug Ctrl/C function (that stops a running program) will not work.

• Send and receive UDP packets to and from the host system running Ladebug.
• Respond to messages from the host system without excessive delay even when the debuggee is running and is not at a breakpoint.

For Ladebug to debug a program there must be symbolic information for the program available to Ladebug on the host in a form that it understands. At present, the only form of symbolic information that Ladebug understands for programs running on Alpha processors is extended COFF (ECOFF) for Tru64 UNIX. The program must follow the register usage, function calling, and other conventions expected of programs that have this form of symbolic information. For example, a program for which the symbolic information is ECOFF must use Tru64 UNIX register usage and function calling conventions.

C.5.2 The Protocol

The Ladebug Remote Debugger Protocol is a request/response protocol running over UDP. The debugger client (Ladebug) initiates all transactions sending a request to the server. On receiving the request the server acts upon the request and sends a response. The server never sends any messages except in response to requests received from the client. The requests that the client can send are listed in Table C-1.

Table C-1 Remote Debugger Protocol Client Requests

Request	Action
Load Process	Loads a new process for debugging.
Connect to Process	Connects to an existing process.
Connect to Process Insist	Connects to an existing process even if other debugger sessions are already connected to it.
Probe Process	Checks the state of the process being debugged.
Disconnect from Process	Disconnects, ending a debugger session.
Kill Process	Kills the process; and then disconnects.
Stop Process	Stops a running process.
Continue Process	Continues running a stopped process.
Step	Executes one instruction in the process being debugged.
Set Breakpoint	Sets a breakpoint at an address.
Clear Breakpoint	Clears a breakpoint at an address.
Get Next Breakpoint	Gets the "next" breakpoint that is known to the server. Breakpoints are returned in an arbitrary order but no breakpoint will be returned more than once in a single scan of the list.
Get Registers	Gets the contents of all the registers.
Set Registers	Sets the contents of all the registers.
Read	Reads memory.
Write	Writes to memory.

Section C.11 contains a full description of the protocol.

C.5.3 Starting a Remote Debugger Session

The protocol provides three alternative requests for starting a debugger session:

• Load Process loads a new process on the target system. The Load Process request contains a file name and various other data that a server may need to load the process.
• Connect to Process connects to an existing process running on target system. It simply sends a 32 bit process ID to the target system to identify the new debuggee.
• Connect to Process Insist is identical in form to Connect to Process. It is intended to be interpreted as a request to the server to disconnect, if necessary, any old debugger sessions from the process before connecting the new debugger session to the process. This is needed because normally only one debugger session can debug any one process at a time.

All servers should implement either Load Process or Connect to Process but a server need not implement both of them. A server that implements Connect to Process can choose any of the following:

• Not to implement Connect to Process Insist
• To implement Connect to Process Insist to mean the same as Connect to Process
• To implement Connect to Process Insist to do more than Connect to Process

To allow a single target machine to run multiple remote debugger sessions at the same time, clients always send Connect and Load requests to a fixed privileged, UDP port on the target. The server is expected to allocate a new unprivileged UDP port before replying. The new port is used on the target as the source and destination of all messages for the remainder of the debugger session.

To allow servers to be run on systems on which security is an issue (for example typical Tru64 UNIX systems) the Connect and Load requests contain the client and server login names. The server can use these login names, together with the name of the host system, to check that the remote user is authorized to run programs on the target system, as is done when a user runs programs through rsh.