There are two different requests that end a remote debugger session:

• The Kill Process request ends a debugger session, killing the debuggee at the same time.
• The Disconnect from Process request ends the remote debugger session without killing the debuggee.

Although there are explicit Ladebug commands that call up each of these requests, Ladebug normally kills processes that it has loaded and disconnects from processes to which it has connected. As such, a server that implements the Load Process function should at least implement the Kill Processes function and a server that implements the Connect to Process function should implement the Disconnect from Process function. The following are optional:

• Implementation of the Kill Process function in servers that only support connecting to existing processes
• Implementation of the Disconnect from Process function in servers that only support Load Process

Two example Ladebug servers are available. The source code of these example servers is available from Digital Equipment Corporation for unrestricted reuse on Alpha based platforms (see the copyright notice in the source code for details).

C.6.1 The Tru64 UNIX Server

The Tru64 UNIX server is designed to allow the debugging of user processes running on remote Tru64 UNIX systems. The version described in this section supports loading new processes using the Load Process request but does not support the Connect to Process or Connect to Process Insist requests.

The server consists of a server daemon and user servers:

• The server daemon receives load messages, checks that they are valid and creates a user server for each valid load request. It then passes the load request on to the user server.
• The user server implements the remainder of the protocol and the low level debugger functions requested by the protocol.

The remote debugger daemon must be run as a root process. It would normally be started at system start-up. The user server loads the debuggee using Tru64 UNIX's fork() and exec() functions and uses Tru64 UNIX's ptrace() interface to implement the low level debugger facilities required. The load server and daemon both use Tru64 UNIX UDP sockets to communicate with the client.

C.6.2 Evaluation Board Server

The evaluation board server is included in the evaluation board debug monitor provided with the Alpha evaluation boards (EB64, EB64+, EB66, etc.). It is designed to provide source level debugging of operating system kernels being ported to these boards, and of programs running on these boards without an operating system. The complete monitor (including the remote debugger server) is designed to be easily ported to other Alpha based hardware.

The server only supports starting debugger sessions through the Connect to Process or Connect to Process Insist requests. This server does not support the Load Process request. Since the monitor is not a multiprocessing system, the server ignores the process ID in the Connect requests. It also ignores the login names in Connect requests.

The user is expected to load the test program using the monitor load facilities (LOAD, NETLOAD, etc.) before starting the debugger server. The server interprets all addresses it receives as physical addresses. The server then performs all debugger functions by directly reading and writing memory.

To set breakpoints, the debugger patches a PAL call into the code being debugged. To avoid conflict with the use of the breakpoint PAL call by operating system kernels, this is not the standard breakpoint PAL call (the BPT PAL call) but a special PAL call (DBGSTOP). DBGSTOP exhibits identical behaviour but has its own system entry address. It is implemented in the debugger version of evaluation boards' PAL code. When this PAL call is executed, it results in a call back to the monitor at which point the state of the debuggee is saved and the server is reentered.

The monitor's ethernet software allows server to register to receive packets addressed to particular UDP port and to send packets on any UDP port. The server depends on interrupts to receive packets while the debuggee is running. Upon receiving any interrupt, the monitor polls the ethernet driver for messages. The ethernet software passes any appropriate messages to the server.

A consequence of using interrupts to receive messages is that some care is needed when debugging programs that do their own interrupt handling. To allow such programs to be debugged, the Evaluation Board user library contains a function that polls the ethernet. This function would normally be called by the application every time it receives an interrupt.

C.6.3 Structure of the Servers

Each server consists of:

• A communicator that receives UDP messages from the clients, checks that they come from valid clients, and passes them on to the protocol handler.
  Once the protocol handler has dealt with a message and built a reply it passes this reply back to the communicator. The communicator then sends this reply to the client. The communicator is target dependent. It makes use of the target's UDP functions to read and write messages. In the Tru64 UNIX server, the communicator also contains the server's main program and the code of the daemon. As such, it is responsible for creating the user servers.
• A protocol handler that interprets the debugger messages received and builds the replies. The protocol handler calls the breakpoint table handler and the debugger kernel to perform the functions requested by the messages. The protocol handler is target independent.
• A target dependent debugger kernel that performs the actual debugger functions (such as loading a process, setting a breakpoint, or reading memory). These are performed by the kernel:
  • Through an operating system interface (for example ptrace() on Tru64 UNIX)
  • In servers for embedded monitors, by directly reading from and writing to memory
• A breakpoint table handler that creates and controls a table of the breakpoints that the server has set in the debuggee. This table handler is target independent.

