Debugging with GDB: In-Process Agent

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

# 30. In-Process Agent

The traditional debugging model is conceptually low-speed, but works fine, because most bugs can be reproduced in debugging-mode execution. However, as multi-core or many-core processors are becoming mainstream, and multi-threaded programs become more and more popular, there should be more and more bugs that only manifest themselves at normal-mode execution, for example, thread races, because debugger's interference with the program's timing may conceal the bugs. On the other hand, in some applications, it is not feasible for the debugger to interrupt the program's execution long enough for the developer to learn anything helpful about its behavior. If the program's correctness depends on its real-time behavior, delays introduced by a debugger might cause the program to fail, even when the code itself is correct. It is useful to be able to observe the program's behavior without interrupting it.

Therefore, traditional debugging model is too intrusive to reproduce some bugs. In order to reduce the interference with the program, we can reduce the number of operations performed by debugger. The In-Process Agent, a shared library, is running within the same process with inferior, and is able to perform some debugging operations itself. As a result, debugger is only involved when necessary, and performance of debugging can be improved accordingly. Note that interference with program can be reduced but can't be removed completely, because the in-process agent will still stop or slow down the program.

The in-process agent can interpret and execute Agent Expressions (see section F. The GDB Agent Expression Mechanism) during performing debugging operations. The agent expressions can be used for different purposes, such as collecting data in tracepoints, and condition evaluation in breakpoints.

You can control whether the in-process agent is used as an aid for debugging with the following commands:

`set agent on`
  Causes the in-process agent to perform some operations on behalf of the debugger. Just which operations requested by the user will be done by the in-process agent depends on the its capabilities. For example, if you request to evaluate breakpoint conditions in the in-process agent, and the in-process agent has such capability as well, then breakpoint conditions will be evaluated in the in-process agent.

`set agent off`
  Disables execution of debugging operations by the in-process agent. All of the operations will be performed by GDB.

`show agent`
  Display the current setting of execution of debugging operations by the in-process agent.

> 30.1 In-Process Agent Protocol |  |

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 30.1 In-Process Agent Protocol

The in-process agent is able to communicate with both GDB and GDBserver (see section 30. In-Process Agent). This section documents the protocol used for communications between GDB or GDBserver and the IPA. In general, GDB or GDBserver sends commands (see section 30.1.2 IPA Protocol Commands) and data to in-process agent, and then in-process agent replies back with the return result of the command, or some other information. The data sent to in-process agent is composed of primitive data types, such as 4-byte or 8-byte type, and composite types, which are called objects (see section 30.1.1 IPA Protocol Objects).

> 30.1.1 IPA Protocol Objects |  |
> 30.1.2 IPA Protocol Commands |  |

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 30.1.1 IPA Protocol Objects

The commands sent to and results received from agent may contain some complex data types called objects.

The in-process agent is running on the same machine with GDB or GDBserver, so it doesn't have to handle as much differences between two ends as remote protocol (see section E. GDB Remote Serial Protocol) tries to handle. However, there are still some differences of two ends in two processes:

1. word size. On some 64-bit machines, GDB or GDBserver can be compiled as a 64-bit executable, while in-process agent is a 32-bit one.
2. ABI. Some machines may have multiple types of ABI, GDB or GDBserver is compiled with one, and in-process agent is compiled with the other one.

Here are the IPA Protocol Objects:

1. agent expression object. It represents an agent expression (see section F. The GDB Agent Expression Mechanism).
2. tracepoint action object. It represents a tracepoint action (see section Tracepoint Action Lists) to collect registers, memory, static trace data and to evaluate expression.
3. tracepoint object. It represents a tracepoint (see section 13. Tracepoints).

The following table describes important attributes of each IPA protocol object:

@headitem Name Size | Description agent expression object |  |
length | 4 | length of bytes code
byte code | length | contents of byte code
tracepoint action for collecting memory |  |
'M' | 1 | type of tracepoint action
addr | 8 | if basereg is ``-1'`, addr is the address of the lowest byte to collect, otherwise addr is the offset of basereg for memory collecting.
len | 8 | length of memory for collecting
basereg | 4 | the register number containing the starting memory address for collecting.
tracepoint action for collecting registers |  |
'R' | 1 | type of tracepoint action
tracepoint action for collecting static trace data |  |
'L' | 1 | type of tracepoint action
tracepoint action for expression evaluation |  |
'X' | 1 | type of tracepoint action
agent expression | length of | agent expression object
tracepoint object |  |
number | 4 | number of tracepoint
address | 8 | address of tracepoint inserted on
type | 4 | type of tracepoint
enabled | 1 | enable or disable of tracepoint
step_count | 8 | step
pass_count | 8 | pass
numactions | 4 | number of tracepoint actions
hit count | 8 | hit count
trace frame usage | 8 | trace frame usage
compiled_cond | 8 | compiled condition
orig_size | 8 | orig size
condition | 4 if condition is NULL otherwise length of agent expression object
| zero if condition is NULL, otherwise is agent expression object actions | variable
| numactions number of tracepoint action object

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 30.1.2 IPA Protocol Commands

The spaces in each command are delimiters to ease reading this commands specification. They don't exist in real commands.

``FastTrace:tracepoint_object gdb_jump_pad_head'`
  Installs a new fast tracepoint described by tracepoint_object (see tracepoint object). gdb_jump_pad_head, 8-byte long, is the head of jumppad, which is used to jump to data collection routine in IPA finally.

  Replies:

  ``OK target_address gdb_jump_pad_head fjump_size fjump'`
    target_address is address of tracepoint in the inferior. gdb_jump_pad_head is updated head of jumppad. Both of target_address and gdb_jump_pad_head are 8-byte long. fjump contains a sequence of instructions jump to jumppad entry. fjump_size, 4-byte long, is the size of fjump.
  ``E NN'`
    for an error

``close'`
  Closes the in-process agent. This command is sent when GDB or GDBserver is about to kill inferiors.

``qTfSTM'`
  See qTfSTM.
``qTsSTM'`
  See qTsSTM.
``qTSTMat'`
  See qTSTMat.
``probe_marker_at:address'`
  Asks in-process agent to probe the marker at address.

  Replies:

  ``E NN'`
    for an error
``unprobe_marker_at:address'`
  Asks in-process agent to unprobe the marker at address.

[ << ] | [ >> ] |  |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

This document was generated by GNAT Mailserver on April, 17 2014 using texi2html