The simplest way of creating a server for a new target is to base it upon one of the example servers. Normally, if you are developing the server to be part of a monitor program, you should base it upon the evaluation board server.

If, however, you are developing it as an operating system utility you should probably base it upon the Tru64 UNIX server. You should try to make as few changes as possible to the example servers, since you are likely to have no satisfactory way of debugging software (and hence the servers themselves) until you have successfully ported them to your target system.

C.7 The Communicators

This section describes

• The communicator interface functions (see Section C.7.1)
• The Tru64 UNIX communicator (see Section C.7.2)
• The evaluation board monitor (see Section C.7.3)
• How to port communicators to other systems (see Section C.7.4)

The communicator contains the main function to the debugger server, to which the interface is target-dependent. It also contains some functions that the other components of the server can call. These functions are as follows:

• int a_client_is_connected(void)---This function returns true if there is a client already connected to the server, and false otherwise.
• int this_client_is_connected(void)---This function returns true if the client from whom the communicator last received a message is connected to the server and false otherwise.
• void set_connected(void)---This function tells the communicator that the last packet received connected a client to the server.
• void disconnect_client(void)---This function tells the communicator that there is no client connected to the server.

The Tru64 UNIX communicator is implemented in the C source file server_main.c. This file contains the daemon's entry point (main()), the main function of the user servers (user_server_main() ), and the interface functions previously described.

When the daemon is started, main() creates a socket and binds it to the Ladebug remote debugger connect port. It then reads packets from this port ignoring any packets that are not load requests. When it receives a load request, it checks that the client user is allowed to run remote debugger sessions on this machine using the server user name he has requested. This it does by calling to the Tru64 UNIX function ruserok().

If the request is valid, the daemon creates a child process (by forking). The parent process then simply continues round the packet reading loop. The child process:

1. Creates a new session.
2. Changes its group ID to the primary group ID of the requested server user.
3. Changes its login name to the server user name.
4. Changes its uid to the server user's uid.
5. Calls user_server_main() with the client address and the load request packet as arguments. When user_server_main() returns, the child process exits.

If, for any reason, the daemon is unable to start the user server, it then sends a load request response to the client containing an error code.

The user server function user_server_main() starts by creating a UDP socket for communicating with the client. It then:

1. Finds a free unprivileged UDP and binds the socket to this address.
2. Processes the load packet passed to it (by calling ProcessPacket() ) and sends the response to the client.
3. Enters its main loop; in this loop it reads packets from the client, processes them, and sends the responses back to the server.
4. Breaks out of this loop and exits from the user server when the client disconnects from it.

One complication in the code of the communicator is that the daemon has to be able to handle the receipt of duplicate load messages. The client sends such duplicate load messages when the server's load response message is lost or does not reach the client within the client's time-out time.

To handle such duplicate load messages, a pipe is created between the daemon and each user server. When the daemon receives a duplicate load message, it uses this pipe to pass it on the appropriate user server. The user server treats this message like any other duplicate message.

C.7.3 Evaluation Board Monitor

The evaluation boards' Ethernet driver software passes received frames to other parts of the monitor's software through call-back functions. A component of the monitor that wishes to receive frames on a UDP port calls a registration function provided by the Ethernet driver software.

The registration functions take as an argument the address of the call-back function to be called when such frames are received. When a component registers a call-back function, it can do either of the following:

• Register it for a particular port by calling udp_register_well_known_port().
• Ask the ethernet driver to allocate a port by calling udp_create_port() . Any component of the monitor can then poll the ethernet at any time, by calling ethernet_process_one_packet().

If the ethernet hardware has received a packet for any registered UDP port then the driver will call the appropriate call-back function. The call-back function called may be in a completely different component of the monitor from that which called ethernet_process_one_packet() . Once any call-back function has completed its processing, ethernet_process_one_packet() will return with a result indicating whether any packets were processed.

All packets passed to the ethernet driver must be built in fixed sized buffers provided by the driver, so that the ethernet driver never has to copy any data. The ethernet driver allocates these buffers at addresses from which the ethernet devices can send data and to which they can receive data.

To avoid the need for complex allocation algorithms, and complex error handling if buffer allocation fails, any component of the monitor can allocate a number of buffers at start-up. To maintain this buffer count the ethernet send functions always return to the caller a buffer to replace the buffer containing the packet to be sent.

On completion, the call-back functions used to receive frames must always return an ethernet buffer to the ethernet drivers. This can be, but need not be, the buffer that contained the received frame.

The debugger server does not need its own pool of buffers, since it only sends a frame immediately following the receipt of a frame. As such it handles received frames in the following steps:

1. Receive a frame through call-back function.
2. Process the frame.
3. Send a response frame in the received buffer. The send function returns a buffer (most likely a different one).
4. Exit call-back function returning the buffer returned by the send function.

The server's communicator is largely implemented in C source file server_read_loop.c . This contains the following code:

• The interface functions previously described.
• Two call-back functions for receiving frames. The communicator uses one of these functions to receive frames on the connection port, and the other to receiving frames on the port assigned when a client has connected. Both call-back functions pass received packet to the protocol handler and send the response to the client before returning.
• The function enable_ladbx_msg() . This enables the receipt of connection messages from the client by registering the connection port. For compatibility with older versions of Ladebug it also registers a second connection port with an unprivileged port number.
• The function read_packets() . The server calls this function whenever it wishes to poll the ethernet for received packets. It simply calls ethernet_process_one_packet() until there are no more packets to process.
• The function data_received() . This is a wrapper for read_packets() that is used when the reason for polling the ethernet is that there has been an interrupt. It disables interrupts before calling read_packets() and restores the interrupt state once read_packets() returns.
• The function app_poll() . Applications that have their own interrupt handlers (and therefore disable the monitor's interrupt handler) call this function to poll the ethernet for debugger frames. It stores its return point as the debuggee's program counter and then calls data_received() . The reason for setting the debuggee's program counter is that this if the server receives a stop request then it will need to know where to put a breakpoint to stop the debuggee.
• An initialization function called ladebug_server_init_module() . This function places a pointer to app_poll() at a standard address in memory so that an independently linked application can call it.

In addition, the file kutil.s contains the source of the monitor's interrupt function. The monitor only enables interrupts when an application is running. When the monitor receives any interrupt, it saves the debuggee's state and polls the Ethernet for received frames. Since the monitor will normally receive regular 1ms timer interrupts this will ensure that it receives all the client's debugger frames.

C.7.4 Porting the Communicators to Other Systems

It should be possible to port the Tru64 UNIX communicator to most other versions of Tru64 UNIX and Tru64 UNIX derivatives with few changes. For operating systems that are not derived from Tru64 UNIX, the mechanism for starting user servers may have to be significantly modified.

In particular, many operating systems have no exact equivalent of fork() and instead start a new process by running a new executable file. On such a system, the communicator will have to be split into two separate executable files (one for the daemon and the other for the server). Also in such systems the new process typically does not have access to data set up by its parent before it was created, so some other mechanism will have to be used to transfer the first packet, and other data, to the user process.

The mechanism for setting the user identifier of the user server will vary widely between operating systems. Be aware that although the term daemon is a Tru64 UNIX term almost all operating systems have some mechanism for installing and running privileged background processes.

The socket mechanism used to read data from the network is quite widely available. If this mechanism is not available, then any other mechanism that allows the communicator to wait for the receipt of UDP packets on particular ports can be used.

If the operating system does not provide any such mechanism (for example, a real time kernel that does not include networking support), then one option is to port part or all of the networking code in the Evaluation Board Monitor to this environment. In this case, it may be easier to base your communicator upon the that in the Evaluation Board Server rather than basing it upon that in the Tru64 UNIX Server.

For embedded servers, few (if any) changes should be needed to the Evaluation Board's communicator. However, for many such systems you will need to rewrite the network device drivers. These are contained in the ethernet code of the Evaluation Board Monitor.

C.8 The Protocol Handler: Interface Functions and Implementation

The protocol handler's main interface function is ProcessPacket() . The only argument to this function is a pointer to the packet that it is to process. As a part of its processing of the packet ProcessPacket() converts the request packet passed to it into a response packet. The caller must ensure that the buffer pointed to by the argument is large enough to contain any possible response packet.

The function DumpPacket() can also be called by the communicator. This dumps the contents of packets passed to it, if the protocol handler is compiled with tracing enabled.

The code for the packet handler is identical for the two servers. It should not need to change for other server implementations. The source code is in the files packet-handling.c and packet-util.c ; packet-handling.c contains the function ProcessPackets(). When this function receives a packet, it:

1. Checks whether the packet is a duplicate of the previous packet, by checking whether the sequence number is the same:
   • If the packet is a duplicate, the function copies the last response sent into the packet buffer, updates the retransmission count in this packet, and returns.
   • If the packet is not a duplicate, it reads the command code. It uses the value of the command code to check that the request is legal in the debuggee's current state (for example a Get Registers request is only legal when the debuggee is stopped).
   • If the request is not legal the function puts an appropriate error code in the return value field of the packet and returns it as the response.
2. Carries out the action appropriate to the request it has received.
   This normally consists of extracting some arguments from the packet and passing them to the appropriate debugger kernel function. Where a request changes the state of the connection to the client (for example the kill command disconnects from the client), it calls the appropriate communicator interface function to inform the communicator that this has happened. In some cases, it also retrieves data from kernel functions (for example, the contents of the registers) and copies them into the packet.
3. Converts the packet into a response packet by setting the top bit of the packet's command code.
   It also sets the packet's return value. Before it returns the response packet to the communicator, it makes a copy of it so that it can be resent if the next packet duplicates the request packet.

packet-util.c contains utility functions for reading and writing the fields of packets and for dumping the contents of a packet. To avoid any possible alignment problems the utility functions read and write packet fields a byte at a time.

C.9 The Debugger Kernels

This section describes:

• The debugger kernel interface functions (see Section C.9.1)
• The Tru64 UNIX server debugger kernel (see Section C.9.2)
• The evaluation board server (see Section C.9.3)
• Porting the debugger kernels to other systems (see Section C.9.4)

The debugger kernels provide the following interface functions to the protocol handler:

• int kload_implemented(void)---Returns TRUE if this server can load new processes; FALSE otherwise.
• int kload(char * name, char * argv[], char * standardIn, char * standardOut, char * standardError, address_value loadAddress, address_value startAddress)---
  Loads a new process. The arguments are:
  • name---The name of the process to be loaded as a NULL terminated string. This will normally be the name of an executable file.
  • argv---The argument array. Each argument is a NULL terminated string. The argument array is terminated by an empty string (i.e one with a NULL as its first character).
  • standardIn---The name of the file to which standard input should be directed as a NULL terminated string. An empty string means do not redirect standard input.
  • standardOut---The name of the file to which standard output should be directed as a NULL terminated string. An empty string means do not redirect standard output.
  • standardError---The name of the file to which standard error should be directed as a NULL terminated string. An empty string means do not redirect standard error.
  • loadAddress---The address at which the kernel should load the executable file (or -1 if unknown).
  • startAddress---The address at which the kernel should start executing the debuggee. It is ignored if the load address is unknown.
  
  The result is TRUE if successful or FALSE if the load fails. If the load is successful the processes will become the new debuggee and stop at its entry point.
• int kconnect_implemented(void)---Returns TRUE if this server can connect to existing processes; FALSE otherwise.
• int kconnect(int pid)---Connects to an existing process with the given pid. The result is TRUE if the server connects to the process and FALSE if not. If the server manages to connect to this process, then it becomes the new debuggee.
• int kkill_possible(void)---Checks whether the kernel can kill the current debuggee. Returns TRUE if it can and FALSE if it cannot.
• void kkill(void)---Kills the current process.
• int kdetach_possible(void)---Checks whether the kernel can detach from the current debuggee without killing it. Returns TRUE if it can and FALSE if it cannot.
• void kdetach(void)---Detaches from the current process.
• int kpid(void)---Returns the pid of the current process.
• void kgo(void)---Tells the debuggee to continue running until it hits a breakpoint.
• void kstop(void)---Tells the debuggee to stop as soon a possible.
• int kaddressok(address_value address)---Checks whether an address in the debuggee is readable. Returns TRUE if it is and FALSE if it is not.
• ul kcexamine(address_value address)---Gets the data at address. If address points at a breakpoint or there is a breakpoint within 8 bytes of address the data that was at the address before the breakpoint was inserted is returned.
• int kcdeposit(address_value *address, ul value)--- puts value at address, updating the saved data for breakpoints if necessary.
• void kstep(void)---Steps one instruction.
• address_value kpc(void)---Returns the debuggee's program counter.
• void ksetpc(address_value address)---Sets the contents of the debuggee's program counter.
• register_value kregister(int reg)---Returns the contents of the debuggee's register number reg. For Alpha targets the register number of fixed point register n is n: and that of floating point register n is n+32.
• void ksetreg(int reg, register_value value)--- sets the contents of register number reg with value.
• short int kbreak(address_value address)---Sets a breakpoint at address. Returns the result that should be returned to the client.
• int kremovebreak(address_value address)---Removes the breakpoint at address. Returns the result that should be returned to the client.
• int kpoll(void)---Returns the state of the debuggee. This is one of:
  • PROCESS_STATE_PROCESS_RUNNING---The debuggee is running.
  • PROCESS_STATE_PROCESS_AT_BREAK ---The debuggee is stopped at a breakpoint or after a performing a single step.
  • PROCESS_STATE_PROCESS_SUSPENDED ---The debuggee is stopped somewhere else due to a signal, trap or exception.
  • PROCESS_STATE_PROCESS_TERMINATED ---The debuggee has exited.